API reference

Bitcoin API documentation

A single REST API over the fully-indexed Bitcoin blockchain. Authenticate with a bearer key, then query addresses, transactions, blocks, UTXOs, on-chain metrics and the rich list, or drop to SQL. Here is everything you need to make your first request.

Jump to endpoints

Introduction

The BitcoinDatabase API is organized around predictable, resource-oriented REST. Every request is sent over HTTPS, accepts and returns JSON, and authenticates with a bearer key. The chain is indexed since the 2009 genesis block and new blocks are indexed within seconds. The base URL for all endpoints is:

https://api.bitcoindatabase.com/v1

Authentication

Authenticate every request by passing your secret key in the Authorization header as a bearer token. Keep your key secret, on a server and out of client-side code. You get a key when you create an account.

Authorization header BEARER

Authorization: Bearer $BITCOINDATABASE_API_KEY

Need a key? BitcoinDatabase serves informational on-chain data and analytics only, not financial or legal advice.

GET /v1/address/{addr}

Look up a single address. Returns its confirmed balance to the satoshi, transaction count, first and last seen, and any entity label such as exchange, miner or service.

Request

curl https://api.bitcoindatabase.com/v1/address/bc1q...x7 \
  -H "Authorization: Bearer $BITCOINDATABASE_API_KEY"

import requests

r = requests.get(
    "https://api.bitcoindatabase.com/v1/address/bc1q...x7",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
data = r.json()

const res = await fetch("https://api.bitcoindatabase.com/v1/address/bc1q...x7", {
  headers: { Authorization: `Bearer ${process.env.BITCOINDATABASE_API_KEY}` },
});
const data = await res.json();

Response · 200 OK

{
  "address": "bc1q...x7",
  "balance_sat": 182734991,
  "tx_count": 47,
  "first_seen": "2017-03-11",
  "label": { "entity": "exchange", "name": "example-exchange" }
}

Core endpoints

Endpoint	Returns
GET /v1/address/{addr}	Address balance, tx count, first or last seen and entity label.
GET /v1/address/{addr}/transactions	Paged transaction history for an address, newest first.
GET /v1/tx/{txid}	A transaction with inputs, outputs, fee and confirmations.
GET /v1/block/{height}	A block by height with header fields and its transactions.
GET /v1/metrics/{metric}	An on-chain metric series: active addresses, realized cap, SOPR and more.
GET /v1/addresses/top	The rich list, the top addresses ranked by balance.

GET /v1/tx/{txid}

Resolve a transaction by its hash. Returns the full set of inputs and outputs, the fee, the block it was mined in and its current confirmation count. Unconfirmed transactions in the mempool come back with a confirmations value of zero.

Request

curl https://api.bitcoindatabase.com/v1/tx/4a5e1e4b...c8d \
  -H "Authorization: Bearer $BITCOINDATABASE_API_KEY"

Response · 200 OK

{
  "txid": "4a5e1e4b...c8d",
  "block_height": 847291,
  "confirmations": 312,
  "fee_sat": 2140,
  "inputs": [ { "address": "bc1q...a2", "value_sat": 5000000 } ],
  "outputs": [ { "address": "bc1q...x7", "value_sat": 4997860 } ]
}

SQL access

From the Growth plan and up, you can query the indexed chain with raw SQL. Write your own joins across addresses, transactions, blocks, UTXOs and metric tables, reproduce any dashboard number from the underlying rows, and export results in bulk. A SQL query costs more credits than a single REST lookup.

POST /v1/sql

curl https://api.bitcoindatabase.com/v1/sql \
  -H "Authorization: Bearer $BITCOINDATABASE_API_KEY" \
  -d '{ "query": "SELECT day, active_addresses FROM metrics_daily ORDER BY day DESC LIMIT 30" }'

Rate limits and credits

Each plan includes a monthly pool of API credits and a per-second request limit. Calls cost credits by type, so light lookups are cheap and heavier queries cost more. If you exceed your rate, the API returns 429 with a Retry-After header.

Plan	Credits / mo	Requests / s
Developer	500K	10
Growth	5M	50
Scale	50M	250
Enterprise	Custom	Custom

SDKs

Official Python and JavaScript SDKs wrap every endpoint with typed responses, retries and pagination, so you can look up an address or page a metric series in a couple of lines. The REST API is always available if you prefer raw HTTP from any language.

pip install bitcoindatabase
npm i bitcoindatabase

Webhooks

Subscribe an address or transaction to a webhook URL and BitcoinDatabase posts to your endpoint on new activity and on confirmation changes, so you never poll the chain. Each delivery is signed, so you can verify it came from us before you ingest the data.

POST /hooks/bitcoindatabase
X-Bdb-Signature: t=...,v1=...

Informational data only. BitcoinDatabase serves on-chain data and analytics, not financial, investment or legal advice. AML and risk features surface labels, signals and flows to support a regulated team\'s own review, with no accusations and no deanonymization. Read the compliance policy.

Make your first API call

Get a key, send a request, and get an address, transaction, block or metric back from the fully-indexed chain. Informational on-chain data only.

See how it works