blockspace.wiki

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.

block.space is one server. It renders the pages and serves the same numbers as JSON under /api/*. The numbers come from BTI and its holders 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.

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. 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, Book B, 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:

"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: 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. 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/<protocol>/<ref> none one token: all three books, fees, supply, claim and attempt counts, protocol coverage
/api/block/<height> 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/<height>/<index> 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/<height>, /api/t1/tx/<height>/<index>, /api/t1/residue, /api/t1/lookup?q= bucket; from, limit; tx, limit; limit, offset; q the byte 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. /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):

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

{
  "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:<adapter> row per T2 unit), each with height and updated_at. See 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:

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

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

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

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

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

  1. block.space JSON API, read-only GETs (every /api/* endpoint) · block.space/api/summary
  2. block.space meter and summary APIs · block.space/api/summary
  3. block.space frontier API (the three tier cursors and the chain tip) · block.space/api/frontier
  4. block.space protocols API · block.space/api/protocols
  5. Blockspace Holdings records

Live figures: books as of block 972,299, 2026-10-20 09:30:48 UTC. Refreshed hourly.

Updated 2026-10-20 · This page as Markdown