Trade Request Lifecycle¶

Core rule¶

Trade commands in the TCP API are asynchronous by design.

A successful command response means:

the request payload passed validation
the business checks passed
the trade action was accepted into the server runtime flow

A successful command response does not guarantee that the final trade execution state has already been reached at the time of the response.

This applies to both:

client trade flow
manager trade flow

Request acknowledgment semantics¶

For trade mutation methods, the response should be treated as an acknowledgment of accepted processing, not as a final execution report.

Practical meaning:

200 means the server accepted the request into the trade lifecycle
later state changes are delivered through trade events and trade queries
clients should correlate subsequent trade events by order

Lifecycle stages¶

The trade lifecycle has two layers:

request acceptance layer
execution/state-transition layer

1. Request acceptance layer¶

At this stage the server:

validates input
checks permissions
checks account/group/symbol constraints
reserves identifiers when needed
enqueues the trade operation into runtime processing

If this stage succeeds, the API returns success.

2. Execution and state-transition layer¶

After acknowledgment, the trade continues through runtime processing and may transition to a new final or intermediate state.

Examples:

open request becomes active open position
close request becomes closed trade
cancel request becomes deleted trade
restore request becomes restored open trade

Canonical flow¶

Client or Manager Command
        |
        v
Input validation / permission checks
        |
        v
Trade business checks
        |
        v
Reserve order id if needed
        |
        v
Accept request into runtime queue
        |
        +--> TCP response: accepted acknowledgement
        |
        v
Runtime trade processing
        |
        v
Trade state transition
        |
        v
Trade event broadcast / trade query reflects new state

State transition examples¶

The exact internal state set depends on the command and runtime processing path, but the high-level lifecycle is:

Operation	Accepted request state	Typical resulting state
Open trade	`TS_OPEN_REQUEST`	`TS_OPEN_NORMAL`
Close trade	`TS_CLOSE_REQUEST`	`TS_CLOSED_NORMAL`
Delete trade	`TS_DELETE_REQUEST`	`TS_DELETED`
Cancel market trade	`TS_CANCEL_REQUEST`	`TS_DELETED`
Cancel pending trade	`TS_CANCEL_REQUEST`	`TS_DELETED`
Restore trade	`TS_RESTORE_REQUEST`	`TS_OPEN_RESTORED`
Update open trade	`TS_OPEN_UPDATE_REQUEST`	updated open trade
Update close trade	`TS_CLOSED_UPDATE_REQUEST`	updated closed trade
Update pending trade	`TS_PENDING_UPDATE_REQUEST`	updated pending trade

Pending order activation policy¶

Pending orders are activated asynchronously when market conditions reach the pending trigger price.

At activation time the server does not just flip the state. It reruns the same core open-trade checks used for a market open path, including:

symbol and group trade permissions
market/session availability
stop-level validation
current executable price resolution with group spread settings
margin calculation
commission calculation
free-margin check

This means pending activation is validated against the current runtime state of the account and market, not only against the values that existed when the pending order was originally accepted.

Activation outcomes¶

Activation result	Runtime behavior
Activation succeeds	Order moves through `TS_OPEN_REQUEST` to active open trade processing
`RET_TRADE_NO_MONEY`	Order stays pending and may be retried later
`RET_TRADE_MARKET_CLOSED`	Order stays pending and may be retried later
Terminal business/configuration error	Order moves to `TS_CANCEL_REQUEST` with `activation = ACTIVATION_CANCEL`

Examples of terminal activation errors:

invalid SL/TP
disabled trading for account/group/security
invalid volume versus current group security limits
missing security binding in the account group
incorrect resulting market command

When the server cancels a pending activation for a terminal reason, it appends the human-readable reason to the trade comment in the form:

[ACTIVATION_CANCEL: <reason>]

This allows downstream clients and managers to distinguish between:

a pending order that is still waiting for retryable conditions
a pending order that was rejected permanently during activation

Important design note¶

The initial API response and the final trade state are intentionally decoupled.

This makes the TCP trade API suitable for:

runtime queueing
deterministic order correlation
unified event-driven clients
manager operations and client operations with the same async model

Order as correlation identifier¶

order is the primary identifier for tracking a trade request through its lifecycle.

For open operations in particular, the response should include order, because:

the order id is reserved before the runtime enqueue step
subsequent events are correlated by order
follow-up actions such as update, close, cancel, or delete require order

Recommended response contract¶

For trade mutation methods, the recommended response shape is a flat acknowledgment payload in the response body:

{
  "accepted": true,
  "order": 123456,
  "state": 1
}

Additional fields may be returned when they are already known at acknowledgment time:

login
symbol
cmd
volume
action

What should not be assumed from the immediate response¶

After a successful response, the client should not assume that:

the trade is already fully executed
account recalculation is already fully propagated everywhere
all downstream trade events have already been emitted
the returned acknowledgment is a full final trade snapshot

Client responsibilities¶

Clients integrating with TCP trade methods should:

treat successful mutation responses as request acknowledgments
store the returned order
subscribe to trade events
refresh trade state by order when strict confirmation is required

Scope¶

This lifecycle declaration is the canonical contract for:

client trade methods
manager trade methods
structured acknowledgment responses for trade mutation methods