API documentation

Authentication

Every request carries an API key as a Bearer token. Keys have permissions and can be limited to some of your MetaTrader accounts and to a time.

Updated

Bearer keys

Send the key in the Authorization header, exactly as Bearer <key> (capital B, one space). Keys look like gw_<12 hex characters>_<secret>; the first part (the prefix) identifies the key in lists and logs, the secret is stored only as a hash.

bash
curl https://api.propmetaapi.com/v1/accounts \
  -H "Authorization: Bearer gw_1a2b3c4d5e6f_Xy9…"
  • A missing, malformed, wrong, revoked or expired key answers 401 UNAUTHORIZED. A revoked key stops within seconds and its open WebSockets close within 10 seconds (close code 4401).
  • Too many failed authentications from one address (30 in a minute) block that address for the rest of the minute with 429 RATE_LIMITED — fix the key instead of retrying.
  • If your access has an IP allowlist, other addresses get 403 FORBIDDEN_IP. GET /v1/debug/headers shows the address the gateway sees.
  • The WebSocket accepts the key in the same header, or as a sub-protocol for browsers — see WebSocket streaming.
Call the API from your server. A key in browser JavaScript or a mobile app can be read by anyone — give such clients a narrow read-only key of their own, or proxy the calls through your backend.

Your primary key

The key issued with your plan has every permission (read, trade, manage) on all your accounts. In Account → API → Token & keys you can:

  • Reveal — show and copy it after confirming your password (and 2FA code, if enabled).
  • Rotate — issue a new primary key; the old one stops working within seconds. Keys you made yourself with POST /v1/keys stay valid.

Another key cannot revoke the primary key through the API (403 FORBIDDEN); rotate it in the panel. A renewal of your plan keeps your keys.

Permissions

A key has one or more permissions. A call the key is not allowed to make answers 403 FORBIDDEN and names the permission it needs:

PermissionAllows
readEvery GET (accounts, positions, orders, history, quotes, symbols, statistics, events, commands …), the WebSocket /v1/ws, and the POST / DELETE calls that only read or follow data: POST …/check, POST and DELETE …/subscriptions, POST …/rates/requests, POST and DELETE …/tick-history, POST …/refresh, POST /v1/tools/ping-host.
tradeTrade commands: POST …/orders, PATCH and DELETE …/orders/{orderId}, PATCH …/positions/{positionId}, POST …/close and …/close-by, POST …/close-all, PUT and DELETE trailing stops.
manageEvery other change: register, activate, deactivate, reconnect and remove accounts, passwords and proxy, watches, broker files, risk trackers, webhooks, keys, copy trading. Reading keys, webhooks, invoices and usage needs manage too.
json
403 Forbidden
{
  "code": "FORBIDDEN",
  "message": "this API key has no \"trade\" permission",
  "retryable": false,
  "details": { "permission": "trade", "keyPermissions": ["read"] }
}
  • Risk trackers whose action closes positions (CLOSE_POSITIONS, CLOSE_AND_BLOCK) and copy-trading settings make trades: they need trade as well as manage.
  • Client-wide calls need a key that is not limited to some accounts: registering accounts, uploading / replacing / removing broker files, invoices and usage, copy trading.
  • The API reference names the permission of every endpoint.

Scoped keys

Create narrower keys for each app, server or teammate with POST /v1/keys (needs manage) or in the panel (it asks for your password and, with 2FA on, your code). The full key is in the answer once — store it right away.

bash
curl -X POST https://api.propmetaapi.com/v1/keys \
  -H "Authorization: Bearer $GW_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "reporting dashboard",
    "permissions": ["read"],
    "accountIds": ["3f0c2b9e-5d1a-4c7e-9a51-0b6f2d8e4a10"],
    "expiresAt": "2026-12-31T23:59:59Z"
  }'
201 Created
{
  "id": "b7e1…",
  "prefix": "9f8e7d6c5b4a",
  "label": "reporting dashboard",
  "scope": "CLIENT",
  "permissions": ["read"],
  "accountIds": ["3f0c2b9e-5d1a-4c7e-9a51-0b6f2d8e4a10"],
  "issuedBy": "client",
  "createdAt": "2026-10-05T09:00:00.000Z",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "revokedAt": null,
  "lastUsedAt": null,
  "key": "gw_9f8e7d6c5b4a_…"            ← shown only in this answer
}
const res = await fetch("https://api.propmetaapi.com/v1/keys", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GW_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ label: "copier", permissions: ["read", "trade"], accountIds: [accountId] }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const created = (await res.json()) as { id: string; key: string };
console.log(created.key); // shown once — store it now
  • permissions must be a subset of the calling key's (default: the same). A key limited to some accounts can only make keys for a subset of them.
  • accountIds limits the key to those accounts: every other account answers 404, the event feed, WebSocket and webhooks only show theirs (plus events without an account, such as plan notices).
  • expiresAt ends the key at that time; a key never outlives the key that made it. Revoking a key also revokes the keys it made.
  • You can hold up to 20 working keys of your own (403 QUOTA_EXCEEDED beyond that — revoke one first).
bash
# keys this key may manage (current: true marks the calling key)
curl https://api.propmetaapi.com/v1/keys -H "Authorization: Bearer $GW_KEY"

# revoke a key (and every key it made); its WebSockets close within 10 s
curl -X DELETE https://api.propmetaapi.com/v1/keys/$KEY_ID -H "Authorization: Bearer $GW_KEY"

Rotating a scoped key without downtime: create the new key, deploy it, then revoke the old one.

Rate limits

Requests are counted per customer and calendar minute in two separate buckets: trade calls (tradesPerMin) and all other calls (requestsPerMin). All your keys share the same buckets, so a second key does not double the limit. Your limits are limits.requestsPerMin and limits.tradesPerMin in GET /v1/me. Over the limit the answer is 429 RATE_LIMITED with a Retry-After header (seconds until the next minute).

Errors & limits →