WebSockets

Connecting#

wss://api.ordermap.si/v1/ws/options/trades?symbols=SPXW&min_premium=100000
Authorization: Bearer om_...

• Send the key in the Authorization or X-API-Key header of the HTTP upgrade request. A key in the query string is rejected. The upgrade counts as one request against your rate limit.
• The query string can carry an initial subscription: symbols (comma-separated) and the stream's filters. You can also subscribe after connecting.
• One connection per account per stream. A second upgrade on a stream that already has a connection is refused with 409 stream_connection_limit before the upgrade, and the first connection is not disturbed. A client that crashed is noticed within about 20 seconds, after which you can reconnect.
• Errors before the upgrade are ordinary JSON errors: 400 (bad symbols or filters), 401, 403 (streaming_not_in_plan, dataset_release_restricted, account_suspended), 409, 426 upgrade_required (not a WebSocket request), 429 (rate limit or cooldown) and 503 stream_unavailable (the stream is not running; retry after Retry-After).

import WebSocket from "ws";

const ws = new WebSocket("wss://api.ordermap.si/v1/ws/options/trades?symbols=SPXW&min_premium=100000", {
  headers: { Authorization: `Bearer ${process.env.ORDERMAP_API_KEY}` },
});

ws.on("message", (raw) => {
  const message = JSON.parse(raw.toString());
  if (message.type === "event") console.log(message.seq, message.data.option_symbol, message.data.premium);
  if (message.type === "gap") console.warn("continuity lost: refetch through REST", message);
  if (message.type === "error") console.error(message.code, message.message);
});
ws.on("close", (code, reason) => console.log("closed", code, reason.toString()));

// Change the subscription while connected:
ws.on("open", () => {
  ws.send(JSON.stringify({ action: "subscribe", symbols: ["SPXW", "SPY"], filters: { side: ["above_ask", "at_ask"] } }));
});

From a browser#

A browser cannot set headers on a WebSocket object, so it sends the key as a subprotocol: new WebSocket(url, ["ordermap.v1", "ordermap.key.om_..."]). The server reads it only on an upgrade to a stream (a path under /v1/ws/) that has neither an Authorization nor an X-API-Key header and offers ordermap.v1. It answers with Sec-WebSocket-Protocol: ordermap.v1, never repeats or logs the key, and treats it exactly like a bearer key: the same rate limit, abuse checks and 30-second revalidation.

// A browser cannot set headers on a WebSocket: the key travels as a subprotocol.
const ws = new WebSocket("wss://api.ordermap.si/v1/ws/futures/trades?symbols=ES", ["ordermap.v1", "ordermap.key." + key]);

Messages#

The protocol is ordermap.v1. Every message is one JSON text frame.

{"type":"hello","protocol":"ordermap.v1","event_type":"options.trades","heartbeat_ms":10000,"max_symbols":100,"wildcard":true,"filters":{}}

• One event per message, delivered when it happens. There is no timed batching and no resend buffer. Value-style streams (index values, basis, forming bars) are limited to 60 events per second per symbol. The futures quote, depth and bar streams, the index value stream and the basis stream send the latest state right after you subscribe. Trade streams start with the next trade.
• After a disconnect there is no replay. Reconnect, resubscribe and use the REST endpoints for anything you missed. A gap message tells you when continuity was lost while connected.
• Cancelled option prints are not retracted on the stream. Reconcile through the REST trades endpoint, which leaves cancelled prints out.
• Symbols are validated per stream. A family symbol (SPX, NDX, RUT, VIX) also selects its weekly root (SPXW, NDXP, RUTW, VIXW), and a futures product (ES) selects its front contract, so on one socket you cannot subscribe to both a family and one of its members (overlapping_symbols). Option-stream symbols are option roots.

Error messages#

The code of an error message is one of: invalid_message, unknown_action, invalid_symbol, too_many_symbols, wildcard_not_allowed, overlapping_symbols, invalid_filter, symbol_unavailable (the symbol cannot be served on this stream), capacity and account_capacity (too many subscriptions in the service, or held by your account alone), and inbound_rate_limited.

Keepalive and limits#

• The server pings every 10 seconds and closes a connection that has not answered (or sent any frame) within 20 seconds. Standard WebSocket libraries answer pings automatically.
• Client messages are limited to 4 KiB and 10 per second. More closes the connection with 1008.
• At most 100 symbols per connection, fewer on some streams (see the table below). A stream that accepts * takes it only as the sole subscription.
• Each connection has an outbound queue of 4,096 messages or 4 MiB. A client that cannot keep up is closed with 4008 slow_consumer instead of silently losing events.
• Your key, project, account and plan are re-checked every 30 seconds.

Close codes#

Streams#

Each stream has a page in the reference with its filters, the event schema and an example event. The symbol limit is per stream.

Analytics snapshots#

/v1/ws/analytics pushes the complete response of any REST endpoint marked streamable whenever its data changes. Each subscription names an endpoint and its ordinary query parameters:

{"action":"subscribe","id":"levels","route":"/v1/options/levels","params":{"underlying_symbol":"SPX"},"interval_ms":5000}

The hello message lists the streamable endpoints with their minimum refresh interval (routes[].min_interval_ms, from half a second to five seconds) and max_subscriptions (20). The server answers with subscribed (the subscriptions with the interval applied), then sends events:

{"type":"event","event_type":"analytics","seq":1,"data":{"id":"levels","route":"/v1/options/levels","revision":"1","resync":true,"response":{"data":{},"meta":{}}}}

• response is the endpoint's usual {data, meta} envelope, always the full snapshot, never a delta. revision increases with each change of the data, and resync is true on the first snapshot after subscribing. Send {"action":"unsubscribe","id":"levels"} to stop one subscription (no id stops all).
• id is yours: up to 64 letters, digits, _, -, ., :. Re-subscribing with the same id replaces the subscription. interval_ms can only slow a subscription down (up to one hour), never below the endpoint's minimum.
• An account's subscriptions together may refresh at most 10 times a second (the sum of 1/interval). Beyond that the subscribe is refused with poll_budget_exceeded: choose longer intervals. Subscriptions with the same endpoint and parameters share one refresh.
• A paginated endpoint streams its first page: has_more is reported and next_cursor_id and next_url are null. Results larger than 4 MiB are not streamed (response_too_large).
• Under heavy load a refresh can be skipped and retried about one interval later, so a snapshot may arrive late. After several skipped refreshes in a row the server sends a status message with state: degraded and reason: refresh_delayed, and state: live when refreshes resume. Load never produces an error message.
• Other analytics errors: invalid_route (not streamable; see /v1/catalog), too_many_subscriptions and invalid_filter (bad params).

Streamable endpoints#