API documentation

WebSocket streaming

One multiplexed WebSocket carries live quotes, bars, depth, profits, order updates, account state and your event feed for all your accounts.

Updated

Connect

URL
wss://api.propmetaapi.com/v1/ws
  • Authenticate with the header Authorization: Bearer <key> (recommended). Where headers cannot be set (browsers), send the key as an entry of the Sec-WebSocket-Protocol list, e.g. ["bearer", key]. Keys in the URL (?key=) are refused: URLs end up in proxy and server logs.
  • The key needs the read permission; a key limited to some accounts only streams those accounts and their events.
  • A refused handshake answers an HTTP error with the usual JSON body: 401 UNAUTHORIZED (bad, revoked or expired key, key without read, or your plan ended), 403 CLIENT_SUSPENDED, 403 FORBIDDEN_IP, 429 RATE_LIMITED (more than 50 open sockets for the key).
  • After connecting you receive { op: "hello", at, channels }.

Messages

You send subscribe, unsubscribe and ping; the server answers and then pushes data and event messages. Every message is one JSON object.

json
← { "op": "hello", "at": "2026-10-05T09:00:00.000Z", "channels": ["quote", "book", …, "events"] }

→ { "op": "subscribe", "channel": "quote", "accountId": "3f0c…", "symbols": ["EURUSD", "XAUUSD"], "id": "q1" }
← { "op": "subscribed", "id": "q1", "channel": "quote", "accountId": "3f0c…", "symbols": ["EURUSD", "XAUUSD"], "intervalMs": 0 }
← { "op": "data", "channel": "quote", "accountId": "3f0c…", "at": "…", "snapshot": true, "items": [ … ] }
← { "op": "data", "channel": "quote", "accountId": "3f0c…", "at": "…", "items": [ { "symbol": "EURUSD", "bid": 1.0841, "ask": 1.08412, … } ] }

→ { "op": "subscribe", "channel": "profits", "accountId": "3f0c…", "intervalMs": 2000 }
→ { "op": "subscribe", "channel": "ohlc", "accountId": "3f0c…", "symbols": ["EURUSD"], "timeframe": "M5" }

→ { "op": "subscribe", "channel": "events", "after": "1842" }
← { "op": "event", "id": "1843", "type": "ORDER_UPDATE", "accountId": "3f0c…", "occurredAt": "…", … }

→ { "op": "unsubscribe", "channel": "quote", "accountId": "3f0c…", "symbols": ["XAUUSD"], "id": "u1" }
← { "op": "unsubscribed", "id": "u1", "channel": "quote", "accountId": "3f0c…" }

→ { "op": "ping" }
← { "op": "pong", "at": "…" }

← { "op": "error", "id": "q2", "code": "VALIDATION", "message": "symbols required", "retryable": false }
  • subscribe: channel, accountId (not for events), symbols (up to 200; required for quote, book, ohlc, tickValue, marketWatch), timeframe (ohlc, default M1), intervalMs (0–60000: at most one message per symbol — or per account for the profit channels — per interval; profit channels default to 1000), after (events) and an optional id echoed in the answer.
  • Subscribing again to the same channel and account adds symbols (ohlc: per timeframe). unsubscribe with symbols removes only those.
  • The first data message of quote, marketWatch, the profit channels and accountState is a snapshot (snapshot: true) of the current values.
  • Errors come as { op: "error", id, code, message, retryable, details? }: VALIDATION (unknown op or channel, missing symbols, not JSON, more than 200 symbols for one account and channel), NOT_FOUND (account), NOT_SUPPORTED_ON_PLATFORM, RATE_LIMITED (more than 500 subscriptions on the socket, or more than 20 messages a second on average with bursts up to 600; the id of the dropped message is in the error, and a socket that stays over it for 5 seconds in a row is closed with 1008).

Channels

