Supply, rows and status

The dashboard's own feeds: what its Statistics, Transfers and Extractions views show. Briefly documented; their shapes follow the rare-sat index and may grow.

Supply #

GET/api/supply

The latest supply of every row (supply: {height, hash, time, rows}, each row with total, stats and active_non_extracted), the row definitions (rows) and their groups (groups). A row the site shows as a sub-category of another although its types do not say so names that row in sub_of: the milestone alphas (kilosat_alpha, decasat_alpha, centasat_alpha, megasat_alpha), labelled Kilosat, Decasat, Centasat and Megasat uncommon, are sub-categories of uncommon, and the milestone omegas (kilosat_omega, decasat_omega, centasat_omega, megasat_omega), labelled Kilosat, Decasat, Centasat and Megasat black, of black. With years, every row's supply over the sats mined in those years (rows with none have zeros), and years echoed; with luck, over the sats mined in blocks of those lucks, and luck echoed ({min, max}, max null for "or more"); with month, over the sats mined in that month, and month echoed.

Query parameters #

Example request #

curl 'https://raresats.net/api/supply?years=2009,2010&luck=10&month=2017-12'

const response = await fetch('https://raresats.net/api/supply?years=2009,2010&luck=10&month=2017-12');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/supply", params={"years": "2009,2010", "luck": "10", "month": "2017-12"}).json()

Response 200 #

A JSON object.

Errors #

{error} (a message, no code):

By mint year #

Every number of the supply can be narrowed to the sats mined in some years: ?years=2009 on /api/supply and /api/rows/{id}, or several years (?years=2009,2010). The counters of a set of years add up, but for the holders, which count each address once however many of the years it holds sats of. ?years=2009 gives the same numbers the 2009 rows did: uncommon_2009 and rare_2009 are retired, and /api/rows/uncommon?years=2009 is what /api/rows/uncommon_2009 was (the latter now answers 404 with a retired field naming the row and years to ask for, as does every route taking row=; /collection/uncommon_2009 redirects to /collection/uncommon?year=2009). Every year's numbers at once:

GET/api/supply/years

Every row's supply split by the year its sats were mined: {height, hash, time, years: [{year, from_height, to_height}], rows: [{id, years: {"2009": {total, stats, active_non_extracted}}}]}, a row listing only the years it has sats of. What the year chips count; cached per block. Needs a rare-sat index with a year breakdown (fork.status.year_stats in /api/status), else 501.

Example request #

curl 'https://raresats.net/api/supply/years'

const response = await fetch('https://raresats.net/api/supply/years');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/supply/years").json()

Response 200 #

A JSON object.

Errors #

{error} (a message, no code):

By block luck #

The same numbers can be narrowed to the sats mined in lucky blocks instead: ?luck=10 (blocks of luck 10 or more) or ?luck=10-12 on /api/supply and /api/rows/{id}. A block's luck is the leading zero bits of its hash beyond its target's: most blocks are luck 0 to 3, about one in eight hundred is 10 or more. The holders count each address once, as for years; a luck lists no top holders. Years and a luck do not combine in the supply (a 400): the index breaks it down by one or the other. Every luck's numbers at once, with the blocks of each luck:

GET/api/supply/lucks

Every row's supply split by the luck of the blocks its sats were mined in: {height, hash, time, lucks: [{luck, blocks}], rows: [{id, lucks: {"12": {total, stats, active_non_extracted}}}]}, a row listing only the lucks it has sats of (lucks: the blocks of each luck). What the luck selects count; cached per block. Needs a rare-sat index with a luck breakdown (fork.status.luck_stats in /api/status), else 501.

Example request #

curl 'https://raresats.net/api/supply/lucks'

const response = await fetch('https://raresats.net/api/supply/lucks');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/supply/lucks").json()

Response 200 #

A JSON object.

Errors #

{error} (a message, no code):

By mint month #

Or to the sats mined in one month (UTC): ?month=2017-12 on /api/supply and /api/rows/{id}. A month is one at a time, with its own holders (exact) and top holders; it does not combine with years or a luck (a 400). A month is counted as its year is, by the running latest block time, so a year's months add up to it; five blocks of mainnet (272,376 to 272,380) whose own time is 30 November 2013 count in December 2013, where the chain's time already was. Every month's numbers at once, compactly (an array of counters per month, in the order fields names them):

