Hottest Chains

GET https://api.unusualwhales.com/api/screener/option-contracts

Request

Security: Bearer Auth Authorization: Bearer <token>

Query Parameters

ticker_symbol Ticker optional

A comma separated list of tickers. To exclude certain tickers prefix the first ticker with a `-`.

Example: AAPL,INTC

sectors[] Sectors optional

An array of 1 or more sectors.

Example: Consumer CyclicalTechnologyUtilities

enum: Basic Materials, Communication Services, Consumer Cyclical, Consumer Defensive, Energy, Financial Services, Healthcare, Industrials, Real Estate, Technology, Utilities

unusual boolean optional

Convenience preset that returns only "unusual" contracts by applying the contract-expressible subset of the [live options flow](https://unusualwhales.com/live-options-flow) criteria: volume>OI, OTM, DTE≤60, ask-side≥50%, premium≥$10k, issue types ADR/Common Stock/ETF. These are applied as defaults, so any of those filters you pass explicitly (e.g. `max_dte=30`, `min_premium=25000`) overrides the preset.

min_underlying_price string optional

The minimum stock price.

max_underlying_price string optional

The maximum stock price.

is_otm boolean optional

Only include contracts which are currently out of the money.

is_itm boolean optional

Only include contracts which are currently in the money. Calls are ITM when strike is below the underlying price; puts are ITM when strike is above the underlying price.

exclude_ex_div_ticker boolean optional

When set to true, all tickers that trade ex-dividend today will be excluded. This is useful since on the day prior to the ex-dividend date, there will be above-average ITM call flow due to dividend arbitrage traders.

min_dte integer optional

The minimum days to expiry.

max_dte integer optional

The maximum days to expiry.

min_diff string optional

The minimum OTM diff of a contract.

max_diff string optional

The maximum OTM diff of a contract.

min_strike string optional

The minimum strike.

max_strike string optional

The maximum strike.

type OptionType optional

The option type to filter by if specified.

enum: call, Call, put, Put

expiry_dates[] Expiry dates optional

An array of 1 or more expiry dates.

Example: 2024-02-022024-01-26

min_marketcap string optional

The minimum marketcap.

max_marketcap string optional

The maximum marketcap.

min_volume Min Contract Volume optional

The minimum volume on the option contract. Min: 0.

Example: 12300

>= 0

max_volume Max Contract Volume optional

The maximum volume on the option contract. Min: 0.

Example: 55600

>= 0

min_ticker_30_d_avg_volume integer optional

The minimum 30-day average stock volume for the underlying ticker.

max_ticker_30_d_avg_volume integer optional

The maximum 30-day average stock volume for the underlying ticker.

min_contract_30_d_avg_volume integer optional

The minimum 30-day average options contract volume for the underlying ticker.

max_contract_30_d_avg_volume integer optional

The maximum 30-day average options contract volume for the underlying ticker.

min_multileg_volume_ratio string optional

The minimum multi leg volume to contract volume ratio.

max_multileg_volume_ratio string optional

The maximum multi leg volume to contract volume ratio.

min_floor_volume_ratio string optional

The minimum floor volume to contract volume ratio.

max_floor_volume_ratio string optional

The maximum floor volume to contract volume ratio.

min_perc_change string optional

The minimum % price change of the contract to the previous day. Acceptable range: -1.00 to +inf.

max_perc_change string optional

The maximum % price change of the contract to the previous day. Acceptable range: -1.00 to +inf.

min_daily_perc_change string optional

The minimum intraday price change of the contract from open till now.

max_daily_perc_change string optional

The maximum intraday price change for the contract since market open.

min_premium string optional

The minimum premium on that contract.

max_premium string optional

The maximum premium on that contract.

min_avg_price string optional

The minimum average price of the contract.

max_avg_price string optional

The maximum average price of the contract.

min_volume_oi_ratio string optional

The minimum contract volume to open interest ratio.

max_volume_oi_ratio string optional

The maximum contract volume to open interest ratio.

min_open_interest integer optional

The minimum open interest on that contract.

max_open_interest integer optional

The maximum open interest on that contract.

min_floor_volume integer optional

The minimum floor volume on that contract.

max_floor_volume integer optional

The maximum floor volume on that contract.

vol_greater_oi boolean optional

Only include contracts where the volume is greater than the open interest.

issue_types[] Issue types optional

An array of 1 or more issue types.

Example: Common StockIndex

enum: Common Stock, ETF, Index, ADR

min_ask_perc string optional

The minimum ask percentage of volume that transacted on the ask.

max_ask_perc string optional

The maximum ask percentage of volume that transacted on the ask.

min_bid_perc string optional

The minimum bid percentage of volume that transacted on the bid.

max_bid_perc string optional

The maximum bid percentage of volume that transacted on the bid.

min_skew_perc string optional

The minimum skew percentage. Setting this to 0.8 would return all contracts where either 80% of vol transacted on the ask or bid side

max_skew_perc string optional

The maximum skew percentage.Setting this to 0.8 would return all contracts where max 80% of vol transacted on the ask or bid side

min_bull_perc string optional

The minimum bull percentage.

max_bull_perc string optional

The maximum bull percentage.

min_bear_perc string optional

The minimum bear percentage.

max_bear_perc string optional

The maximum bear percentage.

min_bid_side_perc_7_day string optional

The minimum percentage of days over the last 7 days where the contract traded primarily on the bid side

max_bid_side_perc_7_day string optional

The maximum percentage of days over the last 7 days where the contract traded primarily on the bid side

min_ask_side_perc_7_day string optional

The minimum percentage of days over the last 7 days where the contract traded primarily on the ask side

max_ask_side_perc_7_day string optional

The maximum percentage of days over the last 7 days where the contract traded primarily on the ask side

min_days_of_oi_increases integer optional

The minimum days of consecutive trading days where the open interest increased

max_days_of_oi_increases integer optional

The maximum days of consecutive trading days where the open interest increased

min_days_of_vol_greater_than_oi integer optional

The minimum days of consecutive days where volume was greater than open interest.

max_days_of_vol_greater_than_oi integer optional

The maximum days of consecutive days where volume was greater than open interest.

min_iv_perc string optional

The minimum implied volatility percentage.

max_iv_perc string optional

The maximum implied volatility percentage.

min_delta string optional

The minimum delta. Acceptable range: -1.00 to +1.00.

max_delta string optional

The maximum delta. Acceptable range: -1.00 to +1.00.

min_gamma string optional

The minimum gamma. Acceptable range: 0.00 to +inf.

max_gamma string optional

The maximum gamma. Acceptable range: 0.00 to +inf.

min_theta string optional

The minimum theta. Acceptable range: -inf to 0.00.

max_theta string optional

The maximum theta. Acceptable range: -inf to 0.00.

min_vega string optional

The minimum vega. Acceptable range: 0.00 to +inf.

max_vega string optional

The maximum vega. Acceptable range: 0.00 to +inf.

min_return_on_capital_perc string optional

The minimum return on capital percentage (ROC).

max_return_on_capital_perc string optional

The maximum return on capital percentage (ROC).

min_oi_change_perc string optional

The minimum open interest change percentage. Acceptable range: -1.00 to +inf.

max_oi_change_perc string optional

The maximum open interest change percentage. Acceptable range: -1.00 to +inf.

min_oi_change integer optional

The minimum open interest change as an absolute change.

max_oi_change integer optional

The maximum open interest change as an absolute change.

min_volume_ticker_vol_ratio string optional

The minimum ratio of contract volume to total option volume of the underlying. Acceptable range: 0.00 to 1.00.

max_volume_ticker_vol_ratio string optional

The maximum ratio of contract volume to total option volume of the underlying. Acceptable range: 0.00 to 1.00.

min_sweep_volume_ratio string optional

The minimum sweep volume ratio. Acceptable range: 0.00 to 1.00.

max_sweep_volume_ratio string optional

The maximum sweep volume ratio. Acceptable range: 0.00 to 1.00.

min_from_low_perc string optional

The minimum percentage change of the current price from todays low. Acceptable range: -1.00 to +inf.

max_from_low_perc string optional

The maximum percentage change of the current price from todays low. Acceptable range: -1.00 to +inf.

min_from_high_perc string optional

The minimum percentage change of the current price from todays high. Acceptable range: -1.00 to +inf.

max_from_high_perc string optional

The maximum percentage change of the current price from todays high. Acceptable range: -1.00 to +inf.

min_earnings_dte Min Earnings DTE optional

The minimum days until the next earnings report.

Example: 5

max_earnings_dte Max Earnings DTE optional

The maximum days until the next earnings report.

Example: 30

min_days_between_expiry_and_earnings MinDaysBetweenExpiryAndEarnings optional

Minimum value of (contract_expiry_date - underlying_next_earnings_date) in days. Negative = contract expires BEFORE earnings; zero = same day; positive = AFTER earnings. Use together with `max_days_between_expiry_and_earnings` to target a window around the next earnings announcement. Examples: to exclude contracts that expire after the next earnings, set `max_days_between_expiry_and_earnings=-1`. To target contracts that expire the same week as (and after) earnings, set `min_days_between_expiry_and_earnings=1&max_days_between_expiry_and_earnings=6`. Contracts whose underlying has no known next earnings date are excluded whenever this filter is used.

Example: 1

max_days_between_expiry_and_earnings MaxDaysBetweenExpiryAndEarnings optional

Maximum value of (contract_expiry_date - underlying_next_earnings_date) in days. Negative = contract expires BEFORE earnings; zero = same day; positive = AFTER earnings. Use together with `min_days_between_expiry_and_earnings` to target a window around the next earnings announcement. Examples: to exclude contracts that expire after the next earnings, set `max_days_between_expiry_and_earnings=-1`. To target contracts that expire the same week as (and after) earnings, set `min_days_between_expiry_and_earnings=1&max_days_between_expiry_and_earnings=6`. Contracts whose underlying has no known next earnings date are excluded whenever this filter is used.

Example: 6

min_transactions integer optional

The minimum number of transactions.

max_transactions integer optional

The maximum number of transactions.

min_close string optional

The minimum contract price (not underlying price).

max_close string optional

The maximum contract price (not underlying price).

order Screener contract order by field optional

The field to order by.

Example: volume

enum: bid_ask_vol, bull_bear_vol, contract_pricing, daily_perc_change, diff, dte, earnings, expires, expiry, floor_volume, floor_volume_ratio, from_high, from_low, iv, multileg_volume, open_interest, premium, spread, stock_price, tape_time, ticker, total_multileg_volume_ratio, trades, volume, volume_oi_ratio, volume_ticker_vol_ratio

order_direction OrderDirection optional

Whether to sort descending or ascending. Descending by default.

Example: asc Default: desc

enum: desc, asc

limit Default 50, Max 250 Min 1 optional

How many items to return. Default: 50. Max: 250. Min: 1.

Example: 10 Default: 1

>= 1 <= 250

page Page optional

Page number (use with limit). Starts on page 0.

Example: 1

date Optional Market Date optional

A trading date in the format of YYYY-MM-DD. This is optional and by default the last trading date.

Example: 2024-01-18

is_new boolean optional

Return only new option contracts

opex_only boolean optional

Return only monthly option expirations

Responses

200 422 500

Response Body 200 OK

ask_side_volume Option Contract Ask Volume

The amount of volume that happened on the ask side. Ask side is defined as (ask + bid) / 2 < fill price.

Example: 119403

avg_price Option Contract Avg Price

The volume weighted average fill price of the contract.

Example: 1.0465802437910297887119234370

bid_side_volume Option Contract Bid Volume

The amount of volume that happened on the bid side. Bid side is defined as (ask + bid) / 2 > fill price.

Example: 122789

chain_prev_close Option Contract Previous Close Price

The previous trading day's contract price.

Example: 1.29

close Option Contract Close

The last fill on the contract.

Example: 0.03

cross_volume Option Contract Cross Volume

The amount of cross volume. Cross volume consists of all transaction that have the cross trade code.

Example: 0

er_time Stock Earnings time

The time when the earnings will be released.

Example: premarket

expiry Option Contract Expiry

The contract expiry date in ISO format.

Example: 2023-12-22

floor_volume Option Contract Floor Volume

The amount of floor volume. Floor volume consists of all transaction that have the floor trade code.

Example: 142

high Option Contract High

The highest fill on that contract.

Example: 2.95

last_fill Option Contract Last Transaction Time

The last time there was a transaction for the given contract as UTC timestamp.

Example: 2023-09-08T17:45:32Z

low Option Contract Low

The lowest fill on that contract.

Example: 0.02

mid_volume Option Contract Mid Volume

The amount of volume that happened in the middle of the ask and bid. Mid is defined as (ask + bid) / 2 == fill price.

Example: 22707

multileg_volume Option Contract Multi Leg Volume

The amount of volume that happened as part of a multileg trade with another contract. This can be spreads/rolls/condors/butterflies and more.

Example: 7486

next_earnings_date Stock Next Earnings Date

The next earnings date of the ticker. Null if either unknown as of now or if the ticker does not have any earnings such as an ETF

Example: 2023-10-26

no_side_volume Option Contract No Side Volume

The amount of volume that happened on no identifiable side. This can be late, out of sequence and/or cross transactions.

Example: 0

open Option Contract Open

The first fill on that contract.

Example: 0.92

open_interest Option Contract Open interest

The open interest for the contract.

Example: 18680

option_symbol Option Contract Symbol

The option symbol of the contract. You can use the following regex to extract underlying ticker, option type, expiry & strike: `^(?<symbol>[\w]*)(?<expiry>(\d{2})(\d{2})(\d{2}))(?<type>[PC])(?<strike>\d{8})$` Keep in mind that the strike needs to be multiplied by 1,000.

option_type Option Contract Option Type

The option type of the contract.

Example: call

premium Option Contract Premium

The total option premium.

Example: 27723806.00

sector Market General Sector

The financial sector of the ticker. Empty if unknown or not applicable such as ETF/Index.

Example: Technology

stock_multi_leg_volume Option Contract Stock Multi Leg Volume

The amount of volume that happened as part of a stock transaction and possibly other option contracts. This can be covered calls and more.

Example: 52

stock_price Stock Close Price

The close stock price of the ticker.

Example: 182.91

strike Option Contract Strike

The contract strike.

Example: 375

... and 6 more fields

Try It GET

API Token

Query Parameters

ticker_symbol Ticker

sectors[] Sectors

unusual boolean

min_underlying_price string

max_underlying_price string

is_otm boolean

is_itm boolean

exclude_ex_div_ticker boolean

min_dte integer

max_dte integer

min_diff string

max_diff string

min_strike string

max_strike string

type OptionType

expiry_dates[] Expiry dates

min_marketcap string

max_marketcap string

min_volume Min Contract Volume

max_volume Max Contract Volume

min_ticker_30_d_avg_volume integer

max_ticker_30_d_avg_volume integer

min_contract_30_d_avg_volume integer

max_contract_30_d_avg_volume integer

min_multileg_volume_ratio string

max_multileg_volume_ratio string

min_floor_volume_ratio string

max_floor_volume_ratio string

min_perc_change string

max_perc_change string

min_daily_perc_change string

max_daily_perc_change string

min_premium string

max_premium string

min_avg_price string

max_avg_price string

min_volume_oi_ratio string

max_volume_oi_ratio string

min_open_interest integer

max_open_interest integer

min_floor_volume integer

max_floor_volume integer

vol_greater_oi boolean

issue_types[] Issue types

min_ask_perc string

max_ask_perc string

min_bid_perc string

max_bid_perc string

min_skew_perc string

max_skew_perc string

min_bull_perc string

max_bull_perc string

min_bear_perc string

max_bear_perc string

min_bid_side_perc_7_day string

max_bid_side_perc_7_day string

min_ask_side_perc_7_day string

max_ask_side_perc_7_day string

min_days_of_oi_increases integer

max_days_of_oi_increases integer

min_days_of_vol_greater_than_oi integer

max_days_of_vol_greater_than_oi integer

min_iv_perc string

max_iv_perc string

min_delta string

max_delta string

min_gamma string

max_gamma string

min_theta string

max_theta string

min_vega string

max_vega string

min_return_on_capital_perc string

max_return_on_capital_perc string

min_oi_change_perc string

max_oi_change_perc string

min_oi_change integer

max_oi_change integer

min_volume_ticker_vol_ratio string

max_volume_ticker_vol_ratio string

min_sweep_volume_ratio string

max_sweep_volume_ratio string

min_from_low_perc string

max_from_low_perc string

min_from_high_perc string

max_from_high_perc string

min_earnings_dte Min Earnings DTE

max_earnings_dte Max Earnings DTE

min_days_between_expiry_and_earnings MinDaysBetweenExpiryAndEarnings

max_days_between_expiry_and_earnings MaxDaysBetweenExpiryAndEarnings

min_transactions integer

max_transactions integer

min_close string

max_close string

order Screener contract order by field

order_direction OrderDirection

limit Default 50, Max 250 Min 1

page Page

date Optional Market Date

is_new boolean

opex_only boolean

Request Sample

curl -X GET "https://api.unusualwhales.com/api/screener/option-contracts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

import http.client

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

Response Example 200

{
  "data": [
    {
      "ask_side_volume": 119403,
      "avg_price": "1.0465802437910297887119234370",
      "bid_side_volume": 122789,
      "chain_prev_close": "1.29",
      "close": "0.03",
      "cross_volume": 0,
      "er_time": "unknown",
      "expiry": "2023-09-08",
      "floor_volume": 142,
      "high": "2.95",
      "last_fill": "2023-09-08T17:45:32Z",
      "low": "0.02",
      "mid_volume": 22707,
      "multileg_volume": 7486,
      "next_earnings_date": "2023-10-18",
      "no_side_volume": 0,
      "open": "0.92",
      "open_interest": 18680,
      "option_symbol": "TSLA230908C00255000",
      "option_type": "call",
      "premium": "27723806.00",
      "sector": "Consumer Cyclical",
      "stock_multi_leg_volume": 52,
      "stock_price": "247.94",
      "strike": "255.0",
      "sweep_volume": 18260,
      "ticker_vol": 2546773,
      "total_ask_changes": 44343,
      "total_bid_changes": 43939,
      "trades": 39690,
      "volume": 264899
    }
  ]
}