Arb
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.
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.
Send
Subscribe to orderbook
Subscribe to aggregated orderbook updates for markets
action"subscribe"requiredchannel"orderbook" | "trades"requiredoutcomeIdsstring[]requiredOutcome IDs to subscribe to
{
"action": "subscribe",
"channel": "orderbook",
"outcomeIds": [
"clv2abc123def456",
"clv2xyz789ghi012"
]
}Unsubscribe from orderbook
action"unsubscribe"requiredchannel"orderbook" | "trades"requiredoutcomeIdsstring[]requiredOutcome IDs to unsubscribe from
{
"action": "unsubscribe",
"channel": "orderbook",
"outcomeIds": [
"clv2abc123def456",
"clv2xyz789ghi012"
]
}Receive
Arb-return update for a specific market
Pushed to clients subscribed to { channel: "arb", marketIds } when the engine detects a new arbReturn value for that market.
type"arb_market_update"requiredmarketIdstringrequiredactiveVenuesOnlytruerequiredProducer assertion that globally inactive venues were excluded
venueEventIdstring | nullrequiredarbReturnnumberrequiredtsnumberrequiredliquidityUsdnumberliquidityTier"deep" | "shallow"{
"type": "arb_market_update",
"marketId": "mkt_abc123",
"activeVenuesOnly": true,
"venueEventId": "evt_xyz789",
"arbReturn": 0.05,
"ts": 1710000000000,
"liquidityUsd": 0,
"liquidityTier": "deep"
}Subscription confirmed
type"subscribed"requiredoutcomeIdsstring[]marketIdsstring[]channel"orderbook" | "trades" | "arb" | "arb-feed"required{
"type": "subscribed",
"outcomeIds": [
"clv2abc123def456",
"clv2xyz789ghi012"
],
"marketIds": [
"string"
],
"channel": "orderbook"
}Unsubscription confirmed
type"unsubscribed"requiredoutcomeIdsstring[]marketIdsstring[]channel"orderbook" | "trades" | "arb" | "arb-feed"required{
"type": "unsubscribed",
"outcomeIds": [
"clv2abc123def456",
"clv2xyz789ghi012"
],
"marketIds": [
"string"
],
"channel": "orderbook"
}Error
Sent on validation failures, auth errors, or malformed messages
type"error"requiredmessagestringrequired{
"type": "error",
"message": "Invalid request: outcomeIds must be a non-empty array"
}