Trades

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

Receive

Trade

Public trade event from a venue

type"trade"required

outcomeIdstringrequired

channel"orderbook" | "trades"

venuestringrequired

side"buy" | "sell"required

pricenumberrequired

Normalized 0-1 price

sizenumberrequired

Venue-native units

timestampnumberrequired

{
  "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

type"error"required

messagestringrequired

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