> ## Documentation Index
> Fetch the complete documentation index at: https://routeme.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket API

RouteMesh supports real-time event streams over WebSocket using the standard Ethereum `eth_subscribe` / `eth_unsubscribe` protocol. This lets you receive pushed notifications — like new blocks or contract logs — without polling.

## Connecting

Connect to the WebSocket URL with your API key in the path (same keys you use for HTTP RPC):

```text theme={null}
wss://lb.routeme.sh/rpc/{chain_id}/{api_key}
```

The connection must be upgraded from HTTP. On a successful handshake, the server returns an `X-WebSocket-Session-ID` header you can use for debugging.

The handshake validates your API key, origin, and credit balance before the socket is upgraded. Common handshake failures return an HTTP status before upgrade:

* **402** — Insufficient credits
* **429** — Service draining or too many concurrent connections from your IP (a `Retry-After` header tells you when to retry)
* **503** — All connection slots are currently in use
* **401** — Unauthorized (invalid or inactive API key)

## Subscribing and receiving notifications

To subscribe, send `eth_subscribe` with a subscription type:

```json theme={null}
{"jsonrpc":"2.0","method":"eth_subscribe","params":["newHeads"],"id":1}
```

The server replies with a subscription ID, then streams notifications to you as JSON-RPC `eth_subscription` messages:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x0f5f...",
    "result": { ... }
  }
}
```

To stop receiving events for a subscription, send `eth_unsubscribe` with the subscription ID.

## Supported subscription types and pricing

The available subscription types (and their prices) can change as we add chains and providers, so instead of a static list use the live endpoints:

* `GET /pricing/ws` — current WebSocket notification prices per chain and subscription type (price per million notifications)
* `GET /chains/ws` — the chains currently supported over WebSocket

## Reliability

RouteMesh runs WebSocket streams with the same redundancy we apply to HTTP RPC:

* **Seamless provider failover** — if the upstream node behind your subscription goes down, RouteMesh transparently reconnects to an alternate provider while keeping your connection alive. You don't need to re-subscribe.
* **Gap backfill and deduplication** — when we fail over to an alternate provider, we replay any notifications missed during the switch, drop duplicate events, and keep the stream in order, so you don't lose data while connected.

Because this recovery happens while your connection stays open, you get a durable event stream for the lifetime of the socket. If your client disconnects, subscriptions end with the connection — reconnect and re-subscribe to continue.