Skip to main content

Server events subscription

POST 
/v1/server-events/accounts/:account_id/ws/events

This OpenAPI operation models the WebSocket subscription command message. The actual WebSocket connection handshake is signed as a GET request. The signed path field in EXN-DATA must exactly match the WebSocket connection path: /v1/server-events/accounts/{account_id}/ws/events.

Use this stream for:

  • transactions
  • account_state
  • instruments
  • hmr

Do not subscribe to ticks through this stream. Use /v1/server-events/accounts/{account_id}/ws/ticks for live ticks.

Server events subscription provides realtime updates about:

  • finalized account and trading state changes
  • rejected or failed processing results
  • account state events
  • HMR period snapshots and updates
  • instrument updates

After successful subscription to transactions, the server sends trading_state_snapshot containing the current trading state of the account.

Subsequent finalized account and trading state changes are delivered through transaction_event.

A transaction event may represent:

  • a trading transaction
  • a non-trading balance transaction
  • a rejected or failed processing result without changed trading entities

Trading transactions contain only entities that were created or changed as a result of the concrete transaction. Examples:

  • pending order placement may include one order and account_state
  • pending order placement with SL/TP may include multiple changed orders, for example the main pending order and a related SLTP order, plus account_state
  • market order execution may include order, deal, position and account_state
  • partial position close is delivered as a transaction_event; the position remains open and its volume decreases
  • position close may include order, deal, position and account_state

Trading snapshot may represent active SL/TP values directly on the related pending order, while transaction_event may include a separate SLTP order as one of the changed entities.

Non-trading balance transactions are also delivered as transaction events. Examples:

  • balance (deposit, withdrawal)
  • null_compensation
  • swap_fee
  • admin_fee
  • dividend
  • exness_dollar

Such events may contain only a balance-type deal and account_state. operation_id is omitted when absent, including for non-trading balance transactions.

Rejected or failed processing results are also delivered through transaction_event. They may contain an empty payload when no trading entities were changed. status values have the following meaning:

  • success means a finalized account or trading state change was produced
  • rejected means processing was rejected by validation or trading rules
  • failed means processing failed

Subscription account_state delivers periodic account floating state updates. In the current version, this subscription is intended for equity monitoring and sends account_state_event messages with:

  • balance
  • equity
  • used_margin

These events represent account state recalculation, primarily equity / floating state changes. Balance-changing operations are not delivered through account_state. The current standard delivery interval is 2 seconds.

Correlation fields:

  • operation_id identifies the concrete operation or platform-generated event operation and is placed at the event envelope level

Standalone periodic account state events are delivered through account_state_event.

Subscription hmr delivers High Margin Requirement events through this same server events stream. The client must supply an explicit list of instruments to receive HMR period events for. HMR events are delivered without the generic payload wrapper. For hmr_snapshot, periods is placed at the event top level. For hmr_update, upserted_periods and removed_period_ids are placed at the event top level. HMR events do not include event_time in the current version. After a successful hmr subscription, the server sends an hmr_snapshot message containing the full active and scheduled future HMR period state applicable to the selected account in periods. This snapshot is a recalculation of the client-applicable HMR conditions at the time it is produced; it is not a list of changed fields. Each period reports the concrete instruments it affects.

Subscription rules:

  • the client must provide one or more instruments; there is no all wildcard for hmr
  • each requested instrument must be available for the selected account
  • the list of instruments available for subscription can be retrieved using GET /v1/configuration/accounts/{account_id}/instruments
  • if at least one requested instrument is not available for the account, the entire hmr subscription request is rejected; existing subscriptions are not affected

The server may send a new hmr_snapshot during an active subscription only when the account's effective flexible HMR status changes. Clients should replace their local HMR period state with the latest snapshot.

New or updated HMR periods and removed HMR periods are delivered as incremental hmr_update messages while the hmr subscription is active. Clients should apply incremental updates on top of the latest HMR period snapshot and treat any subsequent hmr_snapshot as the new full baseline.

To stop receiving HMR period updates, send an unsubscribe request with event: hmr and the instrument list to remove from the active subscription.

Subscription instruments delivers realtime instrument condition updates.

After successful subscription, the client receives instrument_event messages only for instruments included in the subscription request.

Subscription rules:

  • the client may subscribe to one or more instruments; use ["all"] to subscribe to all instruments available for the selected account
  • each requested instrument must be available for the selected account
  • the list of instruments available for subscription can be retrieved using GET /v1/configuration/accounts/{account_id}/instruments
  • if at least one requested instrument is not available for the account, the entire subscription request is rejected; existing subscriptions are not affected

Instrument update semantics:

  • an instrument_event is sent when an instrument is created, updated, or deleted in the configuration; action indicates the lifecycle stage: new, upd, or del
  • the event contains the full current instrument condition object, not only changed fields; the payload schema matches InstrumentConditionResponse
  • events are account-scoped: the payload is resolved for the selected account and may differ between accounts
  • events are delivered only for instruments selected in the subscription request

To stop receiving instrument updates, send an unsubscribe request with event: instruments and the instrument list to remove from the active subscription. Use ["all"] to unsubscribe from all instrument updates.

Runtime restrictions:

  • unavailable if trade_mode is trading_disabled

Recovery guarantees and limits:

  • The WebSocket connection is not a durable event log. The server does not support replaying missed events, resuming a previous connection, or requesting gap-fill by id, operation_id, or timestamp.
  • Events are delivered only while the connection is alive and the corresponding subscription is active. Events produced while the client is disconnected or not subscribed may be missed.
  • If the per-connection send buffer overflows, for example because the client reads too slowly, the server may close the WebSocket connection; missed messages from that connection are not replayed.
  • On reconnect, the client must open a new WebSocket connection, send subscribe requests again, and treat the new trading_state_snapshot as the baseline for current state.
  • The snapshot contains current open orders, open positions, and account state. It does not reconstruct every missed transaction_event; use Trading History to reconcile historical orders and deals when needed.
  • If a REST ACK was received but the expected operation_id is not observed in Server Events, poll GET /v1/trading/accounts/{account_id}/operations/{operation_id} while operation status is retained, then reconcile current state using the trading snapshot.
  • If the client receives an unknown operation_id or cannot prove event continuity after reconnect, it should resubscribe and reconcile from snapshots instead of assuming that no events were missed.

Request​

Responses​

OK