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

# WebSocket Connection

> Connect to the 0xArchive WebSocket, authenticate, keep the socket alive, and reconnect safely.

Connect when you need streaming data or replay control. Use REST for one-off snapshots.

<Steps>
  <Step title="Open the socket">
    ```javascript theme={"theme":"github-dark"}
    const ws = new WebSocket("wss://api.0xarchive.io/ws?apiKey=0xa_your_api_key");
    ```
  </Step>

  <Step title="Subscribe after open">
    ```javascript theme={"theme":"github-dark"}
    ws.onopen = () => {
      ws.send(JSON.stringify({ op: "subscribe", channel: "orderbook", symbol: "BTC" }));
    };
    ```
  </Step>

  <Step title="Parse every message">
    ```javascript theme={"theme":"github-dark"}
    ws.onmessage = (event) => {
      const message = JSON.parse(event.data);
      console.log(message.type, message);
    };
    ```
  </Step>

  <Step title="Reconnect with backoff">
    Reconnect after close or network failure with capped backoff. Resubscribe only after the new socket opens.
  </Step>
</Steps>

## Keep Alive

```javascript theme={"theme":"github-dark"}
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ op: "ping" }));
  }
}, 25_000);
```

## Reconnect Policy

Reconnect with capped exponential backoff and jitter. Do not reconnect in a tight loop. After a new socket opens, resubscribe explicitly and rebuild any local state that depended on the previous stream. If the stream feeds a local book, replay window, alert, or model, treat the reconnect as a state transition that needs logging.

## Auth And Secrets

Use an API key from the environment or application secret store. The inline `apiKey` example is useful for a minimal connection, but production clients should avoid leaking keys into logs, browser URLs, telemetry, or copied prompts. If the client runs in a browser, proxy through your backend rather than exposing the key to users.

## Message Loop

Parse every message defensively. Expected classes include subscription acknowledgements, snapshots, updates, replay messages, pings or pongs, gap signals, and errors. Preserve any request or correlation identifiers that appear in the message so a streaming issue can be tied back to the connection session.

## Connection State Object

Use a local state object so reconnects and support logs describe the same stream.

```javascript theme={"theme":"github-dark"}
const streamState = {
  status: "connecting",
  activeSubscriptions: new Map(),
  lastMessageAt: null,
  retryCount: 0,
  gapEvents: [],
  unsafeSymbols: new Set()
};
```

Update it inside `onopen`, `onmessage`, `onerror`, and `onclose`. When the socket closes, clear old timers, move the status to `reconnecting`, open a new socket with backoff, then restore subscriptions from `activeSubscriptions`. If a gap arrives for a stateful channel, add the symbol to `unsafeSymbols` until the client rebuilds from a snapshot or replay checkpoint.

## Failure Classes

| Failure               | Client response                                                                |
| --------------------- | ------------------------------------------------------------------------------ |
| Auth or command error | Stop widening the stream and inspect key, command, channel, and symbol         |
| Network close         | Reconnect with capped backoff and restore tracked subscriptions                |
| Repeated close loop   | Stop after the configured retry budget and alert the owning job                |
| Gap event             | Mark derived local state incomplete until it is rebuilt                        |
| Consumer backlog      | Reduce channel count, slow replay, or move heavy work off the message callback |

## Review Rule

Connection examples should include close and error handling before they are copied into an application that maintains state. The reconnect path should recreate subscriptions from tracked state, not by replaying stale assumptions. Log close code, reason, retry count, and restored subscriptions so support can distinguish normal network churn from a broken consumer or bad auth state.