AGG is currently in alpha. APIs, components, and docs may change.
Agg.market — Prediction Market Aggregator logo

Orderbook

Subscribe to aggregated orderbook updates for canonical markets. Receive an initial snapshot, then incremental deltas with sequencing and checksums. Client maintains a local book by applying deltas. Request a resnapshot if your local state drifts. Sequencing: seq increments between consecutive messages for a given market. If you receive a seq that is not your expected next value, request a new snapshot via resnapshot.

Connection

wss://ws.agg.market/ws

Production WebSocket server.

Connection: wss://ws.agg.market/ws?appId=xxx (required). Optionally pass &token=eyJ... for user-level auth on connect.

Reconnection: Reconnect with exponential backoff + jitter: delay = min(1s × 2^attempt + random(0–1s), 30s). On reconnect, re-subscribe to all channels.

Heartbeat: The service emits a JSON heartbeat message clients can observe directly.

Security schemes

appIduserPassword

App-level auth: pass appId as a query parameter on connect. Required for all connections. The appId must belong to an active app with matching allowed origins.

jwtJWT

User-level auth: pass JWT as token query param on connect, or send { action: 'authenticate', token } mid-session. Required for user-specific events (orders, balances). Same JWT as the REST API.

Send

Subscribe to orderbook

Subscribe to aggregated orderbook updates for markets

action"subscribe"required
channel"orderbook" | "trades"required
outcomeIdsstring[]required

Outcome IDs to subscribe to

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

Unsubscribe from orderbook

action"unsubscribe"required
channel"orderbook" | "trades"required
outcomeIdsstring[]required

Outcome IDs to unsubscribe from

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

Request full snapshot

Request a fresh snapshot for the current market state

action"resnapshot"required
channel"orderbook"required
outcomeIdsstring[]required

Request a full snapshot for these outcomes

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

Receive

Orderbook snapshot

Full aggregated orderbook state with venue attribution

type"orderbook_snapshot"required
outcomeIdstringrequired

Outcome ID

channel"orderbook" | "trades"
seqnumberrequired

Sequence number for this outcome

checksumnumberrequired

Checksum of the full book after this update

bidsobject[]required

All bid levels, sorted desc by price

asksobject[]required

All ask levels, sorted asc by price

venueOrderbooksRecord<string, object>required

Per-venue orderbooks

venuesRecord<string, object>required

Per-venue best bid/ask

midpointnumber | nullrequired
spreadnumber | nullrequired
timestampnumberrequired
ticknumber | null
markSource"local" | "local_merged" | "local_one_sided" | "sibling" | "local_boundary" | "none"
{
  "type": "orderbook_snapshot",
  "outcomeId": "clv2abc123def456",
  "channel": "orderbook",
  "seq": 1710000001,
  "checksum": 2918476531,
  "bids": [
    {
      "price": 0.55,
      "totalSize": 1500,
      "venues": {}
    }
  ],
  "asks": [
    {
      "price": 0.55,
      "totalSize": 1500,
      "venues": {}
    }
  ],
  "venueOrderbooks": {},
  "venues": {},
  "midpoint": 0.55,
  "spread": 0.01,
  "timestamp": 1710000000000,
  "tick": 0,
  "markSource": "local"
}

Orderbook delta

Incremental update — only changed levels. size=0 means level removed.

type"orderbook_delta"required
outcomeIdstringrequired

Outcome ID

channel"orderbook" | "trades"
seqnumberrequired

Sequence number for this outcome

checksumnumberrequired

Checksum of the full book after applying this delta

bidChangesobject[]required

Changed bid levels (size=0 means removed)

askChangesobject[]required

Changed ask levels (size=0 means removed)

venueDeltaBooksRecord<string, object>required

Per-venue level changes

venuesRecord<string, object>required

Per-venue best bid/ask

midpointnumber | nullrequired
spreadnumber | nullrequired
ticknumber | null
markSource"local" | "local_merged" | "local_one_sided" | "sibling" | "local_boundary" | "none"
timestampnumberrequired
{
  "type": "orderbook_delta",
  "outcomeId": "clv2abc123def456",
  "channel": "orderbook",
  "seq": 1710000001,
  "checksum": 2918476531,
  "bidChanges": [
    {
      "price": 0.55,
      "totalSize": 1500,
      "venues": {}
    }
  ],
  "askChanges": [
    {
      "price": 0.55,
      "totalSize": 1500,
      "venues": {}
    }
  ],
  "venueDeltaBooks": {},
  "venues": {},
  "midpoint": 0.55,
  "spread": 0.01,
  "tick": 0,
  "markSource": "local",
  "timestamp": 1710000000000
}

Market resolved

Terminal resolution event for a subscribed outcome. Delivered once per outcome subscription; after delivery, the gateway closes out the orderbook channel for that outcome.

type"market_resolved"required
outcomeIdstringrequired

Outcome ID

status"resolved" | "closed"required
resultstring | nullrequired

Winning outcome label, or null if unknown

outcomesobject[]required

Per-outcome resolution data (sibling outcomes for the same market)

timestampnumberrequired
{
  "type": "market_resolved",
  "outcomeId": "clv2abc123def456",
  "status": "resolved",
  "result": "Yes",
  "outcomes": [
    {
      "label": "Yes",
      "winner": true,
      "externalIdentifier": "0xabc123"
    }
  ],
  "timestamp": 1710000000000
}

Subscription confirmed

type"subscribed"required
outcomeIdsstring[]
marketIdsstring[]
channel"orderbook" | "trades" | "arb" | "arb-feed"required
{
  "type": "subscribed",
  "outcomeIds": [
    "clv2abc123def456",
    "clv2xyz789ghi012"
  ],
  "marketIds": [
    "string"
  ],
  "channel": "orderbook"
}

Unsubscription confirmed

type"unsubscribed"required
outcomeIdsstring[]
marketIdsstring[]
channel"orderbook" | "trades" | "arb" | "arb-feed"required
{
  "type": "unsubscribed",
  "outcomeIds": [
    "clv2abc123def456",
    "clv2xyz789ghi012"
  ],
  "marketIds": [
    "string"
  ],
  "channel": "orderbook"
}

Error

Sent on validation failures, auth errors, or malformed messages

type"error"required
messagestringrequired
{
  "type": "error",
  "message": "Invalid request: outcomeIds must be a non-empty array"
}