GET/api/supply/months

Every row's supply split by the month (UTC) its sats were mined in, compactly: {height, hash, time, months: [{month, from_height, to_height}], fields: ["mined", "located", "burned", "lost", "overwritten", "extracted", "holders", "extracted_holders", "inscribed"], rows: [{id, months: {"2017-12": [counts in the order of fields]}}]}, a row listing only the months it has sats of. What a collection's month select counts; cached per block. Needs a rare-sat index with a month breakdown (fork.status.month_stats in /api/status), else 501.

Example request #

curl 'https://raresats.net/api/supply/months'

const response = await fetch('https://raresats.net/api/supply/months');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/supply/months").json()

Response 200 #

A JSON object.

Errors #

{error} (a message, no code):

The sales beside these numbers (the Statistics' Last, 30-day median and volume, and a row's sales chart) follow the same filter: /api/sales/stats?years=2009 and /api/sales?row=alpha_uncommon&years=2009 count only the sales of the row's sats mined in 2009, the very sales the collection's Activity lists with ?year=2009 (see Sales stats). So does a month (?month=2017-12), on any index: the sales are matched on this side, by each block's own day.

Sat type explainers #

The text of the site's /types pages: what each sat type, category and concept is, with its categories' live numbers.

GET/api/types

Every explainer page of /types (one per sat type, category and concept), by section: sections ([{id, label, pages: [{slug, title, summary, href}]}]), and which page explains each row (rows: {rowId: slug}) and each sat type (badges: {type: slug}). The text comes from the site's own pages; the page is /types/{slug}.

Example request #

curl 'https://raresats.net/api/types'

const response = await fetch('https://raresats.net/api/types');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/types").json()

Response 200 #

A JSON object.

{
  "sections": [
    {
      "id": "rarity",
      "label": "Rarity tiers",
      "pages": [
        {
          "slug": "uncommon",
          "title": "Uncommon",
          "summary": "The first sat of a block: the lowest rarity tier above common in ordinal theory, one per block bar the few whose first sat ranks higher.",
          "href": "/types/uncommon"
        }
      ]
    }
  ],
  "rows": {"uncommon": "uncommon"},
  "badges": {"uncommon": "uncommon"}
}

Errors #

None of its own.

GET/api/types/{slug}

One explainer: slug, title, summary, kind and kind_label (its section), badges (the sat types it explains), body (its text as a tree of blocks: {t: 'h3'|'h4', id, c}, {t: 'p', c}, {t: 'ul'|'ol', items: [c]}, where c lists inlines: a string, {t: 'a', href, c, ext?}, {t: 'b'|'i', c}, {t: 'code', text} or {t: 'n', row, field}, a live number found in numbers[row][field]), rows (the categories it explains, each with total, mined, extracted, holders, inscribed and market: last_unit_price, median_30d, sales, and while the marketplace is on floor_unit and listed), also_in (other categories holding its types), related pages and as_of (the block the numbers are of).

Path parameters #

Example request #

curl 'https://raresats.net/api/types/uncommon'

const response = await fetch('https://raresats.net/api/types/uncommon');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/types/uncommon").json()

Response 200 #

A JSON object.

Errors #

{error} (a message, no code):

A row #

GET/api/rows/{id}

One row: row (its supply stats, extracted and non-extracted top holders, label, group and definition) and history (extracted and located counts over time). With years, over the sats mined in those years (years echoed): one year lists its own top holders (at most 100 per list), a set of years none (null), and the history's holder counts are null for a set. With luck, over the sats mined in blocks of those lucks (luck echoed): no top holders (null), and the history's holder counts are null but for a single luck or every luck. With month, over the sats mined in that month (month echoed): its own top holders (at most 100 per list) and holder counts in its history.

Path parameters #

Query parameters #

Example request #

curl 'https://raresats.net/api/rows/uncommon?years=2009&luck=10&month=2017-12'

const response = await fetch('https://raresats.net/api/rows/uncommon?years=2009&luck=10&month=2017-12');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/rows/uncommon", params={"years": "2009", "luck": "10", "month": "2017-12"}).json()

Response 200 #

A JSON object.

Errors #

{error} (a message, no code):

Notable transfers #

