Prepare a listing

POST/api/market/listings/prepare

Step 1 of listing: checks each UTXO (confirmed, unspent, yours, tracked rare sats, no inscription or rune, a valid price) and returns the PSBT to sign with SIGHASH_SINGLE|ANYONECANPAY. Nothing is stored yet.

Request body #

content-type: application/json

Field	Type	Required	Description
`seller_address`	string	yes	The address holding the UTXOs: Taproot (`bc1p…`), native SegWit (`bc1q…`) or nested SegWit (`3…`, P2SH-P2WPKH). Legacy `1…` is refused.
`seller_public_key`	string	yes	The public key of `seller_address`, hex: for Taproot the internal (untweaked) key, 32-byte x-only or 33-byte compressed; for SegWit the 33-byte compressed key.
`payout_address`	string	no	Where the price is paid. Optional: defaults to `seller_address`. Any standard mainnet address.
`items`	array of object	yes	1 to 50 UTXOs, each listed at its own price. One PSBT, one wallet prompt. (1-50 items)
`items[].outpoint`	string	yes	The UTXO to list, `txid:vout`.
`items[].price`	integer	yes	Its price in sats: what you receive. Above the UTXO's own value, at least 546 and at least the payout output's dust limit.

Example request #

cURL

curl -X POST 'https://raresats.net/api/market/listings/prepare' \
  -H 'content-type: application/json' \
  -d '{
  "seller_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
  "seller_public_key": "0283dfe85a3151d2517290da461fe2815591ef69f2b18a2ce63f01697a8b313145",
  "payout_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
  "items": [
    {
      "outpoint": "8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0",
      "price": 94200
    }
  ]
}'

JavaScript

const response = await fetch('https://raresats.net/api/market/listings/prepare', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    "seller_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
    "seller_public_key": "0283dfe85a3151d2517290da461fe2815591ef69f2b18a2ce63f01697a8b313145",
    "payout_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
    "items": [
      {
        "outpoint": "8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0",
        "price": 94200
      }
    ]
  })
});
const data = await response.json();

Python

import requests

data = requests.post("https://raresats.net/api/market/listings/prepare", json={
    "seller_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
    "seller_public_key": "0283dfe85a3151d2517290da461fe2815591ef69f2b18a2ce63f01697a8b313145",
    "payout_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
    "items": [{
        "outpoint": "8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0",
        "price": 94200
    }]
}).json()

Response `200` #

Field	Type	Description
`psbt`	string	The unsigned listing PSBT, base64: input i is UTXO i (with `witnessUtxo`, `sighashType` 0x83, `tapInternalKey` or `redeemScript`), output i pays its price to the payout address; version 2, locktime 0, sequence 0xfffffffd.
`sign`	array of object	The inputs to sign: every input, with `sighash: 131`.
`sign[].index`	integer	The input to sign.
`sign[].address`	string	The address whose key signs it.
`sign[].sighash`	integer	The sighash type to sign with, when it is not the default: 131 (`0x83`, SIGHASH_SINGLE\|ANYONECANPAY) for listings. Absent on purchase inputs: sign with the default (SIGHASH_DEFAULT for Taproot, SIGHASH_ALL for SegWit v0).
`items`	array of object	What each listed UTXO will show.
`items[].outpoint`	string	The UTXO.
`items[].value`	integer	Its value in sats.
`items[].price`	integer	Its listing price in sats.
`items[].unit_price`	number	`(price - value) / count`.
`items[].row`	string	Its own row.
`items[].count`	integer	Sats of that row it holds.

Response

{
  "psbt": "cHNidP8BAF4CAAAAAWroye3nyLiwpcNzDMmz2aV449rKtugMlDF04UqR1gmLAAAAAAD9////AfhvAQAAAAAAIlEgqC8plE1luGrmteXMdeKU6tbFk5Gh7cXgFuNJjGf8e7sAAAAAAAEBK4gYAAAAAAAAIlEgqC8plE1luGrmteXMdeKU6tbFk5Gh7cXgFuNJjGf8e7sBAwSDAAAAARcgg9/oWjFR0lFykNpGH+KBVZHvafKxiizmPwFpeosxMUUAAA==",
  "sign": [
    {
      "index": 0,
      "address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
      "sighash": 131
    }
  ],
  "items": [
    {
      "outpoint": "8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0",
      "value": 6280,
      "price": 94200,
      "unit_price": 14,
      "row": "block9",
      "count": 6280
    }
  ]
}

