BitcoinDatabase.com
How it works
Bitcoin API Block explorer API Address lookup Historical data API Transaction API Bitcoin data API On-chain metrics Rich list Query with SQL Crypto AML API UTXO data Node API Webhook API Price API Transaction monitoring xpub balance API See all →
Glassnode alternative Blockchair alternative BlockCypher alternative Mempool.space alternative Xverse alternative BigQuery alternative Bitquery alternative TimechainIndex alternative CryptoQuant alternative Alchemy alternative QuickNode alternative Hiro alternative Amberdata alternative Elliptic alternative Merkle Science alternative Coin Metrics alternative CoinGlass alternative Crypto APIs alternative Tatum alternative NOWNodes alternative GetBlock alternative Arkham Intelligence alternative Santiment alternative Nansen alternative Allium alternative Flipside alternative SonarX alternative GoldRush alternative Scorechain alternative AMLBot alternative
Docs Pricing Blog Contact Sign in

Query the chain · xpub balance API

xpub balance API for HD wallet addresses and totals

An xpub is the extended public key at the top of a Bitcoin HD wallet, and every receive and change address in that wallet derives from it. The xpub balance API takes an xpub (or ypub or zpub), derives the address chain, checks each derived address against the fully-indexed blockchain, and returns the combined balance to the satoshi along with the transactions behind it, so you track a whole wallet from one key instead of registering addresses one by one.

or try it below ↓

REST API · SQL · dashboards · address history from genesis

Query Console
btc
try:

Hit Run to query the Bitcoin blockchain.

Live from the chain for .

BTC

Balance trail

informational on-chain data · not financial advice

REST API · SQL · dashboards, one indexed dataset. Reading the chain ...

This is what wallets, exchanges and portfolio tools need to show a live balance without holding any private key: the extended public key only reveals addresses and history, never spend authority. Address history reaches back to 2009, so gap-limit scanning, used-versus-fresh address detection and totals come back in one call. SQL and dashboards cover the indexed chain, which grows with every new block. Informational on-chain data only, not financial advice.

REST API SQL DASHBOARDS WEBHOOKS CSV EXPORT

History from genesis queryable in seconds

On-chain data not financial advice

Why it works

What you get with xpub balance API

One key, every address

Pass an xpub, ypub or zpub and we derive the receive and change addresses, scan them against the indexed chain to the gap limit, and return which are used and what each holds.

Whole-wallet balance

Sum the balance across every derived address to the satoshi and pull the combined transaction history, so a portfolio or exchange view reflects the full HD wallet, not a single address.

Watch-only and safe

An extended public key exposes addresses and their history, never the ability to spend. Track balances and monitor deposits without ever touching a private key or seed.

What it handles

The indexed Bitcoin chain, queryable your way

Look up an address, a transaction, a UTXO, the rich list or an on-chain metric, by REST API, SQL or dashboard. The same authoritative data, reconciled block-by-block against the canonical chain, without running a node.

  • Derive receive and change addresses from an xpub, ypub or zpub
  • Total an HD wallet balance to the satoshi in one call
  • Detect used versus fresh addresses within the gap limit
  • Pull combined transaction history across a wallet
  • Query the same data via REST, SQL or dashboards
GET /v1/address/{addr} query result
200 · JSON 
{
  "address": "bc1qxy2k…l0wdv8",
  "balance_btc": 68432.10,
  "balance_usd": 4612165420,
  "tx_count": 1284,
  "unspent_outputs": 37,
  "first_seen": "2014-02-09"
}
indexed from genesis · to the satoshi ✓ reconciled block-by-block

Why BitcoinDatabase

One platform, queryable three ways

Not a raw node to sync, not an indexer to build, and not five vendors to stitch together. The fully-indexed Bitcoin blockchain, available as a REST API, as SQL, and as dashboards, on one authoritative dataset.

REST API

Typed JSON for addresses, transactions, balances, UTXOs and metrics. Drop it into apps, wallets, explorers and agents with curl, Python or any HTTP client.

SQL access

Run SQL directly against the indexed Bitcoin dataset for ad-hoc analysis, cohorts and exports, the same data the API and dashboards read from.

Compliance-first

Informational on-chain data and analytics only. Entity labels and flow tracing are framed as tooling to support a regulated team's own review, not accusations.

Good questions

Questions about xpub balance API

