Skip to main content
Transient network instability, brief client-side hiccups, and other short-lived connectivity disruptions can interrupt a WebSocket connection for a few seconds at a time. A WebSocket session lets a reconnecting client be recognized as the same client picking up where it left off — enabling backfill, which automatically recovers any order events missed during the gap instead of requiring a full reconciliation from scratch.

​
Scope

A session is available on the order stream only — the Order Creation Stream for perpetuals, the Order Management Stream for options. No other stream is session-aware yet.

​
Starting a Session

Add an optional sessionId (UUID) query parameter to the connection URL. Generate one value and reuse it across reconnects to keep the same session:
Omit sessionId to skip starting a session — the connection behaves as a one-off, with no missed messages backfilled and no Summary Message sent.

​
Resumed vs. Fresh Sessions

Whether a session continued or started over is reported as a resumed field on the Summary Message. A session can be resumed for up to 1 minute after a disconnect. Reconnecting with the same sessionId within that window continues the session: resumed is true, and the backfill covers whatever was missed since the last message delivered on the prior connection. resumed is false when either:
  • The connection uses a sessionId that hasn’t been seen before, or
  • The connection reuses a sessionId from a prior session, but reconnects after the 1-minute window has elapsed
In both cases there is no prior position to resume from, so nothing is backfilled. Reconcile local order state from scratch using the HTTP API or emit requests on the relevant streams.

​
Backfill

When sessionId is supplied, backfill runs automatically on connect: any missed messages on the order stream are delivered first, followed by a sessionBackfill message summarizing the session. The summary is sent on every connection that carries a sessionId, even one not subscribed to the order stream.

​
Summary Message

See Order Creation Stream (or the options Order Management Stream) for the exact message shape.

​
Limits

Backfill is capped at 500 missed events per market (or per contract, for Options), and at 10 markets (or contracts) per reconnect. For each market or contract with at least one missed event:
  • If 500 or fewer events accumulated while disconnected, all of them are backfilled and the market (or contract) is listed in backfilledMarkets
  • If more than 500 accumulated, none are backfilled and the market (or contract) is listed in expiredMarkets instead — reconcile that market’s order state from scratch via the HTTP API or emit requests on the relevant streams
  • If more than 10 markets (or contracts) missed events, only the 10 most recently active are replayed, each still subject to the 500-event cap; the rest are listed in expiredMarkets, so reconcile them the same way. On Options, where each contract is its own stream, an account active on many contracts should expect this after most reconnects
No silent gaps: every market or contract with missed activity appears in exactly one of the two arrays.

​
Releasing Capital on Disconnect

A disconnect does not cancel your orders. Sessions are resumable, so resting orders stay on the book through the reconnect window and beyond, and the margin they reserve stays committed until they fill, expire, or you cancel them. To release that capital on demand, cancel every resting order at once. For Options, the operation is deliberately available on both transports, so losing one never leaves you unable to flatten: Both requests cancel the same orders and report through the same Order Management Stream, so whichever connection is still up is the one to use:
  • WebSocket dropped — call the HTTP endpoint. The per-order cancelOrder results are backfilled when the session resumes (within the Limits); otherwise reconcile from Get Open Orders.
  • HTTP unavailable — send cancelAllOrders over the open WebSocket.
The two differ only in what they report. The HTTP response lists every orderId it queued. The WebSocket acknowledgment carries a count, and one cancelOrder confirmation follows per order, each tagged with the sweep’s clientRequestId; the acknowledgment and the confirmations arrive in any order. An empty sweep is still acknowledged, with count: 0. Single cancels are rate limited on both products. On Options the sweep has its own budget, separate from single cancels, and costs one unit per call on either transport however many orders it cancels, so a user who has spent the cancel budget can still close out; the cancels it expands into cost nothing. Over WebSocket the sweep has to find room in a bounded lane of in-flight sweeps; when it cannot, it is refused as TOO_MANY_INFLIGHT_ORDERS (10007) and nothing is cancelled. On a partial options connection (an underlying, expiration or strike without the type) the sweep covers every contract under that prefix. Perpetuals has no WebSocket sweep yet: use Cancel Orders over REST, which cancels by market or across all markets.