Building on self-hosted Bitcoin infrastructure has always meant writing the same glue code — stitching together disparate protocols, managing connections, layering in caching.

blockd replaces that with a single REST and WebSocket endpoint, batched and cached, on one port with one auth model.

---

The Stack

blockd runs co-located with two services it depends on:

bitcoind is the reference implementation of the Bitcoin protocol — a full node that independently downloads, validates, and stores the entire blockchain, enforcing consensus rules without trusting any third party. This self-sovereign validation is the foundation the whole stack rests on. blockd interfaces with bitcoind in two ways: via its JSON-RPC API for queries and commands, and via ZMQ for real-time event streaming — new transactions, new blocks, and mempool sequencing.

Fulcrum handles address indexing and scripthash notifications — it implements the ElectrumX protocol and is the clear performance leader among indexer implementations. See the Sparrow server performance comparison for benchmarks. blockd was developed and tested exclusively against Fulcrum. Other ElectrumX-compatible servers are untested and not supported.

When blockd refers to electrum in configuration and API responses, it means the ElectrumX protocol — not the Electrum wallet.

Together, bitcoind and Fulcrum do the heavy lifting — verifying blocks, indexing addresses, tracking the mempool. But their interfaces are low-level, uncoordinated, and often challenging for modern application development. blockd orchestrates them as a single system — the missing layer that complements the stack and makes it ready to build on.

---

What blockd does

Wallet data, fast. blockd can scan transaction history in sub-second time. It derives your full address set from an extended public key, queries the indexer, fetches transactions, resolves block headers, and computes your UTXO set — then caches everything in RocksDB for instant repeated access.

Real-time address watching. Once a wallet is imported, blockd subscribes to addresses in the set via Fulcrum’s scripthash notification protocol. When any of those addresses see new activity, your app is notified immediately through the WebSocket. You get both historical data and live updates through the same interface — workflows populate the cache, subscriptions keep you current from that point forward.

Multi-wallet support. blockd manages multiple wallets simultaneously. Each is identified by a user-defined name — like test/wallet-1 or mainnet/cold-storage. Behind that simple interface, blockd is managing address derivation, indexer subscriptions, and cache entries for every tracked wallet. Your app just uses the name.

bitcoind RPC proxy. blockd exposes a curated, permissioned set of Core RPC methods through its workflow interface — batched, cached, and accessible over REST. You use bitcoind’s own documentation for method signatures and responses. blockd doesn’t reinvent or re-document the RPC interface, it just makes it available through a modern API with sane access controls.

Node lifecycle awareness. blockd monitors the full node lifecycle — IBD, indexer catch-up, syncing, degraded, ready — and exposes it through a structured health API and WebSocket subscription. During IBD, your app can surface block loading speed and estimated completion time directly to the user. blockd also detects chain reorganizations and identifies the affected block heights, so your app can invalidate stale cache and re-fetch cleanly. See IBD & Node Lifecycle for details.

Fine-grained progress, at two levels. workflow.progress events report percent complete at the step level — driving a progress indicator scoped to a specific operation your app triggered. server.health IBD fields report node-level progress — block loading speed and estimated completion — driving a first-run onboarding view while the node becomes usable for the first time.

---

Workflows

Blockchain data retrieval is multi-step and can be slow by nature. Workflows are blockd’s solution — a declarative list of steps submitted in a single request. blockd returns a workflow ID immediately and executes them asynchronously, caching results in RocksDB. Your app checks status, then queries the cache when ready.

See Workflow Model for the full model, and the REST Workflows for the complete step and parameter reference.

---

Endpoints

Method	Endpoint	Description
GET	/version	blockd and connected service versions
GET	/health	Server health
GET	/health/{level}	Health at basic, tip, or detailed verbosity
GET	/workflows	List queued and running workflows
GET	/workflows/{id}	Get a specific workflow
POST	/workflows	Submit a new workflow
DELETE	/workflows/{id}	Cancel or delete a workflow
GET	/workflows/{id}/results/core	Results of a core.* workflow
POST	/pubkeys-set/txns	Query transactions for a pubkeys set
POST	/pubkeys-set/utxos	Query UTXOs for a pubkeys set

---

WebSocket events

Connect to ws://<node-ip>:21000/events, authenticate, and subscribe to the topics your app needs:

{
  "subscriptions": [
    {"subscribe": "block.activity"},
    {"subscribe": "pubkeys.activity", "args": {"pubkeys_set": "test/wallet-1"}},
    {"subscribe": "workflow.progress"},
    {"subscribe": "server.health", "args": {"interval": 30, "detailed": true}}
  ]
}

Subscription	Description
server.health	Periodic server health snapshots, including IBD progress
workflow.progress	Step-level progress for running workflows
pubkeys.activity	Activity on a tracked wallet’s addresses
block.activity	Block tip changes, including reorg detection
core.hashblock	New block hash from bitcoind
core.hashtx	New transaction hash from bitcoind
core.rawblock	Raw block bytes from bitcoind
core.rawtx	Raw transaction bytes from bitcoind
core.sequence	Mempool and chain sequence events

See the WebSocket Overview for the full event schema, authentication, and connection lifecycle.

---

Network detection

blockd supports mainnet, signet, testnet, testnet4, and regtest. The active network is auto-detected at startup by querying both bitcoind and Fulcrum — blockd verifies they agree and will not start if they disagree. No network configuration is required.