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

# Introduction

> Protocol details for BlockDB's WebSocket (WSS) feed: authentication, subscription lifecycle, and reliability.

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

<Note>
  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 [support@blockdb.io](mailto:support@blockdb.io).
</Note>

## Endpoints

We provide a unified streaming endpoint for all EVM datasets.

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

## Authentication

Authentication is performed during the WebSocket handshake using a Bearer token in the `Authorization` header.

```http theme={null}
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://api.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`.

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

**Response Example (Success):**

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

**Response Example (Error):**

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

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

**Response Example (Success):**

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

## Message Format

Every data message delivered by the stream follows a consistent envelope:

<ResponseField name="chain_id" type="number">
  The identifier of the EVM network.
</ResponseField>

<ResponseField name="dataset_id" type="string">
  The identifier of the dataset (e.g., `0101` for Blocks).
</ResponseField>

<ResponseField name="data" type="object">
  The payload containing the actual record. See specific stream pages for schema details.
</ResponseField>

## 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 `is_reorg: true` to indicate that the update is a canonical correction.
* **Lineage**: Every message includes a `_tracing_id`, which can be used to correlate real-time events with historical archive data.