Hottest Chains - Unusual Whales Docs

Hottest Chains

curl --request GET \
  --url https://api.unusualwhales.com/api/screener/option-contracts \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/screener/option-contracts"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.unusualwhales.com/api/screener/option-contracts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/screener/option-contracts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/screener/option-contracts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/screener/option-contracts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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-08T00:00:00.000Z",
      "floor_volume": 142,
      "high": "2.95",
      "last_fill": "2023-09-08T17:45:32.000Z",
      "low": "0.02",
      "mid_volume": 22707,
      "multileg_volume": 7486,
      "next_earnings_date": "2023-10-18T00:00:00.000Z",
      "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
    }
  ]
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

"Something went wrong"

GET

api

screener

option-contracts

Hottest Chains

curl --request GET \
  --url https://api.unusualwhales.com/api/screener/option-contracts \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.unusualwhales.com/api/screener/option-contracts"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.unusualwhales.com/api/screener/option-contracts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unusualwhales.com/api/screener/option-contracts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unusualwhales.com/api/screener/option-contracts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.unusualwhales.com/api/screener/option-contracts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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-08T00:00:00.000Z",
      "floor_volume": 142,
      "high": "2.95",
      "last_fill": "2023-09-08T17:45:32.000Z",
      "low": "0.02",
      "mid_volume": 22707,
      "multileg_volume": 7486,
      "next_earnings_date": "2023-10-18T00:00:00.000Z",
      "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
    }
  ]
}

{
  "code": "authentication_required",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "expected_format": "uuid",
  "message": "The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000.",
  "reason": "malformed_token",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "code": "missing_access",
  "documentation_url": "https://api.unusualwhales.com/docs",
  "message": "The API token provided is valid but is not permitted to access this route.",
  "reason": "route_not_permitted",
  "request_id": "GNI_YTC1CRnw2LACGBvE",
  "retryable": false,
  "support_email": "[email protected]",
  "token_url": "https://unusualwhales.com/dashboard/api"
}

{
  "msg": "Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18)",
  "path": "/api/darkpool/MSFT12",
  "query": "date=2023-02-140",
  "url": "localhost:4000/api/darkpool/MSFT12?date=2023-02-140"
}

"Something went wrong"

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

ticker_symbol

string

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

Example:

"AAPL,INTC"

sectors[]

enum<string>[]

An array of 1 or more sectors.

A singular sector.

Available options:

Basic Materials,

Communication Services,

Consumer Cyclical,

Consumer Defensive,

Energy,

Financial Services,

Healthcare,

Industrials,

Real Estate,

Technology,

Utilities

Example:

[
  "Consumer Cyclical",
  "Technology",
  "Utilities"
]

unusual

boolean

Convenience preset that returns only "unusual" contracts by applying the contract-expressible subset of the 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

The minimum stock price.

max_underlying_price

string

The maximum stock price.

is_otm

boolean

Only include contracts which are currently out of the money.

is_itm

boolean

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

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

The minimum days to expiry.

max_dte

integer

The maximum days to expiry.

min_diff

string

The minimum OTM diff of a contract.

max_diff

string

The maximum OTM diff of a contract.

min_strike

string

The minimum strike.

max_strike

string

The maximum strike.

type

enum<string>

The option type to filter by if specified.

Available options:

call,

Call,

put,

Put

expiry_dates[]

string[]

An array of 1 or more expiry dates.

A single expiry date in ISO date format.

Example:

[
  "2024-02-02T00:00:00.000Z",
  "2024-01-26T00:00:00.000Z"
]

min_marketcap

string

The minimum marketcap.

max_marketcap

string

The maximum marketcap.

min_volume

integer

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

Required range: x >= 0

Example:

12300

max_volume

integer

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

Required range: x >= 0

Example:

55600

min_ticker_30_d_avg_volume

integer

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

max_ticker_30_d_avg_volume

integer

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

min_contract_30_d_avg_volume

integer

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

max_contract_30_d_avg_volume

integer

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

min_multileg_volume_ratio

string

The minimum multi leg volume to contract volume ratio.

max_multileg_volume_ratio

string

The maximum multi leg volume to contract volume ratio.

min_floor_volume_ratio

string

The minimum floor volume to contract volume ratio.

max_floor_volume_ratio

string

The maximum floor volume to contract volume ratio.

min_perc_change

string

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

max_perc_change

string

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

min_daily_perc_change

string

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

max_daily_perc_change

string

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

min_premium

string

The minimum premium on that contract.

max_premium

string

The maximum premium on that contract.

min_avg_price

string

The minimum average price of the contract.

max_avg_price

string

The maximum average price of the contract.

min_volume_oi_ratio

string

The minimum contract volume to open interest ratio.

max_volume_oi_ratio

string

The maximum contract volume to open interest ratio.

min_open_interest

integer

The minimum open interest on that contract.

max_open_interest

integer

The maximum open interest on that contract.

min_floor_volume

integer

The minimum floor volume on that contract.

max_floor_volume

