Docs
Trading

Place a market order

POST
/v1/accounts/{id}/orders/market

Sends a market order and waits for the broker's answer.

Send an Idempotency-Key header. Without one, a request that times out leaves you unable to retry safely: you cannot tell whether the order was placed, and guessing wrong opens a second position. With one, retrying is free — the same key returns the same answer and never places a second order.

Three failures are worth telling apart, and the response distinguishes them:

  • SEND_FAILED (502) — the order never reached the broker. retryable: true. Safe to resend.
  • ORDER_REJECTED (422) — the broker refused it, with a reason and its own return code. retryable says whether the reason was transient (a requote, a moved price) or permanent (insufficient margin, a closed market).
  • ORDER_UNRESOLVED (502) — we do not know. The order may be live at the broker. It is in unknown while we confirm the result with the broker. Do not resend it; poll the order instead.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer fx_live_<id>_<secret>.

A key is shown once, at creation. We cannot show it again or recover it for you. Keys carry an environment (live or test) in the key itself, so a test key pasted into a production config fails immediately instead of at the worst possible moment.

Scopes are per key. A key without accounts:write can read accounts and nothing else.

In: header

Path Parameters

id*string
Formatuuid

Header Parameters

idempotency-key?string

Any unique string, usually a UUID. A retry with the same key and body returns the first answer instead of placing a second order; the same key with a different body is refused.

Lengthlength <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/orders/market" \  -H "idempotency-key: 3f0c9a52-8a8e-4f7e-9b0e-6c1d2f5a7b10" \  -H "Content-Type: application/json" \  -d '{    "symbol": "EURUSD",    "side": "buy",    "volume": "0.01"  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",    "clientOrderId": null,    "symbol": "string",    "side": "buy",    "type": "market",    "intent": "open",    "brokerPositionId": null,    "volume": null,    "stopLoss": null,    "takeProfit": null,    "state": "accepted",    "stateDetail": null,    "needsReconciliation": true,    "retcode": null,    "retcodeText": null,    "brokerOrderId": null,    "brokerDealId": null,    "filledVolume": null,    "filledPrice": null,    "sentAt": null,    "settledAt": null,    "reconciledAt": null,    "createdAt": "2019-08-24T14:15:22Z"  }}

Place a limit, stop or stop-limit order POST

A success here means **accepted and waiting**, not filled — the broker answers `10008 PLACED` and the order sits in `accepted` until it triggers. A limit waits for a better price (buy below the market, sell above); a stop waits for a worse one and is how a breakout is traded (buy above, sell below). The wrong side is refused before anything is sent, with a message naming the order you probably meant — the broker's own `INVALID_PRICE` says nothing about which way round it should have been.

Positions on an account GET

What we last saw, with `observedAt` saying when. The broker is authoritative and this is a snapshot, not a ledger — `observedAt` is here so you can tell a current view from a stale one rather than having to assume. Open positions only, unless `includeClosed=true`.