API documentation

Integration guide

How to build on PropMetaAPI the right way: which account state to use, how to get changes pushed to you instead of polling, how to enforce risk rules, and how to trade without duplicates.

Updated

How it works

Every ACTIVE account runs in its own MetaTrader terminal on our servers, logged in to your broker around the clock. Your requests go to that terminal; changes it sees (trades, equity, connection) come back to you as events.

A STANDBY account is only stored. Reading it means a short login first, so reads are slower and need ?wait. Decide per account which state it needs — it is the biggest factor for speed and for your plan's ACTIVE limit.

Account lifecycle

StateWhat it meansUse it for
STANDBYStored, no connection. Costs no ACTIVE slot of your plan.Accounts you only read now and then; accounts waiting to be handed out.
CHECKA one-off login (up to ~1 min) that verifies the password and reads balance and history, then logs out.Right after registering; keeping an unused demo account alive (for example weekly).
ACTIVEA permanent connection: live data, events, watches, risk trackers, equity bars, fast trading.Every account your users trade or that you must monitor in real time.
bash
# 1. register (STANDBY) — the password is stored encrypted
curl -X POST https://api.propmetaapi.com/v1/accounts -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" \
  -d '{ "platform": "MT5", "broker": "Exness", "server": "Exness-MT5Trial12", "login": "12345678", "masterPassword": "…" }'

# 2. verify once: logs in, reads balance and history, logs out
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ID/check?wait=60" -H "Authorization: Bearer $GW_KEY"

# 3. hand it to your user: permanent connection
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ID/activate?wait=60" -H "Authorization: Bearer $GW_KEY"

# 4. when the user is done: back to STANDBY (frees the ACTIVE slot), or remove it
curl -X POST https://api.propmetaapi.com/v1/accounts/$ID/deactivate -H "Authorization: Bearer $GW_KEY"
curl -X DELETE https://api.propmetaapi.com/v1/accounts/$ID -H "Authorization: Bearer $GW_KEY"
Register and check accounts ahead of time (for example a pool of demo accounts), keep them STANDBY, and activate one only when you hand it to a user. Deactivate it when the user is done. A CHECK every few days keeps unused demo accounts from expiring at the broker.

Don't poll — get changes pushed

Polling every account every minute wastes your rate limit and still reacts late. Everything you would poll for is pushed:

ChannelWhat it isUse it for
WebhooksServer-to-server, signed, retried for 72 h, up to 50 events per call.Your backend reacting to trades, state changes, watches and risk limits.
Event feed GET /v1/events?after=The same events, pulled with a cursor, kept 14 days.A safety net: catch up after downtime, or instead of webhooks behind a firewall.
WebSocket /v1/wsLive quotes, profits, order updates and events over one socket.Dashboards and user interfaces that show live numbers.

Events you will want

EventWhat it means
ORDER_UPDATEPositions or pending orders changed: opened, modified, partly or fully closed, placed, filled, cancelled.
DEAL_ADDEDA new deal is in the account history.
ACCOUNT_STATE_CHANGEDConnected, disconnected, reconnecting, logged out …
AUTH_REJECTEDThe broker refused the password — ask your user for the new one (PATCH …/credentials).
WATCH_TRIGGEREDEquity crossed one of your watch thresholds.
DAILY_DRAWDOWN_BREACHEDThe account's daily drawdown limit was reached (with your restartId and the day's figures).
RISK_LIMIT_BREACHED / RISK_TARGET_REACHEDA risk tracker reached its drawdown limit or profit target.
COMMAND_FINISHEDA trade command you sent reached its final state.
SUBSCRIPTION_EXPIRING / SUBSCRIPTION_EXPIREDYour plan ends in 3 / 1 days, or has ended.

Reading the event feed

