Option Trades

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

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

fetch('https://api.unusualwhales.com/api/option-trades', 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/option-trades",
  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/option-trades"

	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/option-trades")

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_vol": 2,
      "bid_vol": 1,
      "canceled": false,
      "delta": "0.610546281537814",
      "er_time": "postmarket",
      "ewma_nbbo_ask": "21.60",
      "ewma_nbbo_bid": "21.45",
      "exchange": "MXOP",
      "executed_at": "2024-08-21T13:50:52.278Z",
      "expiry": "2025-01-17T00:00:00.000Z",
      "flow_alert_id": null,
      "full_name": "NVIDIA CORP",
      "gamma": "0.00775013889662635",
      "id": "8ef90a2d-d881-41de-98c9-c1de4318dcb5",
      "implied_volatility": "0.604347250962543",
      "industry_type": "Semiconductors",
      "marketcap": "3130350000000.00",
      "mid_vol": 30,
      "multi_vol": 30,
      "nbbo_ask": "21.60",
      "nbbo_ask_size": 24,
      "nbbo_ask_time": "2024-08-21T13:50:52.274Z",
      "nbbo_bid": "21.45",
      "nbbo_bid_size": 17,
      "nbbo_bid_time": "2024-08-21T13:50:52.271Z",
      "next_earnings_date": "2024-08-28T00:00:00.000Z",
      "no_side_vol": 0,
      "open_interest": 6016,
      "option_chain_id": "NVDA250117C00124000",
      "option_type": "call",
      "premium": "2150.00",
      "price": "21.50",
      "report_flags": [],
      "rho": "0.2316546330093438",
      "rule_id": null,
      "sector": "Technology",
      "size": 1,
      "stock_multi_vol": 0,
      "strike": "124.0000000000",
      "tags": [
        "bid_side",
        "bearish",
        "earnings_next_week"
      ],
      "theo": "21.49999999999999",
      "theta": "-0.0640155364004474",
      "underlying_price": "128.16",
      "underlying_symbol": "NVDA",
      "upstream_condition_detail": "auto",
      "vega": "0.3140468475903719",
      "volume": 33
    }
  ]
}

{
  "error": {
    "code": "historical_data_not_supported",
    "message": "This endpoint only returns data for the latest trading day. Use /api/option-trades/full-tape/:date to download the full market file for a historical trading day."
  }
}

{
  "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"

{
  "error": {
    "code": "historical_data_not_supported",
    "message": "This endpoint only returns data for the latest trading day. Use /api/option-trades/full-tape/:date to download the full market file for a historical trading day."
  }
}

option-trade

Option Trades

Filter the full option trades tape.

This endpoint returns the same data and supports the same filter params as on the unusualwhales website https://unusualwhales.com/live-options-flow.

This endpoint only returns data for the latest trading day. To retrieve historical option trades, use the /api/option-trades/full-tape/:date endpoint to download the full market file for a trading day.

List parameters may be supplied using repeated bracket notation, for example tags[]=ask_side&tags[]=bid_side. Unix timestamps may be supplied in seconds or milliseconds.

Pagination uses the older_than and newer_than cursors, which accept Unix seconds, Unix milliseconds or ISO 8601 values. page and offset are not supported. limit defaults to 50 and has a maximum of 500. A cursor earlier than the latest trading day returns HTTP 400. Use /api/option-trades/full-tape/{date} for older history.

The side-volume fields (ask_vol, bid_vol, mid_vol and no_side_vol) sum to volume. multi_vol and stock_multi_vol are overlapping subsets of volume, not separate amounts to subtract.

On this REST endpoint, executed_at, nbbo_bid_time and nbbo_ask_time are ISO 8601 timestamps in UTC. On the WebSocket option_trades channel, the same fields are Unix epoch timestamps in milliseconds.

GET

api

option-trades

Option Trades

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

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

fetch('https://api.unusualwhales.com/api/option-trades', 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/option-trades",
  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/option-trades"

	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/option-trades")

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_vol": 2,
      "bid_vol": 1,
      "canceled": false,
      "delta": "0.610546281537814",
      "er_time": "postmarket",
      "ewma_nbbo_ask": "21.60",
      "ewma_nbbo_bid": "21.45",
      "exchange": "MXOP",
      "executed_at": "2024-08-21T13:50:52.278Z",
      "expiry": "2025-01-17T00:00:00.000Z",
      "flow_alert_id": null,
      "full_name": "NVIDIA CORP",
      "gamma": "0.00775013889662635",
      "id": "8ef90a2d-d881-41de-98c9-c1de4318dcb5",
      "implied_volatility": "0.604347250962543",
      "industry_type": "Semiconductors",
      "marketcap": "3130350000000.00",
      "mid_vol": 30,
      "multi_vol": 30,
      "nbbo_ask": "21.60",
      "nbbo_ask_size": 24,
      "nbbo_ask_time": "2024-08-21T13:50:52.274Z",
      "nbbo_bid": "21.45",
      "nbbo_bid_size": 17,
      "nbbo_bid_time": "2024-08-21T13:50:52.271Z",
      "next_earnings_date": "2024-08-28T00:00:00.000Z",
      "no_side_vol": 0,
      "open_interest": 6016,
      "option_chain_id": "NVDA250117C00124000",
      "option_type": "call",
      "premium": "2150.00",
      "price": "21.50",
      "report_flags": [],
      "rho": "0.2316546330093438",
      "rule_id": null,
      "sector": "Technology",
      "size": 1,
      "stock_multi_vol": 0,
      "strike": "124.0000000000",
      "tags": [
        "bid_side",
        "bearish",
        "earnings_next_week"
      ],
      "theo": "21.49999999999999",
      "theta": "-0.0640155364004474",
      "underlying_price": "128.16",
      "underlying_symbol": "NVDA",
      "upstream_condition_detail": "auto",
      "vega": "0.3140468475903719",
      "volume": 33
    }
  ]
}

