Greek flow

NOTE: This is the documentation for the websocket channels greek_flow and greek_flow:<TICKER>. For the same data broken out by option expiry, see greek_flow_expiry. Websocket access for personal use is only available through the Advanced plan. You can find fully-functional examples that stream data from many channels here:

Connect to the websocket URI: wss://api.unusualwhales.com/socket?token=<YOUR_API_TOKEN> then join the channel you wish to stream, for example greek_flow:SPY for SPY’s delta and vega flow. Omit the ticker suffix to receive updates for every ticker. Each message carries the delta and vega exposure of the option trades that printed for one ticker in one minute and arrived since the previous message for that minute; see Delivery characteristics below for how to sum them. total_* fields carry the greek’s own sign - for delta that means calls contribute positive and puts negative - so they are net greek exposure regardless of who was the aggressor. dir_* fields instead sign the magnitude by trade sentiment: for delta, bullish trades (bought calls, sold puts) positive and bearish negative; for vega, buys (ask side) positive and sells (bid side) negative. Mid/no-side trades are excluded from every dir_* field.

Delivery characteristics

Read these before writing a client, they are not obvious from the payload:

Each message is a partial sum, not a running total. A minute’s bucket is flushed roughly once per second as trades arrive, so to get that minute’s total you must add together every message sharing the same ticker and timestamp. Grouping on timestamp alone is wrong on the global channel, where every ticker’s messages carry that same minute. A client that overwrites on the key instead of adding will silently under-report.
Because of that, a dropped frame does not just delay a value, it changes your sum. Read from the socket promptly: a slow consumer is not disconnected, but frames it fails to keep up with are dropped.
Updates are trade-driven, not scheduled. A ticker with no option trades in the window produces no message at all - there is no per-minute tick and no zero-valued heartbeat. A minute bucket is also never announced as closed: messages carrying a given timestamp simply stop arriving.
The channels are keyed by the root ticker: weekly/PM index series are folded into their root (SPXW under SPX, NDXP under NDX, VIXW under VIX, RUTW under RUT). Joining greek_flow:SPXW is acknowledged as, and streams, greek_flow:SPX.
All flow values are decimal strings, matching the REST endpoint below.

This is the live counterpart of /stock/:ticker/greek-flow, which returns the same fields with the same encodings. Note the REST endpoint serves each minute’s accumulated total, while this channel serves the per-second partials that add up to it. Payload format for greek_flow:<TICKER>:

[
  "greek_flow:SPY",
  {
    "ticker": "SPY",
    "timestamp": "2026-09-04T15:46:00Z",
    "total_delta_flow": "-21257.36",
    "dir_delta_flow": "-43593.96",
    "otm_total_delta_flow": "-28564.02",
    "otm_dir_delta_flow": "14947.51",
    "total_vega_flow": "350944.58",
    "dir_vega_flow": "31243.04",
    "otm_total_vega_flow": "101745.64",
    "otm_dir_vega_flow": "11421.03",
    "transactions": 1188,
    "volume": 12348
  }
]

Field reference

Field	Type	Description
`ticker`	string	Root ticker of the underlying.
`timestamp`	string	The minute bucket these trades fall into, ISO 8601 UTC.
`total_delta_flow`	string	Sum of signed delta exposure: `delta * contracts * 100`.
`dir_delta_flow`	string	Delta magnitude signed by sentiment: positive for bullish trades (buy call / sell put), negative for bearish.
`otm_total_delta_flow`	string	`total_delta_flow` counting only trades identified as out of the money.
`otm_dir_delta_flow`	string	`dir_delta_flow` counting only trades identified as out of the money.
`total_vega_flow`	string	Sum of vega exposure: `vega * contracts * 100`.
`dir_vega_flow`	string	Vega magnitude signed by side: positive for buys (ask side), negative for sells (bid side).
`otm_total_vega_flow`	string	`total_vega_flow` counting only trades identified as out of the money.
`otm_dir_vega_flow`	string	`dir_vega_flow` counting only trades identified as out of the money.
`transactions`	integer	Number of option trades aggregated into this message. A trade whose delta or vega was unavailable still counts here and in `volume` but adds zero to that greek’s flow fields.
`volume`	integer	Total contracts traded across the aggregated trades.

Overview

Channels

Delivery characteristics

Field reference

​Delivery characteristics

​Field reference

Delivery characteristics

Field reference