Your listing drafts

GET

/v1/address/{address}/listing-preflights

curl --request GET \
  --url 'https://api.digirare.com/v1/address/example/listing-preflights?limit=50&state=in_flight' \
  --header 'x-session-token: <x-session-token>'

Owner operation history for recovering a lost preflight-create response. An unsigned attach past its expiry is reported as expired at read time.

Authorizations

• session

Parameters

Path Parameters

address

required

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

string

Query Parameters

limit

integer

default: 50 >= 1 <= 100

cursor

string

Opaque (created_at,id) continuation token returned as next_cursor.

state

string

Allowed values: in_flight

In_flight returns only the seller’s signed attaches still confirming (broadcasting or awaiting the indexer), newest activity first, at most 50, without paging; limit and cursor are ignored.

Responses

200

Successful listSellerListingPreflights response.

Media typeapplication/json

object

result

required

Array<object>

object

operation_id

required

string

protocol_version

required

string

Allowed value: counterparty_attach_listing_v1

seller

required

string

asset

required

string

quantity_raw

required

Counterparty atomic units. A string preserves integers beyond JSON’s safe numeric range; divisibility affects display, never this wire value.

string

/^[0-9]+$/

asset_utxo

required

object

txid

required

string

vout

required

number

utxo_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

Deadline for reviewing this template. The listing itself has no Bitcoin-level expiry.

number

id

required

string

asset_source

required

Address-level Counterparty balance consumed by the attach. It may be a Legacy sibling while seller owns the modern asset UTXO and listing.

string

mode

required

string

Allowed values: reuse attach

status

required

string

Allowed values: awaiting_attach_signature broadcasting awaiting_indexer prepared ready completed failed expired withdrawn

fees

required

object

network

required

object

asset

required

string

Allowed value: BTC

amount_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

protocol

required

object

asset

required

string

Allowed value: XCP

amount_raw

required

string

actual_amount_raw

required

string | null

observed_block

required

number | null

variable_until_confirmed

required

boolean

charged_at

required

string | null

platform

required

object

asset

required

string

Allowed value: BTC

amount_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

listing

object

psbt_hex

required

string

signer_address

required

string

inputs_to_sign

required

Array<number>

sighash

required

string

Allowed value: SINGLE|ANYONECANPAY

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

attach

object

psbt_hex

required

string

signers

required

Complete signer plan derived from authenticated PSBT prevouts. Input 0 must belong to the preflight’s asset_source; later fee inputs may belong to other permissioned addresses in the same wallet.

Array<object>

object

address

required

string

inputs_to_sign

required

Array<number>

sighash

required

string

Allowed value: ALL

expected_txid

required

string

next_action

required

string | null

Allowed values: sign_attach wait_for_indexer set_price sign_listing list_again

last_error

required

string | null

bitcoin_confirmed_at

required

number | null

created_at

required

number

updated_at

required

number

listing_id

string | null

listed_price_sats

Any of:

integer

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

null

null

listing_status

Current listing state, distinct from successful preparation/submission.

string | null

result_count

required

integer

next_cursor

required

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

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