User events
User-specific events (requires user-level auth via authenticate action or token query param). Streams order confirmations, balance updates, and a venue-agnostic order lifecycle event (order_event) covering DAG steps and terminal fill / failure status across all venues.
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
appIduserPasswordApp-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.
jwtJWTUser-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.
Receive
Order submitted
Order confirmation after trade execution (user-level auth required)
type"order_submitted"requiredvenuestringrequiredorderIdstringrequiredsidestringrequiredpricenumberrequiredsizenumberrequiredoutcomeIdstringtimestampnumberrequired{
"type": "order_submitted",
"venue": "polymarket",
"orderId": "ord_abc123",
"side": "buy",
"price": 0.55,
"size": 100,
"outcomeId": "clv2abc123def456",
"timestamp": 1710000000000
}Balance update
Balance update after execution (user-level auth required)
type"balance_update"requiredvenuestringrequiredtradingBalanceCentsnumberrequiredwalletBalanceCentsnumbertimestampnumberrequired{
"type": "balance_update",
"venue": "polymarket",
"tradingBalanceCents": 94500,
"walletBalanceCents": 100000,
"timestamp": 1710000000000
}Order lifecycle event
Venue-agnostic DAG and order lifecycle stream. Discriminate on the event field. Emitted for every venue automatically.
type"order_event"requiredevent"dag_started" | "dag_completed" | "dag_failed" | "dag_cancelled" | "step_started" | "step_completed" | "step_waiting" | "step_failed" | "step_retrying" | "filled" | "partial_fill" | "failed"requireduserIdstringrequiredorderIdstringrequiredvenuestringfilledAmountRawstringremainingAmountRawstringerrorReasonstringdagRunIdstringstepIdstringstepTypestringtemplateNamestringattemptnumbertimestampnumberrequired{
"type": "order_event",
"event": "dag_started",
"userId": "usr_xyz789",
"orderId": "ord_abc123",
"venue": "polymarket",
"filledAmountRaw": "string",
"remainingAmountRaw": "string",
"errorReason": "string",
"dagRunId": "string",
"stepId": "string",
"stepType": "string",
"templateName": "string",
"attempt": 0,
"timestamp": 1710000000000
}