Skip to main content

Server events subscription

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

Server events subscription provides realtime updates about:

  • finalized account and trading state changes
  • rejected or failed processing results
  • account state events
  • 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 SLTP may include two orders and 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

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 and parent_operation_id are 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
  • parent_operation_id identifies the parent bulk operation when applicable. It is omitted for single-item operations and whenever no parent operation exists.

Standalone periodic account state events are delivered through account_state_event.

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