Real-Time Orderbook

The sufwan-local-test WebSocket delivers a full aggregated orderbook snapshot on subscribe, then incremental deltas as the book changes. Each outcome has its own orderbook — there is no complement derivation. Each level includes per-venue attribution so you can render both the aggregated depth and the venue breakdown from the same stream.

For bounded REST snapshots and the shared single/batch outcome-unit quota, see Market-data API. That guide also explains snapshotChecksum versus the full engine checksum and optional native Worker ownership.

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

const client = createAggClient({
  baseUrl: "https://api.t.sufwankhalid.com",
  appId: "your-app-id",
  wsUrl: "wss://ws.t.sufwankhalid.com/ws",
});

let book = null;

const ws = client.createWebSocket({
  onSnapshot: (_outcomeId, nextBook) => {
    book = nextBook;
    renderOrderbook(book);
  },
  onDelta: (_outcomeId, nextBook) => {
    book = nextBook;
    renderOrderbook(book);
  },
  onError: (msg) => {
    console.error(msg.message);
  },
});

const venueMarketOutcomeId = "vmo_1";
ws.subscribe(venueMarketOutcomeId, "orderbook");

interface OrderbookState {
  outcomeId: string;
  bids: Array<{ price: number; size: number; venues: Record<string, number> }>;
  asks: Array<{ price: number; size: number; venues: Record<string, number> }>;
  venueOrderbooks: Record<
    string,
    {
      bids: Array<{ price: number; size: number }>;
      asks: Array<{ price: number; size: number }>;
    }
  >;
  venues: Record<string, { bestBid: number | null; bestAsk: number | null }>;
  midpoint: number | null;
  spread: number | null;
  seq: number;
  checksum: number;
  timestamp: number; // seconds (SDK converts wire milliseconds)
}

const ws = client.createWebSocket({
  onSnapshot: (_outcomeId, book) => {
    console.log(book.venueOrderbooks.predict?.bids);
    console.log(book.venueOrderbooks.polymarket?.asks);
  },
});

const response = await client.getOrderbooks({
  venueMarketIds: ["your-market-id"],
  depth: 20,
});

const book = response.data[0];
if (book?.status !== "ok") {
  throw new Error(book?.error?.message ?? "No live orderbook available");
}

// book.venueOrderbooks — per-venue depth keyed by venue
// book.matchedMarkets  — venue markets considered for the requested market
// book.requestedMarket — lifecycle metadata for the requested market

IntegrityCopy Anchor Link

The SDK keeps each book correct without any code from you:

• Seq and checksum: it applies deltas only in order, verifies every checksum, and requests a fresh snapshot when either check fails.
• Server-sent snapshots: if sufwan-local-test rebuilds a book, its seq restarts and the gateway sends a new snapshot with the first update from it. The SDK replaces the book with it.
• Connection liveness: it reconnects with backoff after 45 seconds with no frame, and re-subscribes everything. Reconnects authenticate with the token from your latest authenticate() call.
• Resolution: on market_resolved it drops the outcome's book and calls onMarketResolved.
• Book watchdog: heartbeats only prove the connection is alive. Once a minute, the SDK checks any book with no update for 5 minutes against GET /orderbooks/outcomes (see Market-data API). A matching seq means the market is just quiet. A different seq triggers a resnapshot, then a resubscribe if the next check still differs or the snapshot never arrives.

The watchdog is on for sockets from client.createWebSocket(), which the hooks and UI components use too (always with the default timings). Each check costs one market-data quota unit per silent outcome, and it pauses for Retry-After on a 429. With the SDK directly, tune or disable it:

const ws = client.createWebSocket(callbacks, {
  bookWatchdog: { silenceMs: 10 * 60_000, checkIntervalMs: 2 * 60_000 },
  // or: bookWatchdog: false
});

Watch it through onDiagnostics:

const ws = client.createWebSocket({
  onDiagnostics: (event) => {
    if (event.type === "book_watchdog_resync") {
      // { outcomeId, localSeq, serverSeq, action: "resnapshot" | "resubscribe" }
      console.warn("orderbook healed", event);
    }
    if (event.type === "book_watchdog_error") {
      // { status } — the REST check failed; the next tick retries
    }
  },
});

If you are implementing the wire protocol yourself, follow Staleness checks and Best practices on the WebSocket Protocol page.

RelatedCopy Anchor Link