> 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.

# Connection and authentication

Use WSS with JSON text frames. The endpoint and permitted account scopes are supplied through arranged access.

```text
server → hello
client → authenticate
client → subscribe
server → subscribed
server → matching batches → checkpoint → caught_up
server → live batches / checkpoints
client → ack after committing the checkpoint locally
```

There can be zero matching batches at the fixed cut. Checkpoint and `caught_up` still complete the catch-up phase. V1 has no `authenticated` frame.

## Authentication and deadlines

`authenticate.ticket` contains the API key in JSON, never in a URL. Authenticate within `hello.limits.authTimeoutMs`, then subscribe within `subscribeTimeoutMs`. Stop frequent retries when access is rejected.

Client frames require `version: 1` and the appropriate `kind`. Unknown fields in frames, filters and start objects are rejected. `start` must explicitly select `live_cut` or `resume`; it cannot be null.

Client IDs are 1–128 ASCII characters: letters, digits, `.`, `:`, `_`, `-`. Ticket and token values are 1–2048 ASCII characters: letters, digits, `.`, `_`, `-`. Their syntax does not establish credential validity. Copy issued values unchanged.

## Sequence and heartbeat

Every server application frame has a decimal-string `frameSequence`. Hello starts at `"1"`; subsequent values increase by one. Reconnect creates a new sequence and connection ID.

Heartbeat uses native client WebSocket Ping and server Pong, echoing the Ping payload. These are not JSON `ping` messages and do not consume frame sequences. `serverPingIntervalMs` is null; it does not promise automatic server pings.

The implementation caps client frames at 262144 bytes and server frames at 20971520 bytes. These are shape/size bounds, not throughput guarantees or recommended frame sizes. Apply current account and runtime limits as well.

Keep TLS certificate validation enabled. After transport failure, preserve the committed checkpoint and follow [recovery](/polymarket/stream/recovery). Exact message definitions are in [frames](/polymarket/reference/frames).