Trading
Market and pending orders, stop loss and take profit as prices or distances, partial closes, close-by, close-all, server-side trailing stops and risk limits.
Updated
How trade calls work
- Trade calls need a key with the
tradepermission and anIdempotency-Keyheader (1–128 characters, e.g. a UUID). The same key with the same body returns the same command and never trades twice — retry a timed-out call with the same key. The same key with another body is 409 IDEMPOTENCY_MISMATCH. - With
?wait=N(0–60 s) the call answers when the command is final: 200 with the command, itsresultand (on an ACTIVE account) the resultingpositionororder; a failed command answers its error (e.g. 422 TRADE_REJECTED, 422 NOT_ENOUGH_MONEY). Without ?wait, or still running, the answer is 202 with the command. - Follow a command with
GET /v1/commands/{commandId}?wait=30or the eventCOMMAND_FINISHED(commandId, commandType, status, errorCode). - ACTIVE accounts trade at once. A STANDBY account can trade too, but each command first logs in (slower). With a stored investor password the terminal switches to the master password for the trade.
- Trade calls have their own per-minute limit (tradesPerMin in GET /v1/me), separate from reads.
202 Accepted (no ?wait, or still running after it)
{
"commandId": "cmd_Q2x9…", "accountId": "3f0c…", "type": "PLACE_ORDER",
"status": "QUEUED", "errorCode": null, "message": null, "result": null,
"attempts": 0, "deadlineAt": "…", "createdAt": "…", "finishedAt": null
}
curl "https://api.propmetaapi.com/v1/commands/cmd_Q2x9…?wait=30" -H "Authorization: Bearer $GW_KEY"
# 200 when final (SUCCEEDED, FAILED, CANCELLED), 202 while QUEUED / DISPATCHED / RUNNINGPlace an order
POST /v1/accounts/{id}/orders:
| Field | Rule |
|---|---|
symbol | required — symbol name as on the account's server. |
side | required — BUY or SELL. |
type | MARKET (default), LIMIT, STOP, or STOP_LIMIT (MT5 only). |
volume | required — lots (> 0, within the symbol's volumeMin / volumeMax / volumeStep). |
price | Pending orders, required: the order price. STOP_LIMIT: the stop price that triggers the limit order. Not allowed for MARKET. |
stopLimitPrice | STOP_LIMIT, required: the price of the limit order placed when price is reached. |
sl, tp | Stop loss / take profit: a price, or a distance with slUnits / tpUnits. 0 or omitted = none. |
slUnits, tpUnits | ABSOLUTE_PRICE (default), RELATIVE_PRICE, RELATIVE_POINTS, RELATIVE_PIPS, RELATIVE_CURRENCY, RELATIVE_BALANCE_PERCENTAGE. |
trailingStop | { distance, units?, activation?, step? } — a trailing stop for the position the order opens (ACTIVE accounts). |
expirationType | Pending orders: GTC (default), DAY, SPECIFIED, SPECIFIED_DAY (MT4: GTC or SPECIFIED). |
expiration | With SPECIFIED / SPECIFIED_DAY (required then): ISO-8601 time with offset. |
fillPolicy | FOK, IOC or RETURN (default: what the symbol allows). |
deviationPoints | Market orders: accepted slippage in points (0–10000). |
refPrice, maxSlippagePoints | Refuse the order if the price moved more than maxSlippagePoints from refPrice. |
magic | Integer ≥ 0 stored with the order and position. |
comment | Max 27 characters. |
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/orders?wait=30" -H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" -d '{
"symbol": "XAUUSD", "side": "SELL", "volume": 0.05,
"sl": 50, "slUnits": "RELATIVE_CURRENCY",
"tp": 1, "tpUnits": "RELATIVE_BALANCE_PERCENTAGE",
"deviationPoints": 30, "magic": 1001, "comment": "api"
}'# buy limit with an expiry
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/orders?wait=30" -H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" -d '{
"symbol": "EURUSD", "side": "BUY", "type": "LIMIT", "volume": 0.2, "price": 1.0800,
"sl": 15, "slUnits": "RELATIVE_PIPS", "tp": 1.0900,
"expirationType": "SPECIFIED", "expiration": "2026-10-10T16:00:00Z"
}'
# MT5 buy stop-limit: when the ask reaches 1.0950, a buy limit at 1.0940 is placed
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/orders?wait=30" -H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" -d '{
"symbol": "EURUSD", "side": "BUY", "type": "STOP_LIMIT", "volume": 0.1,
"price": 1.0950, "stopLimitPrice": 1.0940
}'The result of a filled market order is { existing, orderId, dealId, positionId, volume, price }; of a pending order { existing, orderId, state, positionId, volume, price }.
Stop loss and take profit as distances
| slUnits / tpUnits | sl / tp means |
|---|---|
ABSOLUTE_PRICE | sl / tp are prices (default). |
RELATIVE_PRICE | A distance in price units, e.g. 0.0020. |
RELATIVE_POINTS | A distance in points (× the symbol's point). |
RELATIVE_PIPS | A distance in pips: 10 points on 3- and 5-digit quotes, otherwise 1 point. |
RELATIVE_CURRENCY | The money (account currency) the position would lose / win at the stop, for this volume. |
RELATIVE_BALANCE_PERCENTAGE | The same as a % of the account balance. |
- The distance is measured from: the current price for a market order (ask for BUY, bid for SELL); the order price for a pending order (STOP_LIMIT: its stopLimitPrice); the open price when you change a position; the (new) order price when you change a pending order.
- The gateway turns it into a price below a buy / above a sell for sl (the other way for tp), rounded to the symbol's tick, and sends that price.
- Distances need the symbol figures from a connected terminal (the account's own, or another connected account of yours on the same server; money units need the account's own). Otherwise the answer is 409 ACCOUNT_NOT_CONNECTED — activate the account or send prices.
Change, cancel, close
# change a pending order (price, stops, expiration); null or 0 removes a stop
curl -X PATCH "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/orders/$ORDER_ID?wait=30" -H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" -d '{ "price": 1.0790, "tp": null }'
# change stops of a position: prices, or distances from its open price
curl -X PATCH "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/positions/$POSITION_ID?wait=30" -H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
-d '{ "sl": 10, "slUnits": "RELATIVE_PIPS", "tp": 1.0990 }'
# cancel a pending order (deleted as a whole)
curl -X DELETE "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/orders/$ORDER_ID?wait=30" \
-H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)"# close part of a position (omit volume to close it all); refuse if the price moved > 20 points from 1.0850
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/positions/$POSITION_ID/close?wait=30" -H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
-d '{ "volume": 0.05, "price": 1.0850, "maxSlippagePoints": 20 }'
# close a position by an opposite one of the same symbol (hedging accounts)
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/positions/$POSITION_ID/close-by?wait=30" -H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
-d '{ "oppositePositionId": "51234570" }'
# close everything (and delete pending orders) — or only one symbol
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/close-all?wait=60" -H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" -d '{}'
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/close-all?wait=60" -H "Authorization: Bearer $GW_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" -d '{ "symbol": "XAUUSD", "includePending": false }'- Closing, cancelling and close-all also work after your plan ended, so you can always flatten an account. Viewing positions and orders does too.
- close-all answers { closedPositions, cancelledOrders, remaining } in result.
Trailing stops
A trailing stop runs on the gateway (your software can be offline) for positions of ACTIVE accounts: the stop loss follows the price at distance, only towards profit, in steps of at least step (default 1 pip), once the position is activation in profit. Units: RELATIVE_PIPS (default), RELATIVE_POINTS, RELATIVE_PRICE. It needs the trade permission but no Idempotency-Key; sending it again replaces the settings. It ends when the position closes (status DONE).
# trail an open position 15 pips behind the price, once it is 10 pips in profit, in 2-pip steps
curl -X PUT https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/positions/$POSITION_ID/trailing-stop \
-H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" \
-d '{ "distance": 15, "units": "RELATIVE_PIPS", "activation": 10, "step": 2 }'
# → { "id": "…", "positionId": "51234567", "status": "ACTIVE", "distance": 0.0015, "activation": 0.001, "step": 0.0002,
# "lastStopLoss": null, "lastError": null, "pendingOrder": false, … }
# or together with the order: { "symbol": "EURUSD", "side": "BUY", "volume": 0.1, "trailingStop": { "distance": 15 } }
curl "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/trailing-stops?status=all" -H "Authorization: Bearer $GW_KEY"
curl -X DELETE https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/positions/$POSITION_ID/trailing-stop -H "Authorization: Bearer $GW_KEY"
curl -X DELETE https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/trailing-stops/$TRAILING_ID -H "Authorization: Bearer $GW_KEY"Statuses: ACTIVE, DONE, FAILED (see lastError), CANCELLED. A distance below the symbol's stops level is 422 INVALID_STOPS.
Risk trackers
A risk tracker measures drawdown and profit of an ACTIVE account every second, per DAY, WEEK (from Monday), MONTH (both from broker-time midnight) or LIFETIME. Limits are measured from the base at the start of each period: BALANCE, EQUITY or the HIGHER one (default).
- A breached drawdown limit raises
RISK_LIMIT_BREACHEDonce per period and, byaction: NOTIFY (event only), CLOSE_POSITIONS (closes everything), CLOSE_AND_BLOCK (closes everything and refuses new orders with 422 TRADE_NOT_ALLOWED until the period ends). - A reached profit target raises
RISK_TARGET_REACHED. - Creating or changing a tracker needs manage; actions that close positions need trade too. Up to 10 trackers per account (the daily drawdown limit not counted); names are unique and cannot start with @.
# daily 5 % drawdown limit: close everything and block new orders until the next broker day
curl -X POST https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/risk-trackers -H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" -d '{
"name": "daily-dd", "period": "DAY", "base": "HIGHER",
"maxDrawdownPct": 5, "action": "CLOSE_AND_BLOCK"
}'
# lifetime trailing drawdown of 1000 from a 10000 start, with a 10 % profit target (events only)
curl -X POST https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/risk-trackers -H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" -d '{
"name": "max-dd", "period": "LIFETIME", "baseBalance": 10000, "trailing": true,
"maxDrawdownAbs": 1000, "profitTargetPct": 10
}'
curl https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/risk-trackers -H "Authorization: Bearer $GW_KEY" # with the current period
curl "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/risk-trackers/$TRACKER_ID/periods?limit=30" -H "Authorization: Bearer $GW_KEY"Equity watches
# the complete list (up to 20); WATCH_TRIGGERED fires once when equity crosses the threshold
curl -X PUT https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/watches -H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" -d '{
"items": [
{ "name": "margin-call", "kind": "EQUITY_BELOW", "threshold": 8000, "hysteresis": 100 },
{ "name": "target", "kind": "EQUITY_ABOVE", "threshold": 12000 }
]
}'
# → { "version": 3 }A watch fires once when equity crosses its threshold and re-arms after equity moved back by hysteresis. The event WATCH_TRIGGERED carries watch, kind, threshold, equity, balance and at.
Copy trading
The gateway copies positions between your own accounts ticket by ticket: a leader position opens one copy on a hedging master account, and its SL/TP changes, partial closes and the close follow. Masters, allocations, volume ratio, filters, caps, the link lifecycle and the COPY_* events are in Copy trading.