Option Trades

GET https://api.unusualwhales.com/api/option-trades

Request

Security: Bearer Auth Authorization: Bearer <token>

Query Parameters

limit Default 50, Max 500 Min 1 optional

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

Example: 10 Default: 50

>= 1 <= 500

ticker_symbol Ticker optional

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

Example: AAPL,INTC

option_contracts[] array[OptionContract] optional

Option contracts to include.

Example: AAPL250117C00200000

chain[] array[OptionContract] optional

Alias for `option_contracts[]`.

Example: AAPL250117C00200000

strike Strike optional

The strike price of an option contract.

Example: 150.0

type OptionType optional

The option type to filter by if specified.

enum: call, Call, put, Put

newer_than NewerThan optional

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 OlderThan optional

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 Canceled optional

Whether the option trade was canceled.

is_multi_leg Flow Alerts Is Multi Leg optional

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

Example: true

volume_greater_oi Volume Greater Than Open Interest Contract optional

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

Example: true

exclude_deep_itm boolean optional

Exclude deep in-the-money contracts.

Example: true

force_15_min_delay boolean optional

Only return trades that are at least 15 minutes old.

Example: true

hide_expired boolean optional

Exclude expired option contracts.

Example: true

include_agg_trades boolean optional

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 optional

Only return trades from the current trading day.

Example: true

is_otm boolean optional

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

Example: true

opening boolean optional

Filter opening or non-opening transactions.

Example: true

opex_only boolean optional

Filter contracts by whether they expire on monthly OpEx Friday.

Example: true

size_greater_oi boolean optional

Filter by whether trade size exceeds open interest.

Example: true

exchanges[] array[string] optional

Options exchanges to include.

Example: AMXOMXOP

enum: AMXO, ARCO, BATO, C2OX, EDGO, EMLD, GMNI, MCRY, MPRL, XBOX, XBXO, XCBO, XISX, XMIO, XNDQ, XPHO, MXOP, SPHR, MXTO, IEXO

excluded_tags[] array[string] optional

Exclude trades containing any of these tags.

Example: bid_side

enum: ask_side, bid_side, mid_side, no_side, china, volatility, dividend, index, arbitrage

expiry_dates[] Expiry dates optional

An array of 1 or more expiry dates.

Example: 2024-02-022024-01-26

industries[] Industries optional

An array of one or more industries.

Example: SemiconductorsSoftware - Infrastructure

issue_types[] Issue types optional

An array of 1 or more issue types.

Example: Common StockIndex

enum: Common Stock, ETF, Index, ADR

marketcap_size[] Market cap sizes optional

An array of one or more market capitalization size categories.

Example: largebig

enum: micro, small, mid, large, big

report_flag[] array[string] optional

Trade report flags to include.

Example: intermarket_sweep

enum: opening, closing, reopening, cross_trade, extended_hours, intermarket_sweep, trade_through_exempt, odd_lot, official_price_report, futures_floor, summary, printable, normal

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

tags[] array[string] optional

Include trades containing any of these tags.

Example: ask_side

enum: ask_side, bid_side, mid_side, no_side, china, volatility, dividend, index, arbitrage

trade_codes[] array[string] optional

OPRA trade code of the executed transaction.

Example: autoslan

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

min_ask_perc Flow Alerts Min Ask Percentage optional

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

Example: 0.25

>= 0 <= 1

max_ask_perc Flow Alerts Max Ask Percentage optional

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

Example: 0.75

>= 0 <= 1

min_bear_perc Flow Alerts Min Bear Percentage optional

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

Example: 0.5

>= 0 <= 1

max_bear_perc Flow Alerts Max Bear Percentage optional

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

Example: 0.9

>= 0 <= 1

min_bid_perc Flow Alerts Min Bid Percentage optional

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

Example: 0.25

>= 0 <= 1

max_bid_perc Flow Alerts Max Bid Percentage optional

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

Example: 0.75

>= 0 <= 1

min_bull_perc Flow Alerts Min Bull Percentage optional

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

Example: 0.5

>= 0 <= 1

