WebSocket market data: stream stocks, forex and crypto in real time

A stock WebSocket API keeps one connection open and pushes each quote and trade as it happens, instead of waiting for you to ask. With TickerLayer the protocol fits in four steps: open wss://stream.tickerlayer.com/?apiKey=YOUR_API_KEY, wait for the ready frame, send a JSON subscribe message that names channels and symbols, then read frames. The same socket streams stocks, forex, crypto, indices, ETFs, commodities, government bond yields and perpetual futures.

This guide is the reference for that protocol, built from frames captured on the live stream. If you are still deciding whether you need a stream at all, WebSocket vs REST covers the trade-off, and the market data API explainer shows how symbols, units and timestamps fit together. If you want working code first, the Python WebSocket client builds a complete streaming client on top of everything below.

WebSocket authentication with the apiKey parameter

The stream authenticates once, during the HTTP upgrade, through the apiKey query parameter. The name is case-sensitive (api_key gets a 401), the value should be URL-encoded, and there is no login message inside the stream: by the time the first frame arrives you are already authenticated. REST uses an x-api-key header instead, because a browser cannot attach custom headers to a WebSocket upgrade.

The endpoint speaks plain WebSocket, not Socket.IO, so any standard client works: the browser WebSocket, ws in Node.js, websockets in Python. A minimal Node.js session:

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

const ws = new WebSocket(
  "wss://stream.tickerlayer.com/?apiKey=" + encodeURIComponent(process.env.TICKERLAYER_API_KEY),
  { perMessageDeflate: false }
);

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === "system" && msg.event === "ready") {
    ws.send(JSON.stringify({ action: "subscribe", channels: ["crypto.quotes", "crypto.trades"], symbols: ["BTCUSD"] }));
    return;
  }
  console.log(JSON.stringify(msg));
});

ws.on("close", (code) => console.log("closed with", code));

{"type":"system","event":"subscribed","channels":["crypto.quotes","crypto.trades"],"symbols":["BTCUSD"]}
{"type":"trade","channel":"crypto.trades","asset":"crypto","symbol":"BTCUSD","price":"82850","size":"0.01105","ts":1790591203601}
{"type":"trade","channel":"crypto.trades","asset":"crypto","symbol":"BTCUSD","price":"82819.16","size":"3e-8","ts":1790591203755}
{"type":"quote","channel":"crypto.quotes","asset":"crypto","symbol":"BTCUSD","bid":"82849.99","ask":"82850","bid_size":"15.50507","ask_size":"1.87429","ts":1790591203836}

If the upgrade fails, you get a plain HTTP status and no frames at all. That is the first branch your client needs, because two of these statuses will never fix themselves:

WebSocket subscribe messages and acknowledgements

Send nothing before ready. After it, every request is a JSON text message with an action. A subscribe names one or more channels and one or more symbols, and the server answers with a subscribed acknowledgement that echoes what it accepted. The echo is normalised (trimmed, uppercased, de-duplicated and sorted), so compare it with your request as a set, not as an array.

{"action": "subscribe", "channels": ["crypto.quotes", "crypto.trades"], "symbols": ["BTCUSD"]}

{"type": "system", "event": "subscribed", "channels": ["crypto.quotes", "crypto.trades"], "symbols": ["BTCUSD"]}

• channels is a non-empty array; symbols is an array or a comma-separated string.
• One message takes at most 500 symbols. Send several messages for more; subscriptions add up.
• unsubscribe takes the same shape and answers unsubscribed. A symbol stays live on every channel you did not name.
• Optional fields: snapshot (next section), interval and session for stocks.agg only, and trade_mode: "full_volume" as an opt-in for US stocks.
• {"action":"ping"} answers {"type":"system","event":"pong","ts":...}: a cheap way to prove the server is still reading you.

Snapshot on subscribe: true, false or "always"

By default, right after the acknowledgement the stream sends one last-known quote and/or trade for every symbol that has a recent value. Snapshot frames have the same shape as live ones plus "snapshot": true, and their ts is the original event time, not the send time. The point is a number on screen immediately instead of an empty cell until the next tick.

Three rules decide whether a snapshot exists at all. US and Asian equities and ETFs replay only a value from roughly the last two minutes, so subscribing to US:KO before the open delivers nothing until the first live tick: exactly the case "always" is for. stocks.status and stocks.agg never replay, because a halt or a settled bar is a statement about something that happens after you subscribe. bonds.quotes always replays, since a daily yield observation stays current until the next one.

Crypto and forex trade continuously, so their first frames are usually ordinary live ticks. When you need a last price at any hour with certainty, ask REST: GET /stocks/snapshot/US:KO answers with the last known value whether the market is open or not.

Channels: one stock WebSocket API for every asset class

A channel is an asset family plus a message kind: forex.quotes, stocks.trades, indices.quotes. Symbols follow the same conventions as REST, so a symbol that works on GET /forex/quote/EURUSD works on forex.quotes. Everything below runs over the same connection. A stock WebSocket API that covered only equities would force a second socket for currencies and a third for coins; here the same connection doubles as a forex WebSocket API and a crypto WebSocket API, and the channel name does the routing.

