Place a collection offer

POST

/v1/policy-offers

curl --request POST \
  --url https://api.digirare.com/v1/policy-offers \
  --header 'Content-Type: application/json' \
  --header 'x-session-token: <x-session-token>' \
  --data '{ "bidder_public_key": "example", "alternatives": [ { "psbt_hex": "example", "leaf_hex": "example", "policy": { "scope": "asset", "asset": "example", "collection": "example", "max_supply_units": 1, "min_supply_units": 1, "issued_year": 1, "series": 1, "artist": "example" } } ] }'

Verifies every bidder-signed parent against chain prevouts and the committed leaf, seals the parents at rest, and stores the funding set, all alternatives, and the anchor commitment atomically (all or none). An identical retry answers 200 with already_placed. Every policy-offer route answers 503 service_unavailable when collection-offer signing is unavailable.

Authorizations

• session

Request Body^required

Media typeapplication/json

object

bidder_public_key

required

string

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

alternatives

required

Array<object>

>= 1 items <= 100 items

object

psbt_hex

required

string

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

leaf_hex

required

string

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

policy

required

Funded_policy_offer_v1 canonical policy (spec 4.4). Exactly these keys, absent traits null; SHA256 of its canonical JSON is the leaf’s policy hash.

object

scope

required

string

Allowed values: asset collection

asset

required

One of:

string

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

string

null

null

collection

required

string | null

>= 1 characters <= 120 characters

max_supply_units

required

integer | null

min_supply_units

required

integer | null

issued_year

required

integer | null

series

required

integer | null

artist

required

string | null

>= 1 characters <= 200 characters

Responses

200

Successful placePolicyOffer response.

Media typeapplication/json

object

result

required

object

protocol_version

required

string

Allowed value: funded_policy_offer_v1

funding_id

required

string

funding_slot_id

required

string

already_placed

required

boolean

offers

required

Array<object>

object

scope

required

string

Allowed values: asset collection

asset

required

string | null

collection

required

string | null

max_supply_units

required

number | null

min_supply_units

required

number | null

issued_year

required

number | null

series

required

number | null

artist

required

string | null

protocol_version

required

string

Allowed value: funded_policy_offer_v1

parent_txid

required

string

funding_slot_id

required

“:”: alternatives sharing it are exclusive.

string

bidder

required

string

kind

required

trait = a collection policy with at least one trait predicate.

string

Allowed values: asset collection trait

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

offer_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

expires_at

required

number

parent_vsize

required

number

parent_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

created_at

required

number

estimate

required

Any of:

object

What accepting would pay a seller at fee_rate, from the offer’s real parent size and a P2TR seller/fee child estimate. A quote, not a promise: the accept preflight recomputes from the seller’s actual UTXO.

object

fee_rate

required

number

child_vsize

required

number

package_vsize

required

number

network_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

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

seller_net_sats

required

A projected net can be negative when fees exceed the offered proceeds.

integer

>= -9007199254740991 <= 9007199254740991

acceptable

required

False when the net falls at or below dust at this rate (grey it out).

boolean

null

null

status

required

string

Allowed values: active expired pending filled superseded cancelled invalid

funding_id

required

string

funding_status

required

string

Allowed values: active claimed settled spent_external cancelled swept onchain_funded invalid

delivery

required

object

mode

required

string

Allowed value: detached

address

required

string

market_key_exposure_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

fill_txid

The settling transaction once this alternative filled; absent from an API that predates it.

string | null

Example

{
  "result": {
    "protocol_version": "funded_policy_offer_v1",
    "offers": [
      {
        "scope": "asset",
        "protocol_version": "funded_policy_offer_v1",
        "kind": "asset",
        "status": "active",
        "funding_status": "active",
        "delivery": {
          "mode": "detached"
        }
      }
    ]
  }
}

201

Successful placePolicyOffer response.

Media typeapplication/json

object

result

required

object

protocol_version

required

string

Allowed value: funded_policy_offer_v1

funding_id

required

string

funding_slot_id

required

string

already_placed

required

boolean

offers

required

Array<object>

object

scope

required

string

Allowed values: asset collection

asset

required

string | null

collection

required

string | null

max_supply_units

required

number | null

min_supply_units

required

number | null

issued_year

required

number | null

series

required

number | null

artist

required

string | null

protocol_version

required

string

Allowed value: funded_policy_offer_v1

parent_txid

required

string

funding_slot_id

required

“:”: alternatives sharing it are exclusive.

string

bidder

required

string

kind

required

trait = a collection policy with at least one trait predicate.

string

Allowed values: asset collection trait

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

offer_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

expires_at

required

number

parent_vsize

required

number

parent_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

created_at

required

number

estimate

required

Any of:

object

What accepting would pay a seller at fee_rate, from the offer’s real parent size and a P2TR seller/fee child estimate. A quote, not a promise: the accept preflight recomputes from the seller’s actual UTXO.

object

fee_rate

required

number

child_vsize

required

number

package_vsize

required

number

network_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

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

seller_net_sats

required

A projected net can be negative when fees exceed the offered proceeds.

integer

>= -9007199254740991 <= 9007199254740991

acceptable

required

False when the net falls at or below dust at this rate (grey it out).

boolean

null

null

status

required

string

Allowed values: active expired pending filled superseded cancelled invalid

funding_id

required

string

funding_status

required

string

Allowed values: active claimed settled spent_external cancelled swept onchain_funded invalid

delivery

required

object

mode

required

string

Allowed value: detached

address

required

string

market_key_exposure_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

fill_txid

The settling transaction once this alternative filled; absent from an API that predates it.

string | null

Example

{
  "result": {
    "protocol_version": "funded_policy_offer_v1",
    "offers": [
      {
        "scope": "asset",
        "protocol_version": "funded_policy_offer_v1",
        "kind": "asset",
        "status": "active",
        "funding_status": "active",
        "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"
}