Errors #

{error, code}; see Errors for every code.

Status	Code	Meaning
400	`bad_address`	An address is not a mainnet address (or not one at all).
400	`bad_items`	`items` is not a list of 1-50 UTXOs (or the PSBT lists more), or an item's `sats` is not null or a list of sat numbers.
400	`bad_json`	The body is not valid JSON.
400	`bad_outpoint`	Not an outpoint (`txid:vout`).
400	`bad_price`	A price is not a whole number of sats.
400	`bad_public_key`	A public key is not hex, or not a valid secp256k1 key of the right size.
400	`bad_request`	The body is not a JSON object, or the engine refused a malformed request (e.g. a purchase submitted without its signed setup PSBT).
400	`duplicate_outpoint`	The same UTXO twice in one listing.
403	`cross_origin`	A POST from a browser on another site (a foreign `Origin`, or `sec-fetch-site: cross-site`). Server-side clients send no `Origin` and are not affected.
405	`method_not_allowed`	Wrong method for the route; the `allow` header lists the right ones.
409	`pending`	The UTXO's listing is being bought, or an offer of it accepted, right now.
409	`spent`	The UTXO (or a listing's UTXO) is spent or does not exist.
409	`unconfirmed`	The UTXO is not confirmed yet.
409	`unindexed`	The ord indexer does not know the UTXO yet.
413	`too_large`	The body is over 256 KiB.
415	`not_json`	A POST without `content-type: application/json`.
422	`bad_payout`	A listed input is paired with an output that pays no address, or the payout address is the marketplace's fee address.
422	`inscribed`	The UTXO carries an inscription: only rare sats are listed; the wallet tools only send it whole.
422	`key_mismatch`	The public key does not control the address.
422	`legacy_address`	A legacy (P2PKH, `1…`) address: use Taproot or SegWit.
422	`no_row`	The UTXO holds no sat of a market row.
422	`not_owner`	The UTXO does not belong to the seller address, or (wallet tools) to the owner's addresses, or the transfer was made by another wallet.
422	`price_too_high`	The price is above 21,000,000 BTC.
422	`price_too_low`	The price is at most the UTXO's own value, below 546 sats, or below the payout output's dust limit.
422	`pubkey_mismatch`	The trade engine found the public key is not the address's key.
422	`runes`	The UTXO carries runes (the wallet tools only send it whole).
422	`too_many_items`	Too many UTXOs in a listing, or listings in a purchase (`max_bulk`); for a wallet transfer, too many rare sats (and the runs between them) to lay out in one UTXO: choose fewer.
422	`unsupported_address`	An address type the marketplace does not trade (only Taproot, native SegWit and nested SegWit).
422	`unsupported_script`	The trade engine met a script type it does not support.
422	`untracked`	The UTXO holds no rare sat the index tracks (send it whole instead).
429	`rate_limited`	Over 30 POSTs a minute from your IPv4 address or IPv6 /64 (in chat, counted per IPv4 address or IPv6 /64: 30 writes and 20 login nonces a minute, 20 sign-ins and 10 display-name changes an hour; one message every 3 s and 20 a minute per address); wait `retry-after` seconds. With the AI moderation on, at most 6 messages and names a minute are checked per address and per IPv4 address or IPv6 /48.
503	`bitcoind_unavailable`	bitcoind is not available.
503	`engine_unavailable`	The trade engine is not available.
503	`fork_behind`	The rare-sat index has not caught up with bitcoind: try again in a minute.
503	`fork_unavailable`	The rare-sat index is not available.
503	`indexer_behind`	The ord indexer is catching up: try again shortly.
503	`market_unavailable`	The marketplace is closed right now (its backends disagree on the network, or are unreachable).
503	`oracle_unavailable`	The ord oracle is not available.

Error (422)

{
  "error": "8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0 carries an inscription: only rare sats are listed here",
  "code": "inscribed",
  "outpoint": "8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0"
}

Sign every input listed in sign with sighash 0x83 (SIGHASH_SINGLE|ANYONECANPAY), then submit the listing. The whole flow, with code: List a UTXO.

Nothing is stored at this step; preparing twice is harmless.
For SegWit v0 sellers, small previous transactions are included as nonWitnessUtxo (some hardware wallets want them).

Prepare a listing

Request body #

Example request #

Response 200 #

Errors #

Response `200` #