ChannelFieldsData
quoteaccountId, symbolsitems: [one quote { symbol, bid, ask, … }] per message; the first message (snapshot: true) has the current quotes.
bookaccountId, symbolsdata: market depth of one symbol (MT5 only; MT4 answers NOT_SUPPORTED_ON_PLATFORM).
ohlcaccountId, symbols, timeframe?items: [the forming bar of a symbol] (timeframe default M1).
tickValueaccountId, symbolsitems: [{ symbol, tickValue, … }] in account currency.
marketWatchaccountId, symbolsitems: [market-watch row: bid / ask, day high / low, change …].
profitsaccountId, intervalMs?data: { equity, balance, items: [{ id, profit, currentPrice, swap }] } at most every intervalMs (default 1000).
openedTicketsaccountId, intervalMs?data: { tickets: [position ids] }.
openedTicketsProfitaccountId, intervalMs?data: { items: [{ ticket, profit }], equity, balance }.
orderUpdateaccountIditems: [{ type, id, symbol, position?, order?, previous?, at }] — every change of positions and pending orders.
orderUpdateSlimaccountIditems: [{ type, id, symbol, at }].
accountStateaccountIdConnection state of the account; the first message is data: { state, reason, connected } (state = runtimeState).
mailaccountIditems: new messages of the terminal's mailbox.
tickHistoryaccountId, symbols?Parts of a tick-history stream started with POST …/tick-history: data { symbol, from, to, done: false, items }, then { done: true }.
quoteHistoryaccountIdResults of POST …/rates/requests: data { requestId, status: DONE | FAILED, symbol, timeframe, bars | error }.
eventsafter?Your event feed as op: "event" messages (no accountId needed). Pass after = the last event id you processed to resume.

An orderUpdate message:

json
{
  "op": "data", "channel": "orderUpdate", "accountId": "3f0c…", "at": "…",
  "items": [
    { "type": "POSITION_MODIFIED", "id": "51234567", "symbol": "EURUSD", "at": "…",
      "position": { "id": "51234567", "symbol": "EURUSD", "side": "BUY", "volume": 0.1, "openPrice": 1.08412,
                    "stopLoss": 1.08412, "takeProfit": 1.08812, "profit": 12.4, … },
      "previous": { "stopLoss": 1.08212 } }
  ]
}
type: POSITION_OPENED, POSITION_MODIFIED, POSITION_PARTIALLY_CLOSED, POSITION_CLOSED,
      ORDER_PLACED, ORDER_MODIFIED, ORDER_PARTIALLY_FILLED, ORDER_FILLED, ORDER_CANCELLED, ORDER_EXPIRED
Live account data streams for ACTIVE accounts that are CONNECTED. Subscribing to a STANDBY account succeeds, but no data arrives until it is activated (accountState still sends its snapshot). Event messages have the same shape as GET /v1/events items and webhook events.

Examples

import WebSocket from "ws"; // npm install ws

const ws = new WebSocket("wss://api.propmetaapi.com/v1/ws", { headers: { Authorization: `Bearer ${process.env.GW_KEY}` } });

ws.on("open", () => {
  ws.send(JSON.stringify({ op: "subscribe", channel: "quote", accountId, symbols: ["EURUSD"] }));
  ws.send(JSON.stringify({ op: "subscribe", channel: "events", after: lastEventId })); // resume
});
ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.op === "data") console.log(msg.channel, msg.items ?? msg.data);
  if (msg.op === "event") { lastEventId = msg.id; console.log("event", msg.type); }
  if (msg.op === "error") console.error(msg.code, msg.message);
});
ws.on("close", (code) => {
  // 4401: the key is no longer valid — fix it before reconnecting; otherwise reconnect with backoff
  console.log("closed", code);
});

Reliability and limits

  • The server sends a WebSocket ping frame every 20 seconds; a client that did not answer the previous one is dropped (WebSocket libraries answer automatically). Send { "op": "ping" } yourself if a proxy closes idle connections.
  • Reconnect with exponential backoff and random jitter — for example 1 s, 2 s, 4 s … up to 60 s, each multiplied by a random 0.5–1.5 — and subscribe again. After a deploy every client reconnects at the same moment; a fixed delay makes them all arrive together and the first attempts may be refused. For events, pass after = the last id you processed: nothing is lost while you were away (up to the 14-day retention). Without after, the events channel starts with new events only.
  • Close codes: 4401 — the key is no longer valid (revoked or expired, plan ended, access suspended, address no longer allowed, read permission removed); an error message precedes it. Fix the key before reconnecting. 1013 — you read too slowly (over 16 MB queued). 1001 — the server is restarting: reconnect.
  • When your socket falls behind (over 4 MB queued), price channels send only the latest value per symbol instead of every tick.
  • When an account you follow is deactivated (STANDBY) or removed, each of its subscriptions gets { op: "ended", channel, accountId, reason } and is removed; subscribe again after activating it.
  • Subscriptions made with POST /v1/accounts/{id}/subscriptions (REST) are read on a socket of the same key with a listening subscription: { op: "subscribe", channel, accountId, passive: true } — it receives every symbol the account streams.
  • Limits: 50 open sockets per key, 500 subscriptions per socket, 200 symbols per subscription, 1 MB per message you send, 20 messages a second you send (bursts up to 600).