Get a listing

GET/api/market/listings/{id}

One listing by id, whatever its status (active, pending, sold, cancelled or moved).

Path parameters #

Parameter	Type	Required	Description
`id`	string	yes	The listing id (16 hex characters).

Example request #

cURL

curl 'https://raresats.net/api/market/listings/3324d08569806818'

JavaScript

const response = await fetch('https://raresats.net/api/market/listings/3324d08569806818');
const data = await response.json();

Python

import requests

data = requests.get("https://raresats.net/api/market/listings/3324d08569806818").json()

Response `200` #

Field	Type	Description
`id`	string	The listing id: 16 lowercase hex characters.
`outpoint`	string	The listed UTXO, `txid:vout`.
`value`	integer	The UTXO's own value in sats (it moves to the buyer whole).
`price`	integer	The listing price in sats: exactly what the seller receives. The buyer pays this plus the platform fee and the network fee.
`unit_price`	number	Price per sat of the listing's own row: `(price - value) / count`, to the hundredth of a sat. Floors and the `unit` sort use it.
`row`	string	The listing's own row (collection): the rarest market row holding every tracked sat of the UTXO, else the rarest market row present. Never a label row.
`count`	integer	How many sats of `row` the UTXO holds (the "×N" of a bulk listing).
`rows`	map of integer	Every row the UTXO's tracked sats count toward, with their counts (label rows included).
`types`	array of TypeGroup \| null	The UTXO's sats grouped by exact type combination, rarest first.
`sats`	integer \| null	Tracked sats in the UTXO (all rows).
`ranges`	array of array of integer \| null	The tracked sats as inclusive `[first, last]` ranges, ascending.
`years`	map of integer \| null	Tracked sats per mint year (UTC year of the block that mined them).
`seller_address`	string	The address that holds the UTXO and signed the listing.
`payout_address`	string	Where the price is paid (the seller's payment output).
`status`	string	`active` (for sale), `pending` (a purchase is in the mempool), `sold`, `cancelled` (or replaced by a newer listing of the same UTXO), `moved` (spent elsewhere). A listing whose UTXO was sold through an accepted offer ends `sold` with `sold_via: "offer"`.
`created_at`	integer	Unix seconds.
`updated_at`	integer	Unix seconds of the last status change.
`txid`	string \| null	The purchase transaction, while `pending` and once `sold`; otherwise `null`.
`signature_public`	boolean	`true` once a broadcast purchase put the seller's signature on the network: the listing can then be bought at this price anywhere until the UTXO moves, even after a cancel here.
`sold_via`	string \| null	`offer` when the listing ended `sold` through an accepted offer of its UTXO: `price` and `unit_price` are then the offer's (what was paid), `offer_id` names it. `null` otherwise.
`offer_id`	string \| null	The accepted offer it was sold through (`sold_via: "offer"`), else `null`.
`best_offer`	BestOffer \| null	The best active offer on the UTXO, or `null`.
`spent_by_pending`	object	A transaction still in the mempool that spends an output (`spent_by_pending`). Absent when nothing pending spends it.
`spent_by_pending.txid`	string	The spending transaction.
`spent_by_pending.vin`	integer \| null	Its input that spends the output.
`spent_by_pending.first_seen`	integer \| null	When the transaction was first seen in the mempool (bitcoind's entry time), unix seconds.
`spent_by_pending.fee_rate`	number \| null	Its fee rate, sat/vB (one decimal).
`spent_by_pending.sale`	boolean	Whether the spend sells this output (a pending sale with it as the seller's input).
`spent_by_pending.replaceable`	boolean	Always true (full RBF): the spend may still be replaced.
`in_bundle`	boolean	Only on a listing read for a row it holds some sats of among others (in bundle: `contains=1`'s `contains`, or a row's activity): `true`. Its `price` is the whole UTXO's and its `unit_price` its own row's, never the row asked for.
`contains_count`	integer \| null	With `in_bundle`: how many sats of the row asked for it holds.

Response

{
  "id": "3324d08569806818",
  "outpoint": "8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0",
  "value": 6280,
  "price": 94200,
  "unit_price": 14,
  "row": "block9",
  "count": 6280,
  "rows": {"block9": 6280, "block9_1st_tx": 6280},
  "types": [
    {
      "types": ["block9", "nakamoto", "vintage"],
      "count": 6280,
      "sats": [45100023043, 45100023044, 45100023045]
    }
  ],
  "sats": 6280,
  "ranges": [[45100023043, 45100029322]],
  "years": {"2009": 6280},
  "seller_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
  "payout_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
  "status": "active",
  "created_at": 1790952985,
  "updated_at": 1790952985,
  "txid": null,
  "signature_public": false,
  "sold_via": null,
  "offer_id": null,
  "best_offer": null
}

Errors #

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

Status	Code	Meaning
400	`bad_path`	The path is not valid percent-encoding.
404	`not_found`	No such listing or offer. In chat: no such message. A display name to remove that does not exist.

Error (404)

{"error": "no such listing", "code": "not_found"}

Use it to follow a listing through its life: active, then pending with the purchase txid, then sold; or cancelled or moved. See The Listing object.

Get a listing

Path parameters #

Example request #

Response 200 #

Errors #

Response `200` #