Compose offer funding

POST

/v1/offer-funding-templates

curl --request POST \
  --url https://api.digirare.com/v1/offer-funding-templates \
  --header 'Content-Type: application/json' \
  --header 'x-session-token: <x-session-token>' \
  --data '{ "price_sats": 1, "delivery_mode": "detached", "slot_count": 1, "fee_rate": 1, "tap_internal_key": "example", "exclude": [ { "txid": "example", "vout": 1 } ] }'

Composes the bidder’s self-send that mints slot_count independent bid outputs from their own asset-free P2WPKH/P2TR inputs, plus change. Detached slots equal price_sats; attached-delivery slots include an additional 330 sat buyer-owned asset UTXO. Returns the unsigned template with signer instructions. Nothing is stored or reserved: the browser signs, finalizes, and hands the bytes to POST /v1/funded-offers. Coins an earlier leg of the same run already spent are passed back in exclude.

Authorizations

• session

Request Body^required

Media typeapplication/json

object

price_sats

required

The offer per edition. An attached-delivery bid output also includes the 330 sat buyer-owned asset UTXO.

integer

>= 1 <= 9007199254740991

delivery_mode

string

default: detached

Allowed values: detached attached

slot_count

How many editions the offer can fill; one bid output each.

integer

default: 1 >= 1 <= 20

fee_rate

number

>= 0.1 <= 500

tap_internal_key

The bidder’s 32-byte x-only internal key; required for a P2TR bidder so the wallet can key-path sign.

string

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

exclude

Outpoints the caller already spent in earlier legs of this run; never chosen as funding.

Array<object>

<= 200 items

object

txid

required

string

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

vout

required

integer

Responses

200

An unsigned offer funding template

Media typeapplication/json

object

result

required

object

bidder

required

Mainnet P2TR or P2WPKH address. The SIGNING capability: every signature is verified by reconstructing a BIP-143/BIP-341 witness sighash.

string

price_sats

required

Offer price per slot; at least 5,000 sats.

integer

>= 1 <= 9007199254740991

platform_fee_sats

required

Marketplace fee pre-funded in each slot: always 0. The seller who accepts is the taker and pays platformFeeSats(price) out of their proceeds.

integer

0

delivery_mode

required

string

Allowed values: detached attached

slot_value_sats

required

Actual value of each bid output: exactly price_sats, plus a 330 sat asset UTXO for attached delivery. No marketplace fee is pre-funded.

integer

>= 1 <= 9007199254740991

slot_count

required

integer

>= 1 <= 20

fee_rate_sat_vb

required

number

>= 0.1 <= 500

funding_value_sats

required

integer

>= 1 <= 9007199254740991

network_fee_sats

required

integer

>= 1 <= 9007199254740991

change_sats

required

integer

inputs

required

The bidder’s asset-free inputs the template spends.

Array<object>

object

txid

required

string

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

vout

required

integer

value_sats

required

integer

>= 1 <= 9007199254740991

slots

required

The bid outpoints the transaction creates: vout 0..slot_count-1, each worth slot_value_sats.

Array<object>

object

txid

required

string

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

vout

required

integer

value_sats

required

integer

>= 1 <= 9007199254740991

funding

required

object

psbt_hex

required

string

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

signers

required

Array<object>

object

address

required

Counterparty address whose balance is attached when a listing is prepared. P2PKH, P2WPKH, or P2TR: these spend families are supported by the attach verifier. The source owns input 0 and may differ from seller, which owns the modern asset UTXO and signs the listing.

string

inputs_to_sign

required

Array<integer>

>= 1 items unique items

sighash

required

Allowed value: ALL

expected_txid

required

string

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

Example

{
  "result": {
    "platform_fee_sats": 0,
    "delivery_mode": "detached",
    "funding": {
      "sighash": "ALL"
    }
  }
}

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"
}