Getting started
PropMetaAPI connects MetaTrader 4 and 5 accounts of any broker to your software over REST, WebSocket and signed webhooks. This page takes you from a new API key to your first trade.
Updated
1. Get your API key
- Create an account with your work email — an address on your company website's domain (personal, free and temporary mailboxes such as Gmail or Outlook are not accepted) — and confirm it from the email we send.
- Order the Free Trial or a paid API plan on the plans page. The trial has the same API as the paid plans.
- When the order is confirmed your API access is created automatically and you get an email.
- Your token is in Account → API → Token & keys (reveal it with your password). It looks like
gw_1a2b3c4d5e6f_….
Your plan decides how many MetaTrader accounts you may keep connected at once (ACTIVE accounts) and for how long; you may register three times as many accounts (inactive accounts count too). The Free Trial has 5 active accounts for 10 days, without payment, for a confirmed work email, once per organization (email domain) and only if your account never had an API subscription; Starter, Growth and Business have 100, 200 and 500 active accounts per month (prices on the plans page). Renewing or upgrading keeps the same API key and adds the new period after the current end. GET /v1/me shows your limits, their usage and the end date.
2. Base URL and conventions
https://api.propmetaapi.com- Every route starts with
/v1and needs the headerAuthorization: Bearer <your key>(the wordBearer, one space, the key). - Requests and answers are JSON (
Content-Type: application/json). Account ids are UUIDs; position, order and deal tickets are strings. - Times are UTC in ISO-8601 (send them with an offset, e.g. 2026-01-01T00:00:00Z); the broker's own clock is in brokerTime fields.
- Field names follow MetaAPI where one exists (POSITION_TYPE_BUY, ORDER_TYPE_BUY_LIMIT, DEAL_ENTRY_OUT …).
- Every error has the same body
{ code, message, retryable, details }— see Errors & limits.
3. Your first request
Check the key with GET /v1/me: it returns your plan, its end date, your limits and how much of them you use.
export GW_KEY="gw_1a2b3c4d5e6f_…" # your token from Account → API → Token & keys
curl https://api.propmetaapi.com/v1/me -H "Authorization: Bearer $GW_KEY"{
"client": { "id": "8c1f…", "name": "…", "plan": "starter-100", "status": "ACTIVE" },
"subscription": { "expiresAt": "2026-11-04T00:00:00.000Z", "active": true, "daysLeft": 30 },
"limits": {
"activeAccounts": { "used": 0, "max": 100 },
"accounts": { "used": 0, "max": 300 },
"requestsPerMin": 6000,
"tradesPerMin": 600
},
"key": { "prefix": "1a2b3c4d5e6f", "scope": "CLIENT", "expiresAt": null }
}max: null means no limit. Every answer also carries the header x-subscription-expires-at with the end of your paid period.
4. Pick the broker server
An account is registered with its broker name and the exact trade server name as the MetaTrader terminal shows it (File → Login to Trade Account). The broker must be one the gateway knows. We provide the brokers listed here (also under Account → API → Brokers) — no files are needed. Look for your broker:
# brokers you can use right away — no files needed
curl "https://api.propmetaapi.com/v1/brokers?platform=MT5" -H "Authorization: Bearer $GW_KEY"
# search by company or server name
curl "https://api.propmetaapi.com/v1/brokers/search?company=exness&platform=MT5" -H "Authorization: Bearer $GW_KEY"The servers field lists the server names of each broker. If your broker is not listed, send a broker request — we add the broker and your request becomes DONE:
# your broker is not listed: ask us to add it (or use "Request a broker" under Account → API → Brokers)
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"] }'
# then poll GET /v1/broker-requests until its status is DONEA broker starts as PENDING and becomes VERIFIED after the first successful check of one of its accounts (step 6). Accounts of a broker can be activated only once it is VERIFIED. Details: Accounts & brokers.
5. Register the MetaTrader account
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": "your-trading-password",
"investorPassword": "your-investor-password",
"externalRef": "customer-42"
}'201 Created
{
"id": "3f0c2b9e-5d1a-4c7e-9a51-0b6f2d8e4a10",
"platform": "MT5",
"broker": "Exness",
"server": "Exness-MT5Trial12",
"login": "12345678",
"desiredState": "STANDBY",
"runtimeState": "IDLE",
"masterAuth": "UNKNOWN",
"investorAuth": "UNKNOWN",
…
}masterPasswordis required (trading needs it).investorPasswordis optional: when given, reads and checks log in read-only and the master password is used only to trade.- Registering again with the same server and login returns the same id (200) and applies changed passwords — safe to repeat.
- Instead of broker + server you may give the server address: { "platform": "MT4", "host": "mt4.example-broker.com", "port": 443, … }.
6. Check the login
A new account is STANDBY: it is registered but not connected. A check logs in once, reads the account and syncs its trade history:
export ACCOUNT_ID="3f0c2b9e-5d1a-4c7e-9a51-0b6f2d8e4a10"
# log in once, read the account and its history (waits up to 60 s)
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/check?wait=60" -H "Authorization: Bearer $GW_KEY"
# 200 → { "commandId": "cmd_…", "status": "SUCCEEDED", …, "account": {…}, "summary": { "balance": 10000, … } }
# 409 AUTH_REJECTED → wrong login / password or serverStill running after ?wait? The answer is 202 with the command — poll GET /v1/commands/{commandId}. A STANDBY account can already be read: pass ?wait=30 to summary, positions or deals and the gateway logs in for the read.
7. Activate and wait for CONNECTED
For live data, streaming and trading, activate the account: it gets a permanent terminal and counts against your active-accounts limit. The account goes ASSIGNING → STARTING → CONNECTING → CONNECTED (usually well under a minute).
# permanent connection; waits up to 60 s for the terminal to log in
curl -X POST "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/activate?wait=60" -H "Authorization: Bearer $GW_KEY"
# 200 → runtimeState "CONNECTED" 202 → still connecting: poll until CONNECTED
until [ "$(curl -s https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID -H "Authorization: Bearer $GW_KEY" | jq -r .runtimeState)" = "CONNECTED" ]; do
sleep 3
doneInstead of polling you can subscribe to the accountState WebSocket channel or the ACCOUNT_STATE_CHANGED event. A wrong password ends in runtimeState: AUTH_REJECTED (409 AUTH_REJECTED with ?wait) — fix it with PATCH /v1/accounts/{id}/credentials.
8. Read the account
# balance, equity, margin … (connected, stale and asOf tell how fresh it is)
curl https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/summary -H "Authorization: Bearer $GW_KEY"
# open positions and pending orders
curl https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/positions -H "Authorization: Bearer $GW_KEY"
curl https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/orders -H "Authorization: Bearer $GW_KEY"
# latest prices
curl "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/quotes?symbols=EURUSD,XAUUSD" -H "Authorization: Bearer $GW_KEY"9. Place, change and close an order
Every trade call needs an Idempotency-Key header: the same key with the same body never trades twice, so retrying after a timeout is safe. With ?wait the call answers with the final result; without it you get 202 and the command to poll.
# buy 0.10 lot EURUSD with a stop loss 20 pips and a take profit 40 pips away
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", "volume": 0.1,
"sl": 20, "slUnits": "RELATIVE_PIPS",
"tp": 40, "tpUnits": "RELATIVE_PIPS"
}'200 OK
{
"commandId": "cmd_Q2x9…",
"accountId": "3f0c2b9e-…",
"type": "PLACE_ORDER",
"status": "SUCCEEDED",
"errorCode": null,
"message": null,
"result": { "existing": false, "orderId": "51234567", "dealId": "41234567", "positionId": "51234567", "volume": 0.1, "price": 1.08412 },
"attempts": 1,
"deadlineAt": "…", "createdAt": "…", "finishedAt": "…",
"position": { "id": "51234567", "type": "POSITION_TYPE_BUY", "symbol": "EURUSD", "volume": 0.1, "openPrice": 1.08412, "stopLoss": 1.08212, "takeProfit": 1.08812, … }
}export POSITION_ID="51234567"
# move the stop loss to break-even (a 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": 1.08412 }'
# close half, then the rest
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 }'
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 '{}'Pending orders, relative stops, trailing stops, close-by and close-all: Trading.
10. Trade history
# closed deals of January (paged: pass nextCursor as ?cursor= until it is null)
curl "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/deals?from=2026-01-01T00:00:00Z&to=2026-02-01T00:00:00Z" \
-H "Authorization: Bearer $GW_KEY"
# closed positions (deal legs grouped per position)
curl "https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/history/positions?from=2026-01-01T00:00:00Z" -H "Authorization: Bearer $GW_KEY"History reads never return a partial list: if the history is not complete up to to yet, the answer is 409 HISTORY_NOT_SYNCED (retryable). More in Market data & history.
11. Deactivate or remove
# stop the permanent connection (it no longer counts against your active accounts)
curl -X POST https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID/deactivate -H "Authorization: Bearer $GW_KEY"
# remove the account for good (passwords are wiped)
curl -X DELETE https://api.propmetaapi.com/v1/accounts/$ACCOUNT_ID -H "Authorization: Bearer $GW_KEY"