---
title: "Orderbook"
description: "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."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

## 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

<ParamField body="appId" type="userPassword">
  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.
</ParamField>
<ParamField body="jwt" type="JWT">
  User-level auth: pass JWT as token query param on connect, or send &#123; action: 'authenticate', token &#125; mid-session. Required for user-specific events (orders, balances). Same JWT as the REST API.
</ParamField>

## Send

### Subscribe to orderbook

Subscribe to aggregated orderbook updates for markets

<ParamField body="action" type={"\"subscribe\""} required />
<ParamField body="channel" type={"\"orderbook\" | \"trades\""} required />
<ParamField body="outcomeIds" type="string[]" required>
  Outcome IDs to subscribe to
</ParamField>

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

### Unsubscribe from orderbook

<ParamField body="action" type={"\"unsubscribe\""} required />
<ParamField body="channel" type={"\"orderbook\" | \"trades\""} required />
<ParamField body="outcomeIds" type="string[]" required>
  Outcome IDs to unsubscribe from
</ParamField>

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

### Request full snapshot

Request a fresh snapshot for the current market state

<ParamField body="action" type={"\"resnapshot\""} required />
<ParamField body="channel" type={"\"orderbook\""} required />
<ParamField body="outcomeIds" type="string[]" required>
  Request a full snapshot for these outcomes
</ParamField>

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

## Receive

### Orderbook snapshot

Full aggregated orderbook state with venue attribution

<ParamField body="type" type={"\"orderbook_snapshot\""} required />
<ParamField body="outcomeId" type="string" required>
  Outcome ID
</ParamField>
<ParamField body="channel" type={"\"orderbook\" | \"trades\""} />
<ParamField body="seq" type="number" required>
  Sequence number for this outcome
</ParamField>
<ParamField body="checksum" type="number" required>
  Checksum of the full book after this update
</ParamField>
<ParamField body="bids" type="object[]" required>
  All bid levels, sorted desc by price

  <Expandable title="properties">
    <ParamField body="price" type="number" required>
      Price level (0–1)
    </ParamField>
    <ParamField body="totalSize" type="number" required>
      Total size across all venues
    </ParamField>
    <ParamField body="venues" type="Record<string, number>" required />
  </Expandable>
</ParamField>
<ParamField body="asks" type="object[]" required>
  All ask levels, sorted asc by price

  <Expandable title="properties">
    <ParamField body="price" type="number" required>
      Price level (0–1)
    </ParamField>
    <ParamField body="totalSize" type="number" required>
      Total size across all venues
    </ParamField>
    <ParamField body="venues" type="Record<string, number>" required />
  </Expandable>
</ParamField>
<ParamField body="venueOrderbooks" type="Record<string, object>" required>
  Per-venue orderbooks

  <Expandable title="properties">
    <ParamField body="bids" type="object[]" required>
      <Expandable title="properties">
        <ParamField body="price" type="number" required>
          Price level (0–1)
        </ParamField>
        <ParamField body="size" type="number" required>
          Size at this price
        </ParamField>
      </Expandable>
    </ParamField>
    <ParamField body="asks" type="object[]" required>
      <Expandable title="properties">
        <ParamField body="price" type="number" required>
          Price level (0–1)
        </ParamField>
        <ParamField body="size" type="number" required>
          Size at this price
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>
<ParamField body="venues" type="Record<string, object>" required>
  Per-venue best bid/ask

  <Expandable title="properties">
    <ParamField body="bestBid" type="number | null" required />
    <ParamField body="bestAsk" type="number | null" required />
  </Expandable>
</ParamField>
<ParamField body="midpoint" type="number | null" required />
<ParamField body="spread" type="number | null" required />
<ParamField body="timestamp" type="number" required />
<ParamField body="tick" type="number | null" />
<ParamField body="markSource" type={"\"local\" | \"local_merged\" | \"local_one_sided\" | \"sibling\" | \"local_boundary\" | \"none\""} />

