# The block.space board APIs The ranking APIs behind block.space/rankings, the leaderboard, the largest inscriptions, the heaviest tokens and the collections, and the address and inscription detail endpoints, all in the one envelope. URL: https://blockspace.wiki/data/block-space-api-boards/ block.space ranks by bytes, never by count. The [rankings](https://blockspace.wiki/glossary/rankings/) boards read [the holders appendix](https://blockspace.wiki/glossary/the-appendix/), which keeps per-token and per-address rankings up to date block by block. Their APIs share one response shape, [the one envelope](https://blockspace.wiki/glossary/the-one-envelope/). The general conventions (the `book` and `denom` mode, `null` as [not measured](https://blockspace.wiki/glossary/not-measured/), caching, errors) are on [the block.space API page](/data/block-space-api/). Every example is a real read-only GET made on 2026-10-20 between 09:42 and 09:47 UTC, trimmed. The public form is `https://block.space/api/...`. ## The one envelope Every board answers in the same envelope: | key | meaning | |---|---| | `as_of` | `{appendix, books, ranking}`: the appendix's sync block (the H every board heading states, "[as of block H](https://blockspace.wiki/glossary/as-of-block-h/)"), the books height the bytes are folded to, and the ranking's own height. The largest inscriptions board adds `census` and `labels`. | | `book`, `denom` | the mode | | `family`, `sub` | the family (protocol) and sub-item filters, or `null` | | `population` | how many things the ranking could rank | | `total` | how deep the ranking goes | | `limit`, `offset` | the page | | `source` | which ranking table answered: `appendix`, or `settle` on a fallback | | `rows` | the page of rows | | `extra` | keys particular to one board | The keys from before the envelope stay one release, deprecated on 2026-10-19: on the leaderboard `protocol`, `mode`, `books_height`, `holder_heights` and `coverage`; on the heaviest tokens board `appendix_height`, `mode`, `labelled`, `cutoff`, `all_attributed`, `family_*`, `families` and `subitems`; on the largest inscriptions board `phase`, `by`, `mode` and `cutoff`. Read them from `as_of` and `extra`. ## Endpoints | endpoint | parameters | rows are | |---|---|---| | `/api/rankings` | none | the index: `as_of` and the top three rows of each board, with its page and API paths | | `/api/leaderboard` | `book`, `denom`, `protocol`, `limit` (1 to 500, default 100), `offset` | addresses, ranked by the bytes behind what they hold | | `/api/leaderboard/coverage` | `book`, `denom` | per protocol: total, placed, fraction, addresses, tokens with and without holders, source heights, `measured`, `pending`, `why` | | `/api/address/` | `book`, `denom`, `limit` (default 500, up to 50,000), `offset` | one script's aggregate, per-protocol split, ranks and a page of holdings | | `/api/largest-inscriptions` | `by` (`inscription` or `sat`), `tag`, `book`, `denom`, `limit`, `offset` | inscriptions (or sats) by content bytes | | `/api/largest-inscriptions/` | `book`, `denom`, `limit`, `offset` | one content family's tokens: `xcp_asset`, `src20`, `brc20` or `tap` | | `/api/inscription/` | none | one inscription, every field of its page | | `/api/heaviest-tokens`, `/api/heaviest-tokens/`, `/api/heaviest-tokens//` | `book`, `denom`, `limit`, `offset` | tokens by the blockspace they bought | | `/api/collections`, `/api/collections/` | `book`, `denom`, `limit`, `offset` | NFT collections by the bytes of their members | | `/api/collections/` | none | one collection: members, totals, holders | `tag` on the largest inscriptions board takes `ordinal`, `counter`, `large` or `reinscription`. Each board reads 100,000 rows deep (the collections 10,000). The collections families are `sat`, `xcp_asset`, `atomicals-nft` and `src101_name`. ## /api/rankings `https://block.space/api/rankings`, read 2026-10-20 09:42 UTC. `boards` holds `leaderboard`, `largest`, `heaviest` and `collections`, each `{href, api, rows}`; the first leaderboard row, trimmed: ```json { "as_of": {"appendix": 972199, "books": 972199, "ranking": 972199}, "boards": { "leaderboard": {"href": "/leaderboard", "api": "/api/leaderboard", "rows": [{"rank": 1, "attributed": 5740264617.587256, "address": "bc1phqvgwn7wn5e4s8g0999rtgafd07jpuuy59rkdrk4s5thw9jafkasg8umr8", "tokens": 7, "protocols": ["alkane"]}]}, "collections": {"href": "/collections", "api": "/api/collections", "rows": []} } } ``` At that moment the collections ranking was still being read, so its rows were empty; see the collections section below. ## /api/leaderboard `https://block.space/api/leaderboard?limit=1`, read 2026-10-20 09:42 UTC, trimmed: ```json { "as_of": {"appendix": 972199, "books": 972199, "ranking": 972199}, "book": "a", "denom": "bytes", "family": null, "sub": null, "population": 4491923, "total": 100000, "limit": 1, "offset": 0, "source": "appendix", "rows": [{ "rank": 1, "attributed": 5740264617.587256, "address": "bc1phqvgwn7wn5e4s8g0999rtgafd07jpuuy59rkdrk4s5thw9jafkasg8umr8", "script": "5120b818874f…", "tokens": 7, "protocols": ["alkane"], "content_bytes": 52.232415105030675, "structure_bytes": 5740020513.489695, "overhead_bytes": 244051.86514668466, "a_bytes": 5740264617.587256, "b_bytes": 5740020565.72211, "c_bytes": 52.232415105030675, "composition": [{"family": "alkane", "bytes": 5740264448.57131, "share": 0.9999999705560706}], "share_of_counted": 0.04294663619711373, "share_of_chain": 0.007388930238615785 }], "extra": { "coverage": {"total": 133660401043.77339, "placed": 126421876377.35614, "fraction": 0.945843910313821, "measured": ["sat"], "not_measured": ["omni_property"], "pending": []}, "holder_heights": {"rune": {"adapter_state:runes": 972291}, "…": "…"}, "mode": {"book": "a", "label": "Book A · inclusive · raw bytes (B)"} } } ``` Field notes: - `address` is null for a non-standard script, which carries `script` and `script_hash` instead. - `attributed` is the held figure for the mode. The six partitions are content, structure and overhead, each in bytes and vbytes. - `composition` is the address's backing by family in the colour key's slot order, as shares of its own total. `protocol_order` lists its protocols largest share first. - `share_of_counted` is the held figure over every byte the books attribute under the mode; `share_of_chain` is over the chain's size to block H. - `extra.coverage.fraction` is the part of the books placed with a holder. `extra.holder_heights` names, per protocol, the height of each source the holders were read from. ## /api/address/<addr> `https://block.space/api/address/bc1phqvgwn7wn5e4s8g0999rtgafd07jpuuy59rkdrk4s5thw9jafkasg8umr8?limit=1`, read 2026-10-20 09:47 UTC, trimmed: ```json { "book": "a", "denom": "bytes", "books_height": 972199, "address": "bc1phqvgwn7wn5e4s8g0999rtgafd07jpuuy59rkdrk4s5thw9jafkasg8umr8", "agg": { "tokens": 7, "protocols": ["alkane", "arc20"], "protocol_ranks": {"": 1, "arc20": 98224, "alkane": 1}, "top_tokens": [{"ref": "2:0", "bytes": 5749192076.866, "share": 0.522988676064, "units": 26064398814169, "protocol": "alkane", "token_id": 280565761}] }, "protocols": [{"protocol": "alkane", "structure_bytes": 5740020345.028466, "tokens": 6}], "ranks": [{"book": "a", "denom": "bytes", "protocol": "", "rank": 1}], "holdings_total": 7, "limit": 1, "offset": 0, "holdings": ["…"], "holdings_pending": false } ``` A rank under the protocol `""` is the overall rank. Holdings carry `units` as text, because balances exceed 2^53, plus `units_total`, `holders`, `share` and the six held figures. A `null` held figure means the token was minted after the books height and has no bytes yet. While the list is still resolving, `holdings_pending` is true and `holdings` is null. A cold address can take 2 to 30 seconds to resolve. An address with no holdings in the appendix is a 404. ## /api/largest-inscriptions `https://block.space/api/largest-inscriptions?limit=1`, read 2026-10-20 09:42 UTC, trimmed. The default book here is [Book C](https://blockspace.wiki/glossary/book-c/), the content book: ```json { "as_of": {"appendix": 972199, "books": 972199, "ranking": 972298, "census": 972298, "labels": 972103}, "book": "c", "denom": "bytes", "family": null, "sub": null, "population": 100000, "total": 100000, "limit": 1, "offset": 0, "source": "appendix", "rows": [{ "rank": 1, "height": 873893, "inscription_id": "269730d6cd8c0795317bb8fd043fc7cecb147bb98ae0fed1a1ca9cc646a0c6a2i0", "number": 79351656, "sat": 257704999999999, "content_type": "text/html;charset=utf-8", "body_bytes": 3969429, "kind": "ord", "cursed": false, "size_class": "whole-block", "a_bytes": 3992635.0, "b_bytes": 3992635.0, "c_bytes": 3969429.0, "fee_sats": 49979388, "tx_bytes": 3992785, "tx_vbytes": 998330, "tags": ["ordinal"], "thumb": "/thumb/269730d6…i0.webp", "page": "/inscription/269730d6…i0" }], "extra": {"phase": 1, "by": "inscription", "cutoff": null, "tag": null, "tag_counts": {"ordinal": 99988, "counter": 37, "large": 207, "reinscription": 1824}} } ``` Rows are per [inscription](https://blockspace.wiki/glossary/inscription/): census bytes, the sat's books beside them, and `sat_label`. With `by=sat` they are per sat, with `label` from the appendix (`null` until resolved). A family path such as `https://block.space/api/largest-inscriptions/brc20?limit=1` ranks that family's tokens instead; its first row on the same morning was the brc20 token `sats`, with `c_bytes` 605,311,064 and `extra.by` = `token`. ## /api/inscription/<id> One inscription in the envelope. `rows[0]` carries every field of its page; `extra` carries `rank`, `prev` and `next`. From `https://block.space/api/inscription/269730d6cd8c0795317bb8fd043fc7cecb147bb98ae0fed1a1ca9cc646a0c6a2i0`, read 2026-10-20 09:45 UTC, the nested blocks of the row: ```json { "tx": {"height": 873893, "tx_index": 1, "size": 3992785, "vsize": 998330, "weight": 3993319, "fee_sats": 49979388}, "token": {"token_id": 267470383, "canonical_ref": "257704999999999", "a_bytes": 3992635.0, "b_bytes": 3992635.0, "c_bytes": 3969429.0, "last_height": 873893}, "label": {"number": 79351656, "content_type": "text/html;charset=utf-8", "content_length": 3969429, "as_of": 972103}, "holder": {"address": "bc1pxj0y2yddwd2vccy9tf29czjun97ssmnyxt4n7w0y7ch9w93w5w8sanhtax", "as_of": 971999, "spent": false}, "counter": null } ``` The row also carries an `ord` block read from blockspace.to's ord (number, value, satpoint, timestamp, parents); see [the ord API](/data/ord-api/). ## /api/heaviest-tokens `https://block.space/api/heaviest-tokens?limit=1`, read 2026-10-20 09:42 UTC, trimmed: ```json { "as_of": {"appendix": 972199, "books": 972199, "ranking": 972199}, "book": "a", "denom": "bytes", "family": null, "sub": null, "population": 100000, "total": 100000, "limit": 1, "offset": 0, "source": "appendix", "rows": [{ "rank": 1, "global_rank": 1, "attributed": 23874344903.7015, "token_id": 249191573, "protocol": "rune", "ref": "1:0", "name": "UNCOMMON•GOODS", "label": "Runes", "created_height": 840000, "a_bytes": 23874344903.7015, "b_bytes": 23862302521.241653, "c_bytes": 0, "op_count": 165758746, "op_mint": 165314008, "op_transfer": 443965, "op_burn": 773 }], "extra": { "labelled": true, "cutoff": 63808.0, "all_attributed": 133660401043.77339, "family_attributed": null, "family_share": null, "family_tokens": null, "families": [{"protocol": "sat", "label": "Ordinal Sats", "family": "sat", "attributed": 56124745876.31794, "share": 0.4199055624405709, "tokens": 125512065, "in_slice": 16, "depth": 100000}], "subitems": [] } } ``` On a family tab (`/api/heaviest-tokens/rune`) `extra.family_attributed`, `family_share` and `family_tokens` are filled; for runes on the same morning they were 32,976,967,605.25 bytes, a share of 0.2467, and 216,277 tokens. `extra.labelled` is false for a sub-item whose source has no claim-source bit yet. An unknown family answers 404 with the list of the 21 known ones; an unknown sub-item of `sat` answered 404 with `["inscriptions", "brc20-carrier", "bitmap", "sns", "cat21"]`. ## /api/collections `https://block.space/api/collections?limit=1`. The ranking is read behind the answer. While it is cold, the API returns the envelope with `rows: []`, `"resolving": true` and `"retry_after": 3`, never a bare 503. That is what the first reads at 09:42 UTC got; a retry at 09:46 UTC answered, trimmed: ```json { "as_of": {"appendix": 972199, "books": 972199, "ranking": 972199}, "book": "a", "denom": "bytes", "population": 10000, "total": 10000, "source": "appendix", "rows": [{ "rank": 1, "group_id": -1, "name": "Degents (degent.club)", "protocol": "sat", "family": "Ordinals", "kind": "list", "provenance": "asserted", "members": 4112, "attributed": 1518920128.5, "share": 0.2772655936566113, "bytes_status": "measured", "page": "/collections/-1" }], "resolving": false, "extra": {"unit": "MB", "ranked_by": "attributed", "nft_total": 5478213536.949545} } ``` `provenance` says where a collection's membership comes from: from the chain, from an index, or asserted by a published list, as here. `share` is the collection's bytes over `extra.nft_total`. Sources: - Blockspace Holdings records - block.space JSON API, read-only GETs (every /api/* endpoint) · https://block.space/api/summary - block.space leaderboard API · https://block.space/api/leaderboard - block.space leaderboard coverage API (holders measured per protocol) · https://block.space/api/leaderboard/coverage - block.space docs: rankings · https://block.space/docs/rankings Updated: 2026-10-20