Release offer funds

POST

/v1/offer-slot-releases

curl --request POST \
  --url https://api.digirare.com/v1/offer-slot-releases \
  --header 'Content-Type: application/json' \
  --header 'x-session-token: <x-session-token>' \
  --data '{ "slots": [ { "txid": "example", "vout": 1 } ], "bidder_public_key": "example", "fee_rate": 1 }'

Release funds for exact offers: an unsigned self-send of the session owner’s own bid slots (live or ended) back to the owner’s own script, the cancel Bitcoin enforces. Spending a slot retires every offer and exact authorization on it once the outspend poller sees it. Every value is read from the chain; nothing is stored or reserved. The result lists slots in the PSBT’s input order with expected_txid, fee_sats, output_sats, and signer instructions; the wallet side proves the PSBT spends exactly those slots into one output paying the owner before signing, then relays through POST /v1/transactions. A slot a signed acceptance is settling answers 409 state_changed; a spent slot answers 409 conflict_spend.

Authorizations

• session

Request Body^required

Media typeapplication/json

object

slots

required

The owner’s bid slots to spend, in input order.

Array<object>

>= 1 items <= 20 items

object

txid

required

string

/^[0-9a-f]{64}$/

vout

required

integer

bidder_public_key

required

P2TR: the 32-byte x-only internal key; P2WPKH: the 33-byte compressed key. Must own the session address’s script.

string

/^[0-9a-f]+$/

fee_rate

number

>= 0.1 <= 500

Example^generated

{
  "slots": [
    {
      "txid": "example",
      "vout": 1
    }
  ],
  "bidder_public_key": "example",
  "fee_rate": 1
}

Responses

200

Successful composeOfferSlotRelease response.

Media typeapplication/json

object

result

required

An unsigned self-send of one or more of the bidder’s exact-offer bid slots back to the bidder’s own script: the certain, on-chain cancel for exact_offer_v1 (spending a slot retires every offer and authorization on it). Composed from chain facts, never stored; the wallet side proves the PSBT spends exactly slots into one output before signing.

object

bidder

required

string

slots

required

The slots in the PSBT’s input order, with their chain values.

Array<object>

object

funding_slot_id

required

string

txid

required

string

vout

required

number

value_sats

required

Integer satoshis, exactly representable as a JSON number. Aggregated historical volume can exceed Bitcoin’s supply, so this is the safe JSON integer ceiling, not a single-transaction spending limit.

integer

<= 9007199254740991

live_offers

required

Live offers this slot still backs; 0 for an ended slot.

number

psbt_hex

required

string

expected_txid

required

string

fee_sats

required

Integer satoshis, exactly representable as a JSON number. Aggregated historical volume can exceed Bitcoin’s supply, so this is the safe JSON integer ceiling, not a single-transaction spending limit.

integer

<= 9007199254740991

output_sats

required

Integer satoshis, exactly representable as a JSON number. Aggregated historical volume can exceed Bitcoin’s supply, so this is the safe JSON integer ceiling, not a single-transaction spending limit.

integer

<= 9007199254740991

fee_rate

required

number

signing

required

object

signer_address

required

string

inputs_to_sign

required

Array<number>

sighash

required

string

Allowed values: DEFAULT ALL

Example

{
  "result": {
    "signing": {
      "sighash": "DEFAULT"
    }
  }
}

4XX

Stable machine-readable failure

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: invalid_request unsupported_address_type unauthenticated forbidden not_found method_not_allowed state_changed expired invalid_transaction rate_limited internal_error upstream_unavailable service_unavailable checkout_changed target_unavailable signature_invalid template_mismatch mempool_rejected broadcast_unknown conflict_spend duplicate_funding_slot offer_selection_unavailable attached_delivery_single_item_only insufficient_funds insufficient_asset_balance price_below_minimum listing_price_above_maximum counter_price_invalid self_trade offer_capacity_full open_offer_limit policy_offer_refused

retryable

boolean

mempool_policy