// Process every event exactly once; survive restarts by storing the cursor.
let after = await db.get("gw_cursor") ?? "0";
for (;;) {
  const res = await fetch(`https://api.propmetaapi.com/v1/events?after=${after}&limit=500`, {
    headers: { Authorization: `Bearer ${process.env.GW_KEY}` },
  });
  if (res.status === 410) { after = await resyncByTime(); continue; } // cursor older than 14 days
  const { items, nextAfter } = await res.json();
  for (const ev of items) await handleOnce(ev.id, ev);   // ev.id is unique and increasing
  after = nextAfter;
  await db.set("gw_cursor", after);
  if (items.length < 500) await new Promise((r) => setTimeout(r, 5000));
}
  • Process by event id and ignore ids you have seen: webhooks are delivered at least once, so the same event can arrive twice.
  • Use webhooks as the fast path and the event feed as the safety net — both carry the same events with the same ids.
  • Need a number now (balance, open positions)? Read it once when the event arrives; there is no need to poll on a timer.

Webhooks and signature checks → · WebSocket channels →

Risk rules (prop firms, managed accounts)

Risk trackers run inside the gateway and check every second, so a rule holds even when your system is slow or down. CLOSE_AND_BLOCK closes everything and refuses new orders until the period ends.

bash
# daily loss limit 5 % (day from 00:00 UTC, loss from start-of-day equity, 5 % of the start balance)
# and overall limit 10 % (trailing), enforced by the gateway every second
curl -X PUT https://api.propmetaapi.com/v1/accounts/$ID/daily-drawdown -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" \
  -d '{ "maxDrawdownPct": 5, "base": "EQUITY", "percentOf": "START_BALANCE", "resetTimezone": "UTC", "action": "CLOSE_AND_BLOCK", "confirmSec": 10, "restartId": "challenge-1:phase-1" }'
curl -X POST https://api.propmetaapi.com/v1/accounts/$ID/risk-trackers -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "max-loss", "period": "LIFETIME", "baseBalance": 10000, "trailing": true, "maxDrawdownPct": 10, "action": "CLOSE_AND_BLOCK" }'

# early warning before the limit: an event when equity drops below 9 600 (and again only after it rose 50 above)
curl -X PUT https://api.propmetaapi.com/v1/accounts/$ID/watches -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" \
  -d '{ "items": [ { "name": "near-limit", "kind": "EQUITY_BELOW", "threshold": 9600, "hysteresis": 50 } ] }'

# one equity candle per minute with its high / low and when they happened — for reports and audits
curl "https://api.propmetaapi.com/v1/accounts/$ID/equity-bars?after=0&limit=1000" -H "Authorization: Bearer $GW_KEY"
  • The daily drawdown limit (PUT …/daily-drawdown, one per account, switch it on or off) starts its day at midnight of any time zone, takes the prop rule "x % of the start-of-day balance", and starts over when you send a new restartId (next phase, voided breach). Risk trackers add WEEK (from Monday), MONTH (midnight broker time) and LIFETIME (from creation); base HIGHER uses the higher of balance and equity at the start of the period.
  • NOTIFY only sends the event (DAILY_DRAWDOWN_BREACHED or RISK_LIMIT_BREACHED); CLOSE_POSITIONS and CLOSE_AND_BLOCK act on the account and need a key with the trade permission.
  • Equity bars are kept 14 days; store them on your side if you need a longer audit trail.

Trading without surprises

bash
# one Idempotency-Key per intended trade; reuse it for every retry of that trade
KEY=$(uuidgen)
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ID/orders?wait=30" -H "Authorization: Bearer $GW_KEY" \
  -H "Idempotency-Key: $KEY" -H "Content-Type: application/json" \
  -d '{ "symbol": "EURUSD", "side": "BUY", "volume": 0.10, "sl": 25, "tp": 50, "slUnits": "RELATIVE_PIPS", "tpUnits": "RELATIVE_PIPS" }'

