Skip to content
DIGIRAREDevelopers

Quote a purchase

POST
/v1/fills/request
curl --request POST \
  --url https://api.digirare.com/v1/fills/request \
  --header 'Content-Type: application/json' \
  --data '{ "items": [ { "asset": "example", "quantity": 1, "max_price_sats": 1, "target_outpoint": { "txid": "example", "vout": 1 } } ], "buyer_address": "example", "buyer_tap_internal_key": "example", "delivery_address": "example", "delivery_mode": "detached", "fee_rate": 1 }'

Returns a 180-second, non-reserving PSBT snapshot. Detached delivery is the default; a one-unit purchase may instead preserve the asset on its own buyer-owned asset UTXO. Public cart quotes may be requested without a session. A counter_id requires a current session matching buyer_address; foreign and missing counters return the same 404.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
object
items
required
Array<object>
>= 1 items <= 10 items
object
asset
required

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

string
quantity
required
integer
>= 1 <= 20
max_price_sats
required
integer
>= 1 <= 9007199254740991
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
buyer_address
required

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

string
buyer_tap_internal_key
string
/^[0-9a-f]{64}$/
delivery_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
fee_rate
number
>= 0.1 <= 500

Responses

Section titled “Responses”

201

Section titled “201”

Non-reserving checkout quote

Media typeapplication/json
object
result
required
object
operation_id
required
string
protocol_version
required
Allowed value: direct_v1
fill_id
required
string
psbt_hex
required
string
/^[0-9a-f]+$/
expected_txid
required
string
/^[0-9a-f]{64}$/
signing
required
object
signer_address
required

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

string
inputs_to_sign
required
Array<integer>
sighash
required
Allowed value: ALL
selected_outpoints
required
object
funding
required
Array<object>
object
txid
required
string
/^[0-9a-f]{64}$/
vout
required
integer
assets
required
Array<object>
object
txid
required
string
/^[0-9a-f]{64}$/
vout
required
integer
settlement_items
required
Array<object>
>= 1 items
object
listing_id
required
string
asset
required

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

string
quantity_raw
required
string
/^[0-9]+$/
seller
required

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

string
outpoint
required
object
txid
required
string
/^[0-9a-f]{64}$/
vout
required
integer
utxo_value_sats
required
integer
>= 1
price_sats
required
integer
>= 1 <= 9007199254740991
seller_payment_sats
required
integer
>= 1
fee_rate
required
number
>= 0.1 <= 500
subtotal_sats
required
integer
>= 1 <= 9007199254740991
network_fee_sats
required
integer
platform_fee_sats
required
integer
platform_fee_internal_key

X-only BIP86 internal key of the marketplace fee output, derived server-side from the fee allocation’s own index (account m/86’/0’/1’, child 0/index, without its parity byte). The fee output is exactly the key-path-only P2TR of this key. Absent when there is no key to vouch for (a pre-fee template, or a fee key that is not configured or no longer derives the stored output).

string
/^[0-9a-f]{64}$/
total_sats
required
integer
>= 1 <= 9007199254740991
change_sats
integer
delivery
required
object
mode
required
string
Allowed values: detached attached
address
required

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

string
defaulted
required
boolean
utxo_value_sats
integer
Allowed value: 330
settlement_groups
required
Allowed value: 1
expires_at
required
integer
reserves_inventory
required
Example
{
  "result": {
    "protocol_version": "direct_v1",
    "signing": {
      "sighash": "ALL"
    },
    "delivery": {
      "mode": "detached",
      "utxo_value_sats": 330,
      "settlement_groups": 1
    },
    "reserves_inventory": false
  }
}

4XX

Section titled “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

Section titled “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"
}