Skip to main content

​
Overview

BlockDB WebSocket (WSS) streams provide low-latency, push-based access to real-time blockchain events. Unlike REST APIs that require polling, WSS streams deliver data as soon as it is processed by our ingestion engine—typically under 150 ms from the block being seen on the P2P network.
BlockDB’s WebSocket delivery is currently in the development and testing phase. If you encounter issues or have specific throughput requirements, please contact us at [email protected].

​
Endpoints

We provide a unified streaming endpoint for all EVM datasets.
EnvironmentProtocolEndpoint
ProductionWSSwss://stream.blockdb.io/v1/evm/

​
Authentication

Authentication is performed during the WebSocket handshake using a Bearer token in the Authorization header. 
GET /v1/evm/stream HTTP/1.1
Host: api.blockdb.io
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer <YOUR_API_KEY>
Alternatively, for clients that do not support custom headers during the handshake, you can pass the API key via the api_key query parameter: wss://stream.blockdb.io/v1/evm/?api_key=YOUR_API_KEY

​
Subscription Lifecycle

Once connected, you must send a JSON message to subscribe to specific datasets. The server will acknowledge your request with a status message.

​
1. Subscribe

To start receiving data, send a subscribe action with the target chain_id, dataset_id, and any optional filters in params. 
{
  "action": "subscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "params": {}
}
Response Example (Success): 
{
  "chain_id": 1,
  "dataset_id": "0101",
  "action": "subscribe",
  "status": "success"
}
Response Example (Error): 
{
  "chain_id": 1,
  "dataset_id": "0101",
  "action": "subscribe",
  "status": "error",
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request contains invalid or missing parameters.",
    "hint": "Ensure 'chain_id' is provided and valid.",
    "severity": "error",
    "retryable": false,
    "details": {
      "invalid_parameters": [
        {
          "name": "chain_id",
          "reason": "missing"
        }
      ]
    },
    "docs_url": "https://docs.blockdb.io/wss-reference/overview/introduction"
  }
}

​
2. Unsubscribe

To stop receiving data from a stream without closing the connection: 
{
  "action": "unsubscribe",
  "chain_id": 1,
  "dataset_id": "0101"
}
Response Example (Success): 
{
  "chain_id": 1,
  "dataset_id": "0101",
  "action": "unsubscribe",
  "status": "success"
}

​
Message Format

Every data message delivered by the stream follows a consistent envelope:
​
chain_id
number
The identifier of the EVM network.
​
dataset_id
string
The identifier of the dataset (e.g., 0101 for Blocks).
​
data
object
The payload containing the actual record. See specific stream pages for schema details.

​
Connection Management

  • Heartbeats: The server sends periodic ping frames. Clients must respond with pong frames to keep the connection alive. Most WebSocket libraries handle this automatically.
  • Idle Timeout: Connections with no active subscriptions or heartbeat responses for more than 60 seconds may be terminated.
  • Reconnection: In the event of a disconnect, clients should implement exponential backoff.

​
Reliability & Reorgs

  • Ordering: Messages within a single stream are delivered in the order they are processed.
  • Reorganizations: BlockDB is reorg-aware. When a chain reorganization occurs, the stream will emit messages with the _is_reorg: true flag to indicate that a block is being re-submitted or updated in the canonical record.
  • Lineage: Every message includes a _tracing_id, which can be used to correlate real-time events with historical archive data.