Authentication And Mode Preconditions

IMC API calls authenticate with the apikey field in the JSON request body. The API key identifies the user, license, broker, and broker-specific analyzer/live mode context.

Mode Metadata

Mode-aware responses include fields such as:

{
  "status": "success",
  "mode": "live",
  "balance_type": "live",
  "mode_version": 7
}

Clients must keep this snapshot and send it with trading-sensitive calls.

Required Fields

Trading/write endpoints and the positionsopen reconciliation read require:

Field	Meaning
expected_mode	Client's last known server mode, such as live or analyze.
expected_balance_type	Client's last known balance type, such as live or sandbox.
expected_mode_version	Client's last known mode version.
request_id	Caller-generated request id for tracing and lease/precondition correlation.

Example:

{
  "expected_mode": "live",
  "expected_balance_type": "live",
  "expected_mode_version": 7,
  "request_id": "order-20260713-001"
}

Error Codes

MODE_PRECONDITION_REQUIRED means the request did not include the required mode precondition fields.

SERVER_MODE_SWITCH_DETECTED means the submitted snapshot is stale. The client must refresh mode context and decide whether to continue.

NO_STRATEGY_EXPOSURE means the submitted strategy has no current broker-side exposure. For close reconciliation, this is zero-exposure proof.

Read Versus Write

Trading/write endpoints acquire protected mode leases before broker or analyzer side effects.

positionsopen is different: it is a read-only reconciliation endpoint. It validates API key identity and mode preconditions, but it does not create an ApiKeyModeLease.

Protected-order release

Protected placement, book, modification, cancellation and recovery require all mode fields above. For placement, request_id is a durable business idempotency key: retain its original payload after ambiguous outcomes. The server separately generates one-use mode-lease IDs. Protected book is non-billable but still mode-checked; DDPI routes require only apikey and retain their usage policy. See protected contracts.

Zero exposure alone is not confirmation of a closing fill or realized P&L.

Executable JSON policy

See request JSON validation. Bruno documentation blocks are prohibited; explanatory text belongs in Markdown. The recursive reserved-field rule is enforced before schemas, usage, queues and execution.