The first page of both feeds (no before, offset 0) also has pending: the notable events of transactions still in the mempool, judged by the same rules as if mined in the next block, outside total (Pending).

GET/api/transfers

Notable transfers of rare sats, newest first: {total, offset, items}. Page with before (an event id) or offset. The first page (no before, offset 0) also has pending: the notable transfers of transactions still in the mempool, newest first, outside total.

Query parameters #

Example request #

curl 'https://raresats.net/api/transfers'

const response = await fetch('https://raresats.net/api/transfers');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/transfers").json()

Response 200 #

A JSON object.

Errors #

{error} (a message, no code):

Notable extractions #

GET/api/extractions

Notable extractions (rare sats newly isolated), newest first, paged like transfers. The first page also has pending, as transfers.

Query parameters #

Example request #

curl 'https://raresats.net/api/extractions'

const response = await fetch('https://raresats.net/api/extractions');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/extractions").json()

Response 200 #

A JSON object.

Errors #

{error} (a message, no code):

Pending (the mempool) #

GET/api/pending

Every pending sale, notable transfer and extraction of transactions still in the mempool, the live listings being spent, and the transactions that left the mempool lately, from the index's mempool overlay (polled every 5 s). Pending items are marked pending: true with first_seen and fee_rate, and count in no stat. A pending sale is txid:vin, a move its txid: the confirmed record with the same key replaces it. The SSE mempool event says when to read it again. available is false against an index without the overlay.

Example request #

curl 'https://raresats.net/api/pending'

const response = await fetch('https://raresats.net/api/pending');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/pending").json()

Response 200 #

Errors #

None of its own.

The index watches the mempool (its overlay, polled every 5 s and right after each block): a transaction still waiting there that moves tracked sats is shown wherever confirmed activity is, marked pending: true with first_seen (unix seconds) and fee_rate (sat/vB). The site shows it with a Pending chip.

• Identity. A pending sale is txid:vin (its key), a pending transfer or extraction its txid (id: pending:<kind>:<txid>). When the transaction confirms, the confirmed record with the same key replaces the pending one at once; nothing is listed twice.
• Leaving. removed names the transactions that left the mempool: confirmed (now in a block), replaced (RBF; replaced_by), conflicted (a block spent an input otherwise) or evicted. Their pending items are gone from the lists.
• Never counted. Pending sales are in no stat, median, volume, floor, leaderboard or supply until they confirm.
• Where else. pending in Sales and the market overview; the first page of /api/transfers and /api/extractions; the first page of Address activity; spent_by_pending and pending_outputs on Address; pending on Sat; spent_in and pending on UTXO; spent_by_pending on the listing of a sat or UTXO page.
• Live. The SSE stream sends mempool whenever what is pending changes: an invalidation, {version, keys: {sales, transfers, extractions, rows, addresses, outpoints}, counts}, naming what changed (the rows, addresses and outpoints of the transactions added, removed or changed), never the items. Read this route, or the answer you show, again when a key you care about is set.
• Against an index without the mempool overlay, available is false and every list is empty.

Everything at once #

GET/api/state

Everything the site shows at once: thresholds, limits, fork, feed, rows, groups, supply, sales, and the newest transfers and extractions. pending is everything pending in the mempool (/api/pending).

Query parameters #

Example request #

curl 'https://raresats.net/api/state'

const response = await fetch('https://raresats.net/api/state');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/state").json()

Response 200 #

A JSON object.

Errors #

{error} (a message, no code):

Live events #

Every change the site shows (blocks, sales, listings, offers, floors, activity, prices, chat) comes down one Server-Sent Events stream: see Live events.

Status #

GET/api/status

The rare-sat index's reachability, mode and progress (fork) and the dashboard's tip (feed).

Example request #

curl 'https://raresats.net/api/status'

const response = await fetch('https://raresats.net/api/status');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/status").json()

Response 200 #

A JSON object.

Errors #

None of its own.

Health #

GET/healthz

{ok, fork, mode, height, tip}: fork is up, stale or down.

Example request #

curl 'https://raresats.net/healthz'

const response = await fetch('https://raresats.net/healthz');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/healthz").json()

Response 200 #

{"ok": true, "fork": "up", "mode": "live", "height": 969001, "tip": 969001}

Errors #

None of its own.