WebSocket ProtocolCopy Anchor Link

Connect to the sufwan-local-test WebSocket API to receive live aggregated orderbook updates, public trades, cross-venue arbitrage-return updates, catalog changes, JSON heartbeat events, and authenticated user events across connected venues. Browsers connect with your app ID; backends connect with an API key and can also stream every user's events.

wss://ws.t.sufwankhalid.com/ws?appId=YOUR_APP_ID

Orderbooks can also stream from a dedicated orderbook socket at wss://ob.agg.market/ws, which adds an opt-in realtime tier and the orderbook firehose.

There is no midpoint channel. A midpoint field on an orderbook frame is not a subscription.

Getting connectedCopy Anchor Link

const ws = new WebSocket(`wss://ws.t.sufwankhalid.com/ws?appId=${appId}`);

{
  "type": "connected",
  "appId": "app_demo123",
  "protocolVersion": 2,
  "auth": "browser"
}

{
  "action": "subscribe",
  "channel": "orderbook",
  "outcomeIds": ["vmo_1", "vmo_2"]
}

Server connectionsCopy Anchor Link

Backends authenticate the handshake with an API key from the admin dashboard (Develop → API). The key replaces the Origin check, and the connection is metered per key rather than per IP, so many sockets from one server are fine.

import { createAggClient } from "@agg-build/sdk";

const client = createAggClient({
  baseUrl: "https://api.t.sufwankhalid.com",
  wsUrl: "wss://ws.t.sufwankhalid.com/ws",
  appId: process.env.AGG_APP_ID,
  apiKey: process.env.AGG_API_KEY, // sent as x-app-api-key, never from a browser
});

const ws = client.createWebSocket({ onError: (e) => console.error(e.code, e.message) });
ws.subscribe("vmo_1");

On Node versions without a global WebSocket, pass the ws package to the SDK: client.createWebSocket(callbacks, { webSocketImpl: WebSocket }).

Orderbook socketCopy Anchor Link

The orderbook channel is also served on a socket of its own:

wss://ob.agg.market/ws?appId=YOUR_APP_ID

Connect to it the same way as above. Browsers are admitted by an allowed Origin, servers by x-app-api-key on the handshake, and you wait for connected before subscribing. An API key is not required for the per-outcome orderbook channel.

orderbook_snapshot and orderbook_delta are the same objects on both sockets. Everything in Orderbook stream applies. The orderbook socket adds two things:

{
  "action": "subscribe",
  "channel": "orderbook",
  "outcomeIds": ["vmo_1"],
  "latency": "realtime"
}

seq is counted separately on each tier. Do not compare a conflated seq with a realtime seq for the same outcome. Sending latency on wss://ws.t.sufwankhalid.com/ws does not turn on realtime.

In the SDK, set orderbookUrl on createAggClient to move only the orderbook channel to this socket, and orderbookLatency to pick the tier. See Orderbook streams for both, and Orderbook firehose for the whole-venue feed.

1. Orderbook streamCopy Anchor Link

Subscribe to an outcome's orderbook to receive a full snapshot followed by incremental deltas. Each outcome has its own orderbook — there is no complement derivation. Levels carry venue attribution for the outcome's venue, and the venue's own book is included alongside.

The snapshot and delta objects below do not change on the orderbook socket. That page is where orderbookUrl moves this channel onto a second socket, and where the optional latency field selects realtime. The default remains the 100 ms conflated tier. A whole-venue feed is the Orderbook firehose.

SubscribeCopy Anchor Link

{
  "action": "subscribe",
  "channel": "orderbook",
  "outcomeIds": ["vmo_1"]
}

You receive a confirmation before the initial snapshot:

{
  "type": "subscribed",
  "outcomeIds": ["vmo_1"],
  "channel": "orderbook"
}

Initial snapshotCopy Anchor Link

{
  "type": "orderbook_snapshot",
  "outcomeId": "vmo_1",
  "seq": 1710000001,
  "checksum": 2918476531,
  "bids": [
    [0.55, 800, { "predict": 800 }],
    [0.54, 400, { "predict": 400 }]
  ],
  "asks": [
    [0.56, 600, { "predict": 600 }],
    [0.57, 300, { "predict": 300 }]
  ],
  "venueOrderbooks": {
    "predict": {
      "bids": [[0.55, 800], [0.54, 400]],
      "asks": [[0.56, 600], [0.57, 300]]
    }
  },
  "venues": {
    "predict": { "bestBid": 0.55, "bestAsk": 0.56 }
  },
  "midpoint": 0.555,
  "spread": 0.01,
  "timestamp": 1710000000000
}

