WebSocket Messages

The Trading API uses WebSocket connections for real-time event streaming. This page documents the protocol mechanics: the message envelope, the messages your strategy sends, and the server heartbeat. Payloads for every server→client event live in the Event Types reference.

Message Format

All messages use JSON with an internally-tagged format. The type field identifies the message type:

{"type": "ping", "timestamp": "2025-01-15T10:30:00Z"}
{"type": "order", "event": "ORDER_FILLED", "order": {...}}

Client to Server Messages

Your strategy sends these messages to the Trading API.

Pong

Response to a server ping heartbeat. Send this to keep the connection alive.

{
  "type": "pong"
}

EventAck

Acknowledge processed events. Required in backtest mode — the engine stops advancing simulated time until an ACK arrives. Informational-only in paper and live modes. A single event_ack frame drains all of the Gateway's outstanding events at once (auto-correlation).

Field	Type	Description
`type`	string	Always `"event_ack"`
`correlation_id`	string	Caller-chosen ID (typically a UUID) useful for correlating ACKs in logs
`events_processed`	string[]	Informational — the Gateway does not match entries to specific events; an empty array is fine
`timestamp`	integer	Unix timestamp (milliseconds) when the strategy finished processing

{
  "type": "event_ack",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "events_processed": ["evt_123", "evt_124"],
  "timestamp": 1700000000000
}

See Event Types → Event Acknowledgment for the full semantics and mode-dependent behavior.

Server to Client Messages

Ping

Server heartbeat. Respond with a pong message to keep the connection alive.

{
  "type": "ping",
  "timestamp": "2025-01-15T10:30:00Z"
}

Event Messages

Every other server→client message is an event, identified by its type field. Full schemas, enums, and JSON examples for each are in the Event Types reference:

`type`	Payload	Reference
`order`	Order state changes — `event` (e.g. `"event": "ORDER_FILLED"`) + `order`	Order Events
`position`	Position state changes — `event` + `position`	Position Events
`account`	Account balance / margin changes — `event` + `account`	Account Events
`trade`	Individual fills — `event` + `trade`	Trade Events
`candle`	OHLCV bar — `bar`	Candle Event
`quote`	Bid/ask/last update — `quote`	Quote Event
`connection`	Gateway / upstream broker connection state	Connection Events
`rate_limit`	Rate limit warnings	Rate Limit Events
`data_staleness`	Market-data freshness went `STALE`/`FRESH`	Data Staleness Events
`error`	Error notifications	Error Events

Event Subscription

Event subscriptions are configured at startup via environment variables, not through WebSocket messages. Configure the SUBSCRIPTIONS environment variable to specify which events your strategy receives. See Connection → Event Subscription for the schema.

Event Types - Full server→client event reference
Connection Guide - How to connect to the Trading API
Order Types - Full order schema reference
Position Types - Full position schema reference