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

# WebSockets

> Subscribe to live Alterscope data streams over WebSocket.

Alterscope publishes live updates over WebSocket. Streams are read-only and filtered per connection; filters are query-string only and are locked at connect time.

<Note>
  WebSocket streams require the **Analyst tier or higher** — the Free tier is REST-only. See [Rate limits](/develop/get-started/rate-limits) for per-tier WebSocket connection counts.
</Note>

## Connect

Connect to `wss://api.alterscope.org/v2/ws/<stream>`. Browsers can't set an `Authorization` header on a WebSocket, so the key is passed as a `token` query parameter; server-side clients can use either.

```javascript theme={null}
const ws = new WebSocket(
  `wss://api.alterscope.org/v2/ws/risk-events?token=${process.env.ALTERSCOPE_API_KEY}`,
);
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  console.log(msg);
};
```

Keep the connection alive with your client's ping/pong; on disconnect, reconnect with backoff and re-apply your filters (filters are fixed for the life of a connection).

## Streams

| Stream       | Path                   | Carries                                                        |
| ------------ | ---------------------- | -------------------------------------------------------------- |
| Risk events  | `/v2/ws/risk-events`   | Depeg, oracle-stale, cap-change, anomaly, regime-shift events. |
| Yield        | `/v2/ws/yield`         | New opportunities, APR shifts, risk-factor changes.            |
| Yield stats  | `/v2/ws/yield/stats`   | Aggregate yield-universe statistics.                           |
| Factors      | `/v2/ws/factors`       | Factor-value changes.                                          |
| Factor stats | `/v2/ws/factors/stats` | Aggregate factor statistics.                                   |

Cross-chain fragmentation (`/v2/ws/cross-chain/fragmentation/{assetId}`) and the generic data multiplexer (`/v2/ws/data/...`) are also available.

## Filtering

Each stream accepts query-string filters, set once at connect. For example, the risk-events stream filters on `types`, `severity`, `subject_id`, `chain`, and `protocol`; the yield stream filters on `chain`, `protocol`, `asset`, and `min_apr`. Try the filters interactively in the [Playground](/develop/realtime/playground).

The `types` filter takes exact event-type strings — see the [Event catalog](/develop/realtime/event-catalog) for every type the risk-events stream carries, when each fires, and a sample payload.

## Message shape

Stream messages carry the same `meta._agentic` freshness/quality signal as REST responses — see [Response envelope](/develop/concepts/response-envelope). For recovery of events missed while disconnected, see [Webhooks → replay](/develop/realtime/webhooks).