Place funded offers

POST

/v1/funded-offers

curl --request POST \
  --url https://api.digirare.com/v1/funded-offers \
  --header 'Content-Type: application/json' \
  --header 'x-session-token: <x-session-token>' \
  --data '{ "funding_tx_hex": "example", "bids": [ { "txid": "example", "vout": 1 } ], "targets": [ { "scope": "asset", "asset": "example", "collection": "example", "max_supply_units": 1, "min_supply_units": 1, "issued_year": 1, "series": 1, "artist": "example", "target_outpoint": { "txid": "example", "vout": 1 } } ], "expires_at": 1, "receive_address": "example", "delivery_mode": "detached" }'

Places offers on bid outputs the signed funding transaction itself proves. Each named output must pay the session’s own address and hold exactly the offer price (plus the 330-sat asset UTXO for attached delivery); the accepting seller pays the marketplace fee. The placement is rehearsed first so a bad target fails before the network sees anything; the bytes are then relayed (a transaction the network already knows is a success) and the cross-product of the outputs and targets is placed. A relay failure places nothing and journals nothing; the client submits the same bytes again.

Authorizations

• session

Request Body^required

Media typeapplication/json

object

funding_tx_hex

required

The fully signed, finalized funding transaction. Its outputs are the only authority for each bid’s value.

string

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

bids

required

Which outputs of the funding transaction are bid slots; txid, when given, must be the transaction’s own.

Array<object>

>= 1 items <= 20 items

object

txid

required

string

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

vout

required

integer

targets

required

Array<object>

>= 1 items <= 500 items

One alternative eligibility policy. Multiple targets sharing one bid outpoint are mutually exclusive choices, not additional capacity.

object

scope

required

string

Allowed values: asset collection

asset

Canonical compact Counterparty key. A subasset uses its A ID; asset_longname is display metadata.

string

collection

string

max_supply_units

integer | null

min_supply_units

integer | null

issued_year

integer | null

series

integer | null

artist

string | null

target_outpoint

Optional exact asset outpoint. Never substitutes another unit. Cart quantity must be 1; offers must have asset scope.

object

txid

required

string

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

vout

required

integer

<= 4294967295

expires_at

required

integer

receive_address

Destination for a detached Counterparty balance. ANY address family Core accepts, legacy P2PKH included: a delivery address is a UTF-8 string inside the detach OP_RETURN, never a signer and never an output script. Deliberately wider than BitcoinAddress.

string

delivery_mode

string

default: detached

Allowed values: detached attached

Responses

201

Successful placeFundedOffers response.

Media typeapplication/json

object

result

required

A placement whose slots were minted by the relayed funding transaction.

object

placement_id

required

string

slot_count

required

number

target_count

required

number

offer_count

required

number

bidder

required

string

price_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

platform_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

funding_slots

required

Array<object>

object

funding_slot_id

required

string

txid

required

string

vout

required

number

offer_ids

required

Array<string>

targets

required

Array<object>

object

target_outpoint

object

txid

required

string

vout

required

number

scope

required

string

Allowed values: asset collection

asset

string | null

collection

string | null

max_supply_units

number | null

min_supply_units

number | null

issued_year

number | null

series

number | null

artist

string | null

expires_at

required

number

delivery

required

object

mode

required

string

Allowed values: detached attached

address

required

string

utxo_value_sats

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

funding

required

object

txid

required

string

Example

{
  "result": {
    "targets": [
      {
        "scope": "asset"
      }
    ],
    "delivery": {
      "mode": "detached"
    }
  }
}

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