integer

The maximum floor volume on that contract.

vol_greater_oi

boolean

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

issue_types[]

enum<string>[]

An array of 1 or more issue types.

A singular issue type.

Available options:

Common Stock,

ETF,

Index,

ADR

Example:

["Common Stock", "Index"]

min_ask_perc

string

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

max_ask_perc

string

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

min_bid_perc

string

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

max_bid_perc

string

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

min_skew_perc

string

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

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

The minimum bull percentage.

max_bull_perc

string

The maximum bull percentage.

min_bear_perc

string

The minimum bear percentage.

max_bear_perc

string

The maximum bear percentage.

min_bid_side_perc_7_day

string

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

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

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

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

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

max_days_of_oi_increases

integer

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

min_days_of_vol_greater_than_oi

integer

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

max_days_of_vol_greater_than_oi

integer

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

min_iv_perc

string

The minimum implied volatility percentage.

max_iv_perc

string

The maximum implied volatility percentage.

min_delta

string

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

max_delta

string

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

min_gamma

string

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

max_gamma

string

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

min_theta

string

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

max_theta

string

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

min_vega

string

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

max_vega

string

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

min_return_on_capital_perc

string

The minimum return on capital percentage (ROC).

max_return_on_capital_perc

string

The maximum return on capital percentage (ROC).

min_oi_change_perc

string

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

max_oi_change_perc

string

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

min_oi_change

integer

The minimum open interest change as an absolute change.

max_oi_change

integer

The maximum open interest change as an absolute change.

min_volume_ticker_vol_ratio

string

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

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

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

max_sweep_volume_ratio

string

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

min_from_low_perc

string

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

max_from_low_perc

string

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

min_from_high_perc

string

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

max_from_high_perc

string

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

min_earnings_dte

integer

The minimum days until the next earnings report.

Example:

5

max_earnings_dte

integer

The maximum days until the next earnings report.

Example:

30

min_days_between_expiry_and_earnings

integer

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

integer

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

The minimum number of transactions.

max_transactions

integer

The maximum number of transactions.

min_close

string

The minimum contract price (not underlying price).

max_close

string

The maximum contract price (not underlying price).

order

enum<string>

The field to order by.

Available options:

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

Example:

"volume"

order_direction

enum<string>

default:desc

Whether to sort descending or ascending. Descending by default.

Available options:

desc,

asc

Example:

"asc"

limit

integer

default:1

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

Required range: 1 <= x <= 250

Example:

10

page

integer

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

Example:

1

date

string

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

Example:

"2024-01-18T00:00:00.000Z"

is_new

boolean

Return only new option contracts

opex_only

boolean

Return only monthly option expirations

Response

ask_side_volume

integer

The amount of volume that happened on the ask side.

Ask side is defined as (ask + bid) / 2 < fill price.

Example:

119403

avg_price

string

The volume weighted average fill price of the contract.

Example:

"1.0465802437910297887119234370"

bid_side_volume

integer

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

string

The previous trading day's contract price.

Example:

"1.29"

string

The last fill on the contract.

Example:

"0.03"

cross_volume

integer

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

Example:

0

er_time

enum<string>

The time when the earnings will be released.

Available options:

unknown,

afterhours,

premarket

Example:

"premarket"

expiry

string

The contract expiry date in ISO format.

Example:

"2023-12-22T00:00:00.000Z"

floor_volume

integer

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

Example:

142

high

string

The highest fill on that contract.

Example:

"2.95"

last_fill

string

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

Example:

"2023-09-08T17:45:32.000Z"

low

string

The lowest fill on that contract.

Example:

"0.02"

mid_volume

integer

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

integer

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

string<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-26T00:00:00.000Z"

no_side_volume

integer

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

Example:

0

open

string

The first fill on that contract.

Example:

"0.92"

open_interest

integer

The open interest for the contract.

Example:

18680

option_symbol

string

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

enum<string>

The option type of the contract.

Available options:

call,

put

Example:

"call"

premium

string

The total option premium.

Example:

"27723806.00"

sector

enum<string>

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

Available options:

Basic Materials,

Communication Services,

Consumer Cyclical,

Consumer Defensive,

Energy,

Financial Services,

Healthcare,

Industrials,

Real Estate,

Technology,

Utilities

Example:

"Technology"

stock_multi_leg_volume

integer

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

string

The close stock price of the ticker.

Example:

"182.91"

strike

string

The contract strike.

Example:

"375"

sweep_volume

integer

The amount of sweep volume. Sweep volume consists of all transaction that have the sweep trade code.

Example:

18260

ticker_vol

integer

The total amount of options volume for the given ticker.

total_ask_changes

integer

The total count of changes to the NBBO ask during that day's trading session.

Example:

165

total_bid_changes

integer

The total count of changes to the NBBO bid during that day's trading session.

Example:

28

trades

integer

The amount of transaction for this contract.

Example:

39690

volume

integer

The contract volume.

Example:

264899

Last modified on September 29, 2026