Cursor & replay

Every event carries a cursor. Save the last cursor you processed and pass it when resubscribing after a disconnect. Missed events are replayed before the subscription settles into the live stream.

Cursor format

slot:transactionIndexInBlock:eventIndexInTransaction

Example:

436312304:15:0

The three components identify one event deterministically. Clients should still treat the complete value as an opaque string: persist and compare it without constructing new cursors.

Resume a subscription

cursor belongs in the command envelope next to stream, not inside params:

{
  "op": "subscribe",
  "id": 1,
  "stream": "token_trades",
  "cursor": "436312304:15:0",
  "params": { "mint": "DD9e..." }
}

An omitted cursor, an empty string, and "0" all mean “start live”.

Replay window

Plan	Replay window
Free	No replay
Starter	20 seconds
Pro	60 seconds
Scale	60 seconds

Replay is recovery after a short disconnect, not historical storage. Events outside the window are unavailable.

Ordering

Replay and live events can arrive interleaved. Restore order using the cursor; do not assume WebSocket arrival order separates replay from live delivery.

Rate limits

A key can request replay six times per hour, with at most three consecutive replays. Once the limit is exhausted:

1. the subscription still opens,
2. a replay_rate_limited notice is sent,
3. delivery starts from live events.

If the cursor is older than the available window, the subscription also opens from live and sends a gap notice.