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

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

ws.subscribe("your-outcome-id", "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. The gateway is a stateless fan-out — all orderbook recovery is handled client-side by the SDK.

2. Read the orderbook

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
}

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({ marketId }) {
  const { orderbook, isConnected, integrity } = useLiveMarket(marketId);

  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 verifies seq and checksum automatically and requests a fresh snapshot when the local book drifts. If you are implementing the wire protocol yourself, use the WebSocket Protocol page for the snapshot/delta formats and resnapshot flow.

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.

Getting Started

Components

REST API

WebSocket Protocol

Authentication

Account

Funding & Execution

Webhooks

Discovery

Real-Time Data

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