Websocket API
Real-time streaming over a single authenticated WebSocket connection — quotes, depth, account metrics, and execution events.
The Trader WebSocket API delivers real-time market data and account events over a single authenticated connection.
Connect
wss://<trader-host>/api/v1/ws?token=<JWT>Pass the JWT obtained from POST /api/v1/login as the token query parameter. Connections without a valid token are closed immediately. Respond to server pings with WebSocket pong frames to keep the connection alive.
Message envelope
Every message — client → server and server → client — uses the same envelope:
{ "type": "<message-type>", "payload": { ... } }The type field selects the payload schema below.
Client → server messages
| Type | Purpose | Payload |
|---|---|---|
subscribe | Subscribe to quote / execution / portfolio events for a symbol list | { symbols: string[], events: ("quoteEvent" | "executionEvent" | "portfolioEvent")[] } |
unsubscribe | Stop a subscribe stream | { symbols: string[], events: string[] } |
depthSubscribe | Subscribe to order-book depth for a symbol | { symbol: string, depth?: number } |
depthUnsubscribe | Stop depth stream | { symbol: string } |
metricsSubscribe | Subscribe to account metrics updates | { accountId: string } |
createOrder / cancelOrder / amendOrder | Trading actions | Same body as the equivalent REST endpoint, e.g. POST /accounts/{account_id}/orders |
closePosition / amendPosition | Position management | Same body as the equivalent REST endpoint |
orderHistory / positionHistory / dealHistory | Historical queries | Same body as the equivalent REST endpoint |
Server → client messages
| Type | Sent when |
|---|---|
subscribed | Acknowledges a subscribe request |
unsubscribed | Acknowledges an unsubscribe request |
quoteEvent | A subscribed symbol's quote changes |
executionEvent | An order belonging to the authenticated account fills, partially fills, or is cancelled |
portfolioEvent | The account's portfolio (positions, balances) changes |
depthEvent | Order-book depth update for a subscribed symbol |
metricsEvent | Account metrics update (equity, margin, P&L) |
error | The server rejected a message; payload includes a code and message |
Example
Subscribe to quotes and executions for two symbols, then stream events:
// → client
{ "type": "subscribe", "payload": { "symbols": ["EURUSD", "GBPUSD"], "events": ["quoteEvent", "executionEvent"] } }
// ← server
{ "type": "subscribed", "payload": { "symbols": ["EURUSD", "GBPUSD"], "events": ["quoteEvent", "executionEvent"] } }
// ← server (continuous)
{ "type": "quoteEvent", "payload": { "symbol": "EURUSD", "bid": 1.0843, "ask": 1.0844, "ts": "2026-06-01T12:00:00Z" } }To send a trading action, wrap the REST request body in the envelope:
{
"type": "createOrder",
"payload": {
"accountId": "acc_123",
"symbol": "EURUSD",
"side": "BUY",
"quantity": 10000,
"type": "MARKET"
}
}The server replies with an executionEvent once the order is accepted, then again on each fill.