Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The WebSocket channel (beta) delivers real-time payloads as soon as BlockDB finalizes them — ideal for trading, monitoring, or alerting stacks that can’t wait for polling intervals. Events mirror the schemas in the data catalog and preserve _tracing_id so you can reconcile back to archives.
BlockDB WebSocket processing time — end-to-end latency from on-chain finalization to payload delivery.
WebSocket delivery is currently in beta. For issues or throughput requirements, contact support@blockdb.io.

​
Endpoint & Authentication

EnvironmentProtocolEndpoint
ProductionWSSwss://api.blockdb.io/v1/evm/
Authenticate during the WebSocket handshake using a Bearer token: 
GET /v1/evm/ HTTP/1.1
Host: api.blockdb.io
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer <YOUR_API_KEY>
If your client cannot send custom headers during the handshake, pass the key as a query parameter: 
wss://api.blockdb.io/v1/evm/?api_key=YOUR_API_KEY

​
Quickstart

​
1) Connect & subscribe

export BLOCKDB_API_KEY="..."
wscat -c wss://api.blockdb.io/v1/evm/ \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -x '{"action":"subscribe","chain_id":1,"dataset_id":"0101","params":{}}'

​
2) Server acknowledgement

{
  "action": "subscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "status": "success"
}

​
3) Live update message

Every data payload follows this envelope: 
{
  "chain_id": 1,
  "dataset_id": "0101",
  "is_reorg": false,
  "data": {
    "block_number": 12345678,
    "block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
    "timestamp_utc": "2025-11-11T18:42:15.123Z",
    "_tracing_id": "010100000000000000000000000000000000",
    "_is_reorg": false
  }
}

​
4) Unsubscribe

Stop a stream without closing the connection: 
{
  "action": "unsubscribe",
  "chain_id": 1,
  "dataset_id": "0101"
}

​
Available Streams

Subscribe using dataset_id — IDs match the data catalog and REST API identifiers.
Dataset IDStream
0101Blocks
0102Transactions
0103Logs
0111Internal transactions
0121Contracts
0122Function results
0201ERC-20 tokens
0202ERC-721 tokens
0203ERC-1155 tokens
0211Liquidity pools
0212Fee terms
0301Reserves
0302Swap prints
0303Swap fees
0304Token transfers
0305Flash loan prints
0404OHLC
0405VWAP
0501Fiat VWAP (USD)
0601TVL USD
0701Arb paths
0702Arb path status
0801Arb opportunities
0411Yields

​
Connection Behavior

BehaviorDetail
HeartbeatsServer sends periodic ping frames. Respond with pong (most libraries handle this automatically). Connections idle for more than 60 s may be terminated.
ReconnectionOn disconnect, implement exponential backoff before reconnecting.
Message orderingMessages within a single stream are delivered in processing order.
Reorg handlingWhen a chain reorganization occurs, affected messages include "_is_reorg": true. Use _tracing_id to correlate with archive records.

​
Full Reference

WSS Introduction

Protocol details: authentication, subscription lifecycle, and message format.

Quickstart

Full code examples in bash, Python, Node.js, Go, .NET, and C.

EVM Streams Overview

Complete stream matrix with links to per-dataset schema pages.

Protobuf (HFT)

Binary-encoded streams for latency-critical and high-frequency trading applications.
Last modified on April 3, 2026