# Contract screener

`GET` `https://api.unusualwhales.com/api/socket/contract_screener`

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



## Authentication

```
Authorization: Bearer YOUR_API_KEY
```



## Example

### curl

```bash
curl -X GET "https://api.unusualwhales.com/api/socket/contract_screener" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Python

```python
import http.client

conn = http.client.HTTPSConnection("api.unusualwhales.com")
headers = {"Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json"}
conn.request("GET", "/api/socket/contract_screener", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))
```

## Response Example

```json
{
  "data": []
}
```