Your first WebSocket session

The goal is an accepted subscription and a durably saved checkpoint. Start with arranged 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.

2. Authenticate

Send this template before hello.limits.authTimeoutMs expires:

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

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

{"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, recovery and the durable consumer pseudocode.