> ## 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.

# WebSocket

> Push-based blockchain data streams via WebSocket — EVM blocks, logs, liquidity & pricing events with sub-150 ms latency.

## 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](/data-catalog/evm/dataset-index) and preserve `_tracing_id` so you can reconcile back to archives.

<Frame>
  <img src="https://mintcdn.com/blockdb/dEbkQS4jcvgtKHAp/images/blockdb-processing-time.png?fit=max&auto=format&n=dEbkQS4jcvgtKHAp&q=85&s=dacf408f57d789a14d83d095c0a127d9" alt="BlockDB WebSocket processing time — end-to-end latency from on-chain finalization to payload delivery." width="1299" height="1045" data-path="images/blockdb-processing-time.png" />
</Frame>

<Note>
  WebSocket delivery is currently in beta. For issues or throughput requirements, contact [support@blockdb.io](mailto:support@blockdb.io).
</Note>

***

## Endpoint & Authentication

| Environment | Protocol | Endpoint                       |
| :---------- | :------- | :----------------------------- |
| Production  | `WSS`    | `wss://api.blockdb.io/v1/evm/` |

Authenticate during the WebSocket handshake using a Bearer token:

```http theme={null}
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

<CodeGroup>
  ```bash bash theme={null}
  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":{}}'
  ```

  ```python Python theme={null}
  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()
  ```

  ```javascript Node.js theme={null}
  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()));
  ```
</CodeGroup>

### 2) Server acknowledgement

```json theme={null}
{
  "action": "subscribe",
  "chain_id": 1,
  "dataset_id": "0101",
  "status": "success"
}
```

### 3) Live update message

Every data payload follows this envelope:

```json theme={null}
{
  "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:

```json theme={null}
{
  "action": "unsubscribe",
  "chain_id": 1,
  "dataset_id": "0101"
}
```

***

## Available Streams

Subscribe using `dataset_id` — IDs match the [data catalog](/data-catalog/evm/dataset-index) and REST API identifiers.

| Dataset ID | Stream                                                                       |
| :--------- | :--------------------------------------------------------------------------- |
| `0101`     | [Blocks](/wss-reference/evm/primitives/blocks)                               |
| `0102`     | [Transactions](/wss-reference/evm/primitives/transactions)                   |
| `0103`     | [Logs](/wss-reference/evm/primitives/logs)                                   |
| `0111`     | [Internal transactions](/wss-reference/evm/primitives/internal-transactions) |
| `0121`     | [Contracts](/wss-reference/evm/primitives/contracts)                         |
| `0122`     | [Function results](/wss-reference/evm/primitives/function-results)           |
| `0201`     | [ERC-20 tokens](/wss-reference/evm/entities/tokens-erc20)                    |
| `0202`     | [ERC-721 tokens](/wss-reference/evm/entities/tokens-erc721)                  |
| `0203`     | [ERC-1155 tokens](/wss-reference/evm/entities/tokens-erc1155)                |
| `0211`     | [Liquidity pools](/wss-reference/evm/entities/pools)                         |
| `0212`     | [Fee terms](/wss-reference/evm/entities/fee-terms)                           |
| `0301`     | [Reserves](/wss-reference/evm/reserves/reserves)                             |
| `0302`     | [Swap prints](/wss-reference/evm/prices/crypto/prices-spot-prints)           |
| `0303`     | [Swap fees](/wss-reference/evm/swaps/swap-fees)                              |
| `0304`     | [Token transfers](/wss-reference/evm/transfers/token-transfers)              |
| `0305`     | [Flash loan prints](/wss-reference/evm/flash-loans/flash-loan-prints)        |
| `0404`     | [OHLC](/wss-reference/evm/prices/crypto/prices-spot-ohlc)                    |
| `0405`     | [VWAP](/wss-reference/evm/prices/crypto/prices-spot-vwap)                    |
| `0501`     | [Fiat VWAP (USD)](/wss-reference/evm/prices/fiat/prices-spot-vwap-fiat)      |
| `0601`     | [TVL USD](/wss-reference/evm/tvl/tvl-usd)                                    |
| `0701`     | [Arb paths](/wss-reference/evm/arbitrage/arb-paths)                          |
| `0702`     | [Arb path status](/wss-reference/evm/arbitrage/arb-path-status)              |
| `0801`     | [Arb opportunities](/wss-reference/evm/arbitrage/arb-opportunities)          |
| `0411`     | [Yields](/wss-reference/evm/yields/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

<CardGroup cols={2}>
  <Card title="WSS Introduction" icon="book-open" href="/wss-reference/overview/introduction">
    Protocol details: authentication, subscription lifecycle, and message format.
  </Card>

  <Card title="Quickstart" icon="rocket-launch" href="/wss-reference/overview/quickstart">
    Full code examples in bash, Python, Node.js, Go, .NET, and C.
  </Card>

  <Card title="EVM Streams Overview" icon="list" href="/wss-reference/evm/overview">
    Complete stream matrix with links to per-dataset schema pages.
  </Card>

  <Card title="Protobuf (HFT)" icon="bolt" href="/user-guide/real-time-delivery/protobuf">
    Binary-encoded streams for latency-critical and high-frequency trading applications.
  </Card>
</CardGroup>