# 200 → done (result.positionId).  202 → still running: ask for the command, never send a new order
curl "https://api.propmetaapi.com/v1/commands/$COMMAND_ID?wait=60" -H "Authorization: Bearer $GW_KEY"
  • Every trade call needs an Idempotency-Key. Same key + same body = the same command, never a second order. Same key + different body = 409 IDEMPOTENCY_MISMATCH.
  • On a timeout or 5xx, resend with the same key or read GET /v1/commands/{id}. A new key after a timeout can open a second position.
  • SL / TP can be prices or distances: RELATIVE_PIPS, RELATIVE_POINTS, RELATIVE_PRICE, RELATIVE_CURRENCY (account money) or RELATIVE_BALANCE_PERCENTAGE.
  • Respect the symbol's minimum, maximum and step volume (GET …/symbols/{symbol}); otherwise 422 INVALID_VOLUME. Outside trading hours you get 423 MARKET_CLOSED.

History you can rely on

  • Deals and closed positions are complete or refused: while the history is still downloading you get 409 HISTORY_NOT_SYNCED (retryable) instead of a short list. Add ?wait=30 to wait for it.
  • Query by time with from / to (UTC). Times are also given in broker time (brokerTime) for daily rules.
  • DEAL_ADDED tells you when to read again, so there is no need to re-download history on a timer.

MT4 and MT5

FeatureMT5MT4
Market orders, SL/TP, partial close, close-by, close-allyesyes
LIMIT and STOP pending ordersyesyes
STOP_LIMIT pending ordersyesno
Pending expiration typesGTC, DAY, SPECIFIED, SPECIFIED_DAYGTC, SPECIFIED
Timeframesall 21 (M1 … MN1)M1, M5, M15, M30, H1, H4, D1, W1, MN1
Tick history and order bookyesno
Certificate accountsyesno

Unsupported features answer 422 NOT_SUPPORTED_ON_PLATFORM. Symbol names, contract sizes and trading hours come from the broker — read them with GET …/symbols instead of hard-coding them.

Security checklist

  • Call the API only from your server. Never put a key in a browser, a mobile app or a public repository.
  • Give each part of your system its own key with only the permissions it needs (read, trade, manage) and, where possible, only its accounts.
  • Ask support to add your servers' IPs (IPv4 addresses or CIDRs) to your client's allowlist; requests from anywhere else are then refused. GET /v1/debug/headers shows the address the gateway sees.
  • Check every webhook's signature and timestamp before trusting it, and answer within 10 s.
  • Rotate keys from the panel when people leave or a key may have leaked; the old key stops at once.

Every endpoint at a glance

All routes your key can use, grouped. Click a path for parameters, request body, responses and a curl example in the API reference

Plan & keys

GET/v1/meYour plan: paid period, limits and usage, and the calling key (answers after expiry and while suspended too)
GET/v1/keysYour keys this key may manage
POST/v1/keysA key with at most this key's permissions and accounts (shown once)
DELETE/v1/keys/{id}Revoke a key this key could have made, and the keys it made (its sockets close within 10 s)

Accounts

GET/v1/accountsList accounts (oldest first, cursor paging)
POST/v1/accountsRegister an account (repeat-safe: same id for the same server+login; 200 when it existed)
GET/v1/accounts/{id}Account state (with its daily drawdown limit)
DELETE/v1/accounts/{id}Remove (no way back)
PATCH/v1/accounts/{id}/credentialsReplace passwords (auth of a changed password back to UNKNOWN; ACTIVE restarts)
POST/v1/accounts/{id}/activatePermanent connection; ?wait: until connected (200) or a failure
POST/v1/accounts/{id}/deactivateBack to STANDBY (the permanent terminal stops)
POST/v1/accounts/{id}/checkOne-off login, read and history sync (verifies the credentials and the broker files)
GET/v1/accounts/{id}/summaryAccount information (balance, equity, margin …) + connected / stale / asOf
GET/v1/accounts/{id}/logsTerminal / EA / lifecycle log lines (14 days), oldest first after a cursor
PATCH/v1/accounts/{id}/connectionProxy and / or MT5 certificate of the terminal (null removes; ACTIVE restarts)
POST/v1/accounts/{id}/reconnectRestart the terminal of an ACTIVE account that lost its connection (DISCONNECTED / CRASHED / ERROR); a start in progress is left alone, at most once per 30 s
POST/v1/accounts/deactivate-allYour ACTIVE accounts (all, or accountIds) back to STANDBY
POST/v1/accounts/orphansYour ACTIVE accounts not in keepAccountIds back to STANDBY (dryRun only reports)
GET/v1/accounts/{id}/detailsEverything the terminal reports about the account (name, stop-out levels, limits, server time...)
GET/v1/accounts/{id}/mailsTerminal mailbox
POST/v1/accounts/{id}/refreshFresh snapshot from the terminal (profits)
GET/v1/accounts/{id}/rawAccount, server, summary, positions, orders and symbols in one answer

