Flow alerts

NOTE: This is the documentation for websocket channel flow-alerts. 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: flow-alerts for all flow alerts. Payload format:

[
  "flow-alerts",
  {
    "rule_id": "5ce5ec11-087c-4c00-b164-08106b015856",
    "rule_name": "RepeatedHitsDescendingFill",
    "ticker": "DIA",
    "option_chain": "DIA241018C00415000",
    "underlying_price": 415.981,
    "volume": 106,
    "total_size": 50,
    "total_premium": 36466,
    "total_ask_side_prem": 36466,
    "total_bid_side_prem": 0,
    "start_time": 1726670212648,
    "end_time": 1726670212748,
    "url": "",
    "price": 7.3,
    "has_multileg": false,
    "has_sweep": false,
    "has_floor": false,
    "open_interest": 575,
    "all_opening_trades": false,
    "id": "29ed5829-e4ce-4934-876b-51985d2f9b70",
    "has_singleleg": true,
    "volume_oi_ratio": 0,
    "trade_ids": [
      "417f0cd6-09ae-4d43-8542-38557bb713aa",
      "4af4c646-4b21-4a27-8326-db7b0698d3d8",
      "74ddcd55-dcb3-4543-a488-16ee7ca91d45",
      "4ec49859-74a2-4d32-9911-ea329dd77326",
      "e164da3a-a6aa-41d9-a948-c17817453a21",
      "b0d98eeb-1429-4494-9dcc-8d5e7eb46f7d",
      "81b1dcad-f3f6-48a2-bf51-0bfd362ad372"
    ],
    "trade_count": 7,
    "expiry_count": 1,
    "executed_at": 1726670212748,
    "ask_vol": 52,
    "bid_vol": 49,
    "no_side_vol": 0,
    "mid_vol": 5,
    "multi_vol": 0,
    "stock_multi_vol": 0,
    "upstream_condition_details": [
      "auto",
      "slan"
    ],
    "exchanges": [
      "XCBO",
      "MPRL"
    ],
    "bid": "7.15",
    "ask": "7.3",
    "iv": 0.2543,
    "delta": 0.4821,
    "gamma": 0.0125,
    "theta": -0.0342,
    "vega": 0.1187,
    "rho": 0.0456,
    "theo": 7.28
  }
]

Field reference

A flow alert is an aggregate of one or more individual option_trades that matched a rule (sweep, repeated hits, etc.). Use trade_ids to look up the underlying option trades.

Field	Type	Description
`id`	uuid string	Unique alert identifier.
`rule_id`	uuid string	Identifier of the rule that produced the alert.
`rule_name`	string \| null	Human-readable rule name (e.g. `"RepeatedHitsDescendingFill"`). May be null if the rule definition is not present.
`ticker`	string	Underlying ticker.
`option_chain`	string	OSI option chain id matched by the alert.
`underlying_price`	float	Spot price of the underlying at `end_time`.
`volume`	int	Aggregate session volume on the contract at `end_time`.
`total_size`	int	Sum of `size` across the trades in this alert.
`total_premium`	float	Sum of `premium` across the trades in this alert.
`total_ask_side_prem` / `total_bid_side_prem`	float	Premium broken out by side classification at trade time.
`start_time` / `end_time`	int (ms)	First and last trade timestamps included in the alert (unix epoch milliseconds).
`executed_at`	int (ms)	Same as `end_time` (kept for backwards compatibility).
`price`	float	Last trade price in the aggregation window.
`bid` / `ask`	decimal string	NBBO at `end_time`.
`open_interest`	int	Open interest on the contract as of the most recent close.
`volume_oi_ratio`	float	`volume / open_interest`. `0` if `open_interest` is `0`.
`has_sweep` / `has_floor` / `has_singleleg` / `has_multileg`	bool	True if at least one matching trade is of that kind.
`all_opening_trades`	bool	True if every matching trade looks like an opening trade (price near ask).
`trade_ids`	string[]	UUIDs of the underlying `option_trades`; cross-reference against the `option_trades` channel or the full-tape endpoint.
`trade_count`	int	`length(trade_ids)`.
`expiry_count`	int	Number of distinct expiries spanned by the matching trades (almost always `1`).
`ask_vol` / `bid_vol` / `mid_vol` / `no_side_vol`	int	Aggregate volume by side classification across the trades.
`multi_vol` / `stock_multi_vol`	int	Multi-leg / stock-combo volume across the trades.
`upstream_condition_details`	string[]	Union of upstream condition codes (`"slan"`, `"auto"`, …) seen across the trades.
`exchanges`	string[]	OPRA exchanges that printed the matching trades.
`url`	string	Deep link to the alert on unusualwhales.com (may be empty).
`iv`	float \| null	Size-weighted implied volatility across the trades in the alert. `null` when unavailable.
`delta`	float \| null	Size-weighted delta across the trades in the alert. `null` when unavailable.
`gamma`	float \| null	Size-weighted gamma across the trades in the alert. `null` when unavailable.
`theta`	float \| null	Size-weighted theta across the trades in the alert. `null` when unavailable.
`vega`	float \| null	Size-weighted vega across the trades in the alert. `null` when unavailable.
`rho`	float \| null	Size-weighted rho across the trades in the alert. `null` when unavailable.
`theo`	float \| null	Size-weighted theoretical option price across the trades in the alert. `null` when unavailable.

Overview

Channels

Field reference

​Field reference

Field reference