Contract screener

NOTE: This is the documentation for websocket channel contract_screener. Websocket access for personal use is only available through the Advanced plan. The data on this channel is the exact same data shown on https://unusualwhales.com/options-screener. 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: contract_screener for live hot-option-contract snapshots (Greeks, side volumes, OI growth indicators). Payload format:

[
  "contract_screener",
  {
    "option_symbol": "WMT260501P00126000",
    "tape_time": "2026-04-27T14:27:56Z",
    "volume": 498,
    "open_interest": 536,
    "prev_oi": 349,
    "trades": 143,
    "premium": "32830.00",
    "ask_side_volume": 231,
    "bid_side_volume": 190,
    "neutral_volume": 0,
    "floor_volume": 50,
    "high": "0.76",
    "low": "0.51",
    "open": "0.53",
    "close": "0.75",
    "iv": "0.3222611630685708",
    "bid": "0.73",
    "ask": "0.75",
    "multileg_volume": 10,
    "avg_price": "0.6592369477911646586345381529",
    "mid_volume": 77,
    "sweep_volume": 2,
    "cross_volume": 0,
    "stock_multi_leg_volume": 0,
    "days_of_oi_increases": 3,
    "days_of_vol_greater_than_oi": 0,
    "chain_prev_close": "0.55",
    "delta": "-0.2759145792070713",
    "gamma": "0.0771084404181128",
    "theta": "-0.180959140636331",
    "vega": "0.04495190198751509",
    "is_new": false,
    "ask_side_perc_7_day": "0.750000",
    "bid_side_perc_7_day": "0.250000"
  }
]

Field reference

Each message is a snapshot of a single option contract that’s currently active. Streamed continuously throughout the session.

Field	Type	Description
`option_symbol`	string	OSI option chain id.
`tape_time`	ISO 8601 string	Snapshot time, UTC.
`volume`	int	Session volume on the contract.
`open_interest`	int	Open interest as of `tape_time`.
`prev_oi`	int	Open interest at the previous session close. Compare with `open_interest` to detect OI growth.
`trades`	int	Number of distinct trades in the session.
`premium`	decimal string	Total dollar premium traded today.
`ask_side_volume`, `bid_side_volume`, `neutral_volume`	int	Volume broken out by side classification.
`mid_volume`	int	Volume executed at the NBBO mid.
`floor_volume`, `sweep_volume`, `cross_volume`, `multileg_volume`, `stock_multi_leg_volume`	int	Volume by trade kind.
`high` / `low` / `open` / `close`	decimal string	Session OHLC for this contract.
`avg_price`	decimal string	Volume-weighted average trade price.
`bid` / `ask`	decimal string	NBBO at `tape_time`.
`iv`	decimal string \| null	Implied volatility at `tape_time`.
`delta` / `gamma` / `theta` / `vega`	decimal string \| null	Greeks at `tape_time`.
`chain_prev_close`	decimal string \| null	Closing price of the contract at the previous session close.
`days_of_oi_increases`	int	Consecutive sessions where OI increased.
`days_of_vol_greater_than_oi`	int	Consecutive sessions where session volume exceeded OI.
`is_new`	bool	`true` for newly listed contracts.
`ask_side_perc_7_day` / `bid_side_perc_7_day`	decimal string \| null	Fraction of the last 7 trading days’ volume that printed on the ask side / bid side.

Overview

Channels

Field reference