Filtering & birthday sats

Every sat was mined in a block, and every block on a UTC day: its mint day. Every block also has a luck, and so every sat in it. Sales and listings can be filtered by the mint days and the luck of the sats they hold, and by the row (collection) and rarer sub-category those sats belong to.

The filters #

All optional, combined with AND:

• row: the collection, e.g. uncommon, block9, black_rare. Without it, every row (the facets then count by row).
• sub: one rarer sub-category of row, e.g. sub=pizza_uncommon under row=uncommon, or sub=450x under row=block9. Only items holding sats of it. Sub-category items count under their own rows, so sub implies subs=1.
• subs=1: include the row's sub-category items (an alpha uncommon is its own row, alpha_uncommon, and only shows under uncommon with subs=1).
• years=2009,2010: items holding a sat mined in one of those years.
• month=2017-12: items holding a sat mined in that month (UTC, by its block's own time).
• blocks=1000-5000: items holding a sat mined in blocks 1,000 to 5,000 (heights, inclusive); blocks=9: in block 9 alone. Up to the tip: a range past it, reversed (5000-1000) or malformed is a 400.
• date=2009-01-09: items holding a sat mined that day (UTC).
• md=01-03: items holding a sat mined on that month-day of any year: birthday sats. Add years to narrow. date and md are exclusive.
• luck=8: items holding a sat of luck 8 or more; luck=8-12: of luck 8 to 12. Any row: luck is a sat's, whatever its type.

An item passes when one of its sats passes them all. That sat is given back as match: {sat, height, date, luck}.

Sat luck #

A sat's luck is its block's: how many more leading zero bits the block's hash has than the block's difficulty target (from the header's bits) required. A block whose hash only just met its target has luck 0; each step up is about half as common: of the first 969,647 blocks (to October 2026), 697,563 have luck 1 or more, 5,400 luck 8 or more, and 10 luck 17 or more (the luckiest, 756,951, has 21). Every sat of a block shares its luck, and it never changes once the block is buried. The sat and UTXO pages show it, and listings name their lead sat's (lead.luck).

Examples #

Uncommon sats of luck 10 or more for sale now:

curl 'https://raresats.net/api/listings/query?row=uncommon&luck=10'

Uncommon sats mined in 2009, sold anywhere, newest first:

curl 'https://raresats.net/api/sales/query?row=uncommon&years=2009&limit=20'

The next page: pass the answer's next as before:

curl 'https://raresats.net/api/sales/query?row=uncommon&years=2009&limit=20&before=4412'

Uncommon sats mined in blocks 1,000 to 5,000 for sale now:

curl 'https://raresats.net/api/listings/query?row=uncommon&blocks=1000-5000'

Sats mined on your birthday (any year) for sale now, cheapest per sat first:

curl 'https://raresats.net/api/listings/query?md=07-14&sort=unit'

Pizza uncommons for sale:

curl 'https://raresats.net/api/listings/query?row=uncommon&sub=pizza_uncommon'

What was mined on 9 January 2009 that the index tracks, and where it is:

curl 'https://raresats.net/api/birthday/counts?date=2009-01-09'

Facets #

Sales and listings answers carry facets, counts to refine with:

• years: matching items per mint year;
• luck: per minimum N, the items holding a sat of luck N or more (what luck=N would match);
• subs: the row's sub-categories with their matching counts ([] without a row);
• rows: without a row, matching items per row.

{
  "years": { "2009": 17, "2010": 21, "2011": 16 },
  "subs": [{ "row": "alpha_uncommon", "count": 154 }, { "row": "vintage_uncommon", "count": 3 }]
}

Notes #

• Dates are UTC and come from block timestamps. A few blocks' timestamps are earlier than their parent's; the table files each such block under the day its time says (exceptions in /api/days).
• Right after a restart the server reads the mint-day and luck tables for a few seconds; date and luck filters then answer 503 {"error": …, "retry": true}. Retry shortly.
• Errors are {error}: 400 for a malformed filter, 404 for an unknown row or sub (and on the listing routes while the marketplace is off: {"enabled": false}).
• Caching: sales queries, counts and the day table may be reused 30 s; listing queries are never cached.