Place offers on bid outputs

POST

/v1/offers

curl --request POST \
  --url https://api.digirare.com/v1/offers \
  --header 'Content-Type: application/json' \
  --header 'x-session-token: <x-session-token>' \
  --data '{ "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" }'

Production requires a session proving control of the shared bid-output address; funding alone is not accepted as identity.

Authorizations

• session

Request Body^required

Media typeapplication/json

Creates the cross-product of exact-price funding outpoints and alternative targets. N bid outpoints provide capacity N; each outpoint may back every target, and its first fill retires all sibling policies over that outpoint. At most 1000 offer rows may be created per request.

object

bids

required

Exact-price BTC outpoints, one per independently fillable collectible unit.

Array<object>

>= 1 items <= 20 items

object

txid

required

string

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

vout

required

integer

targets

required

Alternative asset, collection, or trait policies shared by every supplied funding outpoint.

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 placeOffers response.

Media typeapplication/json

object

result

required

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

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