Skip to main content
Blockbook is an add-on for Bitcoin Mainnet Global Nodes that indexes the chain by address. With Blockbook, one request returns the balance, UTXOs, or transaction history of any address or extended public key (xpub), and a WebSocket subscription pushes new blocks and address activity to your application. Blockbook is the open-source blockchain indexer built by Trezor. Chainstack runs it alongside your Bitcoin node and serves it from a separate endpoint that uses your node’s auth token.
Blockbook is a paid add-on for Bitcoin Mainnet Global Nodes, available starting from the Growth plan. It isn’t available on the Bitcoin testnets.

Why a Bitcoin node can’t answer address queries

A Bitcoin node can’t return an address’s balance or history directly, because Bitcoin doesn’t store either. Getting them from a node means scanning chain data, which is too slow to do on every request. Blockbook does that work once and keeps the result as an index by address. Bitcoin has no account balances. It tracks money with these building blocks:
  • Unspent transaction output (UTXO) — an amount that a transaction paid to an address and that no later transaction has spent yet. Every transaction spends earlier UTXOs and creates new ones.
  • Address balance — the sum of the address’s UTXOs.
  • Address history — every transaction that paid to the address or spent from it.
  • Extended public key (xpub) — the public key of one wallet account. A wallet derives all the addresses of an account from its xpub and uses a new address for each payment, so the funds of one account spread across many addresses.
A Bitcoin node stores transactions by transaction ID and keeps the current set of UTXOs, but it has no index by address. Without an address index:
  • To get the balance of an address, the node’s scantxoutset method reads the entire UTXO set on every call.
  • To get the history of an address, you read every block since 2009 and check every transaction in it. Bitcoin Core lists an address’s transactions only after you import the address into a node wallet, and the import scans the chain again.
  • To show a wallet, you need that history for every address the wallet has used.
Blockbook reads every block once, records each transaction under the addresses it touches, and updates the index with every new block and mempool transaction. Each of these tasks then takes one request: For the Bitcoin Core methods available on Chainstack, see Bitcoin methods.

Install Blockbook

1

Deploy a Bitcoin Mainnet Global Node

If you don’t have one yet, see Add a node to a network.
2

Open the Add-ons tab

On Chainstack, open the node and select the Add-ons tab.
3

Install the add-on

Click Enable on the Blockbook add-on, select a tier in the Install Add-on dialog, and click Install.
To switch tiers or remove the add-on, see Manage node add-ons.

Blockbook tiers

Blockbook has three monthly tiers. Each tier sets the maximum number of requests per second (RPS) for the node’s Blockbook endpoints. For the price of each tier, see Chainstack pricing. The RPS limit applies to the node as a whole, across all your applications. It counts each REST request and each WebSocket message sent to the node’s Blockbook endpoints. A REST request above the limit returns HTTP 429.

How Blockbook requests are billed

Blockbook requests consume request units (RUs) on top of the tier’s monthly price:
  • Each REST request is 1 RU.
  • Each WebSocket request is 1 RU.
  • Each WebSocket subscription notification is 1 RU.
On a node with the Unlimited Node add-on, Blockbook requests don’t consume RUs, and the Blockbook tier’s RPS limit still applies.

Blockbook endpoints

After you install the add-on, the node’s Access and credentials shows two more endpoints:
  • Blockbook HTTPS endpoint — the REST API, https://blockbook-bitcoin-mainnet.core.chainstack.com/YOUR_AUTH_TOKEN/api/v2
  • Blockbook WSS endpoint — the WebSocket API, wss://blockbook-bitcoin-mainnet.core.chainstack.com/YOUR_AUTH_TOKEN/websocket
Both Blockbook endpoints use the node’s auth token, the same token as in the node’s HTTPS endpoint. The node’s own HTTPS and WSS endpoints keep serving Bitcoin Core JSON-RPC. For more on node auth tokens, see Authentication methods.

REST API

The Blockbook REST API takes GET requests under /api/v2 and returns JSON. Broadcasting a transaction also takes POST. Amounts are strings in satoshis, so "balance": "100000000" is 1 BTC.

Get the balance and transactions of an address

/api/v2/address/{address} returns the balance of a legacy, P2SH-SegWit, native SegWit, or Taproot address, and a page of its transaction IDs. This example requests a page of two transaction IDs:
The example address is the first receiving address of the public BIP-84 test vectors. Anyone can send to it and spend from it, so its balance is usually 0. The response has these fields:
  • balance — the confirmed balance
  • totalReceived and totalSent — the confirmed totals over the address’s history
  • unconfirmedBalance — the change from mempool transactions
  • unconfirmedTxs — the number of mempool transactions
  • txs — the number of confirmed transactions
  • txids — the transaction IDs on the current page, newest first
  • page, totalPages, and itemsOnPage — the paging state
These query parameters shape the response:
  • details — basic returns only the balances and counts, and omits unconfirmedBalance. txids is the default. txs returns full transactions instead of IDs.
  • page and pageSize — select a page of transactions.
  • from and to — limit the transactions to a block height range.
