Docs
Waves

Place one trade on many accounts

Request

Synthetic example for the production API. Replace YOUR_API_KEY and the ids. Do not send it against a live account until you mean to.

curl -X POST "https://api.fxapis.com/v1/execution-waves" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 3f0c9a52-8a8e-4f7e-9b0e-6c1d2f5a7b10" \
  -H "Content-Type: application/json" \
  -d '{"accountIds":["string"],"side":"buy","volume":"0.01","symbol":"EURUSD"}'
POST
/v1/execution-waves

A multi-account order: one trade placed on many accounts at once. Every account is brought online first, then the orders are sent together — at executeAt, or as soon as every account is online.

A multi-account order is not all-or-nothing once sent, and cannot be. There is no transaction across a hundred brokers: accounts fill at different prices, some are rejected for margin, some go unanswered. So it never reports a single success or failure — it reports a result for each account, and summary counts what landed. An account whose result is unresolved must not be resent; poll its order.

dispatchSpreadMs is the gap between the first account's order being sent and the last. It is the number worth watching: as it grows, your accounts are getting different prices.

barrierPolicy decides what happens when some accounts are not online in time:

  • release-ready — trade on the accounts that are online, skip the rest. A partial entry beats a late one.
  • all-or-nothing — trade on none unless all are online. Note this is about sending: a broker can still reject an account's order after it was sent.
  • wait — keep waiting past executeAt until every account is online, up to expiresAt.

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 a label (live or test) in the key itself, so each configuration is easy to tell apart. Both reach real brokers: test with a broker demo account.

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

In: header

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

Send symbol or instrument, not both.

TypeScript Definitions

Use the request body type in TypeScript.

Send symbol or instrument, not both.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.fxapis.com/v1/execution-waves" \  -H "idempotency-key: 3f0c9a52-8a8e-4f7e-9b0e-6c1d2f5a7b10" \  -H "Content-Type: application/json" \  -d '{    "accountIds": [      "b75e4440-1cc9-49a6-8c9e-087e1aa69722"    ],    "side": "buy",    "volume": "0.01"  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "label": null,    "clientWaveId": null,    "symbol": null,    "instrument": null,    "side": "buy",    "baseVolume": null,    "state": "planned",    "stateDetail": null,    "barrierPolicy": "release-ready",    "executeAt": null,    "expiresAt": null,    "preparedAt": null,    "releasedAt": null,    "settledAt": null,    "dispatchSpreadMs": null,    "retryOf": null,    "retriedBy": [      "8a956f19-098d-41a0-9786-bbb5b13b13aa"    ],    "summary": {      "total": 0,      "filled": 0,      "partiallyFilled": 0,      "rejected": 0,      "skipped": 0,      "unresolved": 0    },    "legs": [      {        "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",        "orderId": null,        "symbol": "XAUUSD.a",        "volume": null,        "state": "pending",        "stateDetail": null,        "filledVolume": "0.01",        "partiallyFilled": true,        "sentAt": null,        "settledAt": null      }    ],    "createdAt": "2019-08-24T14:15:22Z"  }}

List multi-account orders GET

Multi-account orders in this workspace, newest first, with each one's state, symbol, side, number of accounts and summary of results.

Retry the accounts a multi-account order did not reach POST

Places a new multi-account order for the accounts of this one that were `skipped` (never sent: not online in time, trading switched off, no price). Same market, side, per-account volumes, stops and comment. Add `rejected` to `include` to retry the accounts the broker refused too. A `cancelled` or `abandoned` order sent nothing, so every account is retried. Only once the order has ended (`settled`, `cancelled` or `abandoned`); before that, **409** `WAVE_NOT_ENDED`. **409** `NOTHING_TO_RETRY` when no account matches. An `unresolved` account is never retried: it may have executed. The new order is checked like any new one (plan, accounts, the key's limits) and is linked both ways: its `retryOf` is this order, and this order's `retriedBy` lists it. **An `Idempotency-Key` is required**; the same key again returns the same new order (200, `idempotent-replay: true`).