If you have ever tried to answer a simple question like "what is the transaction history of this address?" by talking directly to a blockchain node, you already know the problem. Nodes are excellent at validating and storing blocks. They are not built to answer questions about addresses.

This article explains why blockchain indexers exist, what Blockbook is and which networks it supports, and then walks through building a working indexer, including the problems you are likely to hit on a real mainnet sync.

1. Why You Need a Blockchain Indexer

What a node gives you

A full node such as Bitcoin Core or Dogecoin Core downloads every block, validates it, and keeps the chain on disk. Through its RPC interface you can ask things like:

  • Give me the block at height 100,000.
  • Give me transaction abc... (if the transaction index is enabled).
  • What is the current chain tip?
  • Broadcast this raw transaction.

Every one of those questions starts from a block hash, a height, or a transaction ID.

What applications actually ask

Wallets, explorers, exchanges, custody platforms and analytics tools ask questions that start from an address:

  • What is this address's balance?
  • Show every transaction this address has ever been part of.
  • Which outputs does this address still have unspent?
  • What does the history of this extended public key (xpub) look like?
  • Notify me when this address receives funds.

A node cannot answer these efficiently. Bitcoin-style chains store data by transaction and block, not by address. To find an address's history, a node would have to scan the entire chain, which can mean hundreds of gigabytes of data for a single query. Address-level lookups are simply not part of the node's design.

The indexer's job

A blockchain indexer sits beside the node and does the expensive work once:

 ┌────────────┐ blocks via RPC ┌──────────────┐ │ Full node │ ───────────────────► │ Indexer │ │ (the │ new-block events │ (address- │ ──► fast API │ ledger) │ ───────────────────► │ indexed DB)│ └────────────┘ └──────────────┘ 
  1. It reads every block from the node.
  2. It builds its own database, keyed by address, transaction and block.
  3. It keeps that database current as new blocks arrive.
  4. It serves the results through a fast API.

The result is that a query that would take a node minutes or hours returns in milliseconds. The cost is extra disk, extra memory during the initial sync, and one more service to operate.

Why not build your own?

You can, and many teams start there. But a correct indexer has to handle:

  • Reorganizations, where the chain tip is replaced by a different branch and your index must roll back cleanly.
  • The mempool, so unconfirmed transactions show up and disappear correctly.
  • UTXO tracking and spent/unspent state.
  • Extended public keys for wallet-style lookups.
  • Crash safety, so a restart does not corrupt the index.

Using a mature open-source indexer saves months of work, and Blockbook is one of the best-known options.

2. What Is Blockbook?

Blockbook is an open-source blockchain indexer and explorer backend written in Go, created by SatoshiLabs, the company behind the Trezor hardware wallet. It powers the backend of Trezor Suite, so it is built for wallet-grade lookups, not just casual browsing.

Blockbook:

  • Connects to a full node you run (or have access to) over RPC.
  • Optionally subscribes to the node's ZMQ message queue for instant new-block and new-transaction notifications.
  • Stores its index in RocksDB, an embedded key-value database designed for heavy write workloads.
  • Exposes a REST API, a WebSocket API and, optionally, a simple built-in block explorer web interface.
  • Supports address lookups, transactions, blocks, UTXOs, xpub/descriptor queries, balance history and fiat rates.

Important: Blockbook does not replace the node. It needs one. The node is the source of truth, and Blockbook is the searchable index built on top of it.

Check the license

Review the license in the repository before using it in a product. As far as I know it is a copyleft license, which matters if you plan to modify and distribute it. Confirm the current terms on the project page rather than relying on this article.

3. Networks Blockbook Supports

Blockbook supports a long list of networks, and each one is described by a JSON file in the repository's configs/coins/ directory. The most reliable way to see what your version supports is to look at that directory:

git clone https://github.com/trezor/blockbook.git ls blockbook/configs/coins/ 

The supported networks fall into two families. The exact list changes between releases, so always check the directory for your checkout.