max_bull_perc Flow Alerts Max Bull Percentage optional

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

Example: 0.9

>= 0 <= 1

min_skew Flow Alerts Min Skew optional

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

Example: 0.3

>= 0 <= 1

max_skew Flow Alerts Max Skew optional

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

Example: 0.7

>= 0 <= 1

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_dte Min DTE optional

The minimum days to expiry. Min: 0.

Example: 1

>= 0

max_dte Max DTE optional

The maximum days to expiry. Min: 0.

Example: 3

>= 0

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_open_interest Min Open Interest optional

The minimum open interest. Min: 0.

Example: 10000

>= 0

max_open_interest Max Open Interest optional

The maximum open interest. Min: 0.

Example: 35000

>= 0

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_size integer optional

Minimum trade size in contracts.

Example: 100

max_size integer optional

Maximum trade size in contracts.

Example: 100

min_delta string optional

Minimum option delta.

Example: abs(0.5)

max_delta string optional

Maximum option delta.

Example: abs(0.5)

min_gamma string optional

Minimum option gamma.

Example: abs(0.05)

max_gamma string optional

Maximum option gamma.

Example: abs(0.05)

min_iv string optional

Minimum implied volatility as a decimal.

Example: 0.5

max_iv string optional

Maximum implied volatility as a decimal.

Example: 0.5

min_theta string optional

Minimum option theta.

Example: abs(0.1)

max_theta string optional

Maximum option theta.

Example: abs(0.1)

min_diff Min Contract Diff optional

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 Max Contract Diff optional

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 Min Marketcap optional

The minimum marketcap. Min: 0.

Example: 1000000

>= 0

max_marketcap Max Marketcap optional

The maximum marketcap. Min: 0.

Example: 250000000

>= 0

min_strike Min Strike optional

The minimum strike. Min: 0.

Example: 120.5

>= 0

max_strike Max Strike optional

The maximum strike. Min: 0.

Example: 1200

>= 0

min_vol_oi_ratio Min Volume OI Ratio optional

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.

Example: 0.32

>= 0

max_vol_oi_ratio Max Volume OI Ratio optional

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.

Example: 1.58

>= 0

min_premium string optional

Minimum trade premium in dollars.

Example: 25000

max_premium string optional

Maximum trade premium in dollars.

Example: 25000

min_price string optional

Minimum option trade price.

Example: 5.25

max_price string optional

Maximum option trade price.

Example: 5.25

min_spread string optional

Minimum bid-ask spread percentage.

Example: 0.1

max_spread string optional

Maximum bid-ask spread percentage.

Example: 0.1

min_underlying_price string optional

Minimum underlying price at execution.

Example: 195.50

max_underlying_price string optional

Maximum underlying price at execution.

Example: 195.50

Responses

200 400 422 500 502

Response Body 200 OK

ask_vol 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

bid_vol 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

canceled Canceled

Whether the option trade was canceled.

delta Delta

The delta of the option trade.

Example: 0.610546281537814

er_time Stock Earnings time

The time when the earnings will be released.

Example: premarket

ewma_nbbo_ask EWMA NBBO Ask

The exponentially weighted moving average of the National Best Bid and Offer ask side.

Example: 21.60

ewma_nbbo_bid EWMA NBBO Bid

The exponentially weighted moving average of the National Best Bid and Offer bid side.

Example: 21.45

exchange Exchange

The exchange the option trade was executed on.

Example: MXOP

executed_at Executed At

The option trade execution time as an ISO 8601 UTC timestamp. The WebSocket `option_trades` channel represents this field as Unix epoch milliseconds instead.

Example: 2024-08-21T13:50:52.278302Z

expiry Option Contract Expiry

The contract expiry date in ISO format.

Example: 2023-12-22

flow_alert_id Flow Alert ID

The flow alert ID of the option trade. If the flow alert ID is null, it means that there is no flow alert associated with the option trade.

full_name Stock Full Name

Full name of the ticker.

Example: APPLE

gamma Gamma

The gamma of the option trade.

Example: 0.00775013889662635