History pages return at most 1,000 items. Requests with pageSize above 1,000 are capped at 1,000 and return HTTP 200. Use page to retrieve subsequent pages.

List the UTXOs of an address

/api/v2/utxo/{address} returns the unspent outputs of an address, including outputs from mempool transactions. Add confirmed=true to return only confirmed outputs:
Each UTXO has txid, vout, value, height, and confirmations.

Get a wallet account by xpub

A Bitcoin wallet uses a new address for each payment, so the funds of one wallet account spread across many addresses. All of them derive from the account’s extended public key (xpub), which hardware and software wallets can export. An xpub can’t sign transactions, but it reveals every address of the account. /api/v2/xpub/{xpub} finds the account’s used addresses and returns their combined balance and transactions. /api/v2/utxo/{xpub} returns the UTXOs of the account. This example uses the account key from the BIP-84 test vectors:
balance, totalReceived, and totalSent add up all the account’s addresses, and usedTokens is the number of derived addresses with transaction history. To list the account’s used addresses with their derivation paths, add details=tokens&tokens=used. Blockbook derives the address type from the key prefix: A key with the wrong prefix for the wallet returns an account with no balance and no transactions, not an error. If your wallet exports every key as xpub, pass an output descriptor instead. For Taproot accounts, pass an output descriptor such as tr(YOUR_XPUB/<0;1>/*). Blockbook also accepts pkh(…), sh(wpkh(…)), and wpkh(…) descriptors. URL-encode the descriptor in the path:

Other REST endpoints

Broadcast a transaction

/api/v2/sendtx/ broadcasts a signed transaction and returns its ID as {"result": "TXID"}. Send the transaction hex as the body of a POST request:
A GET request with the hex in the path, /api/v2/sendtx/SIGNED_TRANSACTION_HEX, also works for transactions short enough to fit in a URL.

REST errors

An invalid request returns HTTP 400 and a JSON body with an error field:

WebSocket API

The Blockbook WebSocket API takes JSON messages with id, method, and params. Each response and each subscription notification carries the id of the request that created it. One connection can run several requests and subscriptions at once, and responses can arrive in a different order than the requests, so match them by id.

Subscribe to new blocks and address activity

This Node.js example subscribes to new blocks and to one address. It uses the ws package, installed with npm install ws:
subscribe.js
The example sends ping every 30 seconds, because a WebSocket connection with no traffic can be closed while a subscription waits for the next block. It prints one line for each new block and each transaction that involves the address:
The subscription methods are:
  • subscribeNewBlock — one notification per new block, with height and hash.
  • subscribeAddresses — one notification per transaction that involves an address in addresses, sent when the transaction enters the mempool. The notification has address and the full transaction as tx.
  • subscribeNewTransaction — one notification for every transaction that enters the mempool.
subscribeAddresses rules:
  • To also get a notification when each transaction is confirmed in a block, add "newBlockTxs": true to params. The confirmed notification has the same id and shows tx.confirmations as 1. With newBlockTxs, one subscription takes up to 100 addresses.
  • Each subscribeAddresses call replaces the connection’s previous address list. To watch more addresses, send the full list again.
  • To stop, send unsubscribeAddresses. The other subscriptions stop with unsubscribeNewBlock and unsubscribeNewTransaction.

Query an address over WebSocket

The REST queries are also available as WebSocket methods. This Python example gets the balance of an address with getAccountInfo. It uses the websockets package, installed with pip install websockets:
account.py
The example prints:
descriptor takes an address, an xpub, or an output descriptor, as in Get a wallet account by xpub. The WebSocket request methods are:

Access and rate limit errors

The Blockbook endpoints return these errors before a request reaches Blockbook:
  • HTTP 403 — the node doesn’t have the Blockbook add-on. The response body is Blockbook is not enabled for this node. Install the add-on to query address data. See https://docs.chainstack.com/docs/blockbook for instructions.
  • HTTP 429 — the node’s Blockbook requests exceeded the tier’s RPS limit. See Blockbook tiers.
When you remove the add-on, the node’s open Blockbook WebSocket connections close.

What isn’t available on Chainstack Blockbook

The upstream Blockbook API reference documents some features that don’t work on Chainstack Blockbook:
  • Fiat exchange rates — Chainstack Blockbook doesn’t collect exchange rates.
    • The /api/v2/tickers/, /api/v2/multi-tickers/, and /api/v2/tickers-list/ endpoints return HTTP 400 with No tickers found.
    • The WebSocket methods getCurrentFiatRates, getFiatRatesForTimestamps, and getFiatRatesTickersList return the same error.
    • subscribeFiatRates confirms the subscription but never sends a notification.
    • Balance history has no fiat values, and its fiatcurrency parameter has no effect.
  • Methods for EVM chains — /api/v2/contract/ and the WebSocket rpcCall method return an error, because they don’t apply to Bitcoin.

See also

Last modified on November 19, 2026