Orderbook timestamp is Unix milliseconds on the wire, and the SDK reports it as seconds.

If no orderbook is available for an id, you get an error whose message starts with Snapshot unavailable for <outcomeId> instead of a snapshot. The subscription stays active, so deltas may still arrive: ignore deltas for an outcome you have no book for. Check that the id is an outcome id (outcomes[].id), not a market id, then retry with resnapshot after a delay rather than in a loop.

Incremental deltasCopy Anchor Link

{
  "type": "orderbook_delta",
  "outcomeId": "vmo_1",
  "seq": 1710000002,
  "checksum": 3847261950,
  "bidChanges": [
    [0.55, 900, { "predict": 900 }]
  ],
  "askChanges": [],
  "venueDeltaBooks": {
    "predict": {
      "bidChanges": [[0.55, 900]],
      "askChanges": []
    }
  },
  "venues": {
    "predict": { "bestBid": 0.55, "bestAsk": 0.56 }
  },
  "midpoint": 0.555,
  "spread": 0.01,
  "timestamp": 1710000001000
}

Market resolvedCopy Anchor Link

After you subscribe to orderbook for an outcome, a resolution or close arrives once as market_resolved. The outcome's orderbook and trade subscriptions end with it: nothing further arrives, and you don't need to unsubscribe. Trade-only subscribers are not sent this message. result is the label of the first outcome with winner: true, or null when none is marked winner. outcomes[] are the sibling outcomes for that market.

{
  "type": "market_resolved",
  "outcomeId": "vmo_1",
  "status": "resolved",
  "result": "Yes",
  "outcomes": [
    {
      "label": "Yes",
      "winner": true,
      "externalIdentifier": "yes-token",
      "payoutPerShare": 1,
      "refundAtCost": false
    },
    {
      "label": "No",
      "winner": false,
      "externalIdentifier": "no-token",
      "payoutPerShare": 0,
      "refundAtCost": false
    }
  ],
  "timestamp": 1710000000000
}

status is resolved or closed. outcomes can be empty, and winner is omitted when it isn't known. payoutPerShare and refundAtCost are omitted when the venue did not report them. winnerSource is venue or matched and is omitted when winner is or when the winner predates this field; a matched winner is provisional (see Inferred winners). Settlement meaning is on Market resolution.

Sequencing and resyncCopy Anchor Link

Every orderbook message includes a seq value for that outcome. seq is monotonic within one stream of the book. Your client is responsible for maintaining local book state and detecting integrity issues.

Apply deltas when delta.seq === book.seq + 1. After applying, recompute the checksum (XOR of per-level CRC32 values) and compare it to checksum in the message. If they match, the book is consistent. The exact level encoding is in the market-data guide.

Drop stale deltas where delta.seq <= book.seq — these can arrive after a subscribe when deltas predate the initial snapshot. Silently discard them.

Request a resnapshot if you detect a forward gap (delta.seq > book.seq + 1) or a checksum mismatch:

{
  "action": "resnapshot",
  "channel": "orderbook",
  "outcomeIds": ["vmo_1"]
}

Always replace your book with an orderbook_snapshot, even when its seq is lower than yours. If sufwan-local-test rebuilds an outcome's book, that book starts a new seq stream. When the first update from the rebuilt book arrives, the gateway sends you a fresh orderbook_snapshot without being asked. Apply the following deltas against the snapshot's seq.

UnsubscribeCopy Anchor Link

{
  "action": "unsubscribe",
  "channel": "orderbook",
  "outcomeIds": ["vmo_1"]
}

Staleness checksCopy Anchor Link

Heartbeats prove the connection is alive, not that each outcome is updating. A quiet market can legitimately go several minutes without a delta, so silence alone is not an error, and silence alone can't tell you a stream has stopped reaching you.

We recommend a 5-minute REST watchdog for every client that keeps books open. The gateway can only resend a snapshot when it sees a new update, so a quiet book that went wrong stays wrong. The watchdog confirms each book against the server instead of trusting that the stream is still flowing.

