Skip to main content

​
What you’ll do

  • Connect to wss://stream.blockdb.io/v1/evm/
  • Authenticate with Authorization: Bearer <API_KEY> (or ?api_key= fallback)
  • Subscribe to a dataset (example: Blocks dataset_id: "0101")
  • Receive update messages
  • Unsubscribe cleanly without closing the socket

​
Prerequisites

  • A valid BlockDB API key (set as BLOCKDB_API_KEY)
  • A WebSocket client (CLI or SDK)

​
1) Connect

# CLI: connect (wscat)
export BLOCKDB_API_KEY="..."
wscat -c wss://stream.blockdb.io/v1/evm/ \
  -H "Authorization: Bearer $BLOCKDB_API_KEY"
If your client cannot send headers during the handshake, use the query parameter fallback: wss://stream.blockdb.io/v1/evm/?api_key=YOUR_API_KEY

​
2) Subscribe (client → server)

This starts a stream. You must provide:
  • action: "subscribe"
  • chain_id (EVM chain)
  • dataset_id (stream dataset)
  • params (stream-specific filters; use {} if none)
# Subscribe to Blocks (dataset_id 0101) on Ethereum mainnet (chain_id 1)
wscat -c wss://stream.blockdb.io/v1/evm/ \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -x '{"action":"subscribe","chain_id":1,"dataset_id":"0101","params":{}}'

​
3) Handle messages (server → client)

After subscribing you will receive:
  • subscribe_response (ack, success or error)
  • update messages (the live data)
subscribe_response (success)
{
  "action": "subscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "status": "success"
}
update
{
  "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 (client → server)

Unsubscribe stops a stream without closing the WebSocket. 
wscat -c wss://stream.blockdb.io/v1/evm/ \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -x '{"action":"unsubscribe","chain_id":1,"dataset_id":"0101"}'
unsubscribe_response (success): 
{
  "action": "unsubscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "status": "success"
}

​
Next steps