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 theSec-WebSocket-Protocollist, 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 optionalidechoed 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
| Channel | Fields | Data |
|---|---|---|
quote | accountId, symbols | items: [one quote { symbol, bid, ask, … }] per message; the first message (snapshot: true) has the current quotes. |
book | accountId, symbols | data: market depth of one symbol (MT5 only; MT4 answers NOT_SUPPORTED_ON_PLATFORM). |
ohlc | accountId, symbols, timeframe? | items: [the forming bar of a symbol] (timeframe default M1). |
tickValue | accountId, symbols | items: [{ symbol, tickValue, … }] in account currency. |
marketWatch | accountId, symbols | items: [market-watch row: bid / ask, day high / low, change …]. |
profits | accountId, intervalMs? | data: { equity, balance, items: [{ id, profit, currentPrice, swap }] } at most every intervalMs (default 1000). |
openedTickets | accountId, intervalMs? | data: { tickets: [position ids] }. |
openedTicketsProfit | accountId, intervalMs? | data: { items: [{ ticket, profit }], equity, balance }. |
orderUpdate | accountId | items: [{ type, id, symbol, position?, order?, previous?, at }] — every change of positions and pending orders. |
orderUpdateSlim | accountId | items: [{ type, id, symbol, at }]. |
accountState | accountId | Connection state of the account; the first message is data: { state, reason, connected } (state = runtimeState). |
mail | accountId | items: new messages of the terminal's mailbox. |
tickHistory | accountId, symbols? | Parts of a tick-history stream started with POST …/tick-history: data { symbol, from, to, done: false, items }, then { done: true }. |
quoteHistory | accountId | Results of POST …/rates/requests: data { requestId, status: DONE | FAILED, symbol, timeframe, bars | error }. |
events | after? | 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_EXPIREDLive 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).