HTTP API
pip install 'multichain-analytics-indexer[serve]'
multichain-indexer serve
serves the local database read-only on http://127.0.0.1:8000, with the OpenAPI schema at
/openapi.json and interactive docs at /docs (the docs page loads its scripts from a CDN;
the schema does not need one).
| Route | Gives |
|---|---|
GET /health |
status and version |
GET /chains |
chains this install can read, and the chains and networks stored |
GET /metrics?days=30 |
every stored chain side by side, as metrics --chain all --json |
GET /chains/{chain}/{network}/metrics?days=30&account= |
one chain's metrics, as metrics |
GET /chains/{chain}/{network}/transactions?account=&days=&offset=0&limit=50 |
stored transactions, newest first, in pages of up to 1,000 |
GET /chains/{chain}/{network}/accounts/{address} |
the account's state as index account last stored it |
curl -s "http://127.0.0.1:8000/chains/bitcoin/testnet4/transactions?limit=1"
{
"total": 4,
"offset": 0,
"limit": 1,
"next_offset": 1,
"items": [
{
"id": "c6f15b762eb44dbe10f2625bb4ddaec9ce1f11aa324aca2df9a530ac11a150a0",
"time": "2026-11-13T16:56:45Z",
"sender": "mgdKMwnT4S5gbx55Uw3tRJchUSrHwAFjzu",
"receiver": "mgdKMwnT4S5gbx55Uw3tRJchUSrHwAFjzu",
"amount": "3561478",
"fee": "522",
"status": "final",
"chain": "bitcoin",
"network": "testnet4",
"native": {"version": 1, "vsize": 519, "fee_rate": 1.0057803468208093, ...}
}
]
}
Amounts and fees in transactions are text, as in exports, because JSON readers such as
JavaScript lose integers past 2**53. Metrics are the exact JSON metrics prints.
Read-only
By default no request reaches the network or writes to the database. An account is answered
from the state index account last stored for it; an account never looked up gets HTTP 404
with the command to run first:
multichain-indexer --chain bitcoin --network testnet4 index account mgdKMwnT4S5gbx55Uw3tRJchUSrHwAFjzu
serve --live-accounts, off by default, lets account lookups read the chain and keep the new
state, exactly as index account does. That is the only way a request can reach a public
endpoint or write to the database. Account lookups read a SQLite database through a read-only
connection.
serve never migrates the database either, so a read-only PostgreSQL user is enough. When it
starts it checks, without writing, that the database is at the schema this version expects. A
database that is missing, or older, such as one 0.6.0 wrote, is refused with a message that says
how to upgrade it: run any other command on the same database once, for example
multichain-indexer --db indexer.db --chain all metrics
and start serve again. A database already at the current schema is served as it is.
Safety
- Every route is a GET.
- It listens on 127.0.0.1.
--hostchanges that, and the command then warns that anyone who can reach the address can read the database. - Each client may send 120 requests a minute (
--requests-per-minute); more get HTTP 429 withRetry-After. With--live-accounts, account lookups reach public endpoints, which have limits of their own. - Errors carry the same one-line messages as the command line: 400 for bad input, 404 for an unknown chain or record, 502 when a public endpoint fails.