The stock-bar channel is the one that behaves differently. stocks.agg pushes closed OHLCV bars only, takes an interval (1m, 5m, 15m, 1h, 4h or 1d) and a session (regular or extended), and never replays: bars that settled while you were disconnected come from GET /stocks/agg. The candlestick chart tutorial combines REST history with a live last candle.

Anatomy of a real frame

{
  "type": "quote",1
  "channel": "crypto.quotes",2
  "asset": "crypto",
  "symbol": "BTCUSD",
  "bid": "82849.99",3
  "ask": "82850",
  "bid_size": "15.50507",
  "ask_size": "1.87429",
  "ts": 17905912038364
}

The string encoding is deliberate: "82850" survives any JSON parser without float surprises, and crypto sizes can arrive in exponent form ("3e-8"). Indices, ETFs and commodities mostly send numbers, but some of their frames arrive as strings too, so the only safe rule is to convert every numeric field whatever the channel. REST, by contrast, always sends JSON numbers.

{"type":"quote","channel":"stocks.quotes","asset":"stocks","symbol":"US:KO","bid":"88.11","ask":"88.3","bid_size":"400","ask_size":"200","ts":1790590887491,"snapshot":true}
{"type":"quote","channel":"indices.quotes","asset":"indices","symbol":"US500","bid":7702.17,"ask":7706.03,"bid_size":98,"ask_size":88,"ts":1790591201606,"timestamp":1790591201606,"snapshot":true}
{"type":"rate","channel":"bonds.quotes","asset":"bonds","symbol":"US:10Y","rate":5.17,"unit":"percent","date":"2026-09-25","prev_rate":5.18,"prev_date":"2026-09-24","change":-0.01,"change_bps":-1,"change_percent":-0.1931,"ts":1790294400000,"timestamp":1790294400000,"snapshot":true}

Read time from ts on every family; the extra timestamp on indices, ETFs, commodities and bonds is a mirror. The bond frame shows why the time field matters: its ts is the observation date at UTC midnight, days older than the moment it arrived. If milliseconds since 1970 still trip you up, the Unix timestamp guide converts them in every language.

Heartbeats, close codes and reconnecting

The server sends native WebSocket ping frames, and every mainstream client library answers them with pongs on its own. If your process stops answering, usually because synchronous work is blocking its event loop, the server sends {"type":"system","event":"disconnect","code":"HEARTBEAT_TIMEOUT"} and closes with 4008. A quiet symbol is not a problem; missed heartbeats are.

Access is also rechecked on open connections, so a downgraded plan or an ended trial closes the socket instead of letting it run on. Whatever the cause, recovery is the same five steps:

1. 1Wait, with jitterStart near one second, double on each failure, cap around 30 seconds, and randomise part of every delay so a crowd of clients does not return in lockstep.
2. 2Reconnect to the same URLNothing survives the close: there is no resume token and no replay of what you missed.
3. 3Wait for readySend nothing until the new socket delivers its ready frame.
4. 4Resubscribe everythingKeep your subscriptions in one list and resend it in full. The server does not remember them.
5. 5Fill the gapThe snapshot restores the latest value. Bars that closed while you were away come from GET /{asset}/agg/....

The WebSocket reconnect tutorial turns these steps into a Node.js and browser client, including detection of half-open sockets that never deliver a close code at all.

Error frames leave the socket open

A request the server cannot honour produces an error frame, and the connection stays up. A rejected subscribe is a problem in the request, so reconnecting only repeats it. Every error frame has type: "error", a machine-readable code and a message; a failed subscribe adds event: "subscribe_failed" and lists the refused pairs in rejected. This one was captured by subscribing to a symbol that does not exist:

{
  "type": "error",
  "event": "subscribe_failed",1
  "code": "INVALID_SYMBOL",2
  "message": "invalid symbol",
  "channel": "stocks.quotes",
  "symbol": "NOTREAL",
  "rejected": [3
    {
      "channel": "stocks.quotes",
      "symbol": "NOTREAL",
      "code": "INVALID_SYMBOL",
      "message": "invalid symbol"
    }
  ]
}

The full list, including the rarer codes, is in the WebSocket troubleshooting reference.

Limits, compression and slow consumers

The distinct-symbol cap is account-wide, counted across every connection and channel, and the connection cap is enforced at the upgrade with a 429. That makes it the stream's version of a rate limit, and the backoff mechanics are the same as for REST, covered in 429 Too Many Requests. The free tier is REST only, with 3,000 requests a month; WebSocket comes with paid plans, and a free account can request a WebSocket trial from its dashboard. Plan details are on the pricing page.

The stream sends uncompressed frames. Turn per-message compression off in your client (perMessageDeflate: false in Node's ws, compression=None in Python websockets) so your process never spends time inflating frames on a busy stream, and keep the message handler fast: hand heavy work to a queue or a worker instead of doing it inside the socket callback. A client that cannot keep up falls further behind with every second, and eventually misses the heartbeats that keep it connected.

Signed-in accounts can also open a real stream from the WebSocket docs page and watch ticks update in place, which is the quickest way to confirm that a symbol and channel pair works before you write any code.