---
title: "Arb-feed"
description: "Subscribe to the full arb-return broadcast feed. Send action: \"subscribe\", channel: \"arb-feed\" (no ids required). Receives batched arb_feed_batch messages for all markets whenever the engine publishes arb updates."
---

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

### Batched arb-return feed update

Pushed to clients subscribed to &#123; channel: "arb-feed" &#125;. Contains arb updates for multiple markets in a single batch.

<ParamField body="type" type={"\"arb_feed_batch\""} required />
<ParamField body="feed" type={"\"arb\""} required />
<ParamField body="activeVenuesOnly" type="true" required>
  Producer assertion that globally inactive venues were excluded
</ParamField>
<ParamField body="entries" type="object[]" required>
  <Expandable title="properties">
    <ParamField body="marketId" type="string" required />
    <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\""} />
  </Expandable>
</ParamField>
<ParamField body="flushTs" type="number" required />
<ParamField body="chunk" type="number" required />
<ParamField body="chunkCount" type="number" required />

```json
{
  "type": "arb_feed_batch",
  "feed": "arb",
  "activeVenuesOnly": true,
  "entries": [],
  "flushTs": 1710000000000,
  "chunk": 1,
  "chunkCount": 1
}
```

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