Concepts

Rows (collections) #

The index tracks rare sats in rows: uncommon, rare, black, alpha_uncommon, block9, 450x, vintage_alpha, pizza_palindrome and many more. A row is a kind of sat; on the site a market row is a collection (/collection/<row>). GET /api/supply lists every row's definition (id, label, all_of types, total, and market).

• A listing's own row (row) is the rarest market row holding every tracked sat of the UTXO (a "pure" row). When no row holds them all, it is the rarest market row present. This is how sales are placed too, so rows don't overlap: a plain uncommon is uncommon, a 2012 uncommon is alpha_uncommon, a block 9 chunk is block9, a 450x chunk is 450x.
• The primary-sat rule (sales). A sale that no single row holds whole (a bundle) is placed under its primary row: the rarest market row it sold sats of, and on a tie in rarity a first-sat row (the uncommon side: uncommon, rare, epic, alpha_uncommon, …) before a last-sat row (the black side: black, black_rare, black_omega, …). So the classic pair, the last sat of one bitcoin and the first of the next, is an alpha_uncommon sale, and its black omega is a secondary row: every sale names its secondary rows (secondary: {"black_omega": 1}), and a secondary row's markets, medians and volumes never count it, so nothing is counted twice. GET /api/sales?row=black_omega&led=1 lists those sales as context.
• A label row (market: false, e.g. block9_1st_tx) is never a listing's own row. Filtering listings by a label row lists everything lying in it.
• A rarer sub-category of a row is a row whose sats it also holds whole (an alpha_uncommon is also an uncommon). GET /api/market/listings?row=uncommon&sub=1 adds them. The milestone alphas, the first sat of a thousand, ten thousand, a hundred thousand or a million bitcoin (kilosat_alpha, decasat_alpha, centasat_alpha, megasat_alpha), are shown as Kilosat, Decasat, Centasat and Megasat uncommon, Uncommon's rarest sub-categories (sub_of in the GET /api/supply rows). All but 20 of them (in blocks after height 2,100,000) are the first sat of a block, but the 79 of them that are rare, epic or mythic are not also uncommon: they are never listed or counted under uncommon. Likewise the milestone omegas, the last sat of a thousand bitcoin and so on (kilosat_omega, decasat_omega, centasat_omega, megasat_omega), are shown as Kilosat, Decasat, Centasat and Megasat black, Black's rarest sub-categories: all but 20 are the last sat of a block, but the 78 that are black rare or black epic (the last sat before a difficulty adjustment or a halving) are never listed or counted under black. The pair rule treats them as black sats: a Kilosat black sold or listed with a Kilosat uncommon (or any alpha uncommon) is the uncommon's, with the Kilosat black as its secondary row, though Megasat black (20 sats) is rarer than Megasat uncommon (21).
• rows on a listing gives every row the UTXO's sats count toward, label rows included; types groups its sats by exact type combination.

Price, unit price and bulk #

• price is the listing price in sats: exactly what the seller receives (the seller's payment output). Sellers pay no fee.
• value is the UTXO's own value. It moves to the buyer whole.
• count is how many sats of the listing's own row the UTXO holds. A UTXO of 100 black sats is one listing with count: 100 ("×100").
• unit_price = (price − value) / count, to the hundredth of a sat: the premium per sat of the row, over the UTXO's own value. It is the same measure as the sales' unit prices, so listings and sales compare directly.

Example: a block 9 chunk of 6,280 sats in a 6,280-sat UTXO listed at 94,200 sats has unit_price = (94,200 − 6,280) / 6,280 = 14 sats per sat.

A row's floor is the lowest unit_price among its active listings (floors).

A listing is in bundle under a row when it holds some of that row's sats but not all of its tracked sats: a 330-sat Block 9 chunk holding one Block 9 palindrome is a block9 listing, in bundle under block9_palindrome and nakamoto_palindrome; the omega of an alpha+omega pair is in bundle under the omega's row. It shows on those rows' pages ("Also contains", contains=1), and its events and offers in their activity, marked in_bundle, but it is priced only in its own row: it never sets their floor, unit price or statistics (floors count it apart, as contains).

What can be listed #

A UTXO can be listed when all of these hold:

• it is confirmed and unspent (mempool included);
• it holds at least one tracked rare sat of a market row;
• it carries no inscription and no runes (rare sats only);
• it belongs to the seller address, which is Taproot (bc1p…), native SegWit (bc1q…) or nested SegWit (3…, P2SH-P2WPKH). Legacy 1… addresses are not supported;
• its price is a whole number of sats, above its own value, at least 546 and at least the dust limit of the payout address.

The platform fee #

• The buyer pays a platform fee of 2.5% of the summed listing prices, on top of them, with a minimum of 546 sats: fee = max(ceil(Σ price × 250 / 10000), 546).
• It is one output per purchase to the fee address in GET /api/market/config (fee_address), currently bc1qycdj49gt04zvc07xyzzgsvgglc7qyhz8r3sfs6.
• A purchase referred by an affiliate (any address but the fee address, no registration; not the buyer's own wallet) splits that fee 50/50 between the fee address and the affiliate, as a second output in the same transaction (both at least 546 sats); the buyer pays the same. See Affiliates.
• Every purchase also carries exactly one OP_RETURN marker, value 0: OP_RETURN <push "raresats.net">, script 6a0c72617265736174732e6e6574. It is not a runestone and relays on default node policies.
• The buyer also pays the network fee, at a rate they choose (at least minimum from GET /api/market/fees).

The transaction layout #

Listings and purchases use Magisat's standard on-chain layout, signed SIGHASH_SINGLE|ANYONECANPAY by the seller.

Listing PSBT (the seller signs): version 2, locktime 0. Input i is listed UTXO i (sequence 0xfffffffd, sighashType 0x83); output i pays its price to the payout address. A seller's 0x83 signature commits to its own input and to the output at the same index, and nothing else, so a buyer can add their inputs and outputs around it.

Purchase of k listings (the buyer signs their inputs; the server adds the sellers' signatures):

The padding is what makes the sats land right: sats flow first-in first-out, so output 0 takes exactly the padding sats and each listed UTXO's sats land at offset 0 of their own output. When the payment address lacks k+1 padding UTXOs plus funding, prepare adds a setup transaction that makes them first (no fee, no marker); the purchase spends its outputs. See Buy listings.

The buyer pays only with plain cardinal UTXOs of the payment address: confirmed, unspent, no inscription or rune, nothing the index tracks, and no sat of a collectible range. A buyer's rare sats are never spent as padding or funding.

Listing statuses #

Every live listing is rechecked against the chain on every new block and every minute; as_of on list answers says when.

Signature custody. The sellers' signatures stay on the server; no response ever contains them, and purchase PSBTs carry none until submit. A cancelled, replaced, sold or moved listing's signature is deleted. Once a purchase is broadcast, though, its signatures are on the network (true of every SIGHASH_SINGLE|ANYONECANPAY marketplace): the listing then says signature_public: true, and only moving the UTXO makes a cancel certain. See Cancel listings.