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

# WebSockets

> Subscribe to live Polymarket onchain events — trading, positions, market lifecycle, oracle, and resolution.

Radion WebSockets send you Polymarket events live. You get each event the moment it is confirmed on the blockchain. You can also get pending transactions from the Polygon mempool, before they land in a block. One open connection can hold many subscriptions at once, and you can mix confirmed and pending subscriptions. So you get only the data you want, and you never have to poll.

## Use cases

<CardGroup cols={3}>
  <Card title="Mirror a wallet" icon="copy">
    Follow a wallet and copy its moves in real time. See its trades the moment
    they land onchain.
  </Card>

  <Card title="Wallet alerts" icon="bell">
    Get a signal whenever a wallet you watch buys, sells, or moves money.
  </Card>

  <Card title="Whale watching" icon="fish">
    See big trades. Stream only fills above a USD amount you pick.
  </Card>

  <Card title="Market monitoring" icon="chart-line">
    Watch open interest, liquidity, and price ticks for every market. No need to
    poll the REST API.
  </Card>

  <Card title="Resolution tracking" icon="flag">
    Listen for oracle events to know the second a market resolves.
  </Card>

  <Card title="Mempool / early visibility" icon="hourglass">
    Get pending transactions from the Polygon mempool, before they are in a
    block.
  </Card>
</CardGroup>

## Endpoint

```text theme={null}
wss://api.radion.app/ws
```

Put your API key in the `X-API-Key` header of the WebSocket upgrade request. See [Authentication](/websockets/authentication) for the details and safety tips.

<Note>
  One connection can hold many subscriptions, and you can mix confirmed and
  pending subscriptions. How many connections and subscriptions you may open
  depends on your [plan](/websockets/rate-limits).
</Note>

## Quickstart

```js theme={null}
import WebSocket from "ws";

const ws = new WebSocket("wss://api.radion.app/ws", {
  headers: { "X-API-Key": process.env.RADION_API_KEY },
});

ws.on("open", () => {
  ws.send(
    JSON.stringify({ action: "subscribe", id: "s1", channel: "trading" })
  );
});

ws.on("message", (raw) => {
  const frame = JSON.parse(raw.toString());
  console.log(frame.type, frame.channel, frame.data);
});
```

1. **Connect** — open the socket with your `X-API-Key` header.
2. **Subscribe** — send a `subscribe` message with the channel name (and filters if you want).
3. **Receive** — read the JSON frames that come back. Each one has a `type`, a `channel`, and a `data` payload.

See [Subscribe](/websockets/subscribe) for every message shape, and [Frames](/websockets/frames) for the full frame reference.

## Channels at a glance

| Channel                                         | Purpose                                                                 |
| ----------------------------------------------- | ----------------------------------------------------------------------- |
| [`trading`](/websockets/channels/trading)       | Order fills, matches, cancels, preapprovals, and trading pauses.        |
| [`fees`](/websockets/channels/fees)             | Exchange fees charged on trades.                                        |
| [`oracle`](/websockets/channels/oracle)         | UMA Adapter and UMA Optimistic Oracle question events.                  |
| [`resolution`](/websockets/channels/resolution) | Condition resolutions, reported results, and resolution pauses.         |
| [`lifecycle`](/websockets/channels/lifecycle)   | Market, event, condition, and token preparation.                        |
| [`positions`](/websockets/channels/positions)   | CTF base-layer splits, merges, and payout redemptions.                  |
| [`combos`](/websockets/channels/combos)         | Module, neg-risk, combinatorial, bridge, and migration position events. |
| [`transfers`](/websockets/channels/transfers)   | ERC-1155 outcome-token transfers.                                       |
| [`accounts`](/websockets/channels/accounts)     | Proxy and deposit wallet creation.                                      |
| [`wallets`](/websockets/channels/overview)      | Events that touch one or more wallet addresses.                         |
| [`markets`](/websockets/channels/overview)      | Events that touch market ids or token ids.                              |

Use [filters](/websockets/filters) to narrow a channel down to certain wallets, markets, tokens, or trade sizes. Watching big trades? Subscribe to `trading` with a `min_usd` filter.

## Connection lifecycle

1. **Open** — start the WebSocket connection with your API key in the upgrade header.
2. **Authenticate** — Radion checks the key and accepts the connection. A bad key returns HTTP `401`.
3. **Subscribe** — send one or more `subscribe` messages to start getting frames on the channels you name.
4. **Receive frames** — handle the JSON event and control frames until you are done or an error happens.
5. **Reconnect** — if the connection drops, connect again with exponential back-off, then send your subscriptions again. See [Connection state](/websockets/connection-state) for heartbeat and reconnect tips.

## Further reading

<CardGroup cols={2}>
  <Card title="Examples" icon="code" href="/websockets/examples">
    Ready-to-run Node.js + TypeScript examples for every channel.
  </Card>

  <Card title="Authentication" icon="key" href="/websockets/authentication">
    Put your API key in the upgrade request.
  </Card>

  <Card title="Subscribe" icon="satellite-dish" href="/websockets/subscribe">
    Subscribe, unsubscribe, and ping messages.
  </Card>

  <Card title="Channels" icon="list" href="/websockets/channels/overview">
    Full channel list with typed schemas.
  </Card>

  <Card title="Filters" icon="funnel" href="/websockets/filters">
    Narrow a channel to wallets, markets, tokens, or size.
  </Card>

  <Card title="Frames" icon="braces" href="/websockets/frames">
    Event, control, and error frame shapes.
  </Card>

  <Card title="Mempool" icon="hourglass" href="/websockets/mempool">
    Pending transactions before they are in a block.
  </Card>

  <Card title="Connection state" icon="plug" href="/websockets/connection-state">
    Reconnect, heartbeats, and the health endpoint.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/websockets/rate-limits">
    Connection and subscription limits per plan.
  </Card>

  <Card title="Limitations" icon="triangle-alert" href="/websockets/limitations">
    What the WebSocket streams do and do not promise.
  </Card>
</CardGroup>