Blockchain Data WebSocket Streaming

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

Environment	Protocol	Endpoint
Production	`WSS`	`wss://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

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":{}}'

import os, json, websocket

def on_open(ws):
    ws.send(json.dumps({
        "action": "subscribe",
        "chain_id": 1,
        "dataset_id": "0101",
        "params": {}
    }))

def on_message(ws, msg):
    print(msg)

ws = websocket.WebSocketApp(
    "wss://api.blockdb.io/v1/evm/",
    header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
    on_open=on_open,
    on_message=on_message,
)
ws.run_forever()

const WebSocket = require('ws');

const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
  headers: { Authorization: `Bearer ${process.env.BLOCKDB_API_KEY}` }
});

ws.on('open', () => {
  ws.send(JSON.stringify({
    action: 'subscribe',
    chain_id: 1,
    dataset_id: '0101',
    params: {}
  }));
});

ws.on('message', (data) => console.log(data.toString()));

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 ID	Stream
`0101`	Blocks
`0102`	Transactions
`0103`	Logs
`0111`	Internal transactions
`0121`	Contracts
`0122`	Function results
`0201`	ERC-20 tokens
`0202`	ERC-721 tokens
`0203`	ERC-1155 tokens
`0211`	Liquidity pools
`0212`	Fee terms
`0301`	Reserves
`0302`	Swap prints
`0303`	Swap fees
`0304`	Token transfers
`0305`	Flash loan prints
`0404`	OHLC
`0405`	VWAP
`0501`	Fiat VWAP (USD)
`0601`	TVL USD
`0701`	Arb paths
`0702`	Arb path status
`0801`	Arb opportunities
`0411`	Yields

Connection Behavior

Behavior	Detail
Heartbeats	Server sends periodic `ping` frames. Respond with `pong` (most libraries handle this automatically). Connections idle for more than 60 s may be terminated.
Reconnection	On disconnect, implement exponential backoff before reconnecting.
Message ordering	Messages within a single stream are delivered in processing order.
Reorg handling	When 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.

About BlockDB

Real-Time Delivery

Archive Delivery

WebSocket

Overview

Endpoint & Authentication

Quickstart

2) Server acknowledgement

3) Live update message

4) Unsubscribe

Available Streams

Connection Behavior

Full Reference

WSS Introduction

Quickstart

EVM Streams Overview

Protobuf (HFT)

​Overview

​Endpoint & Authentication

​Quickstart

​1) Connect & subscribe

​2) Server acknowledgement

​3) Live update message

​4) Unsubscribe

​Available Streams

​Connection Behavior

​Full Reference

WSS Introduction

Quickstart

EVM Streams Overview

Protobuf (HFT)

Overview

Endpoint & Authentication

Quickstart

1) Connect & subscribe

2) Server acknowledgement

3) Live update message

4) Unsubscribe

Available Streams

Connection Behavior

Full Reference