API documentation

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 trade permission and an Idempotency-Key header (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, its result and (on an ACTIVE account) the resulting position or order; 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=30 or the event COMMAND_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.
json
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 / RUNNING

Place an order

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

FieldRule
symbolrequired — symbol name as on the account's server.
siderequired — BUY or SELL.
typeMARKET (default), LIMIT, STOP, or STOP_LIMIT (MT5 only).
volumerequired — lots (> 0, within the symbol's volumeMin / volumeMax / volumeStep).
pricePending orders, required: the order price. STOP_LIMIT: the stop price that triggers the limit order. Not allowed for MARKET.
stopLimitPriceSTOP_LIMIT, required: the price of the limit order placed when price is reached.
sl, tpStop loss / take profit: a price, or a distance with slUnits / tpUnits. 0 or omitted = none.
slUnits, tpUnitsABSOLUTE_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).
expirationTypePending orders: GTC (default), DAY, SPECIFIED, SPECIFIED_DAY (MT4: GTC or SPECIFIED).
expirationWith SPECIFIED / SPECIFIED_DAY (required then): ISO-8601 time with offset.
fillPolicyFOK, IOC or RETURN (default: what the symbol allows).
deviationPointsMarket orders: accepted slippage in points (0–10000).
refPrice, maxSlippagePointsRefuse the order if the price moved more than maxSlippagePoints from refPrice.
magicInteger ≥ 0 stored with the order and position.
commentMax 27 characters.
bash
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"
}'
bash
# 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 / tpUnitssl / tp means
ABSOLUTE_PRICEsl / tp are prices (default).
RELATIVE_PRICEA distance in price units, e.g. 0.0020.
RELATIVE_POINTSA distance in points (× the symbol's point).
RELATIVE_PIPSA distance in pips: 10 points on 3- and 5-digit quotes, otherwise 1 point.
RELATIVE_CURRENCYThe money (account currency) the position would lose / win at the stop, for this volume.
RELATIVE_BALANCE_PERCENTAGEThe 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

bash
# 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)"
bash
# 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).

bash
# 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).

For a daily loss limit per account — the day in your time zone, prop-firm percentage rules, a confirmation time and restarts — use Daily drawdown (one per account, listed here with kind DAILY_DRAWDOWN).
  • A breached drawdown limit raises RISK_LIMIT_BREACHED once per period and, by action: 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 @.
bash
# 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

bash
# 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.

When a trade fails

Trade errors, their HTTP status and whether a retry may help are listed in Errors & limits.