Skip to content

WebSockets · Futures

Futures delta stream

Futures order-flow delta per minute.
WS/v1/ws/futures/deltawsFuturesDelta
On this page

The buy, sell and unknown volume, delta (buy minus sell), trade count and the session's cumulative delta of the forming and closed one-minute bar of a product or dated contract. No price is sent. A forming minute is sent at most 60 times a second; the closed minute (closed: true) is sent once, when it ends. cumulative_delta is the contract's running delta since the session opened. It is seeded from the session profile when that is held, otherwise from the captured tape of the current session; when the tape has already dropped early prints of the session the events carry partial: true, because the total may then miss them. Subscribe and unsubscribe products (ES, a product selects its front contract) or dated contracts (NQZ6) on one socket.

Connect and subscribe

Open wss://api.ordermap.si/v1/ws/futures/delta?symbols=ES with your key in the Authorization header and your saved installation ID in X-OrderMap-Device-ID, then send a subscribe message. Up to 25 symbols per connection. Streams need API Pro. All keys and projects share one active device per account and one connection per event type. Reuse the same installation ID for every stream and reconnect. Browser subprotocols, limits and close codes are in WebSockets.

Node.js

import WebSocket from "ws";

// Create a UUID once per installation, save it, and reuse it for every stream.
const deviceId = process.env.ORDERMAP_DEVICE_ID;
if (!deviceId) throw new Error("Set ORDERMAP_DEVICE_ID to this installation's saved UUID.");

const ws = new WebSocket("wss://api.ordermap.si/v1/ws/futures/delta?symbols=ES", {
  headers: {
    Authorization: `Bearer ${process.env.ORDERMAP_API_KEY}`,
    "X-OrderMap-Device-ID": deviceId,
  },
});

ws.on("open", () => ws.send(JSON.stringify({ action: "subscribe", symbols: ["ES"] })));
ws.on("message", (raw) => {
  const message = JSON.parse(raw.toString());
  if (message.type === "event") console.log(message.seq, message.data);
  if (message.type === "gap") console.warn("continuity lost: refetch the range over REST", message);
});
ws.on("close", (code, reason) => console.log("closed", code, reason.toString()));

Subscribe message

{"action":"subscribe","symbols":["ES"]}

Upgrade headers

A persistent installation ID is required. Supply the header below, or offer it as an ordermap.device.<id> browser subprotocol with ordermap.v1. Reuse the same saved ID for every event type, key, project and reconnect. Headers are not subscription filters.

ParameterType and limitsDescription
X-OrderMap-Device-IDheaderoptionalstringat least 16 charactersat most 128 characterspattern ^[A-Za-z0-9_-]{16,128}$Required unless supplied as an ordermap.device.<id> subprotocol together with ordermap.v1. Generate one random identifier per client installation and persist it across event types, keys, projects and reconnects. Never send it in the URL.

Subscription parameters

1 parameter, none required. Send them in the query string of the upgrade request, or as the filters of a subscribe message.

ParameterType and limitsDescription
symbolsqueryoptionalarray<string>comma-separated in one parameter1 to 25 itemseach at most 128 characterspattern ^[A-Za-z][A-Za-z0-9.]{0,9}$Symbols to subscribe to (up to 25).

Event

Each event is one message: {"type":"event","event_type":"futures.delta","seq":N,"data":{...}}.

data of futures.delta

  • bar_timeintegerunix-msrequiredStart of the minute. Unix epoch milliseconds (UTC).
  • buy_volumeintegerrequiredContracts bought at the ask in the minute.
  • closedbooleanrequiredFalse while the minute forms; true once, when it has ended.
  • contractstringrequiredDated contract.
  • cumulative_deltaintegerrequiredBuy minus sell contracts of the contract since the session opened, including this minute.
  • deltaintegerrequiredbuy_volume minus sell_volume.
  • partialbooleanrequiredTrue when cumulative_delta may miss prints of the session because the capture had already dropped early ones.
  • sell_volumeintegerrequiredContracts sold at the bid in the minute.
  • symbolstringrequiredThe symbol subscribed to.
  • tradesintegerrequiredPrints in the minute.
  • unknown_volumeintegerrequiredContracts whose aggressor could not be determined.

Example event

{
  "type": "event",
  "event_type": "futures.delta",
  "seq": 1,
  "data": {
    "bar_time": 1792161000000,
    "buy_volume": 640,
    "closed": false,
    "contract": "ESZ6",
    "cumulative_delta": 8420,
    "delta": 120,
    "partial": false,
    "sell_volume": 520,
    "symbol": "ES",
    "trades": 412,
    "unknown_volume": 20
  }
}

Before the upgrade

Errors before the upgrade are ordinary JSON errors; after it, problems arrive as messages and close codes (see WebSockets).

StatusMeaningBody
101Switching protocols: WebSocket protocol ordermap.v1.Switching protocols
400Invalid handshake parameters or missing, malformed or conflicting persistent device identifier.Error object
401Missing or invalid API key (Authorization, X-API-Key or, from a browser, the ordermap.key. subprotocol).Error object
403The plan has no streaming (streaming_not_in_plan), the dataset is not released, or the account is suspended.Error object
409stream_connection_limit: the account is already connected on another device, or already has this event type open on the active device. The existing connection is preserved.Retry-AfterError object
426The request is not a WebSocket upgrade.Error object
429Rate limit or WebSocket cooldown.Retry-AfterError object
503stream_unavailable: the stream is not enabled or its source is down; retry after Retry-After seconds.Retry-AfterError object

Authenticated responses carry the X-RateLimit-* headers (see rate limits); 429 and 503 add Retry-After.