Query listings
Active listings and marketplace activity, filtered by row, rarer sub-category, mint years, a mint day or a month-day, and sat luck: the marketplace counterpart of Query sales. How the filters combine: Filtering & birthday sats.
Each listing of the query also names its lead sat with its block, mint day and luck (lead), and the block that created its UTXO (utxo): the columns of the site's listings grid.
Listings #
GET/api/listings/query
Active marketplace listings filtered like /api/sales/query, sorted like /api/market/listings, with facets. Not cached. 404 {enabled: false} while the marketplace is off.
Query parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
row | string | no | Only this row (collection). None: every row. |
sub | string | no | A rarer sub-category of row (e.g. pizza_uncommon under uncommon): only items holding sats of it. Implies subs=1. |
subs | string | no | 1 includes the row's sub-category items (sold or listed under their own rows). One of: 0, 1. Default: 0. |
contains | string | no | With row: 1 also answers, apart, the listings holding only some sats of the row among others (in bundle: a Block 9 chunk holding one Block 9 palindrome under block9_palindrome) as contains (the first limit, in the asked sort and order; sort=unit orders them by total price, a bundle having no unit price of this row) and contains_total; only answers those alone as listings/total, paged by limit and offset. They are priced as the whole UTXO, never in the row's floor. One of: 0, 1, only. Default: 0. |
years | string | no | Mint years, comma-separated (2009,2010; up to 40): items holding a sat mined in one of them. Each must be a year sats were mined in, 2009 to this one (400 otherwise); repeats and order do not matter. year is accepted too. |
month | string | no | A mint month, YYYY-MM (UTC, by each block's own time): items holding a sat mined that month. Combines with the other filters. |
blocks | string | no | A block range: heights from-to, inclusive (1000-5000), or one block (9): items holding a sat mined in those blocks. Up to the tip (400 past it or for a malformed or reversed range). Combines with the other filters. |
date | string | no | A mint day, YYYY-MM-DD (UTC), 2009 to this year: items holding a sat mined that day. Exclusive with md. |
md | string | no | A month-day, MM-DD: items holding a sat mined that day of any year (with years, of those years). Birthday sats. |
luck | string | no | Sat luck, a minimum (8: luck 8 or more) or an inclusive range (8-12), 0 to 254: items holding a sat of that luck. A sat's luck is its block's: the leading zero bits of the block hash less those of the block's target. Combines with the other filters (the matched sat passes them all). 503 for the few seconds after a first start while the luck of every block is read. |
sort | string | no | unit, price or new. One of: unit, price, new. Default: unit. |
order | string | no | asc or desc. Default: asc, except desc for sort=new. One of: asc, desc. |
limit | integer | no | Page size, 1-200. Default: 50. (min 1, max 200) |
offset | integer | no | Listings to skip, 0-100,000. Default: 0. (min 0, max 100000) |
Example request #
curl 'https://raresats.net/api/listings/query?row=uncommon&years=2009&month=2017-12&blocks=1000-5000&luck=8'const response = await fetch('https://raresats.net/api/listings/query?row=uncommon&years=2009&month=2017-12&blocks=1000-5000&luck=8');
const data = await response.json();import requests
data = requests.get("https://raresats.net/api/listings/query", params={"row": "uncommon", "years": "2009", "month": "2017-12", "blocks": "1000-5000", "luck": "8"}).json()Response 200 #
| Field | Type | Description |
|---|---|---|
row | string | null | The row asked for. |
filter | object | The filter as the server understood it. |
filter.years | array of integer | The years asked for (ascending), [] for none. |
filter.month | string | null | The month asked for (YYYY-MM), null for none. |
filter.date | string | null | The day asked for. |
filter.md | string | null | The month-day asked for. |
filter.blocks | object | null | The blocks asked for: {from, to}, heights inclusive (one block: from = to), null for none. |
filter.blocks.from | integer | |
filter.blocks.to | integer | |
filter.luck | object | null | The luck asked for: {min, max} (max null for a minimum alone), null for none. |
filter.luck.min | integer | |
filter.luck.max | integer | null | |
filter.sub | string | null | The sub-category asked for. |
filter.subs | boolean | Whether sub-category items are included (absent on events and counts). |
filter.led | boolean | Whether sales led by another row are included (led=1; sales only). |
total | integer | Matching active listings. |
facets | object | null | Counts for refining the filter; null with contains=only. |
listings | array of object | One page, in the requested order. |
listings[].id | string | The listing id: 16 lowercase hex characters. |
listings[].outpoint | string | The listed UTXO, txid:vout. |
listings[].value | integer | The UTXO's own value in sats (it moves to the buyer whole). |
listings[].price | integer | The listing price in sats: exactly what the seller receives. The buyer pays this plus the platform fee and the network fee. |
listings[].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. |
listings[].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. |
listings[].count | integer | How many sats of row the UTXO holds (the "×N" of a bulk listing). |
listings[].rows | map of integer | Every row the UTXO's tracked sats count toward, with their counts (label rows included). |
listings[].types | array of TypeGroup | null | The UTXO's sats grouped by exact type combination, rarest first. |
listings[].sats | integer | null | Tracked sats in the UTXO (all rows). |
listings[].ranges | array of array of integer | null | The tracked sats as inclusive [first, last] ranges, ascending. |
listings[].years | map of integer | null | Tracked sats per mint year (UTC year of the block that mined them). |
listings[].seller_address | string | The address that holds the UTXO and signed the listing. |
listings[].payout_address | string | Where the price is paid (the seller's payment output). |
listings[].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). |
listings[].created_at | integer | Unix seconds. |
listings[].updated_at | integer | Unix seconds of the last status change. |
listings[].txid | string | null | The purchase transaction, while pending and once sold; otherwise null. |
listings[].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. |
listings[].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. |
listings[].offer_id | string | null | The accepted offer it was sold through (sold_via: "offer"), else null. |
listings[].match | object | null | The sat that made the item pass a date or luck filter: its number, block, mint day (UTC) and luck. null without such a filter. |
listings[].match.sat | integer | The sat. |
listings[].match.height | integer | The block that mined it. |
listings[].match.date | string | null | Its mint day, YYYY-MM-DD. |
listings[].match.luck | integer | null | Its luck (its block's: the leading zero bits of the block hash less the target's); null while the luck table is being read. |
listings[].best_offer | BestOffer | null | The best active offer on the UTXO, or null. |
listings[].lead | object | null | The listing's lead sat: the sat that matched a date or luck filter, else the first sat of its rarest combination of types; its number, block, mint day (UTC) and luck (the grid's Luck column). null when the listing names no sat. |
listings[].lead.sat | integer | The sat. |
listings[].lead.height | integer | The block that mined it. |
listings[].lead.date | string | null | Its mint day, YYYY-MM-DD (UTC); null while the day table is being read. |
listings[].lead.luck | integer | null | Its luck (its block's: the leading zero bits of the block hash less the target's); null while the luck table is being read. |
listings[].utxo | object | null | The block that created the listed UTXO and that block's day (UTC), as the marketplace's last check of its listings saw it. null before the first check after the listing, or while the UTXO is unconfirmed. |
listings[].utxo.height | integer | The block height. |
listings[].utxo.date | string | null | Its day, YYYY-MM-DD (UTC); null while the day table is being read. |
listings[].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. |
listings[].contains_count | integer | null | With in_bundle: how many sats of the row asked for it holds. |
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 |
ms | integer | Server time spent, ms. |
contains | array of object | Only with contains=1: the first limit listings passing the filter that hold some sats of the row among others (in bundle, each in_bundle: true, its lead its first sat of the row), by total price, the cheapest first. Never in listings, total or facets. |
contains[].id | string | The listing id: 16 lowercase hex characters. |
contains[].outpoint | string | The listed UTXO, txid:vout. |
contains[].value | integer | The UTXO's own value in sats (it moves to the buyer whole). |
contains[].price | integer | The listing price in sats: exactly what the seller receives. The buyer pays this plus the platform fee and the network fee. |
contains[].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. |
contains[].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. |
contains[].count | integer | How many sats of row the UTXO holds (the "×N" of a bulk listing). |
contains[].rows | map of integer | Every row the UTXO's tracked sats count toward, with their counts (label rows included). |
contains[].types | array of TypeGroup | null | The UTXO's sats grouped by exact type combination, rarest first. |
contains[].sats | integer | null | Tracked sats in the UTXO (all rows). |
contains[].ranges | array of array of integer | null | The tracked sats as inclusive [first, last] ranges, ascending. |
contains[].years | map of integer | null | Tracked sats per mint year (UTC year of the block that mined them). |
contains[].seller_address | string | The address that holds the UTXO and signed the listing. |
contains[].payout_address | string | Where the price is paid (the seller's payment output). |
contains[].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). |
contains[].created_at | integer | Unix seconds. |
contains[].updated_at | integer | Unix seconds of the last status change. |
contains[].txid | string | null | The purchase transaction, while pending and once sold; otherwise null. |
contains[].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. |
contains[].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. |
contains[].offer_id | string | null | The accepted offer it was sold through (sold_via: "offer"), else null. |
contains[].match | object | null | The sat that made the item pass a date or luck filter: its number, block, mint day (UTC) and luck. null without such a filter. |
contains[].match.sat | integer | The sat. |
contains[].match.height | integer | The block that mined it. |
contains[].match.date | string | null | Its mint day, YYYY-MM-DD. |
contains[].match.luck | integer | null | Its luck (its block's: the leading zero bits of the block hash less the target's); null while the luck table is being read. |
contains[].best_offer | BestOffer | null | The best active offer on the UTXO, or null. |
contains[].lead | object | null | The listing's lead sat: the sat that matched a date or luck filter, else the first sat of its rarest combination of types; its number, block, mint day (UTC) and luck (the grid's Luck column). null when the listing names no sat. |
contains[].lead.sat | integer | The sat. |
contains[].lead.height | integer | The block that mined it. |
contains[].lead.date | string | null | Its mint day, YYYY-MM-DD (UTC); null while the day table is being read. |
contains[].lead.luck | integer | null | Its luck (its block's: the leading zero bits of the block hash less the target's); null while the luck table is being read. |
contains[].utxo | object | null | The block that created the listed UTXO and that block's day (UTC), as the marketplace's last check of its listings saw it. null before the first check after the listing, or while the UTXO is unconfirmed. |
contains[].utxo.height | integer | The block height. |
contains[].utxo.date | string | null | Its day, YYYY-MM-DD (UTC); null while the day table is being read. |
contains[].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[].contains_count | integer | null | With in_bundle: how many sats of the row asked for it holds. |
contains_total | integer | Only with contains=1: how many such listings pass (all pages; contains=only pages them). |
Errors #
{error} (a message, no code):
| Status | When |
|---|---|
| 400 | A malformed parameter (e.g. a date that is no date, date with md). |
| 404 | An unknown row or sub, or the marketplace is off (enabled: false). A retired row (uncommon_2009, rare_2009) answers 404 too, its retired field naming the row and years to ask for instead. |
| 503 | Mint dates or sat luck are still being read (retry: true): try again in a few seconds. Without retry: this server has no sat luck for its chain. |
Activity #
GET/api/listings/events
The marketplace's listed, cancelled and sold events of listings that pass the filter, newest first (the newest 2,000 events searched). Not cached. 404 while the marketplace is off.
Query parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
row | string | no | Only this row (collection). None: every row. Events of every listing under the row, any kind (marked sub or in_bundle when its own row is another). |
sub | string | no | A rarer sub-category of row (e.g. pizza_uncommon under uncommon): only items holding sats of it. Implies subs=1. |
years | string | no | Mint years, comma-separated (2009,2010; up to 40): items holding a sat mined in one of them. Each must be a year sats were mined in, 2009 to this one (400 otherwise); repeats and order do not matter. year is accepted too. |
month | string | no | A mint month, YYYY-MM (UTC, by each block's own time): items holding a sat mined that month. Combines with the other filters. |
blocks | string | no | A block range: heights from-to, inclusive (1000-5000), or one block (9): items holding a sat mined in those blocks. Up to the tip (400 past it or for a malformed or reversed range). Combines with the other filters. |
date | string | no | A mint day, YYYY-MM-DD (UTC), 2009 to this year: items holding a sat mined that day. Exclusive with md. |
md | string | no | A month-day, MM-DD: items holding a sat mined that day of any year (with years, of those years). Birthday sats. |
luck | string | no | Sat luck, a minimum (8: luck 8 or more) or an inclusive range (8-12), 0 to 254: items holding a sat of that luck. A sat's luck is its block's: the leading zero bits of the block hash less those of the block's target. Combines with the other filters (the matched sat passes them all). 503 for the few seconds after a first start while the luck of every block is read. |
limit | integer | no | Events, 1-200. Default: 60. (min 1, max 200) |
Example request #
curl 'https://raresats.net/api/listings/events?row=uncommon&years=2009&month=2017-12&blocks=1000-5000&luck=8&limit=5'const response = await fetch('https://raresats.net/api/listings/events?row=uncommon&years=2009&month=2017-12&blocks=1000-5000&luck=8&limit=5');
const data = await response.json();import requests
data = requests.get("https://raresats.net/api/listings/events", params={"row": "uncommon", "years": "2009", "month": "2017-12", "blocks": "1000-5000", "luck": "8", "limit": 5}).json()Response 200 #
| Field | Type | Description |
|---|---|---|
row | string | null | The row asked for. |
filter | object | The filter as the server understood it. |
filter.years | array of integer | The years asked for (ascending), [] for none. |
filter.month | string | null | The month asked for (YYYY-MM), null for none. |
filter.date | string | null | The day asked for. |
filter.md | string | null | The month-day asked for. |
filter.blocks | object | null | The blocks asked for: {from, to}, heights inclusive (one block: from = to), null for none. |
filter.blocks.from | integer | |
filter.blocks.to | integer | |
filter.luck | object | null | The luck asked for: {min, max} (max null for a minimum alone), null for none. |
filter.luck.min | integer | |
filter.luck.max | integer | null | |
filter.sub | string | null | The sub-category asked for. |
filter.subs | boolean | Whether sub-category items are included (absent on events and counts). |
filter.led | boolean | Whether sales led by another row are included (led=1; sales only). |
events | array of object | Newest first. |
events[].seq | integer | Event sequence number (rising). |
events[].type | string | What happened. One of: listed, cancelled, sold. |
events[].listing_id | string | The listing. |
events[].outpoint | string | The listed UTXO. |
events[].row | string | The listing's own row. |
events[].count | integer | Sats of that row. |
events[].price | integer | The listing price in sats. |
events[].unit_price | number | The listing's unit price. |
events[].seller_address | string | The seller (same as seller). |
events[].txid | string | null | The purchase transaction of a sold event; null otherwise. |
events[].time | integer | Unix seconds. |
events[].seller | string | null | The seller's address. |
events[].buyer | string | null | A sale's buyer: the address the sats went to. null for other events, or when unknown. |
events[].affiliate | string | null | A sale bought here with an applied referral: the affiliate it paid. null otherwise. |
events[].sat | integer | The sat that matched (absent without one). |
events[].match | object | null | The sat that made the item pass a date or luck filter: its number, block, mint day (UTC) and luck. null without such a filter. |
events[].match.sat | integer | The sat. |
events[].match.height | integer | The block that mined it. |
events[].match.date | string | null | Its mint day, YYYY-MM-DD. |
events[].match.luck | integer | null | Its luck (its block's: the leading zero bits of the block hash less the target's); null while the luck table is being read. |
events[].offer_id | string | null | The offer, on an offer event; null otherwise. |
events[].bidder | string | null | The bidder's payment address, on an offer event; null otherwise. |
events[].sub | boolean | Only on an event read for a row (row=) that is not its own row but holds every tracked sat of the item (a sub-category or a label row): true. |
events[].in_bundle | boolean | Only on an event read for a row (row=) whose listing or offer holds some sats of that row among others (in bundle, e.g. a Block 9 chunk under block9_palindrome): true. Its price and unit price are those of its own row. |
events[].contains_count | integer | null | With in_bundle: how many sats of the row asked for the item holds. |
Errors #
{error} (a message, no code):
| Status | When |
|---|---|
| 400 | A malformed parameter (e.g. a date that is no date, date with md). |
| 404 | An unknown row or sub, or the marketplace is off (enabled: false). A retired row (uncommon_2009, rare_2009) answers 404 too, its retired field naming the row and years to ask for instead. |
| 503 | Mint dates or sat luck are still being read (retry: true): try again in a few seconds. Without retry: this server has no sat luck for its chain. |