Get listings by outpoint
Look up whether UTXOs are listed, one or up to 100 at a time. Both forms return only live listings: active, or pending while a purchase is in the mempool. A sold, cancelled or moved listing is no longer the outpoint's.
One outpoint #
GET/api/market/listings/by-outpoint/{outpoint}
The live listing (active, or pending while a purchase is in the mempool) of one outpoint, or 404 not_listed.
Path parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
outpoint | string | yes | The UTXO, txid:vout. |
Example request #
curl 'https://raresats.net/api/market/listings/by-outpoint/8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0'const response = await fetch('https://raresats.net/api/market/listings/by-outpoint/8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0');
const data = await response.json();import requests
data = requests.get("https://raresats.net/api/market/listings/by-outpoint/8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0").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. |
{
"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_outpoint | Not an outpoint (txid:vout). |
| 400 | bad_path | The path is not valid percent-encoding. |
| 404 | not_listed | That outpoint has no live listing. |
{"error": "not an outpoint (txid:vout)", "code": "bad_outpoint"}Many outpoints #
GET/api/market/listings/by-outpoint
The batch form: the live listings of up to 100 outpoints at once, keyed by outpoint. Outpoints that are not listed are simply absent.
Query parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
outpoints | string | yes | 1-100 outpoints (txid:vout), comma-separated. |
Example request #
curl 'https://raresats.net/api/market/listings/by-outpoint?outpoints=8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0,2fb6fb60ece3672924a373d7479d144d9ce4d3591185bfb5a00e62aedd53d3a9:0'const response = await fetch('https://raresats.net/api/market/listings/by-outpoint?outpoints=8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0,2fb6fb60ece3672924a373d7479d144d9ce4d3591185bfb5a00e62aedd53d3a9:0');
const data = await response.json();import requests
data = requests.get("https://raresats.net/api/market/listings/by-outpoint", params={"outpoints": "8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0,2fb6fb60ece3672924a373d7479d144d9ce4d3591185bfb5a00e62aedd53d3a9:0"}).json()Response 200 #
| Field | Type | Description |
|---|---|---|
listings | map of Listing | The live (active or pending) listing of each outpoint asked for, keyed by outpoint. Outpoints with none are absent. |
as_of | object | null | When the marketplace last checked every live listing against the chain: the block height and unix seconds. null until the first check. |
as_of.height | integer | null | Block height |
as_of.checked_at | integer | Unix seconds |
{
"listings": {
"8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0": {
"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
}
},
"as_of": {"height": 969001, "checked_at": 1790952985}
}Errors #
{error, code}; see Errors for every code.
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_outpoint | Not an outpoint (txid:vout). |
| 400 | bad_outpoints | outpoints lists none, or more than 100. |
{"error": "outpoints must list 1-100 outpoints", "code": "bad_outpoints"}An outpoint with no live listing is simply absent from listings; one malformed outpoint fails the whole request (400 bad_outpoint).