GET /v2/ws

Open the streaming WebSocket

stream_connectWs

Upgrades to the streaming WebSocket. Authenticate in-band: the first frame carries a ticket from POST /v2/stream/ticket, and the HTTP handshake itself takes no Authorization header.

Details

Entitlements are checked when that first frame arrives and again on every subscription. The wire format is /v2/ws-protocol.proto.

Response

Prices are dollars, timestamps epoch milliseconds, strikes integer thousandths of a dollar; null means unknown. Units →

101

Switching Protocols — authenticate in-band with proto 2 (legacy) or proto 3 (symbol-routed)

Request

# The WebSocket upgrade is not a plain HTTP call.
# 1. Mint a ticket:
curl -sS -X POST "https://api.itmatrixhq.com/v2/stream/ticket" \
  -H "Authorization: Bearer $ITM_API_KEY"
# 2. Connect to wss://api.itmatrixhq.com/v2/ws and send
#    {"op":"auth","ticket":"<ticket>","proto":3,"encoding":"protobuf"}
#    as the first frame. See /api/streaming.

import asyncio
import json
import os

import httpx
import websockets  # pip install websockets


async def main():
    ticket = httpx.post(
        "https://api.itmatrixhq.com/v2/stream/ticket",
        headers={"Authorization": f"Bearer {os.environ['ITM_API_KEY']}"},
    ).json()["data"]["ticket"]

    async with websockets.connect("wss://api.itmatrixhq.com/v2/ws") as ws:
        await ws.send(json.dumps({"op": "auth", "ticket": ticket, "proto": 3, "encoding": "protobuf"}))
        await ws.send(json.dumps({"op": "sub", "id": "gex-spy", "topic": "gex", "symbol": "SPY"}))
        async for message in ws:
            if isinstance(message, bytes):
                print("frame:", len(message), "bytes")  # one protobuf Frame
                continue
            control = json.loads(message)  # authed, ack, nack, ping, bye
            if control["op"] == "ping":
                await ws.send(json.dumps({"op": "pong", "t": control["t"]}))
            else:
                print(control)


asyncio.run(main())

import asyncio
import os
import itmatrix as itm


async def main():
    async with itm.AsyncITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
        async with client.stream.gex("SPY") as updates:
            async for frame in updates:
                print(frame.symbol, frame.WhichOneof("payload"))


asyncio.run(main())

// Node 22+ and browsers have WebSocket built in.
const minted = await fetch("https://api.itmatrixhq.com/v2/stream/ticket", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ITM_API_KEY}` },
});
const { data } = await minted.json();

const ws = new WebSocket("wss://api.itmatrixhq.com/v2/ws");
ws.binaryType = "arraybuffer";
ws.onopen = () => {
  ws.send(JSON.stringify({ op: "auth", ticket: data.ticket, proto: 3, encoding: "protobuf" }));
  ws.send(JSON.stringify({ op: "sub", id: "gex-spy", topic: "gex", symbol: "SPY" }));
};
ws.onmessage = ({ data: message }) => {
  if (typeof message !== "string") {
    console.log("frame:", message.byteLength, "bytes"); // one protobuf Frame
    return;
  }
  const control = JSON.parse(message); // authed, ack, nack, ping, bye
  if (control.op === "ping") ws.send(JSON.stringify({ op: "pong", t: control.t }));
  else console.log(control);
};

import { ITMClient } from "@itmatrixhq/core";

const client = new ITMClient({ apiKey: process.env.ITM_API_KEY });
for await (const frame of client.stream.gex("SPY")) {
  console.log(frame.symbol, frame.gexSnap?.netGex ?? frame.gexDelta);
}