# The block.space API Every public JSON endpoint under https://block.space/api/: what each one returns, its parameters, the shared conventions, and real responses with their as of. URL: https://blockspace.wiki/data/block-space-api/ block.space is one server. It renders the pages and serves the same numbers as JSON under `/api/*`. The numbers come from [BTI](https://blockspace.wiki/glossary/bti/) and its [holders appendix](https://blockspace.wiki/glossary/the-appendix/). This page covers the chain, book and token endpoints. The ranking boards (leaderboard, largest inscriptions, heaviest tokens, collections, rankings) and the address and inscription detail endpoints are on [the boards page](/data/block-space-api-boards/). Every example below is a real read-only GET made on 2026-10-20 between 09:42 and 09:47 UTC, trimmed to a few fields. The public form of each address is `https://block.space/api/...`. ## Conventions The API follows these rules, and the live responses bear them out: - Every endpoint returns `application/json`, allows cross-origin reads (`Access-Control-Allow-Origin: *`) and is cached for a few seconds to a minute (`Cache-Control: public, max-age=5` on `/api/meter`, 60 on the leaderboard). - Values are exact and unrounded. Formatting is the client's job. - `null` means [not measured](https://blockspace.wiki/glossary/not-measured/). It never means zero. - An unknown endpoint is a 404 whose body lists every endpoint. An unknown family or sub-item on a board is a 404 that lists the known ones. - A database failure is a 503 with `{"error": "database unavailable", "detail": ...}`; a fault in the site itself is a 500 with `{"error": "internal error", ...}`. ### The mode: book and denom Most endpoints take two toggles, the mode: | parameter | values | default | |---|---|---| | `book` | `a`, `b`, `c` ([Book A](https://blockspace.wiki/glossary/book-a/), [Book B](https://blockspace.wiki/glossary/book-b/), [Book C](https://blockspace.wiki/glossary/book-c/)) | `a` (`c` on the largest inscriptions board) | | `denom` | `bytes` (raw bytes), `vbytes` | `bytes` | An invalid value falls back to the default rather than failing. Responses that take a mode carry a `mode` block that names it: ```json "mode": { "book": "a", "book_name": "Book A · inclusive", "book_answers": "how much blockspace was consumed by transactions that touched a token", "denom": "bytes", "denom_name": "raw bytes", "base_unit": "B", "label": "Book A · inclusive · raw bytes (B)" } ``` `limit` and `offset` are clamped to each endpoint's range, not refused. ### The one envelope The ranking APIs answer in [the one envelope](https://blockspace.wiki/glossary/the-one-envelope/): `as_of` {`appendix`, `books`, `ranking`}, `book`, `denom`, `family`, `sub`, `population`, `total`, `limit`, `offset`, `source`, `rows`, and board-specific keys under `extra`. It is set out with examples on [the boards page](/data/block-space-api-boards/). Keys from before the envelope stay one release, marked deprecated since 2026-10-19; read the new names. ## Endpoint list | endpoint | parameters | returns | |---|---|---| | `/api/summary` | none | chain bytes walked, attributed totals per book, token and operation counts, coverage classes, the frontier and a units note | | `/api/frontier` | none | every BTI cursor row, the indexed window, the active sources and the chain tip | | `/api/meter` | none | the heights each stage has reached, with times and the chain tip | | `/api/tiers`, `/api/t2`, `/api/t3` | none | the three tiers' heights, T2's per-adapter cursors, T3's books and per-protocol roll-up | | `/api/coverage` | none | per-protocol book coverage, claim rows by coverage class, envelope-extractor findings, carrier and unexplained bytes | | `/api/envelopes` | none | the envelope-extractor findings alone | | `/api/protocols` | `book`, `denom` | per-protocol roll-up for the mode, with `book_measured` per row and the per-source split | | `/api/tokens` | `book`, `denom`, `sort`, `protocol`, `q`, `limit` (1 to 500, default 50), `offset` | ranked tokens; `attributed` is the figure for the mode, and every book is returned per row | | `/api/token//` | none | one token: all three books, fees, supply, claim and attempt counts, protocol coverage | | `/api/block/` | `tx` (offset), `limit` (1 to 500) | one block: its ledger row, attributed bytes, per-protocol bytes, top tokens, byte kinds and a page of transactions | | `/api/tx//` | none | one transaction with its book entries | | `/api/growth` | `bucket` (500 to 5,000, default 1,000) | per-bucket and cumulative chain bytes, vbytes, Book A and Book C, plus the landmarks | | `/api/landmarks` | none | named heights with descriptions and whether the walker has reached them | | `/api/t1`, `/api/t1/series`, `/api/t1/blocks`, `/api/t1/block/`, `/api/t1/tx//`, `/api/t1/residue`, `/api/t1/lookup?q=` | `bucket`; `from`, `limit`; `tx`, `limit`; `limit`, `offset`; `q` | the [byte census](https://blockspace.wiki/glossary/the-census/) (T1): coverage, bucket totals, block and transaction views, the residue, and a lookup of a height, block hash or txid | | `/api/projects` | none | the project list shown at block.space/projects, in the one envelope | | `/api/cache` | none | the age in seconds of each cached aggregate | | `/healthz` | none | liveness, the derive and walker heights, and the chain tip | `sort` takes `attributed` (the default), `ops`, `created`, `supply`, `content`, `fees` or `name`. The board endpoints are listed on [the boards page](/data/block-space-api-boards/). `/api/largest` answers with a permanent redirect to `/api/largest-inscriptions`. ## Examples ### /api/meter How far each stage has got. `counted` is the census, `catalogued` the claims, `books_written` the books. Read 2026-10-20 09:42 UTC (`https://block.space/api/meter`): ```json { "counted": 972301, "catalogued": 972301, "books_raw": 972299, "books_written": 972299, "counted_at": "2026-10-20T09:22:42Z", "catalogued_at": "2026-10-20T09:35:17Z", "books_at": "2026-10-20T09:30:48Z", "tokens_through": 972199, "books_hash": {"win_lo": 972200, "win_hi": 972299, "rows": 473449, "hash": "319bcb87…"}, "chain_tip": {"height": 972303, "source": "bitcoind"} } ``` ### /api/summary Read 2026-10-20 09:42 UTC (`https://block.space/api/summary`), trimmed: ```json { "ledger": {"blocks_walked": 972302, "max_height": 972301, "chain_bytes": 777036635205, "chain_vbytes": 567699528020, "chain_fees": 30078456613267, "chain_txs": 1464145200}, "books": { "a": {"bytes": 133751488039.71294, "protocols": 21, "measured_protocols": 21, "complete": true}, "b": {"bytes": 126977437621.66104, "protocols": 21, "measured_protocols": 21, "complete": true}, "c": {"bytes": 36378763001.0, "protocols": 21, "measured_protocols": 21, "complete": true} }, "tokens": 126866878, "ops": 623207877, "coverage_classes": [{"coverage": "ABC", "tokens": 126866878}], "frontier": {"cursors": [{"name": "census", "height": 972301, "updated_at": "2026-10-20T09:22:42Z"}, "…"]} } ``` The wiki's own figures read from the same API; on its latest reading (as of block 972,299, 2026-10-20 09:30:48 UTC) Book A held 133.75 GB at block 972299. ### /api/frontier The same cursor list as `summary.frontier`: one row per cursor (`census`, `claims`, `attributions`, `aggs:folded`, and one `claims:` row per T2 unit), each with `height` and `updated_at`. See [the frontier](/concepts/the-frontier/) for what the cursors mean. ### /api/protocols Read 2026-10-20 09:45 UTC (`https://block.space/api/protocols`), the first row and one entry of `sources`: ```json { "book": "a", "denom": "bytes", "rows": [ {"protocol": "sat", "books": "ABC", "note": null, "book_measured": true, "tokens": 125512065, "attributed": 56124745876.31794, "attributed_vb": 21498797593.27078, "a_bytes": 56124745876.31794, "c_bytes": 33433631755.9125, "fees": 604022087850.3802, "ops": 129007141, "first_height": 767430, "last_height": 972199} ], "sources": { "alkane": { "alkanes": {"protocol": "alkane", "source": "alkanes", "attributed": 11943112257.933353, "tokens": 103972, "entries": 107312782, "fees": 6119789975.588749} } } } ``` `sources` splits a protocol's bytes by the T2 source that claimed them; `family` and `source_names` ride along for the client's table. ### /api/tokens and /api/token/<protocol>/<ref> `https://block.space/api/tokens?limit=1`, read 2026-10-20 09:45 UTC: ```json { "book": "a", "denom": "bytes", "sort": "attributed", "protocol": null, "q": null, "limit": 1, "offset": 0, "total": 126866878, "rows": [ {"rn": 1, "token_id": 249191573, "protocol": "rune", "ref": "1:0", "name": "UNCOMMON•GOODS", "created_height": 840000, "burned_height": null, "attributed": 23874344903.7015, "a_bytes": 23874344903.7015, "b_bytes": 23862302521.241653, "c_bytes": 0, "op_count": 165758746, "last_height": 972199, "current_supply": 165289796, "coverage": "ABC", "op_mint": 165314008, "op_transfer": 443965, "op_inscribe": 0, "op_burn": 773, "op_other": 0} ] } ``` The same token by reference, `https://block.space/api/token/rune/1:0`, adds `protocol_books`, `protocol_note`, `claims` (165,758,746) and `attempts` (0). ### /api/block/<height> `https://block.space/api/block/972000?limit=1`, read 2026-10-20 09:43 UTC, trimmed: ```json { "height": 972000, "ledger": {"n_tx": 4533, "total_bytes": 1852602, "total_vbytes": 1000727, "total_weight": 3992658, "total_fees": 997259, "block_hash": "00000000000000000001f09a…"}, "attributed": {"claimed_bytes": 1195767.875, "carriage_bytes": 66148.5, "burned_bytes": 0, "unclaimed_bytes": 598941.0, "content_bytes": 400142.0}, "protocols": [{"protocol": "sat", "a_bytes": 424517.6041666667, "c_bytes": 397253.5}, "…"], "kinds": {"base_bytes": 713352, "wit_bytes": 1139250, "signatures": 488524, "data_payload": 474729, "unexplained": 399}, "written_to": 972299, "counted_to": 972301, "transactions": {"total": 4533, "rows": ["…"]} } ``` A block the census has not reached is a 404 with `{"error": "not counted yet", "counted_to": ...}`. ### /api/growth `https://block.space/api/growth?bucket=5000`, read 2026-10-20 09:43 UTC, the first bucket: ```json { "bucket": 5000, "frontier_height": 972299, "clipped_to": 972299, "last_bucket_partial": true, "series": [{"h": 0, "chain_bytes": 715886, "chain_vbytes": 715886, "a_bytes": 0, "c_bytes": 0, "txs": 5063, "blocks": 5000, "t0": 1231006505, "t1": 1235134923, "cum_chain_bytes": 715886, "cum_a_bytes": 0}], "landmarks": [{"name": "genesis", "height": 0, "descr": "Bitcoin genesis block"}] } ``` ### Endpoints that did not answer in the example window On 2026-10-20 at 09:43 UTC `/api/coverage` returned the 503 `database unavailable` body (a statement timeout), and `/api/envelopes` returned `{"error": "aggregation unavailable"}`. Both are heavy aggregates and are documented as normal endpoints. ## The Minute API, under block.space/minute `https://block.space/minute/api/` forwards to the Minute API, a separate package with its own OpenAPI spec (`/minute/api/openapi.json`) and `llms.txt` (`/minute/api/llms.txt`). It is a mint flow (`POST /v1/mint/plan`, `/v1/mint/commit-psbt`, `/v1/mint/finalize`, `/v1/mint/broadcast`), not a data API. Its documentation says mainnet is off until roadmap gate G1 passes unless the operator explicitly allows it; the live `/v1/fees` answer below reports `mainnet`. Its one plain read is `GET /v1/fees`, read 2026-10-20 09:46 UTC: ```json {"network": "mainnet", "chain": "main", "source": "estimatesmartfee", "as_of": 1792489580, "sat_vb": {"fast": 1.01, "medium": 1.01, "slow": 1.01}, "mempool_min_sat_vb": 0.0} ``` Sources: - Blockspace Holdings records - block.space JSON API, read-only GETs (every /api/* endpoint) · https://block.space/api/summary - block.space meter and summary APIs · https://block.space/api/summary - block.space frontier API (the three tier cursors and the chain tip) · https://block.space/api/frontier - block.space protocols API · https://block.space/api/protocols Live figures: books as of block 972,299, 2026-10-20 09:30:48 UTC Updated: 2026-10-20