```json
{
  "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.

<ParamField body="type" type={"\"orderbook_delta\""} required />
<ParamField body="outcomeId" type="string" required>
  Outcome ID
</ParamField>
<ParamField body="channel" type={"\"orderbook\" | \"trades\""} />
<ParamField body="seq" type="number" required>
  Sequence number for this outcome
</ParamField>
<ParamField body="checksum" type="number" required>
  Checksum of the full book after applying this delta
</ParamField>
<ParamField body="bidChanges" type="object[]" required>
  Changed bid levels (size=0 means removed)

  <Expandable title="properties">
    <ParamField body="price" type="number" required>
      Price level (0–1)
    </ParamField>
    <ParamField body="totalSize" type="number" required>
      Total size across all venues
    </ParamField>
    <ParamField body="venues" type="Record<string, number>" required />
  </Expandable>
</ParamField>
<ParamField body="askChanges" type="object[]" required>
  Changed ask levels (size=0 means removed)

  <Expandable title="properties">
    <ParamField body="price" type="number" required>
      Price level (0–1)
    </ParamField>
    <ParamField body="totalSize" type="number" required>
      Total size across all venues
    </ParamField>
    <ParamField body="venues" type="Record<string, number>" required />
  </Expandable>
</ParamField>
<ParamField body="venueDeltaBooks" type="Record<string, object>" required>
  Per-venue level changes

  <Expandable title="properties">
    <ParamField body="bidChanges" type="object[]" required>
      <Expandable title="properties">
        <ParamField body="price" type="number" required>
          Price level (0–1)
        </ParamField>
        <ParamField body="size" type="number" required>
          Size at this price
        </ParamField>
      </Expandable>
    </ParamField>
    <ParamField body="askChanges" type="object[]" required>
      <Expandable title="properties">
        <ParamField body="price" type="number" required>
          Price level (0–1)
        </ParamField>
        <ParamField body="size" type="number" required>
          Size at this price
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>
<ParamField body="venues" type="Record<string, object>" required>
  Per-venue best bid/ask

  <Expandable title="properties">
    <ParamField body="bestBid" type="number | null" required />
    <ParamField body="bestAsk" type="number | null" required />
  </Expandable>
</ParamField>
<ParamField body="midpoint" type="number | null" required />
<ParamField body="spread" type="number | null" required />
<ParamField body="tick" type="number | null" />
<ParamField body="markSource" type={"\"local\" | \"local_merged\" | \"local_one_sided\" | \"sibling\" | \"local_boundary\" | \"none\""} />
<ParamField body="timestamp" type="number" required />

```json
{
  "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.

<ParamField body="type" type={"\"market_resolved\""} required />
<ParamField body="outcomeId" type="string" required>
  Outcome ID
</ParamField>
<ParamField body="status" type={"\"resolved\" | \"closed\""} required />
<ParamField body="result" type="string | null" required>
  Winning outcome label, or null if unknown
</ParamField>
<ParamField body="outcomes" type="object[]" required>
  Per-outcome resolution data (sibling outcomes for the same market)

  <Expandable title="properties">
    <ParamField body="label" type="string" required />
    <ParamField body="winner" type="boolean" />
    <ParamField body="externalIdentifier" type="string" />
  </Expandable>
</ParamField>
<ParamField body="timestamp" type="number" required />

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

### Subscription confirmed

<ParamField body="type" type={"\"subscribed\""} required />
<ParamField body="outcomeIds" type="string[]" />
<ParamField body="marketIds" type="string[]" />
<ParamField body="channel" type={"\"orderbook\" | \"trades\" | \"arb\" | \"arb-feed\""} required />

```json
{
  "type": "subscribed",
  "outcomeIds": [
    "clv2abc123def456",
    "clv2xyz789ghi012"
  ],
  "marketIds": [
    "string"
  ],
  "channel": "orderbook"
}
```

### Unsubscription confirmed

<ParamField body="type" type={"\"unsubscribed\""} required />
<ParamField body="outcomeIds" type="string[]" />
<ParamField body="marketIds" type="string[]" />
<ParamField body="channel" type={"\"orderbook\" | \"trades\" | \"arb\" | \"arb-feed\""} required />

```json
{
  "type": "unsubscribed",
  "outcomeIds": [
    "clv2abc123def456",
    "clv2xyz789ghi012"
  ],
  "marketIds": [
    "string"
  ],
  "channel": "orderbook"
}
```

### Error

Sent on validation failures, auth errors, or malformed messages

<ParamField body="type" type={"\"error\""} required />
<ParamField body="message" type="string" required />

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