Concepts

Idempotency and results

Every write takes an idempotency_key and none defaults it. Retrying with the same key returns the original answer. Execution methods never raise: a transport fault, a timeout and a broker rejection are all results with a reason you can read.

result = await client.execution.place_order(
    terminal.id, symbol="EURUSD", side="buy", volume="0.10",
    sl="1.0820", tp="1.0950", idempotency_key="order-0001",
)
if not result.ok:
    print(result.reason, result.mt5_retcode, result.retcode_text, result.comment_raw)

const result = await client.execution.placeOrder(terminal.id, {
  symbol: "EURUSD", side: "buy", volume: "0.10",
  sl: "1.0820", tp: "1.0950", idempotencyKey: "order-0001",
});
if (!result.ok) console.log(result.reason, result.retcode, result.retcodeText, result.commentRaw);

var result = await client.Execution.PlaceOrderAsync(terminal.Id, new PlaceOrder {
    Symbol = "EURUSD", Side = Side.Buy, Volume = 0.10m,
    Sl = 1.0820m, Tp = 1.0950m, IdempotencyKey = "order-0001",
});
if (!result.Ok) Console.WriteLine($"{result.Reason} {result.Retcode} {result.RetcodeText} {result.CommentRaw}");

ExecutionResult result = client.execution().placeOrder(terminal.id(), PlaceOrder.builder()
    .symbol("EURUSD").side(Side.BUY).volume(new BigDecimal("0.10"))
    .sl(new BigDecimal("1.0820")).tp(new BigDecimal("1.0950"))
    .idempotencyKey("order-0001").build());
if (!result.ok()) System.out.println(result.reason() + " " + result.retcode() + " " + result.retcodeText());

POST /v1/terminals/t_01J9.../orders HTTP/1.1
Idempotency-Key: order-0001

{"symbol": "EURUSD", "side": "buy", "volume": "0.10", "sl": "1.0820", "tp": "1.0950"}

HTTP/1.1 202 Accepted
{"command_id": "0d3c...", "state": "ACCEPTED", "duplicate": false, "expires_at": "2026-10-21T08:12:13Z"}

# The outcome arrives on results:{terminal_id} and events, or read it:
GET /v1/commands/0d3c...

HTTP/1.1 200 OK
{"command_id": "0d3c...", "kind": "order_place", "state": "FAILED", "final": true,
 "result": {"ok": false, "reason": "insufficient_funds", "retryable": false, "mt5_retcode": 10019,
            "retcode_text": "No money", "broker_latency_ms": 112, "agent_latency_ms": 7, ...}}

The result carries whether MFX Hub accepted the command, what the broker did with it, both latencies, and, when it went wrong, a reason from a granular vocabulary rather than a bucket. A reason the platform adds later arrives as its own string, never folded into “failed”.