> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.whalehunt.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.whalehunt.net/_mcp/server.

# Your first WebSocket session

The goal is an accepted subscription and a durably saved checkpoint. Start with [arranged access](/polymarket/access). The address and credentials below are synthetic templates; replace them with values permitted for your integration.

## 1. Open WSS and read hello

Validate `version`, `connectionId`, `streamId`, `historyGeneration`, `scope` and `limits`. Begin checking contiguous `frameSequence` values at `"1"`. The complete shape is in [frames](/polymarket/reference/frames).

## 2. Authenticate

Send this template before `hello.limits.authTimeoutMs` expires:

```json
{"version":1,"kind":"authenticate","ticket":"REPLACE_WITH_API_KEY"}
```

The placeholder is not a working key. There is no `authenticated` frame in v1. Send the subscription within `subscribeTimeoutMs`.

## 3. Subscribe

This is a complete subscribe template. Confirm the allowed stages before using it.

```json
{
  "version": 1,
  "kind": "subscribe",
  "requestId": "request-1",
  "consumerId": "consumer-1",
  "subscriptionId": "wallet-1",
  "filters": {
    "owners": ["0x1111111111111111111111111111111111111111"],
    "stages": ["pending", "included", "reverted", "canonicality", "resolution"]
  },
  "start": {"mode": "live_cut"}
}
```

`live_cut` explicitly starts at a new cut. An existing consumer recovering its saved state uses `resume` instead.

## 4. Save the response boundary

An accepted subscription produces `subscribed` with its generation and binding. Matching batches precede checkpoints; `caught_up` marks the fixed cut. A quiet wallet can have no matching batches and still reach a checkpoint.

Apply all effects through the checkpoint and save dedup state and the full token in one durable local transaction. Only after commit send ACK. This complete ACK template uses synthetic values: replace the token, connection ID and generation with the current server values.

```json
{"version":1,"kind":"ack","token":"REPLACE_WITH_CHECKPOINT_TOKEN","connectionId":"11111111-1111-4111-8111-111111111111","generation":"1"}
```

## 5. Prepare for a disconnect

Resume from the last locally committed token, even if its ACK was lost. A received batch or an ACK log entry is not your durable boundary. Handle a failed resume explicitly rather than silently choosing a new live cut.

Continue with [processing](/polymarket/stream/processing), [recovery](/polymarket/stream/recovery) and the [durable consumer pseudocode](/polymarket/examples/durable-consumer).