> ## Documentation Index
> Fetch the complete documentation index at: https://api.unusualwhales.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> API requests use the base URL https://api.unusualwhales.com and require a bearer token in the `Authorization` header (`Authorization: Bearer <API_KEY>`). Create and manage API tokens at https://unusualwhales.com/dashboard/api.
> For live market data inside an AI tool, use the Unusual Whales MCP server at https://unusualwhales.com/public-api/mcp.
> Instructions for agents using Unusual Whales tools: https://unusualwhales.com/skill.md

# Contract screener

> Receive live option contract snapshots (Greeks, side volumes, OI growth indicators).

**NOTE:**
This is the documentation for websocket channel `contract_screener`.
Websocket access for personal use is only available through the [Advanced plan](https://unusualwhales.com/pricing?product=api).

The data on this channel is the exact same data shown on [https://unusualwhales.com/options-screener](https://unusualwhales.com/options-screener).

You can find fully-functional examples that stream data from many channels here:

* Python: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output)
* Javascript: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs)

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. |