1. Once a minute, find subscribed outcomes whose book has not changed for 5 minutes.
2. Fetch up to 100 of them with GET /orderbooks/outcomes?venueMarketOutcomeIds=id1,id2,…&depth=1 (see Market-data API). Results come back in request order, with null for an id that can't be served.
3. Compare each returned seq with your book's seq:
   • Same: the market is quiet and your book is current. Reset its 5-minute timer.
   • Different: you missed updates. Send resnapshot for that outcome.
   • Still different on the next check: unsubscribe and subscribe the outcome. That resets all per-subscription state on the gateway.
4. Ignore an outcome whose book changed while the request was in flight. Its seq moved on for a normal reason.

Each outcome in a batch costs one market-data quota unit, so check only silent outcomes. On a 429, wait for Retry-After before the next check.

// `books` and `ws` come from your client; see the raw example below.
const SILENCE_MS = 5 * 60_000;
const lastChange = new Map(); // outcomeId -> ms; set on every snapshot and applied delta
const resnapshotted = new Set();
let inFlight = false;
let pausedUntil = 0;

setInterval(async () => {
  const now = Date.now();
  if (inFlight || now < pausedUntil) return;
  const silent = [...books.keys()]
    .filter((id) => now - (lastChange.get(id) ?? now) >= SILENCE_MS)
    .slice(0, 100);
  if (silent.length === 0) return;

  const asked = new Map(silent.map((id) => [id, lastChange.get(id)]));
  const url = new URL("https://api.t.sufwankhalid.com/orderbooks/outcomes");
  url.searchParams.set("venueMarketOutcomeIds", silent.join(","));
  url.searchParams.set("depth", "1");

  inFlight = true;
  try {
    const res = await fetch(url, { headers: { "x-app-id": appId } });
    if (res.status === 429) {
      pausedUntil = Date.now() + Number(res.headers.get("retry-after") ?? 60) * 1000;
      return;
    }
    if (!res.ok) return;
    const { data } = await res.json();

    silent.forEach((id, i) => {
      const server = data[i];
      const book = books.get(id);
      // Skip ids the server can't serve, and books that changed while we asked.
      if (!server || !book || lastChange.get(id) !== asked.get(id)) return;

      if (server.seq === book.seq) {
        lastChange.set(id, Date.now());
        resnapshotted.delete(id);
      } else if (!resnapshotted.has(id)) {
        resnapshotted.add(id);
        lastChange.set(id, Date.now()); // give the snapshot a full window
        ws.send(JSON.stringify({ action: "resnapshot", channel: "orderbook", outcomeIds: [id] }));
      } else {
        resnapshotted.delete(id);
        ws.send(JSON.stringify({ action: "unsubscribe", channel: "orderbook", outcomeIds: [id] }));
        ws.send(JSON.stringify({ action: "subscribe", channel: "orderbook", outcomeIds: [id] }));
      }
    });
  } finally {
    inFlight = false;
  }
}, 60_000);

Best practicesCopy Anchor Link

Connection

• Wait for connected before you subscribe. Only the first 20 messages sent before it are kept; the rest are dropped.
• Answer protocol pings. Browsers and most WebSocket libraries do this automatically; a connection that misses two pings in a row is closed.
• Treat 45 seconds without any frame, heartbeats included, as a dead connection and reconnect. Heartbeats arrive every 30 seconds.
• Reconnect with exponential backoff and jitter. After reconnecting, discard your books, subscribe again to everything, and rebuild from the new snapshots. Subscriptions don't survive a new connection.
• Don't keep reconnecting on 4001 or 4003. Those mean a missing app id, an inactive or unknown app, a disallowed origin, a missing or revoked API key, or a non-user token, and retrying won't help until the configuration is fixed.

Orderbooks

• Apply a delta only when its seq is exactly one more than your book's, and verify its checksum.
• On a forward seq gap or a checksum mismatch, send resnapshot. Never keep patching a book you can't verify.
• Replace your book on every orderbook_snapshot, whatever its seq.
• Run the 5-minute REST watchdog.
• On market_resolved, drop that outcome's book.

Throughput

