# Websocket API

> Real-time streaming over a single authenticated WebSocket connection — quotes, depth, account metrics, and execution events.

Source: /trader/websocket

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`](/trader/api/client-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:

```json
{ "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`](/trader/api/create-order) |
| `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:

```json
// → 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:

```json
{
  "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.