Bitcoin-type chains

These use a UTXO model and a Bitcoin-like node API. Blockbook works with them through the node's RPC interface:

Examples Notes
Bitcoin The primary use case, with testnet/regtest variants
Litecoin
Dogecoin Used in the walkthrough below
Bitcoin Cash
Dash, Zcash, Vertcoin, Namecoin and similar forks Many Bitcoin-derived coins have a config file

Ethereum-type chains

For account-based chains, Blockbook connects to an Ethereum-compatible node and indexes accounts, transactions, token transfers and internal transactions. Supported networks have included Ethereum and several EVM-compatible chains, each using their own backend node (such as Geth or an equivalent). Whether a particular EVM chain is supported depends on the release, so verify against configs/coins/.

Things to check for any network

Before committing to a network:

  1. Is there a config file for it in configs/coins/?
  2. Which node software and version does the config expect? Blockbook needs a compatible node, not just any implementation.
  3. Does the node need special settings? For Bitcoin-type chains, the node must have its full transaction index on (txindex=1) and must not be pruned.
  4. How large are the chain and the index? This decides your disk and RAM budget.

4. Building an Indexer With Blockbook

This walkthrough indexes Dogecoin mainnet against an existing, fully synced Dogecoin node. The same pattern applies to other Bitcoin-type chains: change the coin name, the ports and the credentials.

Setting up the node itself is outside the scope of this article. You need a node that is reachable from your Blockbook server and already synced.

Architecture

 ┌──────────────────┐ RPC (TCP 22555) ┌────────────────────────┐ │ Dogecoin node │ ◄──────────────────── │ Blockbook server │ │ (existing) │ ZMQ (TCP 28333) │ RocksDB index │ │ │ ──────────────────► │ HTTP API on :9130 │ └──────────────────┘ └────────────────────────┘ 

Throughout this guide, NODE_IP, RPC_USER and RPC_PASS are placeholders for your node's address and credentials. Never paste real credentials into chats, tickets or version control.

Step 1: Check the node is ready

Blockbook has hard requirements on the node. Verify them before you install anything, because it is much cheaper to find a problem now than after a 20-hour sync.

Reachability:

nc -zv NODE_IP 22555 # RPC nc -zv NODE_IP 28333 # ZMQ (your node's port may differ) 

Health and settings:

curl -s --user RPC_USER:RPC_PASS \ --data-binary '{"jsonrpc":"1.0","id":"t","method":"getblockchaininfo","params":[]}' \ -H 'content-type: text/plain;' http://NODE_IP:22555/ 

Look for:

Field Required
"chain" "main" for mainnet
"initialblockdownload" false (fully synced)
"pruned" false
blocks vs headers equal, or almost

Transaction index: fetch any old transaction with getrawtransaction. If you get an error mentioning -txindex, the node's owner has to enable it.

Common failures: Connection refused or a timeout means a wrong address or a firewall; 403 Forbidden means your server's IP is not in the node's rpcallowip; 401 Unauthorized means wrong credentials.

Step 2: Size the server

These figures come from a real Dogecoin mainnet run and should be treated as a starting point. Chain sizes change over time, so check current numbers before provisioning.

Resource Recommendation
CPU 4 cores minimum, 8 comfortable
RAM 32 GB for the initial sync (see the memory section below)
Disk 500 GB or more of fast storage, plus room to grow
Network Low-latency link to the node, ideally the same LAN

Fast disks matter: the initial sync is write-heavy.

Step 3: Prepare the machine

On Ubuntu 24.04:

sudo apt update sudo apt install -y build-essential git curl wget pkg-config libssl-dev \ libsnappy-dev zlib1g-dev libbz2-dev liblz4-dev libzstd-dev tmux # Runtime libraries the compiled binary needs on the host sudo apt install -y libzmq5 libsnappy1v5 libgflags2.2 zlib1g libbz2-1.0 liblz4-1 libzstd1 