• Subscribe only to outcomes you are displaying or trading, and unsubscribe when you stop.
• Keep your message handler fast and move heavy work off it. If your client falls more than about 1 MB behind, the gateway skips frames for it. On orderbooks this shows up as a seq gap, which a resnapshot repairs. If it stays behind for 10 seconds, the connection is closed with 4008. Reconnect and resume to recover user events. Skipped trades, heartbeats, arbitrage updates and market_resolved messages are not resent.

Authentication

• Use the authenticate message. The token URL parameter is deprecated.
• On auth_expiring, refresh the token and send authenticate again. After any reconnect, authenticate with resumeFrom set to your last eventId.
• If resumed arrives with complete: false, reload orders, balances and withdrawals over REST.
• Backends: authenticate the handshake with x-app-api-key instead of setting an Origin. Send the key only from your backend, never from a browser.

SDK, hooks, and UI orderbooks are on Real-Time Orderbook. That page does not repeat these frames.

2. Trade streamCopy Anchor Link

Subscribe to the public trade feed for an outcome. No user auth is required.

SubscribeCopy Anchor Link

{
  "action": "subscribe",
  "channel": "trades",
  "outcomeIds": ["vmo_1"]
}

Confirmation:

{
  "type": "subscribed",
  "outcomeIds": ["vmo_1"],
  "channel": "trades"
}

Trade eventCopy Anchor Link

{
  "type": "trade",
  "outcomeId": "vmo_1",
  "venue": "hyperliquid",
  "side": "buy",
  "price": 0.55,
  "size": 100,
  "timestamp": 1710000000000,
  "tradeId": "915328169553830"
}

tradeId is the venue's own id for the fill, present when the venue supplies one (Hyperliquid today). Use it to deduplicate. Two fills can share side, price, size and millisecond timestamp, so those fields alone cannot identify a trade.

UnsubscribeCopy Anchor Link

{
  "action": "unsubscribe",
  "channel": "trades",
  "outcomeIds": ["vmo_1"]
}

For chart-building patterns on top of orderbook and trade data, see Real-Time Charts.

3. Authenticated user eventsCopy Anchor Link

Receive user-specific events, such as order confirmations and balance updates, after the connection has user-level auth.

AuthenticateCopy Anchor Link

Send the user's access token after connected:

