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

# subscribe

> Subscribe to a real-time topic on the XOXNO Relayer WebSocket.

Subscribe to a topic to receive events. The Relayer acknowledges the subscription and starts pushing data immediately.

## Endpoint

`wss://relayer.xoxno.com/ws`

## Body

<ParamField body="action" type="string" required>
  Must be `"subscribe"`.
</ParamField>

<ParamField body="topic" type="string" required>
  Topic to subscribe to. Supported topics:

  | Topic              | Description                                       | Delivery                      |
  | ------------------ | ------------------------------------------------- | ----------------------------- |
  | `gasStats`         | Per-shard gas prices and PPU with percentiles     | 50 ms debounce / 5 s periodic |
  | `networkStats`     | Full network snapshot                             | Adaptive (tracks block time)  |
  | `accounts`         | All account deltas network-wide                   | On each finalized block       |
  | `address/{bech32}` | Account deltas + tx status for a specific address | Event-driven                  |
  | `tx-status/{hash}` | Status updates for a specific transaction         | Event-driven                  |
</ParamField>

## Response

<ResponseField name="action" type="string">
  `"subscribe"`
</ResponseField>

<ResponseField name="status" type="string">
  `"ok"` on success, `"fail"` on error.
</ResponseField>

<ResponseField name="topic" type="string">
  Topic that was subscribed.
</ResponseField>

<ResponseField name="reason" type="string">
  Present when `status` is `"fail"`. See the error table below.
</ResponseField>

## Errors

| Reason                            | Cause                                              |
| --------------------------------- | -------------------------------------------------- |
| `topic limit reached`             | Connection has 64 active subscriptions             |
| `rate limit exceeded`             | More than 64 control messages in a 5-second window |
| `invalid bech32 address in topic` | Address failed bech32 validation                   |
| `unknown topic`                   | Topic matches no supported pattern                 |

<RequestExample>
  ```json Request theme={"system"}
  {
    "action": "subscribe",
    "topic": "address/erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={"system"}
  {
    "action": "subscribe",
    "status": "ok",
    "topic": "address/erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th"
  }
  ```

  ```json Error theme={"system"}
  {
    "action": "subscribe",
    "status": "fail",
    "reason": "topic limit reached"
  }
  ```
</ResponseExample>