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.

block.space ranks by bytes, never by count. The rankings boards read the holders appendix, which keeps per-token and per-address rankings up to date block by block. Their APIs share one response shape, the one envelope. The general conventions (the book and denom mode, null as not measured, caching, errors) are on the block.space API page.

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"), 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/<addr>`	`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/<family>`	`book`, `denom`, `limit`, `offset`	one content family's tokens: `xcp_asset`, `src20`, `brc20` or `tap`
`/api/inscription/<id>`	none	one inscription, every field of its page
`/api/heaviest-tokens`, `/api/heaviest-tokens/<family>`, `/api/heaviest-tokens/<family>/<sub>`	`book`, `denom`, `limit`, `offset`	tokens by the blockspace they bought
`/api/collections`, `/api/collections/<family>`	`book`, `denom`, `limit`, `offset`	NFT collections by the bytes of their members
`/api/collections/<group_id>`	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:

{
  "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:

{
  "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:

{
  "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, the content book:

{
  "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: 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:

{
  "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.

/api/heaviest-tokens #

https://block.space/api/heaviest-tokens?limit=1, read 2026-10-20 09:42 UTC, trimmed:

{
  "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:

{
  "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.