AGG is currently in alpha. APIs, components, and docs may change.
Agg.market — Prediction Market Aggregator logo

Auth

Authenticate mid-session to receive user-specific events. Send your JWT token (same as REST API) to upgrade from app-level to user-level auth. Supports re-authentication for token refresh or user switch. Connect-time auth: Pass ?token=eyJ... as a query param alongside appId.

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

Authenticate user mid-session

Upgrade connection to user-level auth. Uses the same JWT as the REST API. Supports re-authentication for token refresh or user switch.

action"authenticate"required
tokenstringrequired

JWT token for user-level auth (same token used for REST API)

{
  "action": "authenticate",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Receive

User authenticated

Confirms successful mid-session authentication

type"authenticated"required
userIdstringrequired
{
  "type": "authenticated",
  "userId": "usr_xyz789"
}

Connection acknowledged

Sent immediately after successful connection. Includes userId if JWT was provided on connect.

type"connected"required
appIdstringrequired
userIdstring
{
  "type": "connected",
  "appId": "app_demo123",
  "userId": "usr_xyz789"
}

Heartbeat

Application-level heartbeat event for connection liveness

type"heartbeat"required
tsnumberrequired

Server timestamp in milliseconds

{
  "type": "heartbeat",
  "ts": 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"
}