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

# WebSocket lifecycle

> How to connect, subscribe, handle acknowledgments, process events, unsubscribe, and reconnect to the Relayer WebSocket.

Use one Relayer WebSocket connection to send control messages and receive events for subscribed topics.

## Definition

Client-to-server messages are control messages. A control message has an `action`, optional `requestId`, and action-specific fields. Server-to-client messages are acknowledgments or pushed events.

## Lifecycle

<Steps>
  <Step title="Connect">
    Open `wss://relayer.xoxno.com/ws` for subscriptions, `broadcast`, and `relay`. Use `wss://relayer.xoxno.com/ws/stats` only for push-only network stats.
  </Step>

  <Step title="Subscribe">
    Send `{"action":"subscribe","topic":"..."}` for each topic you need.
  </Step>

  <Step title="Read the acknowledgment">
    Match `requestId` when present. Acknowledgment success means the Relayer accepted the control message; future event delivery still depends on matching chain activity.
  </Step>

  <Step title="Process events">
    Branch on `type`, such as `gasStats`, `networkStats`, `accountDelta`, or `txStatus`.
  </Step>

  <Step title="Unsubscribe and reconnect">
    Unsubscribe from topics you no longer need. After reconnect, re-send subscriptions because topic state belongs to the prior connection.
  </Step>
</Steps>

## Limits

| Action                 | Limit                                               |
| ---------------------- | --------------------------------------------------- |
| Active topics          | 64 per connection                                   |
| Message size           | 4 MB                                                |
| Gas stats debounce     | 50 ms, with 5 s periodic fallback                   |
| Network stats interval | Adaptive, default about 6 s, clamped 500 ms to 30 s |

## Worked Example

```ts theme={"system"}
const ws = new WebSocket("wss://relayer.xoxno.com/ws");

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    action: "subscribe",
    requestId: "gas-1",
    topic: "gasStats"
  }));
});

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  if (msg.action === "subscribe") console.log("ack", msg.status);
  if (msg.type === "gasStats") console.log("gas", msg.data);
});
```

## Reconnect Rules

| Case                 | Client action                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------ |
| Socket closes        | Reconnect with exponential backoff and jitter                                              |
| Reconnect succeeds   | Re-subscribe to required topics                                                            |
| Topic limit reached  | Unsubscribe from inactive topics or open another connection                                |
| Duplicate event risk | De-duplicate by transaction hash, address and nonce, or event timestamp depending on topic |

## Related Pages

* [Subscribe action](/api-reference/ws/subscribe)
* [Unsubscribe action](/api-reference/ws/unsubscribe)
* [Connection limits](/relayer/connection-limits)
* [WebSocket protocol](/api-reference/websocket-protocol)