The Bitblocks API

JSON over HTTP, from https://bitblocks.app/api/v1. This page covers how to call it and the endpoints to start with. The linked examples open in a signed-in browser; signed out, they answer 401.

Who can call what

Caller	Reaches	Requests a minute	State
Anyone	`/status`, `/price/bsv`, `/support` and the Bitcom registry exports	30, per IP	Works today, no account needed
Signed in with GitHub	The whole API, from the browser you signed in with	600, per user	Works today, signed in
A key	The whole API, from your own server	The key's own budget	Works today, signed in

Sign in, and you can get a trial key for yourself. A key goes in the header, as Authorization: Bearer bbk_... or x-api-key: bbk_....

Pricing covers what comes after the free tier.

Block and transaction pages are open to anyone, so a link you share simply works. The JSON behind them is the API, and needs a session or a key.

Reading a response

Most answers carry the result in data. A list adds meta, and you page by passing next_cursor back as ?cursor=.

A page of transactions, abridged

{
  "data": [ ... ],
  "meta": { "next_cursor": "...", "per_page": 50, "complete": false }
}

meta.complete is false while any block in a listing's range is still syncing, so an empty page isn't always the end of the story.

Without a session or key: 401

{
  "error": "Sign in at /sign-in, or send an API key as Authorization: Bearer <key>"
}

Too many requests in a minute gets a 429 with a Retry-After header, and an unknown or revoked key gets a 401. A transaction we don't hold gets a 404, which can simply mean the sync hasn't reached its block yet.

Answers that say how sure they are

An output is known to be unspent only once the index reaches the tip, so address and script answers carry a status: exact, partial or unknown. While the sync climbs, expect the last two, and treat unknown as unknown.

Address history reads our index through the last complete block and WhatsOnChain above it, so the newest payments show up soon after they confirm. Each row names its source, and meta.sources says which heights each one covers.

If you need a whole-chain balance today, WhatsOnChain's API is the place to look.

Blocks and transactions

The records themselves.

GET /api/v1/status open: Health, and how far the index reaches.
GET /api/v1/blocks/latest: The newest block held.
GET /api/v1/blocks/:id: A block by height or hash. /api/v1/blocks/170
GET /api/v1/blocks: Blocks, a page at a time.
GET /api/v1/txs/:txid: One transaction. /api/v1/txs/f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16
GET /api/v1/txs: Transactions, a page at a time; filter with ?protocol=, ?type= (a type id from /types) or ?block_hash=.
GET /api/v1/txs/:txid/raw: The transaction's exact bytes, checked against its txid.
GET /api/v1/stream/blocks: New blocks as they arrive, over server-sent events.

Proofs

Evidence you can check without trusting Bitblocks.

GET /api/v1/txs/:txid/proof: A merkle proof: index, siblings and root. /api/v1/txs/f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16/proof
GET /api/v1/txs/:txid/beef: The same proofs as BEEF (BRC-62), for a wallet or an SPV client.
GET /api/v1/txs/:txid/bob: The tx as BOB, unwriter's tapes and cells, so code written for Bitbus reads it.
GET /interop/vectors/v1.json open: Test vectors for BEEF and BUMP, each with its expected outcome and source.

Addresses, scripts and outpoints

What an address or a script holds. Read the status on every answer; see below.

GET /api/v1/addresses/:address/balance: A balance, with its status.
GET /api/v1/addresses/:address/utxos: Known-unspent outputs, and the ones not yet settled.
GET /api/v1/addresses/:address/history: Every transaction touching an address, newest first, with its net sats and status.
GET /api/v1/script/:scripthash/history: Transactions paying a script, with its status.
GET /api/v1/script/:scripthash/unspent: Outputs locked by a script.
POST /api/v1/script/decode: Script hex into a typed description.
GET /api/v1/outpoints/:txid/:vout: Is this outpoint an ordinal or token? Answers yes, no or unknown.

What's on chain

The indexes behind the demos. These are beta, and fill in as the sync climbs.

GET /api/v1/types: Transaction types, with their pages and counts.
GET /api/v1/protocols: Registered on-chain protocols.
GET /api/v1/tokens: BSV-20 and BSV-21 tokens.
GET /api/v1/collections/:id: A collection and its verification. /api/v1/collections/rexxies
GET /api/v1/collections/:id/items: Items in mint order, with owner and trace state. /api/v1/collections/rexxies/items
GET /api/v1/bitcom: The Bitcom registry, with txids to check.
GET /bitcom.json open: The Bitcom registry export, to check without trusting us.
GET /api/v1/bitcom/snapshots open: Versioned snapshots of that export.
GET /api/v1/metanet/:txid: A Metanet node with its parent and children.

Going further

This list is the core of the API, and the code is open if you want to see all of it. Proofs are explained in full in the merkle proofs doc.