{
  "error": {
    "code": "historical_data_not_supported",
    "message": "This endpoint only returns data for the latest trading day. Use /api/option-trades/full-tape/:date to download the full market file for a historical trading day."
  }
}

{
  "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"

{
  "error": {
    "code": "historical_data_not_supported",
    "message": "This endpoint only returns data for the latest trading day. Use /api/option-trades/full-tape/:date to download the full market file for a historical trading day."
  }
}

Authorizations

Authorization

string

header

required

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

Query Parameters

limit

integer

default:50

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

Required range: 1 <= x <= 500

Example:

10

ticker_symbol

string

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

Example:

"AAPL,INTC"

option_contracts[]

string[]

Option contracts to include.

An option contract in the OSI format.

Example:

["AAPL250117C00200000"]

chain[]

string[]

Alias for option_contracts[].

An option contract in the OSI format.

Example:

["AAPL250117C00200000"]

strike

string

The strike price of an option contract.

Example:

"150.0"

type

enum<string>

The option type to filter by if specified.

Available options:

call,

Call,

put,

Put

newer_than

string

The unix time in milliseconds or seconds at which no older results will be returned. Can be used with older_than to paginate by time. Also accepts an ISO date or RFC 3339 datetime (example: 2024-01-25).

Example:

"1_715_083_417"

older_than

string

The unix time in milliseconds or seconds at which no newer results will be returned. Can be used with newer_than to paginate by time. Also accepts an ISO date or RFC 3339 datetime (example: 2024-01-25).

Example:

"1_715_083_417"

canceled

boolean

Whether the option trade was canceled.

Example:

false

is_multi_leg

boolean

Boolean flag whether the transaction is a multi-leg transaction.

Example:

true

volume_greater_oi

boolean

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

Example:

true

exclude_deep_itm

boolean

Exclude deep in-the-money contracts.

Example:

true

force_15_min_delay

boolean

Only return trades that are at least 15 minutes old.

Example:

true

hide_expired

boolean

Exclude expired option contracts.

Example:

true

include_agg_trades

boolean

Whether to roll up related option transactions executed at the same time into a single transaction in the response. This allows filters to apply to their combined premium and size. For example, if one $25,000 order is reported as ten $2,500 transactions, it will only match min_premium=20000 when include_agg_trades=true.

Example:

true

intraday_only

boolean

Only return trades from the current trading day.

Example:

true

is_otm

boolean

Filter out-of-the-money or in-the-money trades.

Example:

true

opening

boolean

Filter opening or non-opening transactions.

Example:

true

opex_only

boolean

Filter contracts by whether they expire on monthly OpEx Friday.

Example:

true

size_greater_oi

boolean

Filter by whether trade size exceeds open interest.

Example:

true

exchanges[]

enum<string>[]

Options exchanges to include.

Available options:

AMXO,

ARCO,

BATO,

C2OX,

EDGO,

EMLD,

GMNI,

MCRY,

MPRL,

XBOX,

XBXO,

XCBO,

XISX,

XMIO,

XNDQ,

XPHO,

MXOP,

SPHR,

MXTO,

IEXO

Example:

["AMXO", "MXOP"]

excluded_tags[]

enum<string>[]

Exclude trades containing any of these tags.

Available options:

ask_side,

bid_side,

mid_side,

no_side,

china,

volatility,

dividend,

index,

arbitrage

Example:

["bid_side"]

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"
]

industries[]

string[]

An array of one or more industries.

Example:

[
  "Semiconductors",
  "Software - Infrastructure"
]

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"]

marketcap_size[]

enum<string>[]

An array of one or more market capitalization size categories.

A market capitalization size category.

Available options:

micro,

small,

mid,

large,

big

Example:

["large", "big"]

report_flag[]

enum<string>[]

Trade report flags to include.

Available options:

opening,

closing,

reopening,

cross_trade,

extended_hours,

intermarket_sweep,

trade_through_exempt,

odd_lot,

official_price_report,