On 422 mempool_rejected from a broadcast: which deterministic node policy refused the bytes. Retrying the same bytes fails the same way. fee_floor: re-quote at a higher fee_rate. chain_too_long: too many unconfirmed ancestors; wait for a confirmation, then retry. truc: a version-3 (TRUC) package rule, such as spending an unconfirmed version-3 output; wait for a confirmation, then retry.

string

Allowed values: fee_floor chain_too_long truc dust nonstandard

mempool_reason

The node’s own reject reason, on mempool_rejected (422) and on state_changed (409) when a broadcast lost to a conflicting or replacing spend.

string

wait_for_confirmation

Present and true when mempool_policy is chain_too_long or truc.

boolean

claims_released

On a checkout or accept completion refused as mempool_rejected: the journaled settlement ended and every listing, bid, and asset claim it held was released (its inputs were proven unspent). The quote or accept is replaced; request a new one.

boolean

refused_listings

Batch listing routes only: every refused item. The first sets the status and code.

Array<object>

One refused item in a batch refusal’s refused_listings array. Nothing in the batch was changed.

object

index

required

integer

listing_id

required

string

status

required

integer

code

required

string

error

required

string

key

additional properties

any

retry_after_seconds

On 429 rate_limited: the exact seconds until the oldest counted request leaves the window; a retry then is admitted (also sent as Retry-After). Limited writes are bucketed per route scope in exact sliding 60-second windows: by session address when a valid x-session-token is present, otherwise by IP, with a per-IP ceiling across sessions. Expensive writes: 20, ceiling 120. Signed completions: 120, ceiling 600. Session minting (/auth/*): 60 per IP. A request refused by any bucket is counted by none.

integer

>= 1

key

additional properties

any

Example

{
  "code": "invalid_request",
  "mempool_policy": "fee_floor"
}

5XX

Stable machine-readable failure

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: invalid_request unsupported_address_type unauthenticated forbidden not_found method_not_allowed state_changed expired invalid_transaction rate_limited internal_error upstream_unavailable service_unavailable checkout_changed target_unavailable signature_invalid template_mismatch mempool_rejected broadcast_unknown conflict_spend duplicate_funding_slot offer_selection_unavailable attached_delivery_single_item_only insufficient_funds insufficient_asset_balance price_below_minimum listing_price_above_maximum counter_price_invalid self_trade offer_capacity_full open_offer_limit policy_offer_refused

retryable

boolean

mempool_policy

On 422 mempool_rejected from a broadcast: which deterministic node policy refused the bytes. Retrying the same bytes fails the same way. fee_floor: re-quote at a higher fee_rate. chain_too_long: too many unconfirmed ancestors; wait for a confirmation, then retry. truc: a version-3 (TRUC) package rule, such as spending an unconfirmed version-3 output; wait for a confirmation, then retry.

string

Allowed values: fee_floor chain_too_long truc dust nonstandard

mempool_reason

The node’s own reject reason, on mempool_rejected (422) and on state_changed (409) when a broadcast lost to a conflicting or replacing spend.

string

wait_for_confirmation

Present and true when mempool_policy is chain_too_long or truc.

boolean

claims_released

On a checkout or accept completion refused as mempool_rejected: the journaled settlement ended and every listing, bid, and asset claim it held was released (its inputs were proven unspent). The quote or accept is replaced; request a new one.

boolean

refused_listings

Batch listing routes only: every refused item. The first sets the status and code.

Array<object>

One refused item in a batch refusal’s refused_listings array. Nothing in the batch was changed.

object

index

required

integer

listing_id

required

string

status

required

integer

code

required

string

error

required

string

key

additional properties

any

retry_after_seconds

On 429 rate_limited: the exact seconds until the oldest counted request leaves the window; a retry then is admitted (also sent as Retry-After). Limited writes are bucketed per route scope in exact sliding 60-second windows: by session address when a valid x-session-token is present, otherwise by IP, with a per-IP ceiling across sessions. Expensive writes: 20, ceiling 120. Signed completions: 120, ceiling 600. Session minting (/auth/*): 60 per IP. A request refused by any bucket is counted by none.

integer

>= 1

key

additional properties

any

Example

{
  "code": "invalid_request",
  "mempool_policy": "fee_floor"
}