Event Types

This reference documents all WebSocket event types in the Trading API, including market data events, order/position updates, and client messages.

Event Message Structure

All events are delivered via WebSocket with a consistent structure:

{
  "type": "event_type",
  "timestamp": "2025-01-15T10:30:00Z",
  ...event-specific fields
}

The type field identifies the event category. Each event type has specific additional fields documented below.

Market Data Events

Candle Event

Delivers OHLCV bar data for subscribed instruments.

Type: candle

Field	Type	Description
`type`	string	Always `"candle"`
`bar`	Bar	The bar data
`timestamp`	datetime	Event timestamp (when event was emitted)

Bar Schema

Field	Type	Description
`symbol`	string	Symbol in canonical format (e.g., "EUR/USD", "AAPL")
`provider`	string	Data source provider (e.g., "alpaca", "binance")
`timeframe`	Timeframe	Bar timeframe
`timestamp`	datetime	Bar start timestamp
`open`	string	Opening price
`high`	string	Highest price during the period
`low`	string	Lowest price during the period
`close`	string	Closing price
`volume`	string	Trading volume during the period

Timeframe Enum

Value	Description
`1m`	1 minute
`2m`	2 minutes
`5m`	5 minutes
`10m`	10 minutes
`15m`	15 minutes
`30m`	30 minutes
`1h`	1 hour
`2h`	2 hours
`4h`	4 hours
`12h`	12 hours
`1d`	1 day
`1w`	1 week

Example

{
  "type": "candle",
  "bar": {
    "symbol": "AAPL",
    "provider": "alpaca",
    "timeframe": "1h",
    "timestamp": "2025-01-15T10:00:00Z",
    "open": "150.00",
    "high": "151.50",
    "low": "149.75",
    "close": "151.25",
    "volume": "1500000"
  },
  "timestamp": "2025-01-15T11:00:00Z"
}

Quote Event

Delivers real-time bid/ask quotes.

Type: quote

Field	Type	Description
`type`	string	Always `"quote"`
`quote`	Quote	The quote data
`timestamp`	datetime	Event timestamp

Quote Schema

Field	Type	Description
`symbol`	string	Symbol in canonical format
`provider`	string	Data source provider
`bid`	string	Best bid price (highest buy offer)
`bid_size`	string?	Quantity available at bid price
`ask`	string	Best ask price (lowest sell offer)
`ask_size`	string?	Quantity available at ask price
`last`	string	Last traded price
`volume`	string?	Trading volume (if available)
`timestamp`	datetime	Quote timestamp

Example

{
  "type": "quote",
  "quote": {
    "symbol": "EUR/USD",
    "provider": "alpaca",
    "bid": "1.0845",
    "bid_size": "100000",
    "ask": "1.0847",
    "ask_size": "100000",
    "last": "1.0846",
    "timestamp": "2025-01-15T10:30:00.123Z"
  },
  "timestamp": "2025-01-15T10:30:00.125Z"
}

Order Events

Delivers order state changes.

Type: order

Field	Type	Description
`type`	string	Always `"order"`
`event`	OrderEventType	Type of order event
`order`	Order	Current state of the order
`parent_order_id`	string?	Parent order ID for bracket/OCO child orders
`timestamp`	datetime	Event timestamp

OrderEventType Enum

Value	Description
`ORDER_CREATED`	Order has been created and submitted
`ORDER_MODIFIED`	Order has been modified (price, quantity, etc.)
`ORDER_CANCELLED`	Order has been cancelled
`ORDER_REJECTED`	Order was rejected by the provider
`ORDER_FILLED`	Order has been completely filled
`ORDER_PARTIALLY_FILLED`	Order has been partially filled
`ORDER_EXPIRED`	Order has expired based on time_in_force
`BRACKET_ORDER_CREATED`	Bracket order (with SL/TP) has been created
`BRACKET_ORDER_MODIFIED`	Bracket order has been modified

Example

{
  "type": "order",
  "event": "ORDER_FILLED",
  "order": {
    "id": "ord_abc123",
    "symbol": "AAPL",
    "side": "BUY",
    "order_type": "LIMIT",
    "quantity": "100",
    "filled_quantity": "100",
    "remaining_quantity": "0",
    "average_fill_price": "150.25",
    "status": "FILLED",
    "time_in_force": "GTC",
    "limit_price": "150.50",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:05Z"
  },
  "timestamp": "2025-01-15T10:30:05Z"
}

Position Events

Delivers position state changes.

Type: position

Field	Type	Description
`type`	string	Always `"position"`
`event`	PositionEventType	Type of position event
`position`	Position	Current state of the position
`timestamp`	datetime	Event timestamp

PositionEventType Enum

Value	Description
`POSITION_OPENED`	New position has been opened
`POSITION_MODIFIED`	Position has been modified (partial close, averaging)
`POSITION_CLOSED`	Position has been fully closed

Example