The second line matters. Blockbook is compiled inside a Docker container, so the finished binary links against libraries your host may not have. Without libzmq5, it fails with error while loading shared libraries: libzmq.so.5.

Install Go (check go.dev/dl for the current version, and use sudo for the extraction because /usr/local is root-owned):

cd ~ wget https://go.dev/dl/go1.27.3.linux-amd64.tar.gz sudo rm -rf /usr/local/go sudo tar -C /usr/local -xzf go1.27.3.linux-amd64.tar.gz echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc source ~/.bashrc go version 

Install Docker, which the build uses, and let your user run it:

curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp docker docker version 

Step 4: Get Blockbook and generate the configuration

cd ~ git clone https://github.com/trezor/blockbook.git cd blockbook ls configs/coins/dogecoin.json go run build/templates/generate.go dogecoin 

Note the coin file is named after the full coin name (dogecoin.json), not an abbreviation. The generate step writes build/pkg-defs/blockbook/blockchaincfg.json.

Open it and point it at your node. The generated file defaults to 127.0.0.1, which is only correct when the node runs on the same machine:

{ "coin_name": "Dogecoin", "coin_shortcut": "DOGE", "rpc_url": "http://NODE_IP:22555", "rpc_user": "RPC_USER", "rpc_pass": "RPC_PASS", "message_queue_binding": "tcp://NODE_IP:28333" } 

(The real file contains more keys. Only change the ones above.) Validate it and lock it down, since it holds the RPC password:

python3 -m json.tool build/pkg-defs/blockbook/blockchaincfg.json > /dev/null && echo OK chmod 600 build/pkg-defs/blockbook/blockchaincfg.json 

Step 5: Build

The build runs in Docker and compiles RocksDB from source. Expect 10 to 25 minutes the first time.

ldd ./build/blockbook | grep "not found" 

No output means all libraries are present.

Step 6: Run it in the foreground first

A short foreground run lets you see problems directly:

./build/blockbook -blockchaincfg=build/pkg-defs/blockbook/blockchaincfg.json \ -datadir=./data-dogecoin-mainnet -sync -public=0.0.0.0:9130 -certfile= -explorer= 

In another terminal:

curl -s http://localhost:9130/api/ | python3 -m json.tool 

You should see "coin": "Dogecoin", a backend chain of main, and a bestHeight that rises. Stop it with Ctrl+C and confirm nothing is left running (pgrep -a blockbook). Two copies on the same data directory will conflict.

Step 7: Run it as a service, with memory limits

On a real mainnet sync, memory is the part that bites. In one run on a 16 GB machine, Blockbook grew to about 15 GB while processing the busier part of the chain, and the Linux out-of-memory killer terminated it. That left the database marked as inconsistent, and Blockbook refused to open it afterwards. The only recovery was to wipe the index and start again from block 0, after roughly 18 hours of work.

So the unit file below does three things: it limits memory in a way that slows the process instead of killing it, it reduces parallelism, and it stops the service from restart-looping on a fatal error.

sudo tee /etc/systemd/system/blockbook.service > /dev/null << EOF [Unit] Description=Blockbook Dogecoin Indexer (mainnet) After=network-online.target Wants=network-online.target StartLimitIntervalSec=600 StartLimitBurst=5 [Service] Type=simple User=$USER WorkingDirectory=$HOME/blockbook ExecStart=$HOME/blockbook/build/blockbook -blockchaincfg=$HOME/blockbook/build/pkg-defs/blockbook/blockchaincfg.json -datadir=$HOME/blockbook/data-dogecoin-mainnet -sync -public=0.0.0.0:9130 -certfile= -explorer= -workers=4 -chunk=50 Restart=on-failure RestartSec=10 RestartPreventExitStatus=255 TimeoutStopSec=120 [Install] WantedBy=multi-user.target EOF sudo mkdir -p /etc/systemd/system/blockbook.service.d sudo tee /etc/systemd/system/blockbook.service.d/memory.conf > /dev/null << 'EOF' [Service] Environment=GOMEMLIMIT=12GiB Environment=MALLOC_ARENA_MAX=2 MemoryHigh=18G MemoryMax=26G MemorySwapMax=16G EOF sudo systemctl daemon-reload sudo systemctl enable --now blockbook 

