Runtime Semantics

Runtime behavior for current state, history, async operations, transaction events, snapshots, idempotency, decimal values, pagination, subscriptions, rate limits, and floating account state.

Core model

The API separates current state, historical data, and realtime updates.

Object	Meaning
Order	A trading instruction.
Position	Open market exposure.
Deal	An executed financial event.
AccountState	Current account monetary state.
transaction_event	A realtime container with objects changed by one finalized account or trading event.

Current state vs history

Current trading state is available through GET /v1/trading/accounts/{account_id}/snapshot and through the trading_state_snapshot event after subscribing to transactions.

Historical data is available through GET /v1/history/accounts/{account_id}/orders and GET /v1/history/accounts/{account_id}/deals.

State boundary

Open orders and open positions are not returned by history endpoints. Read them from snapshot or Server Events.

Asynchronous trading operations

Mutating trading methods return an ACK response first. The ACK means the request was accepted for processing, not that the final trading result is already available.

Method pattern	Purpose
POST /v1/trading/accounts/{account_id}/orders	Place order.
PATCH /v1/trading/accounts/{account_id}/orders/{order_id}	Modify order.
DELETE /v1/trading/accounts/{account_id}/orders/{order_id}	Cancel one order.
DELETE /v1/trading/accounts/{account_id}/orders	Cancel orders.
POST /v1/trading/accounts/{account_id}/positions	Open position.
DELETE /v1/trading/accounts/{account_id}/positions/{position_id}	Close one position.
DELETE /v1/trading/accounts/{account_id}/positions	Close positions.

The final result is delivered through Server Events as transaction_event.

Correlation

Clients should correlate REST requests with final events using operation_id and client_request_id when an idempotency key was provided.

• Idempotency-Key is echoed back as client_request_id in the ACK response.
• The same value appears in the corresponding transaction_event.
• The same value appears in the operation status response.

This lets clients correlate events with originating requests without storing a separate operation_id mapping.

Transaction event semantics

A transaction_event may represent a successful trading transaction, a non-trading balance transaction, or a rejected/failed processing result without changed trading entities.

Status	Meaning	Client action
success	Finalized account or trading state changes were produced.	Apply changed entities to local state.
rejected	Processing was rejected by validation or trading rules.	Read error_code and change the request or account state before retrying.
failed	Processing failed.	Read error_code; retry only when the error is retryable.

For rejected or failed results, the payload may be empty and error_code may be provided.

Transaction payload composition

Transaction payload contains only entities created or changed by the concrete transaction. It must not contain all historically related entities.

Scenario	Possible payload
Pending order placement	order and account_state.
Pending order placement with SL/TP	Main pending order, SLTP order, and account_state.
Position opening	order, deal, position, and account_state.
Partial position close	order, deal, updated position, and account_state.
Balance operation	Balance-type deal and account_state.

Snapshots and recovery

After successful subscription to transactions, the server sends trading_state_snapshot. The snapshot contains currently active orders, currently open positions, and account state.

If the client does not receive expected operation_id values, receives an unknown operation_id, or loses connection, it should:

1. 1
   Restart Server Events subscription.
2. 2
   Receive a fresh trading_state_snapshot.
3. 3
   Reconcile local state using currently open positions and pending orders.
4. 4
   Continue processing subsequent transaction_event messages.

Recovery rule

If the client reconnects, it must resubscribe and rebuild local state from snapshots. WebSocket streams do not provide durable replay, resume tokens, or gap-fill.

Operation status polling

Use GET /v1/trading/accounts/{account_id}/operations/{operation_id} as a recovery mechanism when the corresponding transaction_event is not received within the expected time window.

Status	Client action
pending	Keep waiting or poll again with backoff.
confirmed	Treat the operation as finalized.
rejected	Inspect the error and change the request before retrying.
failed	Inspect the error and retry only if safe.

Operations are retained for 24 hours.

Idempotency

Mutating trading methods may accept Idempotency-Key. Clients should reuse the same idempotency key when safely retrying the same request.

When provided, the same value is returned as client_request_id in ACK, operation status, and transaction event.

Decimal values

Monetary, price, margin, and volume values are represented as decimal strings to avoid precision loss.

^[+-]?[0-9]+(?:\.[0-9]+)?$

Pagination

Historical endpoints use cursor-based pagination.

• cursor is an opaque continuation token.
• Clients must not parse or modify cursor.
• When cursor is used, it cannot be combined with filters except limit, unless explicitly stated otherwise.
• Historical collections are returned in ascending chronological order, from older to newer.

Candle history semantics

Candle history uses time-range or count-based loading.

• from is required.
• Use either from + count or from + to.
• from must be earlier than to.
• count is bidirectional and must be from -1000 to 1000, excluding 0.
• If to is used, the requested range must not exceed from + 1000 candles.
• Returned candles are sorted from older to newer.

Time range semantics: from is inclusive, to is exclusive, and a candle is included when its open time is greater than or equal to from and strictly less than to.

Server Events subscriptions

The Server Events connection supports transactions, account_state, instruments, and high margin requirement periods (hmr).

The Ticks stream uses a separate WebSocket endpoint. HMR no longer uses a separate WebSocket endpoint; HMR subscriptions are sent to the main Server Events stream.

Subscription	Initial message	Subsequent messages
transactions	trading_state_snapshot	transaction_event
account_state	none	account_state_event
instruments	none	instrument_event
hmr	hmr_snapshot	hmr_update, and sometimes a new hmr_snapshot

Account state events

The account_state subscription delivers periodic floating account state updates through account_state_event messages with balance, equity, and used_margin.

These events are intended for equity monitoring. Balance-changing operations are delivered through transaction_event, not through account_state.

Instrument events

The instruments subscription delivers realtime instrument condition updates.

• Clients may subscribe to specific instruments or use ["all"].
• Requested instruments must be available for the account.
• If at least one requested instrument is unavailable, the subscription request is rejected.
• Events are account-scoped.
• Instrument event payload contains the full current instrument condition object, not only changed fields.

Runtime restrictions

Some methods and streams are unavailable when trade_mode = trading_disabled. Some trading methods are unavailable when account_status = close_only.

Mode	Behavior
trading_disabled	Some methods and streams are unavailable.
close_only	Opening positions and placing pending orders are not allowed. Closing positions and cancelling orders remain allowed.

API rate limits

API methods are protected by request rate limits. Rate limit configuration can be retrieved using GET /v1/configuration/accounts/{account_id}/rate-limits.

• The endpoint returns configured limits, not current usage.
• The API does not provide remaining request quota.
• Clients must track request usage and remaining limits locally.

Recommended client behavior:

• Cache rate-limit configuration locally.
• Implement client-side throttling.
• Avoid burst retries for trading operations.
• Use WebSocket subscriptions instead of aggressive polling where possible.

TODO: Needs Product/API validation

The rate-limit endpoint/model is expected to change before final publication. Keep final wording aligned with the approved YAML.

Account floating state and equity

The API provides periodic floating account state updates through the Server Events account_state subscription. Floating account state updates are not delivered on every market tick.

Behavior	Current source detail
Interval	Updates are sent every 2 seconds.
Timing	The interval is shared globally for all subscribers.
Subscription start	The timing window does not depend on subscription start time.

This stream is intended primarily for account monitoring, reconciliation, UI synchronization, and floating state verification.

Clients should calculate floating state locally on every tick using:

equity = balance + unrealized_PNL

• Subscribe to realtime ticks.
• Calculate unrealized PnL locally.
• Recalculate equity on every tick.
• Periodically reconcile with account_state_event.