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_itm

boolean

When set to true, contracts that are in the money or at the money are excluded, as are contracts whose underlying price is unknown. In the money is judged on the real underlying price, even when the response shows a rounded stock_price for index tickers you may not have entitlement for like SPX or VIX.

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.

close_greater_avg

boolean

Only include contracts where the last price (close) is greater than the average price (avg_price).

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 as a decimal (0.19 = 19%).

max_iv_perc

string

The maximum implied volatility as a decimal (0.45 = 45%).

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:50

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

Required range: 1 <= x <= 500

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