What each setting does:

Setting Purpose
-workers=4 Halves the default of 8 parallel block-processing workers, reducing memory at some cost in speed
-chunk=50 Halves the default bulk chunk size of 100 blocks, so less is held in memory at once
GOMEMLIMIT A soft target for the Go heap. It makes the garbage collector work harder near the limit
MALLOC_ARENA_MAX=2 Limits glibc malloc arenas, which can reduce fragmentation from the C libraries RocksDB uses
MemoryHigh A cgroup soft limit. Above it, the kernel throttles the process and reclaims memory instead of killing it
MemoryMax A hard limit that kills the process. Keep it well above MemoryHigh as a last-resort backstop
RestartPreventExitStatus=255 A fatal exit (such as an inconsistent database) is not retried forever

I cannot promise these exact numbers keep your sync under any specific memory figure, because the cause of the growth depends on the chain and the version. They are reasonable settings, and the memory log below shows whether they work for you. If the sync runs too slowly, raise -chunk back toward 100 first. If memory still climbs, add -notxcache and lower -workers further, accepting a slower sync.

A cautionary rule: a hard memory kill during the bulk sync can corrupt the index, so avoid anything that kills the process. That includes the OOM killer, kill -9, and a VM reboot or backup that stops the machine. Always stop it with sudo systemctl stop blockbook.

Step 8: Monitor the initial sync

The initial sync processes the entire chain, so expect many hours to several days. It starts fast, because early blocks are nearly empty, and slows as blocks fill with more transactions.

Progress:

curl -s http://localhost:9130/api/ | python3 -m json.tool 
Field Meaning
blockbook.bestHeight Blocks indexed so far
backend.blocks The node's height (the target)
blockbook.initialSync true during the bulk phase
blockbook.inSync true when fully caught up
blockbook.dbSize Index size in bytes

A small script gives a rate and an ETA, and handles the API being briefly down:

cat > ~/bbprog.sh << 'EOF' #!/bin/bash get() { curl -s --max-time 5 localhost:9130/api/ | python3 -c 'import sys,json;d=json.load(sys.stdin);print(d["blockbook"]["bestHeight"],d["backend"]["blocks"])' 2>/dev/null; } read h1 n < <(get); [ -z "$n" ] && { echo "Blockbook API not responding. Check: systemctl status blockbook"; exit 1; } sleep 60 read h2 n < <(get); [ -z "$n" ] && { echo "API stopped responding"; exit 1; } rate=$(( (h2-h1)/60 )) echo "height $h2 / $n ($(( h2*100/n ))%) rate ${rate} blk/s" [ $rate -gt 0 ] && echo "ETA ~ $(( (n-h2)/rate/3600 )) h at current rate" EOF chmod +x ~/bbprog.sh 

Treat the ETA as optimistic. Percent-by-height is misleading, because the later blocks hold far more work than the early ones.

Logs. Blockbook uses glog, which writes log files to /tmp rather than the systemd journal, so journalctl -u blockbook looks nearly empty. Read the files instead:

ls -lt /tmp/blockbook.*INFO* | head -3 tail -f /tmp/blockbook.INFO ls /tmp | grep -i blockbook # an ERROR file means errors were logged 

For journal output, add -logtostderr to the ExecStart line; for persistent files, add -log_dir= pointing at a directory you own.

Disk:

df -h / du -sh ~/blockbook/data-dogecoin-mainnet 

Grow the disk before it passes about 80% full. A disk that fills mid-sync can corrupt the index.

