Accounts & brokers
How MetaTrader accounts get into the gateway: broker servers, registration, checks, permanent connections, and every state an account can be in.
Updated
Lifecycle
POST /v1/accounts → STANDBY (registered, no terminal)
POST /v1/accounts/{id}/check → logs in once, reads the account, syncs history; verifies the broker
POST /v1/accounts/{id}/activate → ACTIVE (permanent terminal): ASSIGNING → STARTING → CONNECTING → CONNECTED
POST /v1/accounts/{id}/deactivate → STANDBY again
DELETE /v1/accounts/{id} → REMOVED (final)Registered accounts count against limits.accounts and ACTIVE accounts against limits.activeAccounts of GET /v1/me; going over either answers 403 QUOTA_EXCEEDED. Only ACTIVE accounts stream live data, run trailing stops and risk trackers and trade without a login delay. A STANDBY account can still be read and traded: each call then logs in for it.
Broker servers
An account is registered with its broker name and the exact server name its terminal shows. The broker must be one the gateway knows: we provide the server files of the brokers listed by GET /v1/brokers (also shown under Account → API → Brokers), so for these you need no files at all.
curl "https://api.propmetaapi.com/v1/brokers?platform=MT4" -H "Authorization: Bearer $GW_KEY"
# {
# "items": [
# { "id": "…", "platform": "MT4", "name": "IC Markets", "status": "VERIFIED", "approved": true,
# "servers": ["ICMarkets-Demo01", "ICMarkets-Live07", …], "company": "Raw Trading Ltd", … }
# ]
# }
curl https://api.propmetaapi.com/v1/servers -H "Authorization: Bearer $GW_KEY" # servers already in use
curl "https://api.propmetaapi.com/v1/brokers/search?company=icmarkets" -H "Authorization: Bearer $GW_KEY"
curl "https://api.propmetaapi.com/v1/servers/ICMarkets-Live07/access-points?platform=MT4" -H "Authorization: Bearer $GW_KEY"statusis PENDING until an account logs in with the broker's current files (any successful check), then VERIFIED. Activation needs VERIFIED (409 BROKER_NOT_VERIFIED) — run a check first.- Broker missing? Send a broker request and we add it.
Broker requests
Broker not in GET /v1/brokers? Ask us to add it with POST /v1/broker-requests (manage key; no files needed) — or with "Request a broker" under Account → API → Brokers. We add the broker for every customer; your request then becomes DONE and carries its brokerId.
| Field | Rule |
|---|---|
platform | required — MT4 or MT5. |
name | required — broker name, 1–64 characters with at least one letter or digit ("IC Markets"). Case, spaces and punctuation do not matter: "ic-markets" and "ICMarkets" are the same broker. |
servers | optional — up to 50 exact server names as the terminal shows them ("ICMarketsSC-Demo"): letters, digits, space . _ + # ( ) -, 2–64 characters; duplicates are dropped. |
website | optional — the broker's website, an http(s) address of at most 200 characters. |
note | optional — free text for our team, up to 1000 characters (line breaks allowed, no control characters). |
# ask us to add a broker (manage key)
curl -X POST https://api.propmetaapi.com/v1/broker-requests -H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" \
-d '{ "platform": "MT5", "name": "IC Markets", "servers": ["ICMarketsSC-Demo", "ICMarketsSC-Live"], "website": "https://www.icmarkets.com" }'
# 201 (the same OPEN request again while one exists)
# { "id": "7c1e…", "platform": "MT5", "name": "IC Markets", "servers": ["ICMarketsSC-Demo", "ICMarketsSC-Live"],
# "website": "https://www.icmarkets.com", "note": null, "status": "OPEN", "brokerId": null, "operatorNote": null,
# "resolvedAt": null, "createdAt": "2026-10-22T09:00:00.000Z", "updatedAt": "2026-10-22T09:00:00.000Z" }
# 409 STATE_CONFLICT { "details": { "brokerId": "…" } } → the broker is already available: register accounts with it
# 403 QUOTA_EXCEEDED → more than 20 OPEN requests
# poll your requests (newest first) until status is DONE or REJECTED
curl https://api.propmetaapi.com/v1/broker-requests -H "Authorization: Bearer $GW_KEY"
# { "items": [ { "id": "7c1e…", "status": "DONE", "brokerId": "3f0c…", "resolvedAt": "2026-10-23T10:12:00.000Z", … } ] }
# withdraw an OPEN request
curl -X DELETE https://api.propmetaapi.com/v1/broker-requests/$REQUEST_ID -H "Authorization: Bearer $GW_KEY" # { "ok": true }- 201 with the request. Repeat-safe: while an OPEN request of the same broker and platform exists, that request is answered again instead of a second one.
- 409 STATE_CONFLICT when a broker of that name and platform is already available to you (approved for everyone, or your own upload) — details.brokerId names it: register your accounts with it.
- 403 QUOTA_EXCEEDED above 20 OPEN requests; 400 VALIDATION when the name has no letter or digit.
- GET /v1/broker-requests (read key) lists your requests, newest first, at most 200; poll status there. Every item has id, platform, name, servers, website, note, status, brokerId, operatorNote, resolvedAt, createdAt and updatedAt.
- DELETE /v1/broker-requests/{id} withdraws an OPEN request ({ ok: true }); a request that is not open any more (or not yours) answers 404 NOT_FOUND.
| status | Meaning |
|---|---|
OPEN | Waiting for our team. You can withdraw it with DELETE /v1/broker-requests/{id}. |
DONE | The broker was added: brokerId names it and it is in GET /v1/brokers — register accounts with the broker name and the exact server name. resolvedAt tells when. |
REJECTED | We declined it; operatorNote says why. A resolved request can be set back to OPEN when we look at it again. |
A request becomes DONE as soon as the broker is available to every customer — every OPEN request of that broker name and platform is resolved at once. We may also answer a request with an operatorNote, as DONE or REJECTED. There is no API event for it: poll the list (the site also sends you a notification).
Uploading server files yourself (optional)
Not needed for the brokers we provide. If you need a broker before we add it and you have its files, you can upload them (needs a manage key that is not limited to some accounts):
- MT5: one file,
servers.dat, from the terminal data folder (File → Open Data Folder → Config) after you logged in to the broker once. - MT4: the broker's
.srvfiles from the data folder'sconfigfolder (one per server), or the oneconfig/servers.iniof MT4 build 1491+. Account server names are checked against .srv files (not against servers.ini). - Up to 500 files, about 16 MB in all, base64 in JSON. The same name with other files answers 409 STATE_CONFLICT (use PUT …/files instead).
# MT4: every .srv file of the broker (terminal data folder → config/*.srv)
curl -X POST https://api.propmetaapi.com/v1/brokers \
-H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" \
-d "{
\"platform\": \"MT4\",
\"name\": \"IC Markets\",
\"files\": [
{ \"name\": \"ICMarkets-Live07.srv\", \"contentBase64\": \"$(base64 -w0 ICMarkets-Live07.srv)\" },
{ \"name\": \"ICMarkets-Demo01.srv\", \"contentBase64\": \"$(base64 -w0 ICMarkets-Demo01.srv)\" }
]
}"
# 201 Created (200 when exactly these files were uploaded before)
# the broker added servers: replace the files (back to PENDING until the next successful check)
curl -X PUT https://api.propmetaapi.com/v1/brokers/$BROKER_ID/files -H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" -d '{ "files": [ … ] }'- Your upload is private: your accounts can use it at once; other customers only after we approved it (
approved: true). - Like every broker it stays PENDING until a successful check, then VERIFIED.
- You can replace or delete (DELETE /v1/brokers/{id}) only your own upload, only while no other customer's account uses it, and delete only when no registered account uses it.
Register an account
POST /v1/accounts with:
| Field | Rule |
|---|---|
platform | required — MT4 or MT5. |
broker | Broker name as in GET /v1/brokers (case and spaces do not matter). With server, or use host instead. |
server | Exact trade server name, e.g. Exness-MT5Trial12 (max 128). MT4: must be one of the broker's servers listed in GET /v1/brokers. |
host, port | Instead of broker + server: an address of the trade server (port default 443). Unknown address: 422 SERVER_UNKNOWN. |
login | required — account number, digits only, sent as a string. |
masterPassword | required — trading password (1–128 printable characters). |
investorPassword | optional — read-only password; reads and checks then log in read-only and the master password is used only to trade. |
externalRef | optional — your own reference (max 128); filter with ?externalRef=. |
proxy | optional — { type: SOCKS4 | SOCKS5 | HTTP, host, port, user?, password? }; the host must be public. |
certificate | optional, MT5 only — { contentBase64: the .pfx file, password } for brokers with extended authentication. |
dailyDrawdown | optional — the account's daily drawdown limit, same body as PUT /v1/accounts/{id}/daily-drawdown (see Daily drawdown). Registering the same account again with the same setting changes nothing. |
- 201 with the account (STANDBY). The same server + login again answers 200 with the same id and applies new passwords, externalRef or proxy.
- 422 BROKER_NOT_FOUND (no files for that broker), 422 SERVER_NOT_SUPPORTED (MT4 server not in the files — details.servers lists them), 422 SERVER_UNKNOWN (host matches no server), 403 QUOTA_EXCEEDED (registered-accounts limit).
- Registering does not log in. Passwords are stored encrypted and never returned.
# first page (oldest first); then pass nextCursor until it is null
curl "https://api.propmetaapi.com/v1/accounts?state=ACTIVE&limit=100" -H "Authorization: Bearer $GW_KEY"
curl "https://api.propmetaapi.com/v1/accounts?state=ACTIVE&limit=100&cursor=$NEXT_CURSOR" -H "Authorization: Bearer $GW_KEY"
# by your own reference
curl "https://api.propmetaapi.com/v1/accounts?externalRef=customer-42" -H "Authorization: Bearer $GW_KEY"Account states
Every account answer carries two states:
desiredState— what you asked for:STANDBY,ACTIVEorREMOVED.runtimeState— what the gateway observes, with the reason inlastError:
| runtimeState | Meaning |
|---|---|
IDLE | STANDBY account, no terminal running. |
CHECKING | A check (one-off login) is running. |
ASSIGNING | ACTIVE: waiting for a terminal. |
STARTING | ACTIVE: the terminal is starting. |
CONNECTING | ACTIVE: logging in to the broker. |
CONNECTED | ACTIVE: logged in; positions, quotes and trading are live. |
DISCONNECTED | The connection to the broker dropped; the terminal retries by itself (POST …/reconnect forces a restart). |
CRASHED | The terminal stopped unexpectedly; it is restarted automatically. |
AUTH_REJECTED | The broker refused the login or password. Fix it with PATCH …/credentials (an ACTIVE account restarts), or call activate again. |
ACCOUNT_DISABLED | The broker disabled the account. After fixing it with the broker, call activate again. |
ERROR | The terminal could not run (see lastError). Call activate again or POST …/reconnect. |
REMOVED | The account was removed. |
masterAuth and investorAuth are UNKNOWN until a login used that password, then OK or REJECTED. With a REJECTED master password, trade commands fail at once with 409 MASTER_AUTH_REJECTED until you set a new one. historySyncedUntil tells how far the stored deal history reaches.
Check
POST /v1/accounts/{id}/check (read permission) logs in once, reads balance, positions and orders, and downloads the trade history. It is the way to validate credentials before activating, and a successful check marks the broker VERIFIED.
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/check?wait=60" -H "Authorization: Bearer $GW_KEY"
# 200: the check SUCCEEDED
# { "commandId": "cmd_…", "type": "CHECK", "status": "SUCCEEDED", …,
# "account": { "id": "…", "masterAuth": "OK", "historySyncedUntil": "…", … },
# "summary": { "balance": 10000, "equity": 10000, "currency": "USD", "connected": true, … } }
# 202: still running → GET /v1/commands/{commandId}?wait=30
# 409 AUTH_REJECTED: { "code": "AUTH_REJECTED", "details": { "which": "master" }, … }- ?wait defaults to 45 s (max 60). A check that is already running is joined instead of starting another.
- Reads of a STANDBY account with
?wait(summary, positions, orders, deals …) run a check for you; a check that succeeded in the last 60 s is reused, so several reads log in once.
Activate and stay connected
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/activate?wait=60" -H "Authorization: Bearer $GW_KEY"
# 200 CONNECTED · 202 still connecting (poll GET /v1/accounts/{id})
# 403 QUOTA_EXCEEDED { "details": { "limit": 100, "used": 100 } } → deactivate another account or upgrade
# 409 BROKER_NOT_VERIFIED → run a check of an account of the broker first
# 503 NO_CAPACITY (retryable) → retry in a minute- Activate is repeat-safe. On an ACTIVE account stuck in AUTH_REJECTED, ACCOUNT_DISABLED or ERROR it asks for a fresh start.
- Watch the connection with GET /v1/accounts/{id}, the WebSocket channel
accountState, or the eventsACCOUNT_STATE_CHANGEDandAUTH_REJECTED(feed, WebSocket or webhooks).
# the account itself
curl https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID -H "Authorization: Bearer $GW_KEY"
# your ACTIVE accounts that are not CONNECTED right now
curl https://api.propmetaapi.com/v1/status -H "Authorization: Bearer $GW_KEY"
# terminal / lifecycle log lines of the last 14 days
curl "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/logs?level=error" -H "Authorization: Bearer $GW_KEY"Passwords, proxy, certificate, reconnect
# new password(s); a changed password goes back to UNKNOWN and an ACTIVE account restarts its terminal
curl -X PATCH https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/credentials -H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" -d '{ "masterPassword": "new-trading-password" }'
# connect through a proxy (null removes it); MT5 certificate likewise
curl -X PATCH https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/connection -H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" -d '{ "proxy": { "type": "SOCKS5", "host": "proxy.example.com", "port": 1080 } }'
# restart a terminal that lost its connection (DISCONNECTED / CRASHED / ERROR), at most once per 30 s
curl -X POST https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/reconnect -H "Authorization: Bearer $GW_KEY"Deactivate and remove
POST /v1/accounts/{id}/deactivatestops the permanent terminal (202, back to STANDBY). The account, its history and settings stay.DELETE /v1/accounts/{id}removes it for good (202): queued commands are cancelled, watches dropped, copy allocations using it go CLOSE_ONLY and the passwords are wiped (once no command of the account is running — repeat the DELETE to finish). Its history is purged later.
# every ACTIVE account back to STANDBY (dryRun defaults to true and only reports: send false to do it)
curl -X POST https://api.propmetaapi.com/v1/accounts/deactivate-all -H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" -d '{ "dryRun": false }'
# keep only these ACTIVE; the others go STANDBY (dryRun defaults to true here too)
curl -X POST https://api.propmetaapi.com/v1/accounts/orphans -H "Authorization: Bearer $GW_KEY" \
-H "Content-Type: application/json" -d '{ "keepAccountIds": ["3f0c…", "8a2d…"], "dryRun": false }'