Real-Time Orderbook

The AGG 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.

Orderbook subscriptions are keyed by venueMarketOutcomeId — the outcomes[].id on REST market responses — not by venueMarketId. Subscribing with a venueMarketId never resolves a book and the gateway replies with a Snapshot unavailable error. (Only the REST GET /orderbooks endpoint and the arb streams use market-level ids.)

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.

SDK (vanilla JS/TS)
Hooks (React)
UI Components

Full control over the WebSocket connection and local orderbook state.

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

const client = createAggClient({
  baseUrl: "https://api.agg.market",
  appId: "your-app-id",
  wsUrl: "wss://ws.agg.market/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");

The SDK applies snapshots and deltas for you, tracks seq, validates checksum (XOR of per-level CRC32), drops stale deltas where seq <= current.seq, and requests a fresh snapshot when integrity checks fail. It also runs a 5-minute book watchdog; see Integrity.

2. Read the orderbook

Orderbook timestamp is Unix milliseconds on the wire, and the SDK reports it as seconds.The OrderbookState passed to callbacks uses object-shaped levels:

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)
}

3. Per-venue orderbooks

Per-venue depth is available on the same object:

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

4. REST fallback

For one-time fetches without a live socket:

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

See the Setup Guide for the one-time AggProvider and QueryClientProvider wiring. This recipe starts at the hook usage layer.

1. Live orderbook

import { useLiveMarket } from "@agg-build/hooks";

function Orderbook({ venueMarketOutcomeId }) {
  const { orderbook, isConnected, integrity } = useLiveMarket(venueMarketOutcomeId);

  if (!orderbook) return <div>Connecting...</div>;

  return (
    <div>
      <p>Connected: {String(isConnected)}</p>

      <h3>Bids</h3>
      {orderbook.bids.map((level) => (
        <div key={level.price}>
          {(level.price * 100).toFixed(0)}% — {level.size} contracts
          {" ("}
          {Object.entries(level.venues)
            .map(([venue, size]) => `${venue}: ${size}`)
            .join(", ")}
          {")"}
        </div>
      ))}

      <p>
        Midpoint: {orderbook.midpoint} | Spread: {orderbook.spread}
      </p>

      <h3>Asks</h3>
      {orderbook.asks.map((level) => (
        <div key={level.price}>
          {(level.price * 100).toFixed(0)}% — {level.size} contracts
        </div>
      ))}

      {integrity === "resyncing" && <p>Resyncing…</p>}
    </div>
  );
}

2. Per-venue orderbooks

import { useMarketOrderbook } from "@agg-build/hooks";

function VenueOrderbooks({ venueMarketOutcomeId, venueOutcomes }) {
  const { data, isLoading } = useMarketOrderbook({
    venueMarketOutcomeId, // outcomes[].id — NOT a venueMarketId
    venueOutcomes, // [{ venue: "predict", venueMarketOutcomeId: "..." }, ...]
  });

  if (isLoading || !data) return <div>Loading...</div>;

  return (
    <div>
      {Object.entries(data.venueOrderbooks).map(([venue, book]) => (
        <div key={venue}>
          <h4>{venue}</h4>
          <p>Bids: {book.bids.length} levels</p>
          <p>Asks: {book.asks.length} levels</p>
        </div>
      ))}
    </div>
  );
}

3. REST-only (no WebSocket)

import { useAggClient } from "@agg-build/hooks";
import { useQuery } from "@tanstack/react-query";

function StaticOrderbook({ marketId }) {
  const client = useAggClient();
  const { data } = useQuery({
    queryKey: ["orderbooks", marketId],
    queryFn: () =>
      client.getOrderbooks({
        venueMarketIds: [marketId],
      }),
  });

  const book = data?.data[0];
  // book?.venueOrderbooks, book?.matchedMarkets, book?.requestedMarket
}

Drop-in React components for live orderbook depth, venue attribution, and chart/orderbook tabs.

Market Details card with orderbook tab

import { MarketDetails } from "@agg-build/ui/events";

function OrderbookCard({ event, marketId }) {
  return <MarketDetails event={event} marketId={marketId} defaultTab="order-book" />;
}

The card renders bid/ask rows, venue logos, sizes, totals, and live updates without manual subscription code.For a full event page with both chart and orderbook tabs, use EventMarketPage as shown in Real-Time Charts.Browse the live Market Details reference and Event Market Page reference.

Integrity

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 AGG 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.

WebSocket Protocol

Wire format, sequencing, resnapshot requests, and heartbeat behavior.

Real-Time Charts

Build live candles from the same orderbook and trade streams.

User Notifications

Authenticated order and balance events on the same WebSocket connection.

Start here

Core concepts

Account

Trading

Venues

Market data

Security

Real-time

Webhooks

Your users

UI Kit

Releases

2. Read the orderbook

3. Per-venue orderbooks

4. REST fallback

1. Live orderbook

2. Per-venue orderbooks

3. REST-only (no WebSocket)

Market Details card with orderbook tab

Integrity

WebSocket Protocol

Real-Time Charts

User Notifications

​1. Connect and subscribe

​2. Read the orderbook

​3. Per-venue orderbooks

​4. REST fallback

​1. Live orderbook

​2. Per-venue orderbooks

​3. REST-only (no WebSocket)

​Market Details card with orderbook tab

​Integrity

​Related

WebSocket Protocol

Real-Time Charts

User Notifications

1. Connect and subscribe

2. Read the orderbook

3. Per-venue orderbooks

4. REST fallback

1. Live orderbook

2. Per-venue orderbooks

3. REST-only (no WebSocket)

Market Details card with orderbook tab

Integrity

Related