{
  "type": "position",
  "event": "POSITION_OPENED",
  "position": {
    "id": "pos_xyz789",
    "symbol": "BTC/USD",
    "side": "LONG",
    "quantity": "0.5",
    "average_entry_price": "42000.00",
    "current_price": "42100.00",
    "unrealized_pnl": "50.00",
    "realized_pnl": "0.00",
    "opened_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Account Events

Delivers account state changes.

Type: account

Field	Type	Description
`type`	string	Always `"account"`
`event`	AccountEventType	Type of account event
`account`	Account	Current account state
`timestamp`	datetime	Event timestamp

AccountEventType Enum

Value	Description
`BALANCE_UPDATED`	Account balance has changed
`MARGIN_WARNING`	Margin utilization approaching limit
`MARGIN_CALL`	Margin call triggered - reduce positions or add funds

Example

{
  "type": "account",
  "event": "BALANCE_UPDATED",
  "account": {
    "balance": "10000.00",
    "equity": "10250.00",
    "margin_used": "1500.00",
    "margin_available": "8500.00",
    "unrealized_pnl": "250.00",
    "currency": "USD"
  },
  "timestamp": "2025-01-15T10:30:05Z"
}

Trade Events

Delivers individual trade/fill records.

Type: trade

Field	Type	Description
`type`	string	Always `"trade"`
`event`	TradeEventType	Type of trade event
`trade`	Trade	The executed trade
`timestamp`	datetime	Event timestamp

TradeEventType Enum

Value	Description
`TRADE_FILLED`	A trade has been executed

Trade Schema

Field	Type	Description
`id`	string	Unique trade identifier
`order_id`	string	Order ID this trade belongs to
`symbol`	string	Symbol traded
`side`	Side	Trade side (BUY or SELL)
`quantity`	string	Fill quantity in base units
`price`	string	Fill price
`commission`	string	Commission/fee amount
`commission_currency`	string	Currency of the commission
`is_maker`	boolean?	Whether this was a maker trade
`timestamp`	datetime	Trade execution timestamp

Example

{
  "type": "trade",
  "event": "TRADE_FILLED",
  "trade": {
    "id": "trd_123456",
    "order_id": "ord_abc123",
    "symbol": "AAPL",
    "side": "BUY",
    "quantity": "60",
    "price": "150.00",
    "commission": "0.50",
    "commission_currency": "USD",
    "is_maker": false,
    "timestamp": "2025-01-15T10:30:05Z"
  },
  "timestamp": "2025-01-15T10:30:05Z"
}

Connection Events

Delivers connection state changes.

Type: connection

Field	Type	Description
`type`	string	Always `"connection"`
`event`	ConnectionEventType	Type of connection event
`error`	string?	Error message if disconnecting due to error
`timestamp`	datetime	Event timestamp

ConnectionEventType Enum

Value	Description
`CONNECTED`	Successfully connected to the provider
`DISCONNECTING`	Connection is closing
`RECONNECTING`	Attempting to reconnect after disconnect

Example

{
  "type": "connection",
  "event": "CONNECTED",
  "timestamp": "2025-01-15T10:30:00Z"
}

Rate Limit Events

Notifies about rate limiting status.

Type: rate_limit

Field	Type	Description
`type`	string	Always `"rate_limit"`
`event`	RateLimitEventType	Type of rate limit event
`requests_remaining`	integer	Number of requests remaining in current window
`reset_at`	datetime	When the rate limit window resets
`timestamp`	datetime	Event timestamp

RateLimitEventType Enum

Value	Description
`RATE_LIMIT_WARNING`	Approaching rate limit threshold
`RATE_LIMIT_HIT`	Rate limit exceeded, requests will be delayed

Example

{
  "type": "rate_limit",
  "event": "RATE_LIMIT_WARNING",
  "requests_remaining": 10,
  "reset_at": "2025-01-15T10:31:00Z",
  "timestamp": "2025-01-15T10:30:50Z"
}

Error Events

Delivers error notifications.

Type: error

Field	Type	Description
`type`	string	Always `"error"`
`code`	WsErrorCode	Error code
`message`	string	Human-readable error message
`details`	object?	Additional error context
`timestamp`	datetime	Event timestamp

WsErrorCode Enum

Value	Description
`INVALID_MESSAGE`	Received message could not be parsed
`INTERNAL_ERROR`	Server encountered an internal error

Example

{
  "type": "error",
  "code": "INVALID_MESSAGE",
  "message": "Failed to parse order request: missing required field 'symbol'",
  "details": {
    "field": "symbol"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Client Messages

Messages sent from your strategy to the server.

Ping/Pong (Heartbeat)

The server sends ping messages to check connection health. Your client must respond with pong.

Server sends:

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

Client responds:

{
  "type": "pong"
}

Event Acknowledgment

Strategies must acknowledge received events. This is required for backtest mode (controls time simulation) and informational-only for live trading.

Type: event_ack

Field	Type	Description
`type`	string	Always `"event_ack"`
`correlation_id`	string	Unique ID for tracking this acknowledgment
`events_processed`	string[]	List of event IDs that were processed
`timestamp`	integer	Unix timestamp (milliseconds) when events were processed

Example

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

Related Types

Order Types - Order schemas and enums
Position Types - Position schemas and P&L