---
title: "Arb"
description: "Subscribe to per-market arb-return updates. Send action: \"subscribe\", channel: \"arb\", marketIds: string[] . The server echos subscribed marketIds in the subscribed reply. No initial snapshot — updates arrive as arb_market_update messages when the engine detects a change."
---

> **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"
  ]
}
```

## Receive

### Arb-return update for a specific market

Pushed to clients subscribed to &#123; channel: "arb", marketIds &#125; when the engine detects a new arbReturn value for that market.

<ParamField body="type" type={"\"arb_market_update\""} required />
<ParamField body="marketId" type="string" required />
<ParamField body="activeVenuesOnly" type="true" required>
  Producer assertion that globally inactive venues were excluded
</ParamField>
<ParamField body="venueEventId" type="string | null" required />
<ParamField body="arbReturn" type="number" required />
<ParamField body="ts" type="number" required />
<ParamField body="liquidityUsd" type="number" />
<ParamField body="liquidityTier" type={"\"deep\" | \"shallow\""} />

```json
{
  "type": "arb_market_update",
  "marketId": "mkt_abc123",
  "activeVenuesOnly": true,
  "venueEventId": "evt_xyz789",
  "arbReturn": 0.05,
  "ts": 1710000000000,
  "liquidityUsd": 0,
  "liquidityTier": "deep"
}
```

### 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"
}
```