Skip to content
DIGIRAREDevelopers

Price a listing draft

POST
/v1/listing-preflights/{id}/price
curl --request POST \
  --url https://api.digirare.com/v1/listing-preflights/example/price \
  --header 'Content-Type: application/json' \
  --header 'x-session-token: <x-session-token>' \
  --data '{ "price_sats": 1 }'

Binds or replaces the price on prepared inventory and returns the exact unsigned listing authorization.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string
>= 1 characters

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
price_sats
required
integer
>= 1 <= 9007199254740991
Examplegenerated
{
  "price_sats": 1
}

Responses

Section titled “Responses”

200

Section titled “200”

Durable listing operation

Media typeapplication/json
object
result
required
object
id
required
string
operation_id
string
protocol_version
Allowed value: counterparty_attach_listing_v1
seller
required

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

string
asset_source
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
asset
required

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

string
quantity_raw
required
string
/^(0|[1-9][0-9]*)$/
mode
required
string
Allowed values: reuse attach
status
required

Completed: the listing exists. withdrawn (read-time only): a reorg reopened the attach and withdrew its listing by design; the attach has been mined again, so the unit is attached and must be listed again with a new preflight (next_action list_again). A failed, expired, or re-verifying (awaiting_indexer) preflight keeps its own status even when a listing row exists.

string
Allowed values: awaiting_attach_signature broadcasting awaiting_indexer prepared ready completed failed expired withdrawn
asset_utxo
required
object
txid
required
string
/^[0-9a-f]{64}$/
vout
required
integer
utxo_value_sats
required
integer
>= 1 <= 9007199254740991
fees
required
object
network
required
object
asset
required
Allowed value: BTC
amount_sats
required
integer
protocol
required
object
asset
required
Allowed value: XCP
amount_raw
required
string
/^(0|[1-9][0-9]*)$/
actual_amount_raw
One of:
string
/^(0|[1-9][0-9]*)$/
observed_block
integer | null
variable_until_confirmed
required
boolean
charged_at
string | null
platform
required
object
asset
required
Allowed value: BTC
amount_sats
required
integer
listing
object
psbt_hex
required
string
/^[0-9a-f]+$/
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: SINGLE|ANYONECANPAY
price_sats
required
integer
>= 1 <= 9007199254740991
attach
object
psbt_hex
required
string
/^[0-9a-f]+$/
signers
required

Canonical signer groups derived from authenticated PSBT prevouts. Input 0 belongs to asset_source; every input appears exactly once.

Array<object>
>= 1 items
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}$/
next_action
string | null
Allowed values: sign_attach wait_for_indexer set_price sign_listing list_again
expires_at
required
integer
last_error
string | null
bitcoin_confirmed_at
integer | null
created_at
integer
updated_at
integer
listing_id
string | null
listed_price_sats

Accepted listing price when recovered by preflight ID.

integer | null
listing_status

Current listing state, distinct from a completed preparation. Includes expiry derived at read time.

string | null
Example
{
  "result": {
    "protocol_version": "counterparty_attach_listing_v1",
    "mode": "reuse",
    "status": "awaiting_attach_signature",
    "fees": {
      "network": {
        "asset": "BTC"
      },
      "protocol": {
        "asset": "XCP"
      },
      "platform": {
        "asset": "BTC"
      }
    },
    "listing": {
      "sighash": "SINGLE|ANYONECANPAY"
    },
    "attach": {
      "sighash": "ALL"
    },
    "next_action": "sign_attach"
  }
}

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