An xpub is an extended public key: a public key plus a chain code that lets software derive every receive and change address of an HD wallet (BIP32) in the same order, every time. It cannot sign or spend. That is why accountants, auditors and treasury tools ask for the xpub: one string gives the whole wallet balance and history through GET /v1/xpub/{xpub}, with no private key involved.
Give it an extended public key and it derives the wallet's addresses, checks each against the indexed chain, and returns the combined balance to the satoshi plus the transactions behind it. That lets a wallet, exchange or portfolio tool show a live HD-wallet balance from one key, with no private key involved.
An xpub is a public key: it reveals the wallet's addresses and their on-chain history but cannot authorize a spend, so it is used for watch-only tracking. Anyone with it can see your balances and future addresses, so treat it as sensitive for privacy, but it never puts your funds at risk. This is informational data, not financial advice.
Scanners stop deriving addresses after roughly 20 consecutive unused ones, on the assumption that a wallet issues addresses in order. It is a convention, not a consensus rule. If a user generated addresses out of order or skipped a stretch, everything past the gap is invisible and no error is raised, so history goes missing quietly rather than loudly.
Derive the address set from the extended public key, then pull history per address and merge. The practical constraint is paging: public explorers return address history 25 transactions at a time, so a heavy wallet becomes many sequential requests. Pulling a two and a half day slice of one 2.3 million transaction address took us 90 requests.
Raise it when you are ingesting a wallet you did not create, which is most tax and accounting work. A larger window costs derivation and lookups but stops silent history loss. The safer pattern is to widen the scan until you see a long confirmed run of genuinely unused addresses, rather than trusting a fixed number.
No. An extended public key derives receiving addresses and reveals balances and full transaction history, but it cannot authorize a spend, which requires the corresponding private keys. The real risk is privacy: an xpub links every derived address to one wallet, so treat it as sensitive even though it is not spendable.
Yes, if your data source indexes history by height rather than only serving current state. Be careful with public APIs here: Esplora ignores a height parameter and returns a byte-identical current response, and we measured one provider returning every field as zero for a historical query rather than an error, which is worse than failing.
Almost always the derivation path or the gap limit, not the chain. The same extended key produces different address sets under BIP44, BIP49, BIP84 and BIP86, so a tool scanning only legacy paths misses native SegWit and Taproot funds entirely. Confirm which paths and which gap limit each tool used before assuming a data problem.
GET /v1/xpub/{xpub} walks the receiving chain and the change chain separately and stops each after 20 consecutive unused addresses by default. Pass ?gap= up to 50 for a wallet you did not create, and ?limit= up to 200 addresses per chain. The response only lists addresses that were actually used, each with its derivation path, balance, received, spent and transaction count.
The scan has a 25 second budget as well as an address cap, because each derived address is one lookup against the chain. If either runs out, the response flags it per chain with stopped_on_time or stopped_at_cap instead of returning a silently short total, so you know to rerun with a narrower window. A call costs 10 credits on any plan.
Yes, as the first step. The xpub call gives you the full set of used addresses, including change addresses an owner never saw, and today's combined balance. For a date of death or a period end, take that address list into one SQL query at the named block height, available from the Growth plan, so coins received afterwards drop out.
Read every Bitcoin API question

Explore more

More ways to query Bitcoin with BitcoinDatabase

Bitcoin address lookup

Look up any Bitcoin address: balance, full history and UTXOs in one query.

Learn more

Bitcoin historical data API

Full-depth history: every block, transaction and metric back to 2009.

Learn more

Bitcoin address balance history API

What an address held on any past date, not just what it holds now.

Learn more

Bulk Bitcoin address balance checker

Check thousands of addresses in one pass, not twenty at a time.

Learn more

Bitcoin block explorer API

Power an explorer with blocks, transactions and addresses, no node to maintain.

Learn more

Bitcoin node API

JSON-RPC style access to blocks, transactions and balances, with no Bitcoin Core to run.

Learn more

Buyer guides and measurements on this topic

Bitcoin Wallet Statement Tools for Accountants and Lenders The best Bitcoin wallet statement tool for an accounting firm or lender pins the opening and closing balance to a named block, covers the whole wallet... Crypto Date of Death Valuation Tools for Estates A crypto date of death valuation needs the balance at the last block before death and a stated price method. On 1 September 2026 the Eastern-day high... 1099-DA Reconciliation Software for Bitcoin CPAs 1099-DA reconciliation for bitcoin turns on the transferred-in lots the broker leaves without basis. On 28 September 2026, 1,709 deposits swept into o...
See every use case See pricing Back to the Bitcoin API

Stop running a node. Just query Bitcoin.

Run your first query now and get on-chain data back by REST API, SQL or dashboard, with address history back to the genesis block over REST. Informational on-chain data only, not financial advice.

See pricing

History from genesis over REST · SQL · dashboards · addresses, transactions, UTXOs, metrics