id Option Trade ID

The ID of the option trade.

Example: 8ef90a2d-d881-41de-98c9-c1de4318dcb5

implied_volatility Implied Volatility

The implied volatility of the option trade.

Example: 0.604347250962543

industry_type Stock Industry Type

The industry type of the ticker.

Example: Semiconductors

is_agg boolean

Whether this response item combines related option transactions executed at the same time into a single transaction.

Example: true

issue_type string

Example: Common Stock

marketcap Stock Marketcap AUM

The marketcap of the underlying ticker. If the issue type of the ticker is ETF then the marketcap represents the AUM.

Example: 2965813810400

mid_vol 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

multi_vol 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

nbbo_ask NBBO Ask

The National Best Bid and Offer (NBBO) ask price.

Example: 0.03

nbbo_ask_size NBBO Ask Size

The quoted size in contracts at the NBBO ask price. `null` when quote metadata is unavailable.

Example: 24

nbbo_ask_time NBBO Ask Time

The last update time for the NBBO ask quote as an ISO 8601 UTC timestamp. `null` when quote metadata is unavailable. The WebSocket `option_trades` channel represents this field as Unix epoch milliseconds instead.

Example: 2024-08-21T13:50:52.274302Z

nbbo_bid NBBO Bid

The National Best Bid and Offer (NBBO) bid price.

Example: 0.03

... and 25 more fields

Try It GET

API Token

Query Parameters

limit Default 50, Max 500 Min 1

ticker_symbol Ticker

option_contracts[] array[OptionContract]

chain[] array[OptionContract]

strike Strike

type OptionType

newer_than NewerThan

older_than OlderThan

canceled Canceled

is_multi_leg Flow Alerts Is Multi Leg

volume_greater_oi Volume Greater Than Open Interest Contract

exclude_deep_itm boolean

force_15_min_delay boolean

hide_expired boolean

include_agg_trades boolean

intraday_only boolean

is_otm boolean

opening boolean

opex_only boolean

size_greater_oi boolean

exchanges[] array[string]

excluded_tags[] array[string]

expiry_dates[] Expiry dates

industries[] Industries

issue_types[] Issue types

marketcap_size[] Market cap sizes

report_flag[] array[string]

sectors[] Sectors

tags[] array[string]

trade_codes[] array[string]

min_ask_perc Flow Alerts Min Ask Percentage

max_ask_perc Flow Alerts Max Ask Percentage

min_bear_perc Flow Alerts Min Bear Percentage

max_bear_perc Flow Alerts Max Bear Percentage

min_bid_perc Flow Alerts Min Bid Percentage

max_bid_perc Flow Alerts Max Bid Percentage

min_bull_perc Flow Alerts Min Bull Percentage

max_bull_perc Flow Alerts Max Bull Percentage

min_skew Flow Alerts Min Skew

max_skew Flow Alerts Max Skew

min_days_between_expiry_and_earnings MinDaysBetweenExpiryAndEarnings

max_days_between_expiry_and_earnings MaxDaysBetweenExpiryAndEarnings

min_dte Min DTE

max_dte Max DTE

min_earnings_dte Min Earnings DTE

max_earnings_dte Max Earnings DTE

min_open_interest Min Open Interest

max_open_interest Max Open Interest

min_volume Min Contract Volume

max_volume Max Contract Volume

min_size integer

max_size integer

min_delta string

max_delta string

min_gamma string

max_gamma string

min_iv string

max_iv string

min_theta string

max_theta string

min_diff Min Contract Diff

max_diff Max Contract Diff

min_marketcap Min Marketcap

max_marketcap Max Marketcap

min_strike Min Strike

max_strike Max Strike

min_vol_oi_ratio Min Volume OI Ratio

max_vol_oi_ratio Max Volume OI Ratio

min_premium string

max_premium string

min_price string

max_price string

min_spread string

max_spread string

min_underlying_price string

max_underlying_price string

Request Sample

curl -X GET "https://api.unusualwhales.com/api/option-trades" \
  -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/option-trades", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))

Response Example 200

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