Trading

GET/v1/accounts/{id}/positionsOpen positions (409 ACCOUNT_NOT_CONNECTED when not current); sort / filter
GET/v1/accounts/{id}/positions/{positionId}One open position
PATCH/v1/accounts/{id}/positions/{positionId}Change SL/TP of a position (prices, or distances from the open price)
GET/v1/accounts/{id}/ordersPending orders (409 ACCOUNT_NOT_CONNECTED when not current); sort / filter
POST/v1/accounts/{id}/ordersMarket or pending order (LIMIT, STOP, STOP_LIMIT with expiration)
GET/v1/accounts/{id}/orders/{orderId}One pending order
PATCH/v1/accounts/{id}/orders/{orderId}Change a pending order (price, SL/TP, stop-limit price, expiration)
DELETE/v1/accounts/{id}/orders/{orderId}Cancel a pending order
GET/v1/accounts/{id}/ticketsIds of open positions and pending orders
POST/v1/accounts/{id}/positions/{positionId}/closeClose (part of) a position
POST/v1/accounts/{id}/positions/{positionId}/close-byClose a position by an opposite one of the same symbol
POST/v1/accounts/{id}/close-allDelete pendings, close every position (or only those of `symbol`)
PUT/v1/accounts/{id}/positions/{positionId}/trailing-stopServer-side trailing stop of an open position (ACTIVE accounts)
DELETE/v1/accounts/{id}/positions/{positionId}/trailing-stopStop trailing a position (the current stop loss stays)
DELETE/v1/accounts/{id}/trailing-stops/{trailingId}Cancel a trailing stop by its id (also one still waiting for its pending order to fill)
GET/v1/accounts/{id}/trailing-stopsTrailing stops of the account (newest first)

Market data

