# Hottest Chains

`GET` `https://api.unusualwhales.com/api/screener/option-contracts`

A contract screener endpoint to screen the market for contracts by a variety of filter options.

For an example of what can be build with this endpoint check out the [Hottest Contracts](https://unusualwhales.com/hottest-contracts?limit=100&hide_index_etf=true)
on UnusualWhales.

For real time streaming of the same data, subscribe to the `contract_screener` websocket channel, see [https://api.unusualwhales.com/docs/operations/PublicApi.SocketController.contract_screener](https://api.unusualwhales.com/docs/operations/PublicApi.SocketController.contract_screener).

NOTE: Contracts with a volume of less than 200 are not being returned


## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ticker_symbol` | Ticker | No | A comma separated list of tickers. To exclude certain tickers prefix the first ticker with a `-`. |
| `sectors[]` | Sectors | No | An array of 1 or more sectors. |
| `unusual` | boolean | No | Convenience preset that returns only "unusual" contracts by applying the contract-expressible subset of the [live options flow](https://unusualwhales.com/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 | No | The minimum stock price. |
| `max_underlying_price` | string | No | The maximum stock price. |
| `is_otm` | boolean | No | Only include contracts which are currently out of the money. |
| `is_itm` | boolean | No | 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 | No | 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 | No | The minimum days to expiry. |
| `max_dte` | integer | No | The maximum days to expiry. |
| `min_diff` | string | No | The minimum OTM diff of a contract. |
| `max_diff` | string | No | The maximum OTM diff of a contract. |
| `min_strike` | string | No | The minimum strike. |
| `max_strike` | string | No | The maximum strike. |
| `type` | OptionType | No | The option type to filter by if specified. |
| `expiry_dates[]` | Expiry dates | No | An array of 1 or more expiry dates. |
| `min_marketcap` | string | No | The minimum marketcap. |
| `max_marketcap` | string | No | The maximum marketcap. |
| `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_ticker_30_d_avg_volume` | integer | No | The minimum 30-day average stock volume for the underlying ticker. |
| `max_ticker_30_d_avg_volume` | integer | No | The maximum 30-day average stock volume for the underlying ticker. |
| `min_contract_30_d_avg_volume` | integer | No | The minimum 30-day average options contract volume for the underlying ticker. |
| `max_contract_30_d_avg_volume` | integer | No | The maximum 30-day average options contract volume for the underlying ticker. |
| `min_multileg_volume_ratio` | string | No | The minimum multi leg volume to contract volume ratio. |
| `max_multileg_volume_ratio` | string | No | The maximum multi leg volume to contract volume ratio. |
| `min_floor_volume_ratio` | string | No | The minimum floor volume to contract volume ratio. |
| `max_floor_volume_ratio` | string | No | The maximum floor volume to contract volume ratio. |
| `min_perc_change` | string | No | The minimum % price change of the contract to the previous day. Acceptable range: -1.00 to +inf. |
| `max_perc_change` | string | No | The maximum % price change of the contract to the previous day. Acceptable range: -1.00 to +inf. |
| `min_daily_perc_change` | string | No | The minimum intraday price change of the contract from open till now. |
| `max_daily_perc_change` | string | No | The maximum intraday price change for the contract since market open. |
| `min_premium` | string | No | The minimum premium on that contract. |
| `max_premium` | string | No | The maximum premium on that contract. |
| `min_avg_price` | string | No | The minimum average price of the contract. |
| `max_avg_price` | string | No | The maximum average price of the contract. |
| `min_volume_oi_ratio` | string | No | The minimum contract volume to open interest ratio. |
| `max_volume_oi_ratio` | string | No | The maximum contract volume to open interest ratio. |
| `min_open_interest` | integer | No | The minimum open interest on that contract. |
| `max_open_interest` | integer | No | The maximum open interest on that contract. |
| `min_floor_volume` | integer | No | The minimum floor volume on that contract. |
| `max_floor_volume` | integer | No | The maximum floor volume on that contract. |
| `vol_greater_oi` | boolean | No | Only include contracts where the volume is greater than the open interest. |
| `issue_types[]` | Issue types | No | An array of 1 or more issue types. |
| `min_ask_perc` | string | No | The minimum ask percentage of volume that transacted on the ask. |
| `max_ask_perc` | string | No | The maximum ask percentage of volume that transacted on the ask. |
| `min_bid_perc` | string | No | The minimum bid percentage of volume that transacted on the bid. |
| `max_bid_perc` | string | No | The maximum bid percentage of volume that transacted on the bid. |
| `min_skew_perc` | string | No | 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 | No | 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 | No | The minimum bull percentage. |
| `max_bull_perc` | string | No | The maximum bull percentage. |
| `min_bear_perc` | string | No | The minimum bear percentage. |
| `max_bear_perc` | string | No | The maximum bear percentage. |
| `min_bid_side_perc_7_day` | string | No | 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 | No | 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 | No | 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 | No | 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 | No | The minimum days of consecutive trading days where the open interest increased |
| `max_days_of_oi_increases` | integer | No | The maximum days of consecutive trading days where the open interest increased |
| `min_days_of_vol_greater_than_oi` | integer | No | The minimum days of consecutive days where volume was greater than open interest. |
| `max_days_of_vol_greater_than_oi` | integer | No | The maximum days of consecutive days where volume was greater than open interest. |
| `min_iv_perc` | string | No | The minimum implied volatility percentage. |
| `max_iv_perc` | string | No | The maximum implied volatility percentage. |
| `min_delta` | string | No | The minimum delta. Acceptable range: -1.00 to +1.00. |
| `max_delta` | string | No | The maximum delta. Acceptable range: -1.00 to +1.00. |
| `min_gamma` | string | No | The minimum gamma. Acceptable range: 0.00 to +inf. |
| `max_gamma` | string | No | The maximum gamma. Acceptable range: 0.00 to +inf. |
| `min_theta` | string | No | The minimum theta. Acceptable range: -inf to 0.00. |
| `max_theta` | string | No | The maximum theta. Acceptable range: -inf to 0.00. |
| `min_vega` | string | No | The minimum vega. Acceptable range: 0.00 to +inf. |
| `max_vega` | string | No | The maximum vega. Acceptable range: 0.00 to +inf. |
| `min_return_on_capital_perc` | string | No | The minimum return on capital percentage (ROC). |
| `max_return_on_capital_perc` | string | No | The maximum return on capital percentage (ROC). |
| `min_oi_change_perc` | string | No | The minimum open interest change percentage. Acceptable range: -1.00 to +inf. |
| `max_oi_change_perc` | string | No | The maximum open interest change percentage. Acceptable range: -1.00 to +inf. |
| `min_oi_change` | integer | No | The minimum open interest change as an absolute change. |
| `max_oi_change` | integer | No | The maximum open interest change as an absolute change. |
| `min_volume_ticker_vol_ratio` | string | No | 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 | No | 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 | No | The minimum sweep volume ratio. Acceptable range: 0.00 to 1.00. |
| `max_sweep_volume_ratio` | string | No | The maximum sweep volume ratio. Acceptable range: 0.00 to 1.00. |
| `min_from_low_perc` | string | No | The minimum percentage change of the current price from todays low. Acceptable range: -1.00 to +inf. |
| `max_from_low_perc` | string | No | The maximum percentage change of the current price from todays low. Acceptable range: -1.00 to +inf. |
| `min_from_high_perc` | string | No | The minimum percentage change of the current price from todays high. Acceptable range: -1.00 to +inf. |
| `max_from_high_perc` | string | No | The maximum percentage change of the current price from todays high. Acceptable range: -1.00 to +inf. |
| `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_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_transactions` | integer | No | The minimum number of transactions. |
| `max_transactions` | integer | No | The maximum number of transactions. |
| `min_close` | string | No | The minimum contract price (not underlying price). |
| `max_close` | string | No | The maximum contract price (not underlying price). |
| `order` | Screener contract order by field | No | The field to order by. |
| `order_direction` | OrderDirection | No | Whether to sort descending or ascending. Descending by default. |
| `limit` | Default 50, Max 250 Min 1 | No | How many items to return. Default: 50. Max: 250. Min: 1. |
| `page` | Page | No | Page number (use with limit). Starts on page 0. |
| `date` | Optional Market Date | No | A trading date in the format of YYYY-MM-DD.
This is optional and by default the last trading date.
 |
| `is_new` | boolean | No | Return only new option contracts |
| `opex_only` | boolean | No | Return only monthly option expirations |


## Response (200)

| Field | Type | Description |
|-------|------|-------------|
| `ask_side_volume` | Option Contract Ask Volume | The amount of volume that happened on the ask side.

Ask side is defined as (ask + bid) / 2 < fill price.
 |
| `avg_price` | Option Contract Avg Price | The volume weighted average fill price of the contract. |
| `bid_side_volume` | Option Contract Bid Volume | The amount of volume that happened on the bid side.

Bid side is defined as (ask + bid) / 2 > fill price.
 |
| `chain_prev_close` | Option Contract Previous Close Price | The previous trading day's contract price. |
| `close` | Option Contract Close | The last fill on the contract. |
| `cross_volume` | Option Contract Cross Volume | The amount of cross volume.
Cross volume consists of all transaction that have the cross trade code.
 |
| `er_time` | Stock Earnings time | The time when the earnings will be released. |
| `expiry` | Option Contract Expiry | The contract expiry date in ISO format. |
| `floor_volume` | Option Contract Floor Volume | The amount of floor volume.
Floor volume consists of all transaction that have the floor trade code.
 |
| `high` | Option Contract High | The highest fill on that contract. |
| `last_fill` | Option Contract Last Transaction Time | The last time there was a transaction for the given contract as UTC timestamp. |
| `low` | Option Contract Low | The lowest fill on that contract. |
| `mid_volume` | 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.
 |
| `multileg_volume` | 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.
 |
| `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_volume` | 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` | Option Contract Open | The first fill on that contract. |
| `open_interest` | Option Contract Open interest | The open interest for the contract. |
| `option_symbol` | Option Contract Symbol | 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` | Option Contract Option Type | The option type of the contract. |
| `premium` | Option Contract Premium | The total option premium. |
| `sector` | Market General Sector | The financial sector of the ticker. Empty if unknown or not applicable such as ETF/Index. |
| `stock_multi_leg_volume` | 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.
 |
| `stock_price` | Stock Close Price | The close stock price of the ticker. |
| `strike` | Option Contract Strike | The contract strike. |
| `sweep_volume` | Option Contract Sweep Volume | The amount of sweep volume.
Sweep volume consists of all transaction that have the sweep trade code.
 |
| `ticker_vol` | Stock Total Volume | The total amount of options volume for the given ticker. |
| `total_ask_changes` | Option Contract Total Ask Changes | The total count of changes to the NBBO ask during that day's trading session. |
| `total_bid_changes` | Option Contract Total Bid Changes | The total count of changes to the NBBO bid during that day's trading session. |
| `trades` | Option Contract Total Trades Count | The amount of transaction for this contract. |
| `volume` | Option Contract Volume | The contract volume. |


## Example

### curl

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

## Response Example

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