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.
- To get the balance of an address, the node’s
scantxoutsetmethod 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.
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.
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.
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
REST API
The Blockbook REST API takesGET 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:
0.
The response has these fields:
balance— the confirmed balancetotalReceivedandtotalSent— the confirmed totals over the address’s historyunconfirmedBalance— the change from mempool transactionsunconfirmedTxs— the number of mempool transactionstxs— the number of confirmed transactionstxids— the transaction IDs on the current page, newest firstpage,totalPages, anditemsOnPage— the paging state
details—basicreturns only the balances and counts, and omitsunconfirmedBalance.txidsis the default.txsreturns full transactions instead of IDs.pageandpageSize— select a page of transactions.fromandto— limit the transactions to a block height range.
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:
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:
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 HTTP400 and a JSON body with an error field:
WebSocket API
The Blockbook WebSocket API takes JSON messages withid, 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 withnpm install ws:
subscribe.js
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:
subscribeNewBlock— one notification per new block, withheightandhash.subscribeAddresses— one notification per transaction that involves an address inaddresses, sent when the transaction enters the mempool. The notification hasaddressand the full transaction astx.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": truetoparams. The confirmed notification has the sameidand showstx.confirmationsas1. WithnewBlockTxs, one subscription takes up to 100 addresses. - Each
subscribeAddressescall replaces the connection’s previous address list. To watch more addresses, send the full list again. - To stop, send
unsubscribeAddresses. The other subscriptions stop withunsubscribeNewBlockandunsubscribeNewTransaction.
Query an address over WebSocket
The REST queries are also available as WebSocket methods. This Python example gets the balance of an address withgetAccountInfo. It uses the websockets package, installed with pip install websockets:
account.py
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 isBlockbook 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.
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 HTTP400withNo tickers found. - The WebSocket methods
getCurrentFiatRates,getFiatRatesForTimestamps, andgetFiatRatesTickersListreturn the same error. subscribeFiatRatesconfirms the subscription but never sends a notification.- Balance history has no fiat values, and its
fiatcurrencyparameter has no effect.
- The
- Methods for EVM chains —
/api/v2/contract/and the WebSocketrpcCallmethod return an error, because they don’t apply to Bitcoin.