GET/v1/accounts/{id}/symbolsSymbols (names, or full specs with details=true; filter with * and ?)
GET/v1/accounts/{id}/symbols/{symbol}Full specification of one symbol
GET/v1/accounts/{id}/symbols/{symbol}/sessionsQuote and trade sessions per weekday (broker clock)
GET/v1/accounts/{id}/symbol-groupsSymbol groups (from the symbols' paths)
GET/v1/accounts/{id}/trade-rightsTrade rights of symbols (direction, close-only, close-by, order kinds)
GET/v1/accounts/{id}/quotesLatest quotes
GET/v1/accounts/{id}/market-watchMarket watch rows: bid/ask, day high/low, open, previous close, change
GET/v1/accounts/{id}/tick-valuesTick values (format=array: [symbol, tickValue, tickSize])
GET/v1/accounts/{id}/margin-requiredMargin needed for an order
GET/v1/accounts/{id}/sessions/statusIs the trade / quote session open now
GET/v1/accounts/{id}/ratesPrice bars in [from,to), or `count` bars back from `from`; symbols= for several
GET/v1/accounts/{id}/rates/todayBars of today (broker day)
GET/v1/accounts/{id}/rates/monthBars of 30 days from a date
GET/v1/accounts/{id}/rates/high-lowHighest and lowest price in a range, with their times
POST/v1/accounts/{id}/rates/requestsAsynchronous bars: the answer comes on the WebSocket channel quoteHistory
GET/v1/accounts/{id}/rates/requests/{requestId}Result of an asynchronous bars request (kept one hour)
GET/v1/accounts/{id}/ticksTick history (MT5)
POST/v1/accounts/{id}/tick-historyStream the tick history from `from` to now on the WebSocket channel tickHistory (MT5)
DELETE/v1/accounts/{id}/tick-history/{symbol}Stop a tick-history stream
GET/v1/accounts/{id}/server-timeBroker clock, offset and DST of the server
GET/v1/accounts/{id}/subscriptionsLive data subscriptions of this key
POST/v1/accounts/{id}/subscriptionsLive data for this key, kept 10 minutes after the last use. Read it on /v1/ws with a listening subscription: {op:"subscribe", channel, accountId, passive:true} (all symbols the account streams)
DELETE/v1/accounts/{id}/subscriptionsRemove live data subscriptions

History & statistics

GET/v1/accounts/{id}/dealsClosed deal legs in [from,to), ordered by (time, id) — 409 HISTORY_NOT_SYNCED, never a short list
GET/v1/accounts/{id}/positions/{positionId}/dealsAll legs of one position (paged)
GET/v1/accounts/{id}/history/positionsClosed positions (legs aggregated) in [from,to) or by ids — same completeness rule as /deals
GET/v1/accounts/{id}/history/ordersOrders that left the terminal: filled, cancelled, expired (read from the terminal)
GET/v1/accounts/{id}/history/statusHistory sync status
GET/v1/accounts/{id}/closed-ordersLast closed positions, newest first (stored history, no sync wait)
GET/v1/accounts/{id}/statsTrading statistics (win rate, profit factor, drawdown …)
GET/v1/accounts/{id}/equity-historyBalance / equity series (deals, equity bars; reconstruct=true fills older periods from price history)
GET/v1/accounts/{id}/stats/equityStatistics plus the equity series
GET/v1/accounts/{id}/stats/unrealizedFloating profit over time and of the open positions (open positions from the live figures; totalUnrealized = equity - balance - credit; stale: true when the account is not connected)
GET/v1/accounts/{id}/equity-barsClosed one-minute equity bars after a cursor (410 CURSOR_EXPIRED past retention)

Risk management

GET/v1/accounts/{id}/risk-trackersRisk trackers with the current period's figures
POST/v1/accounts/{id}/risk-trackersDrawdown / profit limits per DAY, WEEK, MONTH (broker-time midnight) or LIFETIME
GET/v1/accounts/{id}/risk-trackers/{trackerId}One risk tracker
PATCH/v1/accounts/{id}/risk-trackers/{trackerId}Change limits / action / enabled (applies to the running period)
DELETE/v1/accounts/{id}/risk-trackers/{trackerId}Remove a risk tracker
GET/v1/accounts/{id}/risk-trackers/{trackerId}/periodsStatistics per period, newest first
GET/v1/accounts/{id}/daily-drawdownThe account's daily drawdown limit with today's figures
PUT/v1/accounts/{id}/daily-drawdownSet the daily drawdown limit (the whole setting; the same body again changes nothing)
PATCH/v1/accounts/{id}/daily-drawdownSwitch on / off, or change limits, action, confirmSec, balanceAdjust (applies to the running day)
DELETE/v1/accounts/{id}/daily-drawdownRemove the daily drawdown limit and its days (a block ends with it)
GET/v1/accounts/{id}/daily-drawdown/daysThe days, newest first (a day closed by a restart ends at the restart)

Events & streaming

PUT/v1/accounts/{id}/watchesReplace equity watches (event WATCH_TRIGGERED)
GET/v1/commands/{id}Command status
GET/v1/eventsYour event feed, oldest first after a cursor (410 CURSOR_EXPIRED past the 14-day retention)
GET/v1/wsWebSocket (upgrade): live data and the event feed

Webhooks

GET/v1/webhooksYour webhooks (delivery state)
POST/v1/webhooksDeliver events to a URL (the answer shows the signing secret once)
GET/v1/webhooks/{id}One webhook (delivery state)
PATCH/v1/webhooks/{id}Change url / filters / enabled (enabled: true clears a failure state)
DELETE/v1/webhooks/{id}Remove a webhook
POST/v1/webhooks/{id}/rotate-secretA new signing secret (shown once; the old one stops signing at once)
POST/v1/webhooks/{id}/testSend one WEBHOOK_TEST event now and answer with the URL's answer
GET/v1/webhooks/{id}/deliveriesRecent delivery attempts (7 days), newest first

Billing & usage

GET/v1/billing/invoicesYour invoices, newest first (answers after expiry too)
GET/v1/billing/invoices/{id}One invoice
GET/v1/billing/usageUsage per UTC day (peak ACTIVE accounts, account hours, requests; answers after expiry too)
GET/v1/metrics/meRequests, errors and trade calls of the calling key per minute

Brokers & servers

GET/v1/serversBroker servers your accounts can use
GET/v1/brokersBrokers you can use: approved ones and your own uploads (file metadata, status)
POST/v1/brokersUpload a broker's server files (MT5 servers.dat, MT4 .srv or servers.ini) — repeat-safe; 409 when the broker has other files
GET/v1/brokers/{id}One broker
DELETE/v1/brokers/{id}Remove your own broker no registered account uses
PUT/v1/brokers/{id}/filesReplace the files of your own broker (back to PENDING; running terminals keep theirs until their next start)
GET/v1/broker-requestsYour requests to add a broker (newest first)
POST/v1/broker-requestsAsk the operator to add a broker you have no files for — repeat-safe for an open request
DELETE/v1/broker-requests/{id}Withdraw an open broker request
GET/v1/brokers/searchSearch the brokers and servers you can use by company / name
GET/v1/servers/{name}/access-pointsAddresses of a server with their TCP connect time from the gateway

Copy trading

GET/v1/copy/masters/{accountId}One copy master
PUT/v1/copy/masters/{accountId}Register / change a copy master (only the fields sent change)
GET/v1/copy/allocations/{externalId}One allocation with copy counters
PUT/v1/copy/allocations/{externalId}Upsert an allocation (versioned; leader != master, no cycles)
DELETE/v1/copy/allocations/{externalId}Remove an allocation without open copies (409 STATE_CONFLICT with openLinks otherwise)
POST/v1/copy/allocations/{externalId}/modeACTIVE, CLOSE_ONLY or PAUSED (only positions opened after activation are copied)
PUT/v1/copy/symbol-mapsSymbol mapping between servers (per client)
GET/v1/copy/mastersCopy masters with their account and copy counters
GET/v1/copy/allocationsAllocations (filter by leader, master, mode) with copy counters
GET/v1/copy/linksLeader/master links, newest first, paged
GET/v1/copy/logsCopy log: oldest first after a cursor (default) or newest first with order=desc, limit ≤ 500

mtapi compatibility

GET/compat/{platform}/{method}mtapi.io-compatible methods (same names and parameters; id = account id)

Tools & status

GET/v1/audit-logYour security history: keys, accounts, credentials, webhooks, IP allowlist, copy and risk settings, and operator changes on your data (newest first; needs a key not limited to some accounts)
GET/v1/statusFree capacity and your ACTIVE accounts that are not connected
GET/v1/openapi.jsonThis document (without operator routes)
GET/v1/debug/headersHeaders and client address as the gateway sees them (secrets redacted) — for IP allowlist problems
POST/v1/tools/ping-hostTCP connect time from the gateway to broker addresses
GET/v1/versionVersions of the API and protocol
GET/v1/healthLiveness, no auth
GET/v1/readyReadiness, no auth: Postgres and Redis answer and the api is not shutting down (503 otherwise)
GET/v1/docsSwagger UI (no auth for the page; it asks for the key)