API documentation

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

  1. 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.
  2. Order the Free Trial or a paid API plan on the plans page. The trial has the same API as the paid plans.
  3. When the order is confirmed your API access is created automatically and you get an email.
  4. Your token is in Account → API → Token & keys (reveal it with your password). It looks like gw_1a2b3c4d5e6f_….
Treat the token like a password: keep it on your server, never in browser code or a public repository. If it leaks, rotate it in the panel — the old token stops working within seconds. For apps and teammates, create narrower keys (Authentication).

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

Base URL
https://api.propmetaapi.com
  • Every route starts with /v1 and needs the header Authorization: Bearer <your key> (the word Bearer, 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.

bash
export GW_KEY="gw_1a2b3c4d5e6f_…"      # your token from Account → API → Token & keys

curl https://api.propmetaapi.com/v1/me -H "Authorization: Bearer $GW_KEY"
200 OK
{
  "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:

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

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

A 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

bash
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"
  }'
json
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",
  …
}
  • masterPassword is required (trading needs it). investorPassword is 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:

bash
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 server

Still 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).

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

Instead 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

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

bash
# 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"
  }'
json
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, … }
}
bash
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

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

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