---
title: "Trades"
description: "Subscribe to public trade feed for outcomes. No user auth required. Uses action: \"subscribe\", channel: \"trades\", outcomeIds message format. Shares the 500-subscription limit with orderbook subscriptions."
---

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

### Trade

Public trade event from a venue

<ParamField body="type" type={"\"trade\""} required />
<ParamField body="outcomeId" type="string" required />
<ParamField body="channel" type={"\"orderbook\" | \"trades\""} />
<ParamField body="venue" type="string" required />
<ParamField body="side" type={"\"buy\" | \"sell\""} required />
<ParamField body="price" type="number" required>
  Normalized 0-1 price
</ParamField>
<ParamField body="size" type="number" required>
  Venue-native units
</ParamField>
<ParamField body="timestamp" type="number" required />

```json
{
  "type": "trade",
  "outcomeId": "clv2abc123def456",
  "channel": "orderbook",
  "venue": "polymarket",
  "side": "buy",
  "price": 0.55,
  "size": 100,
  "timestamp": 1710000000000
}
```

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