{
  "action": "authenticate",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

{
  "type": "authenticated",
  "userId": "usr_xyz789",
  "expiresAt": 1710000900000
}

expiresAt is when the token expires (Unix ms). Send authenticate again with a refreshed token at any time. That re-authenticates without opening a second socket, and it also switches users. Suspended users are refused. A user can hold at most 20 authenticated sockets at once.

Session lifetimeCopy Anchor Link

A user session on the socket lasts only as long as its token:

• About a minute before expiry you receive auth_expiring. Refresh the token and send authenticate again.
• At expiry, or within a minute of the user signing out elsewhere or being suspended, you receive auth_expired. The connection stays open at app level: market data keeps flowing, but user events stop until you authenticate again.

{ "type": "auth_expiring", "userId": "usr_xyz789", "expiresAt": 1710000900000 }

{ "type": "auth_expired", "userId": "usr_xyz789", "reason": "expired" }

reason is expired, revoked (signed out or token version bumped) or suspended. Clients created with AggClient.createWebSocket() refresh and re-authenticate for you.

Event ids and resumeCopy Anchor Link

Every user event carries an eventId, along with stream: "user" and the userId. Ids increase within the stream. Keep the last one you processed. When you reconnect, pass it as resumeFrom:

{
  "action": "authenticate",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "resumeFrom": "1710000000123-0"
}

The gateway replays the events after that id, marked "replayed": true, before live events continue. Then it sends:

{
  "type": "resumed",
  "stream": "user",
  "fromEventId": "1710000000123-0",
  "replayed": 3,
  "complete": true
}

• The replay starts slightly before your cursor and may resend events you already have. De-duplicate by eventId.
• complete: false means some events may be missing. This happens when the cursor is older than 24 hours, more than the last 500 events have passed, or the event log was unavailable. In that case, reload orders, balances and withdrawals over REST.
• An event with no eventId was delivered while the event log was unavailable, and a resume can't replay it.

The SDK tracks the cursor, resumes and de-duplicates automatically. Resume covers reconnects. Webhooks remain the durable record for your backend.

Order submittedCopy Anchor Link

{
  "type": "order_submitted",
  "userId": "usr_xyz789",
  "venue": "predict",
  "orderId": "ord_abc123",
  "side": "buy",
  "price": 0.55,
  "size": 100,
  "outcomeId": "vmo_1",
  "timestamp": 1710000000000,
  "eventId": "1710000000123-0",
  "stream": "user"
}

Balance updateCopy Anchor Link

{
  "type": "balance_update",
  "venue": "predict",
  "tradingBalanceCents": 94500,
  "walletBalanceCents": 100000,
  "timestamp": 1710000000000
}

Order eventCopy Anchor Link

Venue-agnostic stream of execution-plan lifecycle and terminal order status events. Emitted for every active venue (Polymarket, Kalshi, Predict, …) automatically — no per-venue handling on the client. Discriminate on the event field.

Step lifecycle (progress UI)Copy Anchor Link

{
  "type": "order_event",
  "event": "step_started",
  "userId": "usr_xyz789",
  "orderId": "ord_abc123",
  "dagRunId": "dag_mnp...",
  "stepId": "execute-...",
  "stepType": "submit-order",
  "sequence": 3,
  "totalSteps": 7,
  "venue": "polymarket",
  "timestamp": 1710000000000
}

event values: step_started | step_completed | step_waiting | step_failed | step_retrying.

sequence is the 1-based declaration index of the step within the execution plan, and totalSteps is the total step count. Pair them to render progress like "Step 3 of 7". dag_started also carries totalSteps so the UI can show an empty progress bar before the first step runs. For branching execution plans, sequence reflects declaration order, not strict execution order — parallel branches may emit non-monotonic sequence values.

Terminal fill (success toast + position refresh)Copy Anchor Link

{
  "type": "order_event",
  "event": "filled",
  "userId": "usr_xyz789",
  "orderId": "ord_abc123",
  "venue": "polymarket",
  "filledAmountRaw": "1000000",
  "remainingAmountRaw": "0",
  "timestamp": 1710000000000
}

event values: filled | partial_fill. remainingAmountRaw is present only on partial_fill.

Failure (error toast)Copy Anchor Link

{
  "type": "order_event",
  "event": "failed",
  "userId": "usr_xyz789",
  "orderId": "ord_abc123",
  "venue": "polymarket",
  "errorReason": "Polymarket CLOB error (400): ...",
  "timestamp": 1710000000000
}

event values: failed (order-level) | dag_failed (execution-plan-level).

Execution plan lifecycle (optional)Copy Anchor Link

{
  "type": "order_event",
  "event": "dag_started",
  "userId": "usr_xyz789",
  "orderId": "ord_abc123",
  "dagRunId": "dag_mnp...",
  "templateName": "route-execution",
  "totalSteps": 7,
  "timestamp": 1710000000000
}

event values: dag_started | dag_completed | dag_failed | dag_cancelled.

redeem_event reports EVM redemption completion. See Market resolution for how to track claims and update positions.

For a notification-focused recipe, see User Notifications. That page does not repeat these frames.

4. Arbitrage streamsCopy Anchor Link

Stream the live cross-venue arbitrage return (arbReturn) for matched markets — the estimated return, as a decimal fraction (e.g. 0.012 = 1.2%), from the best prices across the venues in a matched cluster. This is the same value returned by the List Venue Events API; the stream keeps it live.

There are two ways to consume it: a per-market channel for a focused view (one or a few markets), and a single coalesced feed channel for a whole listing.

Per-market channelCopy Anchor Link

Subscribe with one or more marketIds (a market's id) to receive an update whenever that market's arbitrage return moves.

{
  "action": "subscribe",
  "channel": "arb",
  "marketIds": ["vm_1", "vm_2"]
}

Confirmation. The ack field outcomeIds contains the marketIds you subscribed:

{
  "type": "subscribed",
  "outcomeIds": ["vm_1", "vm_2"],
  "channel": "arb"
}

Update message — published per market as the value changes:

{
  "type": "arb_market_update",
  "marketId": "vm_1",
  "activeVenuesOnly": true,
  "venueEventId": "ve_1",
  "arbReturn": 0.012,
  "ts": 1710000000000
}

activeVenuesOnly is always true: the value only reflects active venues. venueEventId is the parent event of the market (or null), so you can roll updates up to an event-level value (e.g. the max across an event's markets).

Unsubscribe:

{
  "action": "unsubscribe",
  "channel": "arb",
  "marketIds": ["vm_1"]
}

Feed channelCopy Anchor Link

For a listing of many markets, subscribe once to the coalesced feed instead of managing a subscription per visible market. No ids are sent.

{
  "action": "subscribe",
  "channel": "arb-feed"
}

Confirmation:

{
  "type": "subscribed",
  "channel": "arb-feed"
}

Batch message — emitted on a short coalescing interval, carrying only the markets whose arbReturn changed since the last flush (deduped to the latest value per market):

{
  "type": "arb_feed_batch",
  "feed": "arb",
  "activeVenuesOnly": true,
  "entries": [
    { "marketId": "vm_1", "venueEventId": "ve_1", "arbReturn": 0.012, "ts": 1710000000000 },
    { "marketId": "vm_2", "venueEventId": "ve_1", "arbReturn": 0.004, "ts": 1710000000000 }
  ],
  "flushTs": 1710000000300,
  "chunk": 0,
  "chunkCount": 1
}

Unsubscribe:

{
  "action": "unsubscribe",
  "channel": "arb-feed"
}

5. App events (server-to-server)Copy Anchor Link

A backend connected with an API key can receive every user event of its app on one socket. These are the same frames as in section 3: order submitted, balance update, order, redeem and withdrawal events. Each one carries its userId.

{ "action": "subscribe", "channel": "app-events" }

{ "type": "subscribed", "channel": "app-events" }

{
  "type": "order_event",
  "event": "filled",
  "userId": "usr_xyz789",
  "orderId": "ord_abc123",
  "venue": "polymarket",
  "filledAmountRaw": "1000000",
  "timestamp": 1710000000000,
  "eventId": "1710000000456-0",
  "stream": "app"
}

• The channel needs an x-app-api-key issued for this app on the handshake. Browser connections, and keys from another app, get app_events_forbidden.
• eventId here is the app stream's id, not the same as the user stream's id for the same event. Resume with { "action": "subscribe", "channel": "app-events", "resumeFrom": "<eventId>" }. The app stream keeps the last 10,000 events or 24 hours, whichever ends first. The resumed frame works as in Event ids and resume.
• Unsubscribe with { "action": "unsubscribe", "channel": "app-events" }.

const ws = client.createWebSocket(); // client created with apiKey, server-side
const stop = ws.subscribeAppEvents((event) => {
  // Raw frames: timestamps are milliseconds. Resumes across reconnects automatically.
  if (event.type === "order_event" && event.event === "filled") onFill(event.userId, event);
});

6. Catalog feedCopy Anchor Link

Stream new, changed and deleted events and markets, so you can keep your own copy of the catalog without polling. The channel is live only: frames sent while you were disconnected are not replayed. Pair it with the REST catch-up GET /catalog/changes, which serves the same items for the last 24 hours. The whole pattern, and the SDK's watchCatalog, is in Catalog Sync.

The channel works on browser and API-key connections. No user token is needed.

Subscribe, optionally narrowed by venue and entity kind:

{
  "action": "subscribe",
  "channel": "catalog",
  "venues": ["polymarket", "kalshi"],
  "entities": ["market"],
  "id": "cat-1"
}

Confirmation:

{ "type": "subscribed", "channel": "catalog", "id": "cat-1" }

Subscribing again on the same connection replaces the filter. An invalid filter gets an invalid_message error and leaves the previous subscription in place.

Each change is one frame carrying the entity's current state:

{
  "type": "catalog_change",
  "entity": "market",
  "id": "vm_8f2c",
  "op": "updated",
  "version": 4,
  "changedAt": "2026-10-21T12:00:41.512Z",
  "venue": "kalshi",
  "market": {
    "id": "vm_8f2c",
    "venueEventId": "ve_51aa",
    "venue": "kalshi",
    "externalIdentifier": "KXFEDDECISION-26DEC-H0",
    "question": "Will the Fed hold rates in December 2026?",
    "shortTitle": "Hold",
    "status": "open",
    "startDate": "2026-10-20T14:00:00.000Z",
    "endDate": "2026-12-16T19:00:00.000Z",
    "createdAt": "2026-10-20T14:02:11.000Z",
    "outcomes": [
      { "id": "vmo_31d0", "label": "Yes", "title": null },
      { "id": "vmo_31d1", "label": "No", "title": null }
    ],
    "categories": [{ "id": "cat_econ", "name": "Economics" }],
    "matched": true,
    "clusterAnchorId": "vm_77a1",
    "clusterVenues": ["polymarket", "kalshi"]
  }
}

An event change carries an event snapshot instead (id, venue, externalIdentifier, title, slug, status, startDate, endDate, createdAt, categories and the same three matching fields). A delete carries only the id:

{
  "type": "catalog_change",
  "entity": "event",
  "id": "ve_51aa",
  "op": "deleted",
  "version": 9,
  "changedAt": "2026-10-21T12:03:02.004Z",
  "venue": null
}

• Apply a frame only when its (version, changedAt) is newer than what you hold for that (entity, id). Frames can repeat, and two quick edits can arrive as one frame.
• op is created, updated or deleted. On this channel created is best effort and the same entity can be announced as created twice. Treat created and updated as an upsert.
• clusterAnchorId can change as clusters gain and lose members. Key storage on id. See Matching fields.
• outcomes[].id is the outcome id the orderbook stream takes.
• Venues and categories disabled for your app are left out, except deletes.

On a stream_interrupted that lists catalog, or after any reconnect, frames may be missing: catch up over GET /catalog/changes from your last applied changedAt minus about a minute.

Unsubscribe:

{ "action": "unsubscribe", "channel": "catalog" }

Connection managementCopy Anchor Link

HeartbeatCopy Anchor Link

The service emits a JSON heartbeat event that clients can observe directly:

{
  "type": "heartbeat",
  "ts": 1710000000000
}

The gateway sends this event every 30 seconds, along with a protocol-level ping. Browsers don't expose pings to JavaScript, so use the JSON heartbeat (or any frame) as your liveness signal: if nothing arrives for 45 seconds, reconnect.

A connection that doesn't answer two pings in a row is closed by the server.

ReconnectionCopy Anchor Link

If the connection closes, reconnect with exponential backoff and jitter. Once the new connection sends connected, discard your books, subscribe again to everything, and authenticate with resumeFrom set to your last eventId. A catalog subscriber also re-runs its catch-up once the new subscription is confirmed:

function connect(attempt = 0) {
  const ws = new WebSocket(`wss://ws.t.sufwankhalid.com/ws?appId=${appId}`);

  ws.onclose = (event) => {
    if (event.code === 4001 || event.code === 4003) return; // configuration error: don't retry
    // 4008 (slow consumer) and 4029 (rate limited) are retryable with backoff.
    const delay = Math.min(1000 * 2 ** attempt + Math.random() * 1000, 30000);
    setTimeout(() => connect(attempt + 1), delay);
  };

  ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);
    if (msg.type === "connected") {
      attempt = 0;
      clearLocalBooks();
      resubscribeAll(ws);
      ws.send(JSON.stringify({ action: "authenticate", token, resumeFrom: lastEventId }));
    }
    // ...handle other messages
  };
}

Error handlingCopy Anchor Link

Protocol or validation errors arrive as JSON messages:

{
  "type": "error",
  "code": "subscription_limit",
  "message": "Rejected outcomes: vmo_9. Subscription limit reached (max 500)",
  "outcomeIds": ["vmo_9"],
  "id": "req-42"
}

Branch on code, not on message. outcomeIds (or marketIds for arb) lists the ids the error applies to. id echoes the id you put on the request. Any client frame can carry an id (string or number), and acks such as subscribed and authenticated echo it too.

An error about a request, such as a rejected subscription, leaves the connection open. An invalid token also leaves it open: the connection continues at app level.

Connection-level failures send an error and then close with one of these codes:

Stream interruptionsCopy Anchor Link

If the gateway loses its upstream feed briefly, every affected connection receives:

{ "type": "stream_interrupted", "channels": ["orderbook", "trades"], "timestamp": 1710000000000 }

Orderbooks are resnapshotted automatically, so expect fresh orderbook_snapshot frames to follow. Trades and arb updates published during the gap are not resent. When channels includes catalog, re-run the catalog catch-up from your last applied changedAt. User events are not affected, because they don't use this feed.

LimitsCopy Anchor Link

Limits apply per connection unless noted otherwise.

resnapshot only works for outcomes the connection is subscribed to, and a resnapshot already in flight for an outcome absorbs repeat requests for it.

RelatedCopy Anchor Link