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

# WebSocket feed

> Authenticate, renew, subscribe, synchronize, and recover current live feeds.

Use WebSocket events as invalidation hints. REST remains the source of truth.

```text theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
wss://ws.swap.shield.fi/ws
```

## Authentication and renewal

1. Request a ticket from `GET /auth/ws-ticket` with a browser session or `ss_...` API token.
2. Open the socket and send `authenticate` within five seconds.
3. Subscribe only after authentication succeeds.
4. Request and send a new ticket before the 60-second ticket expires.

The socket accepts only WebSocket tickets. It rejects session JWTs and API tokens in the frame.

```json theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
{"action":"authenticate","token":"<ticket>"}
```

Reauthentication must use the same principal. An expired ticket ends the connection if no valid renewal extends it.

## Subscribe and synchronize

```json theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
{"action":"subscribe","room":"trades:<pool_key>"}
{"action":"unsubscribe","room":"trades:<pool_key>"}
{"action":"synchronize"}
```

After reconnecting, restore subscriptions and send `synchronize`. Wait for `{"control":"synchronized"}`. Then refetch every REST resource that depends on the stream.

## Rooms

| Room                    | Purpose                                                   |
| ----------------------- | --------------------------------------------------------- |
| `pool_launches`         | Newly indexed pools                                       |
| `pool_stats:<pool_key>` | Price and liquidity changes                               |
| `ohlcv:<pool_key>`      | Candle updates                                            |
| `trades:<pool_key>`     | Swap and LP activity                                      |
| `balances:<address>`    | Balance-change hints for the authenticated ticket subject |
| `protocol_config`       | Revisioned protocol-configuration invalidations           |

One connection can subscribe to at most 32 rooms. It accepts at most 240 client frames per minute and 2 KB per frame.

## Events and controls

Event types are `PoolLaunch`, `PoolStats`, `Ohlcv`, `Trade`, `BalanceChange`, and `ProtocolConfigChanged`.

Treat `ProtocolConfigChanged` as invalidation data. Fetch:

```text theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
GET /protocol/state?minimum_revision=<revision>
```

If the API returns `503 protocol_revision_pending`, wait for `Retry-After`. Discard or requote any route whose `protocol_revision` is older than the event revision.

Known controls are `synchronized` and `resync_required`. On `resync_required`, refetch affected REST state. Ignore unknown future control values.

## Delivery and reconnect

Delivery is at most once. The server does not replay missed events. During deployment it can close with code 1012. Reconnect with backoff and jitter, obtain a fresh ticket, restore rooms, synchronize, and reload REST snapshots.