futures_floor,

summary,

printable,

normal

Example:

["intermarket_sweep"]

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"
]

tags[]

enum<string>[]

Include trades containing any of these tags.

Available options:

ask_side,

bid_side,

mid_side,

no_side,

china,

volatility,

dividend,

index,

arbitrage

Example:

["ask_side"]

trade_codes[]

enum<string>[]

OPRA trade code of the executed transaction.

Available options:

mlet,

mlat,

mlct,

mlft,

mesl,

masl,

mfsl,

cbmo,

tlet,

tlct,

tlft,

tesl,

tasl,

tfsl,

tlat,

auto,

isoi,

late,

mctp,

open,

opnl,

oseq,

reop,

slai,

slan,

slci,

slcn,

slft

Example:

["auto", "slan"]

min_ask_perc

number

The minimum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.25

max_ask_perc

number

The maximum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.75

min_bear_perc

number

The minimum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.5

max_bear_perc

number

The maximum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.9

min_bid_perc

number

The minimum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.25

max_bid_perc

number

The maximum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.75

min_bull_perc

number

The minimum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.5

max_bull_perc

number

The maximum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.9

min_skew

number

The minimum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.3

max_skew

number

The maximum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.

Required range: 0 <= x <= 1

Example:

0.7

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_dte

integer

The minimum days to expiry. Min: 0.

Required range: x >= 0

Example:

1

max_dte

integer

The maximum days to expiry. Min: 0.

Required range: x >= 0

Example:

3

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_open_interest

integer

The minimum open interest. Min: 0.

Required range: x >= 0

Example:

10000

max_open_interest

integer

The maximum open interest. Min: 0.

Required range: x >= 0

Example:

35000

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_size

integer<int64>

Minimum trade size in contracts.

Example:

100

max_size

integer<int64>

Maximum trade size in contracts.

Example:

100

min_delta

string

Minimum option delta.

Example:

"abs(0.5)"

max_delta

string

Maximum option delta.

Example:

"abs(0.5)"

min_gamma

string

Minimum option gamma.

Example:

"abs(0.05)"

max_gamma

string

Maximum option gamma.

Example:

"abs(0.05)"

min_iv

string

Minimum implied volatility as a decimal.

Example:

"0.5"

max_iv

string

Maximum implied volatility as a decimal.

Example:

"0.5"

min_theta

string

Minimum option theta.

Example:

"abs(0.1)"

max_theta

string

Maximum option theta.

Example:

"abs(0.1)"

min_diff

string

The minimum OTM diff of a contract. Given a strike price of 120 and an underlying price of 98 the diff for a call option would equal to: (120 - 98) / 98 = 0.2245

The diff for a put option would equal to: -1 * (120 - 98) / 98 = -0.2245.

Example:

0.53

max_diff

string

The maximum OTM diff of a contract. Given a strike price of 120 and an underlying price of 98 the diff for a call option would equal to: (120 - 98) / 98 = 0.2245

The diff for a put option would equal to: -1 * (120 - 98) / 98 = -0.2245.

Example:

1.34

min_marketcap

number

The minimum marketcap. Min: 0.

Required range: x >= 0

Example:

1000000

max_marketcap

number

The maximum marketcap. Min: 0.

Required range: x >= 0

Example:

250000000

min_strike

number

The minimum strike. Min: 0.

Required range: x >= 0

Example:

120.5

max_strike

number

The maximum strike. Min: 0.

Required range: x >= 0

Example:

1200

min_vol_oi_ratio

number

The minimum ratio of contract volume to contract open interest. If the open interest of a contract is zero, then this ratio is evaluated as if the open interest of the contract was one (to avoid divide by zero errors). For example, if you set this ratio to 10, then a contract with zero open interest and 7 volume will NOT be included in your results.

Required range: x >= 0

Example:

0.32

max_vol_oi_ratio

number

The maximum ratio of contract volume to contract open interest. If the open interest of a contract is zero, then this ratio is evaluated as if the open interest of the contract was one (to avoid divide by zero errors). For example, if you set this ratio to 50, then a contract with zero open interest and 75 volume will NOT be included in your results.

Required range: x >= 0

Example:

1.58

min_premium

string

Minimum trade premium in dollars.

Example:

"25000"

max_premium

string

Maximum trade premium in dollars.

Example:

"25000"

min_price

string

Minimum option trade price.

Example:

"5.25"

max_price

string

Maximum option trade price.

Example:

"5.25"

min_spread

string

Minimum bid-ask spread percentage.

Example:

"0.1"

max_spread

string

Maximum bid-ask spread percentage.

Example:

"0.1"

min_underlying_price

string

Minimum underlying price at execution.

Example:

"195.50"

max_underlying_price

string

Maximum underlying price at execution.

Example:

"195.50"

Response

data

Option Trade · object[]

Show child attributes

Last modified on September 29, 2026

Docs

Endpoints

Option Trades

Authorizations

Query Parameters

Response