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.
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.
Stored, no connection. Costs no ACTIVE slot of your plan.
Accounts you only read now and then; accounts waiting to be handed out.
CHECK
A 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).
ACTIVE
A 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.
Polling every account every minute wastes your rate limit and still reacts late. Everything you would poll for is pushed:
Channel
What it is
Use it for
Webhooks
Server-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/ws
Live quotes, profits, order updates and events over one socket.
Dashboards and user interfaces that show live numbers.
Events you will want
Event
What it means
ORDER_UPDATE
Positions or pending orders changed: opened, modified, partly or fully closed, placed, filled, cancelled.
DEAL_ADDED
A new deal is in the account history.
ACCOUNT_STATE_CHANGED
Connected, disconnected, reconnecting, logged out …
AUTH_REJECTED
The broker refused the password — ask your user for the new one (PATCH …/credentials).
WATCH_TRIGGERED
Equity crossed one of your watch thresholds.
DAILY_DRAWDOWN_BREACHED
The account's daily drawdown limit was reached (with your restartId and the day's figures).
RISK_LIMIT_BREACHED / RISK_TARGET_REACHED
A risk tracker reached its drawdown limit or profit target.
COMMAND_FINISHED
A trade command you sent reached its final state.
SUBSCRIPTION_EXPIRING / SUBSCRIPTION_EXPIRED
Your 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.
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.
# 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.
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.
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.
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.
Restart 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
Live 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)
Floating 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)
Your 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)