# Option Trades `GET` `https://api.unusualwhales.com/api/option-trades` Fitler 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](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. ## Authentication ``` Authorization: Bearer YOUR_API_KEY ``` ## Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `limit` | Default 50, Max 500 Min 1 | No | How many items to return. Default: 50. Max: 500. Min: 1. | | `ticker_symbol` | Ticker | No | A comma separated list of tickers. To exclude certain tickers prefix the first ticker with a `-`. | | `option_contracts[]` | array[OptionContract] | No | Option contracts to include. | | `chain[]` | array[OptionContract] | No | Alias for `option_contracts[]`. | | `strike` | Strike | No | The strike price of an option contract. | | `type` | OptionType | No | The option type to filter by if specified. | | `newer_than` | NewerThan | No | 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). | | `older_than` | OlderThan | No | 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). | | `canceled` | Canceled | No | Whether the option trade was canceled. | | `is_multi_leg` | Flow Alerts Is Multi Leg | No | Boolean flag whether the transaction is a multi-leg transaction. | | `volume_greater_oi` | Volume Greater Than Open Interest Contract | No | Only include contracts where the volume is greater than the open interest. | | `exclude_deep_itm` | boolean | No | Exclude deep in-the-money contracts. | | `force_15_min_delay` | boolean | No | Only return trades that are at least 15 minutes old. | | `hide_expired` | boolean | No | Exclude expired option contracts. | | `include_agg_trades` | boolean | No | 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`. | | `intraday_only` | boolean | No | Only return trades from the current trading day. | | `is_otm` | boolean | No | Filter out-of-the-money or in-the-money trades. | | `opening` | boolean | No | Filter opening or non-opening transactions. | | `opex_only` | boolean | No | Filter contracts by whether they expire on monthly OpEx Friday. | | `size_greater_oi` | boolean | No | Filter by whether trade size exceeds open interest. | | `exchanges[]` | array[string] | No | Options exchanges to include. | | `excluded_tags[]` | array[string] | No | Exclude trades containing any of these tags. | | `expiry_dates[]` | Expiry dates | No | An array of 1 or more expiry dates. | | `industries[]` | Industries | No | An array of one or more industries. | | `issue_types[]` | Issue types | No | An array of 1 or more issue types. | | `marketcap_size[]` | Market cap sizes | No | An array of one or more market capitalization size categories. | | `report_flag[]` | array[string] | No | Trade report flags to include. | | `sectors[]` | Sectors | No | An array of 1 or more sectors. | | `tags[]` | array[string] | No | Include trades containing any of these tags. | | `trade_codes[]` | array[string] | No | OPRA trade code of the executed transaction. | | `min_ask_perc` | Flow Alerts Min Ask Percentage | No | The minimum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `max_ask_perc` | Flow Alerts Max Ask Percentage | No | The maximum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `min_bear_perc` | Flow Alerts Min Bear Percentage | No | The minimum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `max_bear_perc` | Flow Alerts Max Bear Percentage | No | The maximum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `min_bid_perc` | Flow Alerts Min Bid Percentage | No | The minimum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `max_bid_perc` | Flow Alerts Max Bid Percentage | No | The maximum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `min_bull_perc` | Flow Alerts Min Bull Percentage | No | The minimum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `max_bull_perc` | Flow Alerts Max Bull Percentage | No | The maximum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `min_skew` | Flow Alerts Min Skew | No | The minimum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `max_skew` | Flow Alerts Max Skew | No | The maximum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. | | `min_days_between_expiry_and_earnings` | MinDaysBetweenExpiryAndEarnings | No | 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. | | `max_days_between_expiry_and_earnings` | MaxDaysBetweenExpiryAndEarnings | No | 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. | | `min_dte` | Min DTE | No | The minimum days to expiry. Min: 0. | | `max_dte` | Max DTE | No | The maximum days to expiry. Min: 0. | | `min_earnings_dte` | Min Earnings DTE | No | The minimum days until the next earnings report. | | `max_earnings_dte` | Max Earnings DTE | No | The maximum days until the next earnings report. | | `min_open_interest` | Min Open Interest | No | The minimum open interest. Min: 0. | | `max_open_interest` | Max Open Interest | No | The maximum open interest. Min: 0. | | `min_volume` | Min Contract Volume | No | The minimum volume on the option contract. Min: 0. | | `max_volume` | Max Contract Volume | No | The maximum volume on the option contract. Min: 0. | | `min_size` | integer | No | Minimum trade size in contracts. | | `max_size` | integer | No | Maximum trade size in contracts. | | `min_delta` | string | No | Minimum option delta. | | `max_delta` | string | No | Maximum option delta. | | `min_gamma` | string | No | Minimum option gamma. | | `max_gamma` | string | No | Maximum option gamma. | | `min_iv` | string | No | Minimum implied volatility as a decimal. | | `max_iv` | string | No | Maximum implied volatility as a decimal. | | `min_theta` | string | No | Minimum option theta. | | `max_theta` | string | No | Maximum option theta. | | `min_diff` | Min Contract Diff | No | 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. | | `max_diff` | Max Contract Diff | No | 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. | | `min_marketcap` | Min Marketcap | No | The minimum marketcap. Min: 0. | | `max_marketcap` | Max Marketcap | No | The maximum marketcap. Min: 0. | | `min_strike` | Min Strike | No | The minimum strike. Min: 0. | | `max_strike` | Max Strike | No | The maximum strike. Min: 0. | | `min_vol_oi_ratio` | Min Volume OI Ratio | No | 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. | | `max_vol_oi_ratio` | Max Volume OI Ratio | No | 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. | | `min_premium` | string | No | Minimum trade premium in dollars. | | `max_premium` | string | No | Maximum trade premium in dollars. | | `min_price` | string | No | Minimum option trade price. | | `max_price` | string | No | Maximum option trade price. | | `min_spread` | string | No | Minimum bid-ask spread percentage. | | `max_spread` | string | No | Maximum bid-ask spread percentage. | | `min_underlying_price` | string | No | Minimum underlying price at execution. | | `max_underlying_price` | string | No | Maximum underlying price at execution. | ## Response (200) | Field | Type | Description | |-------|------|-------------| | `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. | | `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. | | `canceled` | Canceled | Whether the option trade was canceled. | | `delta` | Delta | The delta of the option trade. | | `er_time` | Stock Earnings time | The time when the earnings will be released. | | `ewma_nbbo_ask` | EWMA NBBO Ask | The exponentially weighted moving average of the National Best Bid and Offer ask side. | | `ewma_nbbo_bid` | EWMA NBBO Bid | The exponentially weighted moving average of the National Best Bid and Offer bid side. | | `exchange` | Exchange | The exchange the option trade was executed on. | | `executed_at` | Executed At | The time the option trade was executed. | | `expiry` | Option Contract Expiry | The contract expiry date in ISO format. | | `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. | | `gamma` | Gamma | The gamma of the option trade. | | `id` | Option Trade ID | The ID of the option trade. | | `implied_volatility` | Implied Volatility | The implied volatility of the option trade. | | `industry_type` | Stock Industry Type | The industry type of the ticker. | | `is_agg` | boolean | Whether this response item combines related option transactions executed at the same time into a single transaction. | | `issue_type` | string | | | `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. | | `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. | | `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. | | `nbbo_ask` | NBBO Ask | The National Best Bid and Offer (NBBO) ask price. | | `nbbo_bid` | NBBO Bid | The National Best Bid and Offer (NBBO) bid price. | | `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 | | `no_side_vol` | 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. | | `open_interest` | Option Contract Open interest | The open interest for the contract. | | `option_chain_id` | Option Contract Symbol | The option symbol of the contract. You can use the following regex to extract underlying ticker, option type, expiry & strike: `^(?[\w]*)(?(\d{2})(\d{2})(\d{2}))(?[PC])(?\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. | | `premium` | Premium | The premium of the option trade. | | `price` | Fill Price | The fill price of the option trade. | | `report_flags` | Report Flags | The report flags of the option trade. | | `rho` | Rho | The rho of the option trade. | | `rule_id` | Rule ID | The rule ID of the option trade that represents the rule that made up the flow alert | | `sector` | Market General Sector | The financial sector of the ticker. Empty if unknown or not applicable such as ETF/Index. | | `size` | Option Trade Size | The size of the option trade. | | `stock_multi_vol` | 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. | | `strike` | Option Contract Strike | The contract strike. | | `tags` | Tags | Tags related to the institution. | | `theo` | Theoretical Price | The theoretical price of the option trade. | | `theta` | Theta | The theta of the option trade. | | `trade_ids` | array[string] | The component trade IDs for an aggregated trade. | | `underlying_price` | Underlying Price | The price of the underlying asset. | | `underlying_symbol` | Option Contract Underlying Symbol | The underlying symbol of the contract. | | `upstream_condition_detail` | Upstream Condition Detail | The upstream condition detail/trade code of the option trade. | | `vega` | Vega | The vega of the option trade. | | `volume` | Option Trade Volume | The amount of contracts traded till this point. | ## Example ### curl ```bash curl -X GET "https://api.unusualwhales.com/api/option-trades" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" ``` ### Python ```python 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 ```json { "data": [ { "underlying_symbol": "NVDA", "open_interest": 6016, "ask_vol": 2, "ewma_nbbo_bid": "21.45", "bid_vol": 1, "option_type": "call", "delta": "0.610546281537814", "full_name": "NVIDIA CORP", "ewma_nbbo_ask": "21.60", "multi_vol": 30, "industry_type": "Semiconductors", "implied_volatility": "0.604347250962543", "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", "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, "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" } ] } ```