When it is finished: inSync becomes true and bestHeight matches backend.blocks. Only now does the ZMQ subscription start doing real work, so check the log for message-queue warnings. If the node's ZMQ port does not publish the topics Blockbook expects, it still works through RPC polling, but new blocks appear with a short delay. Ask whoever runs the node which ports publish the block and transaction topics.

Step 9: Query the index

# Status (keep the trailing slash, or add -L to follow the redirect) curl http://localhost:9130/api/ # A block by height or hash curl "http://localhost:9130/api/v2/block/100000" # An address and its transactions curl "http://localhost:9130/api/v2/address/ADDRESS?details=txs" # A transaction curl "http://localhost:9130/api/v2/tx/TXID" # Unspent outputs for an address curl "http://localhost:9130/api/v2/utxo/ADDRESS" 

This is the payoff. An address history lookup that a bare node could not answer returns immediately, as JSON, ready for an application.

Step 10: Secure and maintain it

Restrict access. -public=0.0.0.0:9130 listens on every interface. Limit who can reach it:

sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow from YOUR_ADMIN_SUBNET to any port 22 proto tcp sudo ufw allow from CLIENT_SUBNET to any port 9130 proto tcp sudo ufw enable 

Allow SSH before enabling the firewall, or you can lock yourself out. Also remember that RPC credentials and ZMQ traffic between your server and the node travel unencrypted. Keep both on a trusted network, or tunnel the link.

Routine care:

Task How
Health Confirm inSync is true and the height keeps rising
Disk Watch df -h / weekly, since the index grows
Updates Check the Blockbook and node release pages, then git pull, make build and restart
Backups Keep blockchaincfg.json and the unit files. The index can be rebuilt from the node, at the cost of the full sync time
Node changes If the node's address, ports or credentials change, update blockchaincfg.json and restart
Load If the node is shared, tell its owner the initial sync makes heavy RPC requests for hours or days

5. Lessons From a Real Mainnet Sync

A few things that are easy to miss until they cost you a day:

  1. Verify the node first. Pruned nodes and nodes without txindex cannot work with Blockbook, and you only discover it after a long wait if you skip the checks.
  2. Install the runtime libraries. A binary built in Docker still needs libzmq5 and friends on the host.
  3. Plan memory for the heavy part of the chain. Early progress looks cheap, and the later blocks cost far more in both time and RAM.
  4. A killed bulk sync is not resumable. An interrupted initial import leaves the database flagged inconsistent, and the supported recovery is a full resync. The -repair option fixes physical RocksDB corruption, not an interrupted bulk import.
  5. Do not let a service restart-loop on a fatal error. Use Restart=on-failure with RestartPreventExitStatus and a start limit, or you can end up with hundreds of pointless restarts.
  6. The logs are in /tmp. An empty journal does not mean nothing is happening.
  7. Disk can be smaller than you think. Check the actual filesystem size, not the size of the virtual disk.

6. When Blockbook Is (and Isn't) the Right Choice

A good fit when:

  • You need wallet-grade address, UTXO and xpub lookups on a supported chain.
  • You want to self-host rather than depend on a third-party API.
  • You are comfortable operating a node and a database service.

Consider alternatives when:

  • Your chain or network is not in configs/coins/.
  • You need custom, contract-level event indexing with your own schema, which general-purpose indexing frameworks handle better.
  • You cannot dedicate the disk, memory and operational effort a full mainnet index needs.

Conclusion

Nodes store blockchains, and indexers make them usable. Blockbook gives you a proven, wallet-grade indexer for a wide range of networks, with a clean API on top of a fast RocksDB store.

The setup itself is straightforward: verify the node, build the binary, point the configuration at the node, and run it as a service. The real work is operational. Budget enough memory for the heavy blocks, avoid anything that kills the process during the bulk sync, watch your disk, and keep the node's owner informed. Do those things and you end up with a self-hosted address index that answers in milliseconds the questions a bare node cannot answer at all.