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

# Connection Management

> How to connect, authenticate, and handle WebSocket reconnection

This page covers establishing a WebSocket connection, authentication, and handling disconnections.

## Timeout

Maximum session timeout is 1 hour. Clients must manage reconnections.

## Heartbeat

The server sends WebSocket ping frames every 30 seconds. The heartbeat timer refreshes when:

* A pong frame is received
* Any subscribe or unsubscribe activity occurs

## Authentication

All WebSocket connections require authentication via the `Sec-Websocket-Protocol` header:

```
Sec-Websocket-Protocol: decibel, <API_KEY>
```

Replace `<API_KEY>` with your Bearer token from [Geomi](https://geomi.dev/docs/start).

See [REST Authentication](/api-reference/rest/authentication) for how to get credentials.

## Subscribe/Unsubscribe

Send a JSON message with `method` and `topic`:

```json theme={null}
{"method":"subscribe","topic":"account_open_orders:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba"}
```

**Success response:**

```json theme={null}
{"success":true,"method":"subscribe","topic":"account_open_orders:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba"}
```

**Error response (invalid topic type):**

```json theme={null}
{"success":false,"method":"subscribe","topic":"asd:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba","error":"Unknown topic type 'asd'"}
```

To unsubscribe, use `"method":"unsubscribe"` with the same topic.

## Handling Reconnection

Since the maximum session timeout is 1 hour, your client must handle reconnections gracefully.

### Best Practices

1. Implement exponential backoff for reconnection attempts
2. Track active subscriptions to restore them after reconnecting
3. Use sequence numbers to detect missed messages (for orderbook updates)

## Error Messages

Error responses use the same format as subscribe/unsubscribe responses:

```json theme={null}
{
  "success": false,
  "method": "subscribe",
  "topic": "depth:invalid_address",
  "error": "Invalid market address 'invalid_address' for depth topic"
}
```

### Common Errors

| Error                                                        | Cause                                                                         |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `Unknown topic type '{name}'`                                | Unrecognized channel name                                                     |
| `Missing user address for {topic} topic`                     | Topic requires a user/account address but none provided                       |
| `Missing market address for {topic} topic`                   | Topic requires a market address but none provided                             |
| `Invalid user address '{addr}'`                              | Malformed address                                                             |
| `Invalid market address '{addr}'`                            | Malformed address                                                             |
| `Invalid aggregation level '{level}' for depth topic`        | Must be one of: `1`, `2`, `5`, `10`, `100`, `1000`                            |
| `Invalid interval '{interval}' for market_candlestick topic` | Must be one of: `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `1d`, `1w`, `1mo` |
| `Maximum client topic subscription count of 100 reached`     | Too many active subscriptions on one connection                               |

## SDK Managed Connections

The TypeScript SDK handles connection management automatically. See [TypeScript SDK Overview](/typescript-sdk/overview).

## Related

<CardGroup cols={2}>
  <Card title="WebSocket Overview" href="/api-reference/websocket/overview">
    Available channels and message formats
  </Card>

  <Card title="Authentication" href="/api-reference/rest/authentication">
    How to get bearer tokens
  </Card>
</CardGroup>