Introduction
REST and WebSocket reference overview
blockd exposes its API through two complementary interfaces — REST and WebSocket — both on port 21000.
REST is request-driven. You make a request, you get a response. Use it to submit workflows, query cached results, and check server state. All endpoints are documented in REST Overview, including base URL, auth headers, compression, and error codes.
WebSocket is event-driven. Connect to /events, authenticate, subscribe to the topics your app needs, and blockd
pushes notifications as things happen — new blocks, address activity, workflow progress, health changes. Some events
carry a full payload; others are signals that something has changed, letting your app decide when to re-fetch. Listening
for events is generally preferable to polling. See WebSocket Overview for the full connection lifecycle,
subscription reference, and event schema.
One thing worth knowing before you connect: WebSocket requires a Sec-WebSocket-Protocol: blockd-v1 header at
upgrade — connections without it are rejected. Authentication also works differently from REST: instead of a Bearer
header, the first message after connect must be a JSON auth message. The WebSocket Overview covers both.
Most apps use both interfaces: REST to populate initial state on load, WebSocket to stay current from that point forward.
The workflow model
Section titled “The workflow model”Fetching wallet data is multi-step by nature — address derivation, indexer queries, transaction resolution, header fetching, UTXO computation. blockd doesn’t make you wait for this inline.
Instead, you submit a workflow — a declarative list of steps — and receive an ID immediately. blockd executes
asynchronously and caches results in RocksDB. Your app polls for completion or subscribes to workflow.progress
events, then reads from the cache when ready. Subsequent requests for the same data return directly from cache.
This pattern underlies most of what blockd does. Understanding it before reading the Workflows reference makes the step model and async status flow much easier to follow.
Where to go next
Section titled “Where to go next”| I want to… | Start here |
|---|---|
| Understand REST endpoints, auth, and errors | REST Overview |
| Fetch wallet transactions or UTXOs | REST Workflows |
| Monitor server and node health | Health & IBD Reference |
| Subscribe to live events | WebSocket Overview |
| Call a bitcoind RPC method | Core RPC Methods |
| Monitor workflow progress | REST Workflows / Activity Events |