Orderbook streams

The orderbook channel can stay on the same socket as every other channel, or move to a second socket. Either way, orderbook_snapshot and orderbook_delta are unchanged. Field order, levels, and checksums are the ones on WebSocket Protocol.

TiersCopy Anchor Link

There are two tiers.

• Conflated (default). At most one delta per book per 100 ms. That delta is the net change since the previous conflated delta for that book. This is the cadence a client already gets on wss://ws.t.sufwankhalid.com/ws.
• Realtime. Opt in per subscribe. Each accepted change is delivered as it happens.

Omit latency, or set it to "conflated", for the default. Set it to "realtime" to opt in. One socket can hold some outcomes on each tier. The field applies only to the outcomes in that subscribe.

seq is counted separately on each tier. Do not compare a conflated seq with a realtime seq for the same outcome. checksum is the book state, so the same state has the same checksum on both tiers. Apply messages with Sequencing and resync: a delta applies only when its seq is exactly one past the book, and every orderbook_snapshot replaces the book, whatever its seq is.

resnapshot is unchanged. It refreshes an outcome you are already subscribed to, on the tier that subscribe chose. It does not take latency.

The shared socket at wsUrl does not offer this choice. Adding latency there does not turn on realtime.

The orderbook socketCopy Anchor Link

orderbookUrl and orderbookLatency are options on createAggClient. Hooks and UI components use that client. They do not take a separate URL.

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",
  orderbookUrl: "wss://ob.agg.market/ws",
  // "conflated" (default) or "realtime". Sent as `latency` on subscribe.
  orderbookLatency: "conflated",
});

orderbookLatency defaults to "conflated". "realtime" is sent as the optional latency field. The SDK still applies snapshots and deltas, checks seq and checksum, and runs the book watchdog. See Real-Time Orderbook.

This is a connection change, not a wire change. A raw client opens the orderbook socket the same way as the shared one, including appId:

const ws = new WebSocket(`wss://ob.agg.market/ws?appId=${appId}`);

Wait for connected. Browser and server handshakes match Getting connected. A browser is admitted by an allowed Origin. A server sends x-app-api-key on the handshake. An API key is not required for the per-outcome orderbook channel.

SubscribeCopy Anchor Link

Subscriptions stay keyed by outcome id (outcomes[].id), not by market id. The same snapshot unavailable error applies when the id does not resolve.

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

Leave latency off, or send "conflated", for the 100 ms tier. The subscribed ack, orderbook_snapshot, and orderbook_delta that follow use the same objects as the orderbook stream. A snapshot carries the seq of the tier you subscribed.

To stream every non-empty book on a venue from your backend, use the Orderbook firehose. That channel is separate. It stays off until Snag enables it, and it requires an app API key.

RelatedCopy Anchor Link