> ## Documentation Index > Fetch the complete documentation index at: https://api.unusualwhales.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > API requests use the base URL https://api.unusualwhales.com and require a bearer token in the `Authorization` header (`Authorization: Bearer `). Create and manage API tokens at https://unusualwhales.com/dashboard/api. > For live market data inside an AI tool, use the Unusual Whales MCP server at https://unusualwhales.com/public-api/mcp. > Instructions for agents using Unusual Whales tools: https://unusualwhales.com/skill.md # Hottest Chains > 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/websocket/contract-screener](https://api.unusualwhales.com/docs/websocket/contract-screener). NOTE: Contracts with a volume of less than 200 are not being returned ## OpenAPI ````yaml /openapi.yaml get /api/screener/option-contracts openapi: 3.0.0 info: description: > For API Support or any questions email: support@unusualwhales.com Documentation for the official [UnusualWhales](https://unusualwhales.com) api ## Startup Tier Building a product on our data? Get started immediately with our self-serve Startup tier at $750/mo — 500 req/min, 80K daily requests, 90-day lookback, and commercial use included. Annual plan available at $7,500/yr (2 months free) with 1,000 req/min and 10 concurrent requests for market-open bursts. [Start building →](https://unusualwhales.com/checkout?plan=enterprise_startup&interval=monthly) Need Kafka streaming? Our Startup + Kafka tier at $3,000/mo adds real-time Kafka cluster access. Annual plan available at $30,000/yr (2 months free) with the same 1,000 req/min burst allowance. [Start building →](https://unusualwhales.com/checkout?plan=enterprise_startup_kafka&interval=monthly) ## Enterprise/Professional Subscribers For custom enterprise pricing, redistribution licenses, or bespoke solutions, email [oskar@unusualwhales.com, enterprise@unusualwhales.com or nastja.petrovic@unusualwhales.com](mailto:oskar@unusualwhales.com?cc=enterprise@unusualwhales.com,nastja.petrovic@unusualwhales.com). ## Changelog # 2026.09.28 - The websocket documentation moved to [https://api.unusualwhales.com/docs/websocket](https://api.unusualwhales.com/docs/websocket), with one page per channel. REST endpoints that serve the same data as a websocket channel link to that channel's page. # 2026.09.21 - Added a new websocket channel [`stock_screener`](https://api.unusualwhales.com/docs/websocket/stock-screener). It streams the latest stock screener row of every ticker and is the live counterpart of [`/screener/stocks`](https://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.stock_screener). # 2026.09.12 - Added a new websocket channel [`ta_1d_live:{TICKER}`](https://api.unusualwhales.com/docs/websocket/technical-analysis-indicators). The channel streams technical-analysis indicator values (moving averages, RSI, MACD, Bollinger bands, ADX, Aroon, ATR, CCI, MFI, OBV, stochastics and Williams %R) computed on daily candles for one ticker. During regular trading hours it resends the day that is still forming as the price moves, so the newest message for a `date` replaces the ones before it. An indicator reads as `null` until enough daily history exists to compute it. The `1d` in the name is the candle interval and `live` means the values track the open session. # 2026.09.04 - Added new websocket channels [`quotes` and `quotes:{TICKER}`](https://api.unusualwhales.com/docs/websocket/stock-quotes). They stream the live best bid and ask - for every ticker at once, or for a single ticker - and are the live counterpart of [`/stock/:ticker/quote`](https://api.unusualwhales.com/docs/operations/PublicApi.StockQuoteController.show). # 2026.09.01 - Added a global [`greeks`](https://api.unusualwhales.com/docs/websocket/greeks) websocket channel. It streams the same per-contract option greeks as `greeks:`, but for every underlying at once. This is a high volume firehose - prefer the per-ticker channel unless you need the full tape. # 2026.08.30 - MCP now advertises build guidance: `instructions` on initialize; builder prompts `build_dashboard_app`, `build_confluence_alert`, `build_trading_bot`, `build_data_stream`, `start_from_example`, and `setup_api_project`; tools `get_build_recipe` and `get_api_examples` (scripts from [https://github.com/unusual-whales/api-examples](https://github.com/unusual-whales/api-examples)); and `resources/list` / `resources/templates/list` / `resources/read` for playbooks and example files. # 2026.08.28 - Added a new websocket channel [`risk_reversal_skew`](https://api.unusualwhales.com/docs/websocket/risk-reversal-skew). The channel streams live 25- and 10-delta risk reversal skew (put implied volatility minus call implied volatility) per expiry across every ticker, the live counterpart of [`/stock/:ticker/historical-risk-reversal-skew`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.historical_risk_reversal_skew). The channel is global only; there is no per-ticker variant. # 2026.08.22 - Updated [`/stock/:ticker/gex-levels`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.gex_levels) to derive its levels from directionalized volume instead of a cumulative total over the static open-interest snapshot. - Added `date`, `time`, `source`, and `nearby_flips` to the [`/stock/:ticker/gex-levels`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.gex_levels) response. `nearby_flips` lists the five zero-gamma crossings nearest spot, ordered by distance from it. `time` is when the underlying exposure snapshot was calculated. # 2026.08.21 - Added new websocket channels [`interpolated_iv` and `interpolated_iv:TICKER`](https://api.unusualwhales.com/docs/websocket/interpolated-iv). The channels stream interpolated implied volatility and expected moves at fixed horizons (1-365 trading days), the live counterpart of [`/stock/:ticker/interpolated-iv`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.interpolated_iv). - Added new websocket channels [`iv_term_structure` and `iv_term_structure:TICKER`](https://api.unusualwhales.com/docs/websocket/iv-term-structure). The channels stream ATM implied volatility and expected moves per real option expiry — the raw entries behind `interpolated_iv` — the live counterpart of [`/stock/:ticker/volatility/term-structure`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.implied_volatility_term_structure). # 2026.04.30 Added a new advanced-tier endpoint group. All routes below require API Advanced, Enterprise Startup, Enterprise Startup + Kafka, or Enterprise tier. ### Company fundamentals - Added [`/companies/:ticker/profile`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.profile) for sector, industry, market cap, P/E, EPS, dividend yield, analyst targets, 52-week range, moving averages, and the full analyst rating breakdown. - Added [`/companies/:ticker/dividends`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.dividends) for historical dividend events. - Added [`/companies/:ticker/splits`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.splits) for historical stock-split events. - Added [`/companies/:ticker/earnings-estimates`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.earnings_estimates) for forward analyst earnings and revenue estimates by quarter and year. - Added [`/companies/:ticker/transcripts/:quarter`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.transcript) for earnings-call transcripts with speakers, statements, and per-statement sentiment. - Added [`/companies/listings`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.listings) for the master list of US-traded securities (active or delisted). ### Macro - Added [`/commodities/:name`](https://api.unusualwhales.com/docs/operations/PublicApi.CommoditiesController.show) for long-running price series across WTI, Brent, natural gas, copper, aluminum, wheat, corn, cotton, sugar, coffee, and the global commodities index. - Added [`/economy/:indicator`](https://api.unusualwhales.com/docs/operations/PublicApi.EconomyController.show) for US economic indicator series (GDP, GDP per capita, treasury yield, fed funds rate, CPI, inflation, retail sales, durables, unemployment, payrolls). ### Forex - Added [`/forex/rate`](https://api.unusualwhales.com/docs/operations/PublicApi.ForexController.rate) for live FX spot rates with bid and ask. - Added [`/forex/intraday`](https://api.unusualwhales.com/docs/operations/PublicApi.ForexController.intraday) for 1min through 60min FX OHLC bars. - Added [`/forex/history`](https://api.unusualwhales.com/docs/operations/PublicApi.ForexController.history) for daily, weekly, and monthly FX OHLC bars. ### Digital currencies - Added [`/digital-currencies/intraday`](https://api.unusualwhales.com/docs/operations/PublicApi.DigitalCurrenciesController.intraday) for intraday OHLC bars priced against a fiat market. - Added [`/digital-currencies/history`](https://api.unusualwhales.com/docs/operations/PublicApi.DigitalCurrenciesController.history) for daily, weekly, and monthly OHLC bars. ### Market intel and analytics - Added [`/market/movers`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.movers) for pre-ranked top gainers, top losers, and most actively traded US tickers. - Added [`/calendar/ipo`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.ipo_calendar) for upcoming IPOs over the next 3 months. - Added [`/analytics/window`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.analytics_window) for fixed-window statistical analytics across baskets of tickers (mean, stddev, correlation, drawdown, autocorrelation, covariance, and more). - Added [`/analytics/sliding`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.analytics_sliding) for sliding-window statistical analytics. ### Congressional unusual trades (scope `unusual-trades`) - Added [`/congress/unusual-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.recent) for unusual congressional trades filtered by reason tag (committee_conflict, first_person_to_trade, low_marketcap, unusual_industry, unusually_large_trade, fec_donation_conflict). - Added [`/congress/unusual-trades/by-tickers`](https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.by_tickers) with ticker, transaction type, date range, and politician filters. - Added [`/congress/unusual-trades/chart-data`](https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.chart_data) returning trade points with SPY benchmark closes. - Added [`/congress/unusual-trades/stats`](https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.stats) for aggregate overview statistics. ### Private markets (scope `private-markets`) - Added [`/private-markets/companies`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.companies) for the full Nasdaq Private Markets company list with sector and name filters. - Added [`/private-markets/companies/:npm_ticker`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.company_profile) for the company profile with latest price, total funding, and investor count. - Added [`/private-markets/companies/:npm_ticker/funding`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.funding) for funding round history. - Added [`/private-markets/companies/:npm_ticker/investors`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.investors) for disclosed investors. - Added [`/private-markets/companies/:npm_ticker/management`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.management) for disclosed leadership. - Added [`/private-markets/companies/:npm_ticker/pricing`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.pricing) for historical implied per-share pricing. - Added [`/private-markets/investors`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.top_investors) for top investors ranked by distinct company count. - Added [`/private-markets/investors/:name`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.investor_profile) for an investor's portfolio. - Added [`/private-markets/search`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.search) for substring search across companies and investors. ### MCP - Added 5 premium MCP catalogs covering the new endpoints: `uw_companies_extras`, `uw_macro`, `uw_forex`, `uw_digital_currencies`, `uw_intel`. Plus `uw_unusual_trades` and `uw_private_markets` for the scope-gated catalogs above. - Premium MCP catalogs and individual premium commands (`uw_stock.ownership`, `uw_flow.full_tape`, `uw_politicians`) are now hidden by default. Operators opt in via `UW_ENABLE_PREMIUM_TOOLS=true` (all on) or `UW_PREMIUM_TOOLS=uw_companies_extras,uw_macro,...` (per-tool allowlist supporting `` or `.` form). # 2026.04.29 - Added MCP tool `get_short_volume_ratio_by_exchange` for [`/shorts/:ticker/volumes-by-exchange`](https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_volume_by_exchange) data. - Added MCP tool `get_short_volume_ratio_by_ticker` for [`/shorts/:ticker/volume-and-ratio`](https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_volume_and_ratio) data. - Added MCP tool `get_short_screener` for [`/short_screener`](https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_screener) - Added MCP tool `get_short_data_by_ticker` for [`/shorts/:ticker/data`](https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_data) # 2026.04.14 - Enhanced MCP [`/api/mcp`](https://api.unusualwhales.com/docs) `tools/call` validation to reject unsupported arguments, missing required arguments, and invalid enum values before tool execution. - MCP tool errors now include retry guidance telling clients to inspect `tools/list` `inputSchema` and retry with supported arguments. # 2026.03.02 - Added authenticated MCP endpoint [`/api/mcp`](https://api.unusualwhales.com/docs) to expose existing AI tools to API subscribers using the same `Authorization: Bearer ` flow. - Supports MCP `initialize`, `tools/list`, and `tools/call` methods backed by the existing internal tool registry and execution pipeline. # 2026.01.20 - Updated interest-float endpoint with new version and deprecated old version - [`/shorts/:ticker/interest-float/v2`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_interest_and_float_v2) - Added interest-float search screener endpoint - [`/short_screener`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_screener) # 2025.09.23 - Added new websocket channels [`lit_trades`](https://api.unusualwhales.com/docs/websocket/lit-trades) and [`off_lit_trades`](https://api.unusualwhales.com/docs/websocket/off-lit-trades) to stream live lit (exchange-based) and off-lit (dark pool) trades respectively. # 2025.09.22 - Added `newer_than` and `older_than` time filtering parameters to [`/alerts`](https://api.unusualwhales.com/docs#/operations/PublicApi.AlertsController.alerts) endpoint with 14-day maximum lookback period for custom alerts queries # 2025.08.20 - Added [`/market/top-net-impact`](https://api.unusualwhales.com/docs#/operations/PublicApi.MarketController.top_net_impact) endpoint to get the top tickers by net premium (split between bullish and bearish). Supports filtering by `issue_types[]`, `date`, and `limit` (default 20, max 100). # 2025.06.18 - Added [`/market/:sector/sector-tide`](https://api.unusualwhales.com/docs#/operations/PublicApi.MarketController.sec_indst) endpoint to get the market tide for a specific sector # 2025.06.02 - Added [`/stock/:ticker/interpolated-iv`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.interpolated_iv) endpoint to get the interpolated iv for various days # 2025.05.29 - Added [`/option-contract/:id/volume-profile`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionContractController.volume_profile) endpoint to get the volume profile of an option contract (volume by fill price) # 2025.05.23 - Added [`/option-contract/:id/intraday`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionContractController.intraday) endpoint to get the volume, premium & OHLC for a contract in 1min ticks for a given trading day # 2025.05.07 - Added `prev_close_price` field to [`/stock/:ticker/stock-state`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.last_stock_state) endpoint to provide the previous close price. # 2025.04.30 - Enhanced [`/option-trades/full-tape/{date}`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionTradeController.full_tape) to allow users with `websocket` scope to access the last two trading days of data # 2025.04.23 - Added [`/net-flow/expiry`](https://api.unusualwhales.com/docs#/operations/PublicApi.NetFlowController.expiry) endpoint to track net premium flow by tide type, moneyness, and expiration categories. This powers charts like those found on the [zero-DTE dashboard](https://unusualwhales.com/zero-dte) # 2025.04.08 - Enhanced [`/market/correlations`](https://api.unusualwhales.com/docs#/operations/PublicApi.MarketController.correlations) endpoint with new date filtering options: `start_date` and `end_date` parameters to specify custom date ranges, complementing the existing `interval` parameter # 2025.03.23 - Updated [`/stock/{ticker}/net-prem-ticks`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.net_prem_ticks) endpoint to include `call_volume`, `put_volume`, `call_volume_bid_side`, `put_volume_bid_side`, `call_volume_ask_side`, `put_volume_ask_side` & `net_delta`. # 2025.03.10 - Added [`/news/headlines`](https://api.unusualwhales.com/docs#/operations/PublicApi.NewsController.headlines) endpoint to access financial news headlines with filtering capabilities - Added Shorts API endpoints: - [`/shorts/:ticker/data`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_data) - [`/shorts/:ticker/volumes-by-exchange`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_volume_by_exchange) - [`/shorts/:ticker/ftds`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.failures_to_deliver) - [`/shorts/:ticker/interest-float`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_interest_and_float) - [`/shorts/:ticker/volume-and-ratio`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_volume_and_ratio) # 2025.02.19 - The endpoint [`/stock/:ticker/spot-exposures/:expiry/strike`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.spot_exposures_by_strike_expiry) has been deprecated and been replaced by [`/stock/:ticker/spot-exposures/expiry-strike`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.spot_exposures_by_strike_expiry_v2) To migrate over replace all your `/api/stock/:ticker/spot-exposures/:expiry/strike` calls with `/api/stock/:ticker/spot-exposures/expiry-strike?expirations[]=expiry` # 2025.02.13 - The endpoint `/congress/recent-reports` has been removed as it returns the same data as `/congress/recent-trades`. # 2025.02.05 - Enhanced [`/market/fda-calendar`](https://api.unusualwhales.com/docs#/operations/PublicApi.MarketController.fda_calendar) with better FDA data, additional fields (notes, outcomes, sources), and filtering by company metrics # 2025.02.03 - Updated dark pool/off lit endpoints to allow filtering for size, premium & consolidated volume # 2025.01.22 - Added [`gex_strike_expiry:`](https://api.unusualwhales.com/docs/websocket/gex) channel to the websocket - Added `call_option_symbol` & `put_option_symbol` to [`/stock/{ticker}/greeks`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.greeks) # 2025.01.16 - Added [`/stock/:ticker/spot-exposures/:expiry/strike`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.spot_exposures_by_strike_expiry) # 2024.12.11 - Added [`/alerts/configuration`](https://api.unusualwhales.com/docs#/operations/PublicApi.AlertsController.configs) - Added [`/alerts`](https://api.unusualwhales.com/docs#/operations/PublicApi.AlertsController.alerts) This allows one to grab all the alerts that have been triggerd for any alert that one has configured. With an existing unusualwhales account you can view and configure alerts directly on the [website](https://unusualwhales.com/custom-alerts) # 2024.12.02 - Added [`/stock/:ticker/oi-per-strike`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.oi_per_strike) - Added [`/stock/:ticker/oi-per-expiry`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.oi_per_expiry) # 2024.11.19 - Improved all earnings endpoint # 2024.11.09 - Added `perc_of_total` & `perc_of_share_value` to [`/institution/:name/holdings`](https://api.unusualwhales.com/docs#/operations/PublicApi.InstitutionController.holdings) # 2024.10.30 - Added [`/stock/:ticker/nope`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.nope) # 2024.10.28 - Added [`/group-flow/:flow_group/greek-flow`](https://api.unusualwhales.com/docs#/operations/PublicApi.GroupFlowController.greek_flow) - Added [`/group-flow/:flow_group/greek-flow/:expiry`](https://api.unusualwhales.com/docs#/operations/PublicApi.GroupFlowController.greek_flow_expiry) - Added [`/stock/:ticker/greek-flow`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.greek_flow) - Added [`/stock/:ticker/greek-flow/:epxiry`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.greek_flow_expiry) # 2024.10.16 - Added etf inflow & outflow endpoint [`/etfs/:ticker/in_outflow`](PublicApi.EtfController.in_outflow) # 2024.10.15 - Added institutional latest filings endpoint [`/institution/latest_filings`](PublicApi.InstitutionController.latest_filings) - Added institutional ownership endpoint [`/institution/:ticker/ownership`](PublicApi.InstitutionController.ownership) # 2024.10.14 - Added 2 new fields: `days_of_oi_increases` & `days_of_vol_greater_than_oi` to [`/market/oi-change`](PublicApi.MarketController.oi_change) ``` days_of_oi_increases: The number of consecutive days that the open interest has increased for this contract. If on any day the open interest decreases or does not change the count will reset. days_of_vol_greater_than_oi: The number of consecutive days that the volume has been greater than the open interest for this contract. If on any day the volume is less than or equal to the open interest the count will reset. ```
# 2024.10.10 - Added institutional activity endpoint [`/institution/:name/activity`](PublicApi.InstitutionController.activity) # 2024.10.09 - Added institutional list endpoint [`institutions`](PublicApi.InstitutionController.list) - Added institutional holdings endpoint [`/institution/:name/holdings`](PublicApi.InstitutionController.holdings) - Added institutional sector exposure endpoint [`/institution/:name/sectors`](PublicApi.InstitutionController.sectors) # 2024.08.01 - Added new flow per strike intraday endpoint [`/stock/:ticker/flow-per-strike-intraday`](PublicApi.TickerController.flow_per_strike_intraday) # 2024.07.11 - Added new correlation endpoint [`/market/correlations?tickers=SPY,QQQ,JPM,BAC`](PublicApi.MarketController.correlations) # 2024.05.30 - Added the ability to filter [`/darkpool/:ticker`](PublicApi.DarkPoolController.darkpool_ticker) by timestamps through the two new query parameters `older_than` and `newer_than` # 2024.05.21 - Added directionalized volume fields to [`/stock/:ticker/spot-exposures`](PublicApi.TickerController.spot_exposures_one_minute) and [`/stock/:ticker/spot-exposures/strike`](PublicApi.TickerController.spot_exposures_by_strike) # 2024.05.17 - Added the channels `gex:TICKER` & `gex_strike:TICKER` to the [websocket](https://api.unusualwhales.com/docs/websocket) # 2024.05.07 - Added the ability to filter [`/option-trades/flow-alerts`](PublicApi.OptionTradeController.flow_alerts) by timestamps through the two new query parameters `older_than` and `newer_than` # 2024.05.06 - Added endpoint [`/stock/:ticker/stock-state`](PublicApi.TickerController.last_stock_state) to retrieve the last stock price & volume - Added endpoint [`/stock/:ticker/volatility/realized`](PublicApi.TickerController.realized_volatility) to retrieve a stock's realized volatility # 2024.05.03 - The data returned by /stock/:ticker/option-contracts has been limited to 500 results # 2024.05.02 - Added endpoint [`/market/:ticker/etf-tide`](PublicApi.MarketController.etf_tide) # 2024.05.01 - Added endpoint [`/stock/:ticker/spot-exposures/strike`](PublicApi.TickerController.spot_exposures_by_strike) - Added new channel [`price:TICKER`](https://api.unusualwhales.com/docs/websocket) to the websocket. The channel will push live price updates for the given ticker. # 2024.04.25 - Added endpoint [`/stock/:ticker/greek-exposure/strike`](PublicApi.TickerController.greek_exposure_by_strike) - Added endpoint [`/stock/:ticker/greek-exposure/expiry`](PublicApi.TickerController.greek_exposure_by_expiry) - Added endpoint [`/stock/:ticker/greek-exposure/strike-expiry`](PublicApi.TickerController.greek_exposure_by_strike_expiry) # 2024.03.28 - Fixed field name volatility -> risk_reversal for endpoint [`/stock/:ticker/historical_risk_reversal_skew`](PublicApi.TickerController.historical_risk_reversal_skew) # 2024.03.26 - Added endpoint [`/stock/:ticker/greeks`](PublicApi.TickerController.greeks) - Added endpoint [`/stock/:ticker/historical_risk_reversal_skew`](PublicApi.TickerController.historical_risk_reversal_skew) # 2024.03.23 - BREAKING CHANGE: Previously `/option-contract/:id/flow` would return the data as a json list. This has been now changed so that the endpoint returns the data in the format `{"data": [], "date": "2024-03-22"}`. Secondly, the endpoint will now only return data for a single trading day. # 2024.03.06 - Added endpoint [`/option-trades/flow-alerts`](PublicApi.OptionTradeController.flow_alerts) - Added flow-alerts streaming to the WebSocket. # 2024.03.04 - Added endpoint [`/stock/:ticker/max-pain`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.max_pain) # 2024.02.16 - Added new endpoint section [`Seasonality`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.market_seasonality) with new endpoints: - [`/seasonality/market`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.market_seasonality) - [`/seasonality/:month/performers`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.month_performers) - [`/seasonality/:ticker/monthly`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.monthly) - [`/seasonality/:ticker/year-month`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.year_month) # 2024.02.07 - Added endpoints [`/stock/:ticker/expiry-breakdown`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionContractController.expiry_breakdown) & [`/stock/:ticker/option-contracts`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionContractController.option_contracts). These 2 endpoints allow access to the data located here: [https://unusualwhales.com/stock/AAPL/option-chains](https://unusualwhales.com/stock/AAPL/option-chains) title: UnusualWhales Api version: '1.0' servers: - url: https://api.unusualwhales.com variables: {} security: - authorization: [] tags: [] paths: /api/screener/option-contracts: get: tags: - screener summary: Hottest Chains description: > 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/websocket/contract-screener](https://api.unusualwhales.com/docs/websocket/contract-screener). NOTE: Contracts with a volume of less than 200 are not being returned operationId: PublicApi.ScreenerController.contract_screener parameters: - description: '' in: query name: ticker_symbol required: false schema: $ref: '#/components/schemas/Ticker' - description: '' in: query name: sectors[] required: false schema: $ref: '#/components/schemas/Sectors' - description: >- 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. in: query name: unusual required: false schema: type: boolean - description: The minimum stock price. example: '5.23' in: query name: min_underlying_price required: false schema: type: string - description: The maximum stock price. example: '10.53' in: query name: max_underlying_price required: false schema: type: string - description: Only include contracts which are currently out of the money. in: query name: is_otm required: false schema: type: boolean - description: >- 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. in: query name: is_itm required: false schema: type: boolean - description: >- 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. in: query name: exclude_ex_div_ticker required: false schema: type: boolean - description: The minimum days to expiry. example: '1' in: query name: min_dte required: false schema: type: integer - description: The maximum days to expiry. example: '3' in: query name: max_dte required: false schema: type: integer - description: The minimum OTM diff of a contract. example: '0.53' in: query name: min_diff required: false schema: type: string - description: The maximum OTM diff of a contract. example: '1.34' in: query name: max_diff required: false schema: type: string - description: The minimum strike. example: '120.5' in: query name: min_strike required: false schema: type: string - description: The maximum strike. example: '1200' in: query name: max_strike required: false schema: type: string - description: '' in: query name: type required: false schema: $ref: '#/components/schemas/OptionType' - description: '' in: query name: expiry_dates[] required: false schema: $ref: '#/components/schemas/Expiry_dates' - description: The minimum marketcap. example: '1000000' in: query name: min_marketcap required: false schema: type: string - description: The maximum marketcap. example: '250000000' in: query name: max_marketcap required: false schema: type: string - description: '' in: query name: min_volume required: false schema: $ref: '#/components/schemas/Min_Contract_Volume' - description: '' in: query name: max_volume required: false schema: $ref: '#/components/schemas/Max_Contract_Volume' - description: The minimum 30-day average stock volume for the underlying ticker. example: '1500000' in: query name: min_ticker_30_d_avg_volume required: false schema: type: integer - description: The maximum 30-day average stock volume for the underlying ticker. example: '50000000' in: query name: max_ticker_30_d_avg_volume required: false schema: type: integer - description: >- The minimum 30-day average options contract volume for the underlying ticker. example: '500' in: query name: min_contract_30_d_avg_volume required: false schema: type: integer - description: >- The maximum 30-day average options contract volume for the underlying ticker. example: '10000' in: query name: max_contract_30_d_avg_volume required: false schema: type: integer - description: The minimum multi leg volume to contract volume ratio. example: '0.3' in: query name: min_multileg_volume_ratio required: false schema: type: string - description: The maximum multi leg volume to contract volume ratio. example: '0.5' in: query name: max_multileg_volume_ratio required: false schema: type: string - description: The minimum floor volume to contract volume ratio. example: '0.2' in: query name: min_floor_volume_ratio required: false schema: type: string - description: The maximum floor volume to contract volume ratio. example: '0.45' in: query name: max_floor_volume_ratio required: false schema: type: string - description: >- The minimum % price change of the contract to the previous day. Acceptable range: -1.00 to +inf. example: '0.5' in: query name: min_perc_change required: false schema: type: string - description: >- The maximum % price change of the contract to the previous day. Acceptable range: -1.00 to +inf. example: '0.68' in: query name: max_perc_change required: false schema: type: string - description: >- The minimum intraday price change of the contract from open till now. example: '0.2' in: query name: min_daily_perc_change required: false schema: type: string - description: >- The maximum intraday price change for the contract since market open. example: '0.6' in: query name: max_daily_perc_change required: false schema: type: string - description: The minimum premium on that contract. example: '12500.5' in: query name: min_premium required: false schema: type: string - description: The maximum premium on that contract. example: '53100.32' in: query name: max_premium required: false schema: type: string - description: The minimum average price of the contract. example: '1.50' in: query name: min_avg_price required: false schema: type: string - description: The maximum average price of the contract. example: '25.00' in: query name: max_avg_price required: false schema: type: string - description: The minimum contract volume to open interest ratio. example: '0.32' in: query name: min_volume_oi_ratio required: false schema: type: string - description: The maximum contract volume to open interest ratio. example: '1.58' in: query name: max_volume_oi_ratio required: false schema: type: string - description: The minimum open interest on that contract. example: '12300' in: query name: min_open_interest required: false schema: type: integer - description: The maximum open interest on that contract. example: '55600' in: query name: max_open_interest required: false schema: type: integer - description: The minimum floor volume on that contract. example: '12300' in: query name: min_floor_volume required: false schema: type: integer - description: The maximum floor volume on that contract. example: '55800' in: query name: max_floor_volume required: false schema: type: integer - description: >- Only include contracts where the volume is greater than the open interest. in: query name: vol_greater_oi required: false schema: type: boolean - description: '' in: query name: issue_types[] required: false schema: $ref: '#/components/schemas/Issue_types' - description: The minimum ask percentage of volume that transacted on the ask. example: '0.19' in: query name: min_ask_perc required: false schema: type: string - description: The maximum ask percentage of volume that transacted on the ask. example: '0.45' in: query name: max_ask_perc required: false schema: type: string - description: The minimum bid percentage of volume that transacted on the bid. example: '0.19' in: query name: min_bid_perc required: false schema: type: string - description: The maximum bid percentage of volume that transacted on the bid. example: '0.45' in: query name: max_bid_perc required: false schema: type: string - description: >- 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 example: '0.19' in: query name: min_skew_perc required: false schema: type: string - description: >- 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 example: '0.45' in: query name: max_skew_perc required: false schema: type: string - description: The minimum bull percentage. example: '0.19' in: query name: min_bull_perc required: false schema: type: string - description: The maximum bull percentage. example: '0.45' in: query name: max_bull_perc required: false schema: type: string - description: The minimum bear percentage. example: '0.19' in: query name: min_bear_perc required: false schema: type: string - description: The maximum bear percentage. example: '0.45' in: query name: max_bear_perc required: false schema: type: string - description: >- The minimum percentage of days over the last 7 days where the contract traded primarily on the bid side example: '0.19' in: query name: min_bid_side_perc_7_day required: false schema: type: string - description: >- The maximum percentage of days over the last 7 days where the contract traded primarily on the bid side example: '0.45' in: query name: max_bid_side_perc_7_day required: false schema: type: string - description: >- The minimum percentage of days over the last 7 days where the contract traded primarily on the ask side example: '0.19' in: query name: min_ask_side_perc_7_day required: false schema: type: string - description: >- The maximum percentage of days over the last 7 days where the contract traded primarily on the ask side example: '0.45' in: query name: max_ask_side_perc_7_day required: false schema: type: string - description: >- The minimum days of consecutive trading days where the open interest increased example: '3' in: query name: min_days_of_oi_increases required: false schema: type: integer - description: >- The maximum days of consecutive trading days where the open interest increased example: '10' in: query name: max_days_of_oi_increases required: false schema: type: integer - description: >- The minimum days of consecutive days where volume was greater than open interest. example: '2' in: query name: min_days_of_vol_greater_than_oi required: false schema: type: integer - description: >- The maximum days of consecutive days where volume was greater than open interest. example: '7' in: query name: max_days_of_vol_greater_than_oi required: false schema: type: integer - description: The minimum implied volatility percentage. example: '0.19' in: query name: min_iv_perc required: false schema: type: string - description: The maximum implied volatility percentage. example: '0.45' in: query name: max_iv_perc required: false schema: type: string - description: 'The minimum delta. Acceptable range: -1.00 to +1.00.' example: '-0.50' in: query name: min_delta required: false schema: type: string - description: 'The maximum delta. Acceptable range: -1.00 to +1.00.' example: '0.80' in: query name: max_delta required: false schema: type: string - description: 'The minimum gamma. Acceptable range: 0.00 to +inf.' example: '0.01' in: query name: min_gamma required: false schema: type: string - description: 'The maximum gamma. Acceptable range: 0.00 to +inf.' example: '0.15' in: query name: max_gamma required: false schema: type: string - description: 'The minimum theta. Acceptable range: -inf to 0.00.' example: '-0.10' in: query name: min_theta required: false schema: type: string - description: 'The maximum theta. Acceptable range: -inf to 0.00.' example: '-0.01' in: query name: max_theta required: false schema: type: string - description: 'The minimum vega. Acceptable range: 0.00 to +inf.' example: '0.05' in: query name: min_vega required: false schema: type: string - description: 'The maximum vega. Acceptable range: 0.00 to +inf.' example: '0.25' in: query name: max_vega required: false schema: type: string - description: The minimum return on capital percentage (ROC). example: '0.19' in: query name: min_return_on_capital_perc required: false schema: type: string - description: The maximum return on capital percentage (ROC). example: '0.45' in: query name: max_return_on_capital_perc required: false schema: type: string - description: >- The minimum open interest change percentage. Acceptable range: -1.00 to +inf. example: '-0.25' in: query name: min_oi_change_perc required: false schema: type: string - description: >- The maximum open interest change percentage. Acceptable range: -1.00 to +inf. example: '0.50' in: query name: max_oi_change_perc required: false schema: type: string - description: The minimum open interest change as an absolute change. example: '-1000' in: query name: min_oi_change required: false schema: type: integer - description: The maximum open interest change as an absolute change. example: '5000' in: query name: max_oi_change required: false schema: type: integer - description: >- The minimum ratio of contract volume to total option volume of the underlying. Acceptable range: 0.00 to 1.00. example: '0.25' in: query name: min_volume_ticker_vol_ratio required: false schema: type: string - description: >- The maximum ratio of contract volume to total option volume of the underlying. Acceptable range: 0.00 to 1.00. example: '0.85' in: query name: max_volume_ticker_vol_ratio required: false schema: type: string - description: 'The minimum sweep volume ratio. Acceptable range: 0.00 to 1.00.' example: '0.15' in: query name: min_sweep_volume_ratio required: false schema: type: string - description: 'The maximum sweep volume ratio. Acceptable range: 0.00 to 1.00.' example: '0.75' in: query name: max_sweep_volume_ratio required: false schema: type: string - description: >- The minimum percentage change of the current price from todays low. Acceptable range: -1.00 to +inf. example: '0.19' in: query name: min_from_low_perc required: false schema: type: string - description: >- The maximum percentage change of the current price from todays low. Acceptable range: -1.00 to +inf. example: '0.45' in: query name: max_from_low_perc required: false schema: type: string - description: >- The minimum percentage change of the current price from todays high. Acceptable range: -1.00 to +inf. example: '0.19' in: query name: min_from_high_perc required: false schema: type: string - description: >- The maximum percentage change of the current price from todays high. Acceptable range: -1.00 to +inf. example: '0.45' in: query name: max_from_high_perc required: false schema: type: string - description: '' in: query name: min_earnings_dte required: false schema: $ref: '#/components/schemas/Min_Earnings_DTE' - description: '' in: query name: max_earnings_dte required: false schema: $ref: '#/components/schemas/Max_Earnings_DTE' - description: '' in: query name: min_days_between_expiry_and_earnings required: false schema: $ref: '#/components/schemas/MinDaysBetweenExpiryAndEarnings' - description: '' in: query name: max_days_between_expiry_and_earnings required: false schema: $ref: '#/components/schemas/MaxDaysBetweenExpiryAndEarnings' - description: The minimum number of transactions. example: '10' in: query name: min_transactions required: false schema: type: integer - description: The maximum number of transactions. example: '500' in: query name: max_transactions required: false schema: type: integer - description: The minimum contract price (not underlying price). example: '1.50' in: query name: min_close required: false schema: type: string - description: The maximum contract price (not underlying price). example: '25.00' in: query name: max_close required: false schema: type: string - description: '' in: query name: order required: false schema: $ref: '#/components/schemas/Screener_contract_order_by_field' - description: '' in: query name: order_direction required: false schema: $ref: '#/components/schemas/OrderDirection' - description: '' in: query name: limit required: false schema: $ref: '#/components/schemas/Default_50_Max_250_Min_1' - description: '' in: query name: page required: false schema: $ref: '#/components/schemas/Page' - description: '' in: query name: date required: false schema: $ref: '#/components/schemas/Optional_Market_Date' - description: Return only new option contracts example: 'true' in: query name: is_new required: false schema: type: boolean - description: Return only monthly option expirations example: 'true' in: query name: opex_only required: false schema: type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/Option_Contract_Screener_response.' description: '' '401': content: application/json: schema: $ref: '#/components/schemas/Authentication_Error' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/Forbidden_Error' description: Forbidden '422': content: application/json: schema: $ref: '#/components/schemas/Error_Message' description: Unprocessable Entity '500': content: text/plain: schema: $ref: >- #/components/schemas/Error_Message_on_an_internal_server_error. description: Internal Server Error callbacks: {} components: schemas: Ticker: description: >- A comma separated list of tickers. To exclude certain tickers prefix the first ticker with a `-`. example: AAPL,INTC title: Ticker type: string Sectors: description: An array of 1 or more sectors. example: - Consumer Cyclical - Technology - Utilities items: $ref: '#/components/schemas/Single_sector' title: Sectors type: array OptionType: description: The option type to filter by if specified. enum: - call - Call - put - Put title: OptionType type: string Expiry_dates: description: An array of 1 or more expiry dates. example: - '2024-02-02T00:00:00.000Z' - '2024-01-26T00:00:00.000Z' items: $ref: '#/components/schemas/Single_expiry_date' title: Expiry dates type: array Min_Contract_Volume: description: 'The minimum volume on the option contract. Min: 0.' example: 12300 minimum: 0 title: Min Contract Volume type: integer Max_Contract_Volume: description: 'The maximum volume on the option contract. Min: 0.' example: 55600 minimum: 0 title: Max Contract Volume type: integer Issue_types: description: An array of 1 or more issue types. example: - Common Stock - Index items: $ref: '#/components/schemas/Single_issue_type' title: Issue types type: array Min_Earnings_DTE: description: The minimum days until the next earnings report. example: 5 title: Min Earnings DTE type: integer Max_Earnings_DTE: description: The maximum days until the next earnings report. example: 30 title: Max Earnings DTE type: integer MinDaysBetweenExpiryAndEarnings: description: >- 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 title: MinDaysBetweenExpiryAndEarnings type: integer MaxDaysBetweenExpiryAndEarnings: description: >- 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 title: MaxDaysBetweenExpiryAndEarnings type: integer Screener_contract_order_by_field: description: The field to order by. enum: - 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 title: Screener contract order by field type: string OrderDirection: default: desc description: Whether to sort descending or ascending. Descending by default. enum: - desc - asc example: asc title: OrderDirection type: string Default_50_Max_250_Min_1: default: 1 description: 'How many items to return. Default: 50. Max: 250. Min: 1.' example: 10 maximum: 250 minimum: 1 title: Default 50, Max 250 Min 1 type: integer Page: description: Page number (use with limit). Starts on page 0. example: 1 title: Page type: integer Optional_Market_Date: description: | 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' title: Optional Market Date type: string Option_Contract_Screener_response.: description: '' example: 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 properties: ask_side_volume: $ref: '#/components/schemas/Option_Contract_Ask_Volume' avg_price: $ref: '#/components/schemas/Option_Contract_Avg_Price' bid_side_volume: $ref: '#/components/schemas/Option_Contract_Bid_Volume' chain_prev_close: $ref: '#/components/schemas/Option_Contract_Previous_Close_Price' close: $ref: '#/components/schemas/Option_Contract_Close' cross_volume: $ref: '#/components/schemas/Option_Contract_Cross_Volume' er_time: $ref: '#/components/schemas/Stock_Earnings_time' expiry: $ref: '#/components/schemas/Option_Contract_Expiry' floor_volume: $ref: '#/components/schemas/Option_Contract_Floor_Volume' high: $ref: '#/components/schemas/Option_Contract_High' last_fill: $ref: '#/components/schemas/Option_Contract_Last_Transaction_Time' low: $ref: '#/components/schemas/Option_Contract_Low' mid_volume: $ref: '#/components/schemas/Option_Contract_Mid_Volume' multileg_volume: $ref: '#/components/schemas/Option_Contract_Multi_Leg_Volume' next_earnings_date: $ref: '#/components/schemas/Stock_Next_Earnings_Date' no_side_volume: $ref: '#/components/schemas/Option_Contract_No_Side_Volume' open: $ref: '#/components/schemas/Option_Contract_Open' open_interest: $ref: '#/components/schemas/Option_Contract_Open_interest' option_symbol: $ref: '#/components/schemas/Option_Contract_Symbol' option_type: $ref: '#/components/schemas/Option_Contract_Option_Type' premium: $ref: '#/components/schemas/Option_Contract_Premium' sector: $ref: '#/components/schemas/Market_General_Sector' stock_multi_leg_volume: $ref: '#/components/schemas/Option_Contract_Stock_Multi_Leg_Volume' stock_price: $ref: '#/components/schemas/Stock_Close_Price' strike: $ref: '#/components/schemas/Option_Contract_Strike' sweep_volume: $ref: '#/components/schemas/Option_Contract_Sweep_Volume' ticker_vol: $ref: '#/components/schemas/Stock_Total_Volume' total_ask_changes: $ref: '#/components/schemas/Option_Contract_Total_Ask_Changes' total_bid_changes: $ref: '#/components/schemas/Option_Contract_Total_Bid_Changes' trades: $ref: '#/components/schemas/Option_Contract_Total_Trades_Count' volume: $ref: '#/components/schemas/Option_Contract_Volume' title: Option Contract Screener response. type: object Authentication_Error: description: >- Returned with HTTP 401 when a request carries no API token, or carries one the API cannot use. The response also carries a `WWW-Authenticate` header with the `Bearer` challenge. Branch on `reason` rather than on `message`, whose wording can change. example: 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: dev@unusualwhales.com token_url: https://unusualwhales.com/dashboard/api properties: code: description: Always `authentication_required`. enum: - authentication_required type: string documentation_url: description: Where to read this API documentation. type: string expected_format: description: >- Present only when `reason` is `malformed_token`. The format the token must take. enum: - uuid type: string message: description: A plain description of the failure, written for a person. type: string reason: description: >- Which authentication failure occurred. `missing_token` means the request carried no token. `malformed_token` means a token was supplied but is not a UUID. `unrecognized_token` means the token is a UUID that no active token matches, which happens after a token is revoked or regenerated, or when it belongs to a different account. enum: - missing_token - malformed_token - unrecognized_token type: string request_id: description: >- Identifies this request in Unusual Whales logs. Quote it when contacting support. It matches the `x-request-id` response header, and is absent when no request id was assigned. type: string retryable: description: >- Always `false`. Replaying the same request unchanged returns the same error. Retrying with a corrected token can succeed. enum: - false type: boolean support_email: description: Where to send questions about API access. type: string token_url: description: Where to create and manage API tokens. type: string title: Authentication Error type: object Forbidden_Error: description: >- Returned with HTTP 403 when the API token is valid and recognized, but is not entitled to what the request asked for. Branch on `code`, which names the entitlement that is missing; `message` is written for a person and its wording can change. Unlike a 401 this response carries no `WWW-Authenticate` header, because presenting different credentials for the same token does not change the outcome. Only `code` and `message` are guaranteed. The remaining fields are sent by some checks and not others, so treat every one of them as optional. A 403 whose body is not JSON, or is JSON without a `code` field, did not come from this API. Those are produced by Cloudflare in front of the API, or by a proxy on the caller's own network, and neither says anything about the token or the subscription. example: 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: dev@unusualwhales.com token_url: https://unusualwhales.com/dashboard/api properties: code: description: >- Which entitlement is missing. `missing_access` means the token is restricted to a set of routes that excludes the requested one. `historic_data_access_missing` means a date in the request predates the earliest date the token may query. `advanced_tier_required`, `futures_access_required`, `politics_scope_required` and `volatility_scope_required` each mean the endpoint needs a subscription tier or data add-on the account does not have. `admin_required` means the endpoint is internal to Unusual Whales. enum: - missing_access - historic_data_access_missing - advanced_tier_required - futures_access_required - politics_scope_required - volatility_scope_required - admin_required type: string documentation_url: description: Where to read this API documentation. type: string message: description: >- A plain description of what is missing and how to obtain it, written for a person. Do not branch on this string. type: string reason: description: >- Present only when `code` is `missing_access`. Narrows the cause within that code. enum: - route_not_permitted type: string request_id: description: >- Identifies this request in Unusual Whales logs. Quote it when contacting support. It matches the `x-request-id` response header, and is absent when no request id was assigned. type: string retryable: description: >- When present, always `false`. Replaying the same request unchanged returns the same error. Changing the request, the token, or the subscription can succeed. enum: - false type: boolean support_email: description: Where to send questions about API access. type: string token_url: description: Where to create and manage API tokens. type: string required: - code - message title: Forbidden Error type: object Error_Message: description: A json object containing information on the error cause. example: 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 properties: msg: description: An error message containing information about the faulty input. type: string path: description: The URL path segment. type: string query: description: The URL query segment. type: string url: description: The full URL causing the error. type: string title: Error Message type: object Error_Message_on_an_internal_server_error.: description: >- A plain message informing, that an internal server error occured. In this case please send a mail with the full URL that caused the issue to support@unusualwhales.com. example: Something went wrong title: Error Message on an internal server error. type: string Single_sector: description: A singular sector. enum: - Basic Materials - Communication Services - Consumer Cyclical - Consumer Defensive - Energy - Financial Services - Healthcare - Industrials - Real Estate - Technology - Utilities example: Real Estate title: Single sector type: string Single_expiry_date: description: A single expiry date in ISO date format. example: '2024-02-02T00:00:00.000Z' title: Single expiry date type: string Single_issue_type: description: A singular issue type. enum: - Common Stock - ETF - Index - ADR example: Common Stock title: Single issue type type: string Option_Contract_Ask_Volume: description: | The amount of volume that happened on the ask side. Ask side is defined as (ask + bid) / 2 < fill price. example: 119403 title: Option Contract Ask Volume type: integer Option_Contract_Avg_Price: description: The volume weighted average fill price of the contract. example: '1.0465802437910297887119234370' title: Option Contract Avg Price type: string Option_Contract_Bid_Volume: description: | The amount of volume that happened on the bid side. Bid side is defined as (ask + bid) / 2 > fill price. example: 122789 title: Option Contract Bid Volume type: integer Option_Contract_Previous_Close_Price: description: The previous trading day's contract price. example: '1.29' title: Option Contract Previous Close Price type: string Option_Contract_Close: description: The last fill on the contract. example: '0.03' title: Option Contract Close type: string Option_Contract_Cross_Volume: description: | The amount of cross volume. Cross volume consists of all transaction that have the cross trade code. example: 0 title: Option Contract Cross Volume type: integer Stock_Earnings_time: description: The time when the earnings will be released. enum: - unknown - afterhours - premarket example: premarket title: Stock Earnings time type: string Option_Contract_Expiry: description: The contract expiry date in ISO format. example: '2023-12-22T00:00:00.000Z' title: Option Contract Expiry type: string Option_Contract_Floor_Volume: description: | The amount of floor volume. Floor volume consists of all transaction that have the floor trade code. example: 142 title: Option Contract Floor Volume type: integer Option_Contract_High: description: The highest fill on that contract. example: '2.95' title: Option Contract High type: string Option_Contract_Last_Transaction_Time: description: >- The last time there was a transaction for the given contract as UTC timestamp. example: '2023-09-08T17:45:32.000Z' title: Option Contract Last Transaction Time type: string Option_Contract_Low: description: The lowest fill on that contract. example: '0.02' title: Option Contract Low type: string Option_Contract_Mid_Volume: description: | 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 title: Option Contract Mid Volume type: integer Option_Contract_Multi_Leg_Volume: description: > 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 title: Option Contract Multi Leg Volume type: integer Stock_Next_Earnings_Date: description: >- 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' format: date title: Stock Next Earnings Date type: string Option_Contract_No_Side_Volume: description: | The amount of volume that happened on no identifiable side. This can be late, out of sequence and/or cross transactions. example: 0 title: Option Contract No Side Volume type: integer Option_Contract_Open: description: The first fill on that contract. example: '0.92' title: Option Contract Open type: string Option_Contract_Open_interest: description: The open interest for the contract. example: 18680 title: Option Contract Open interest type: integer Option_Contract_Symbol: description: > 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. title: Option Contract Symbol type: string Option_Contract_Option_Type: description: The option type of the contract. enum: - call - put example: call title: Option Contract Option Type type: string Option_Contract_Premium: description: The total option premium. example: '27723806.00' title: Option Contract Premium type: string Market_General_Sector: description: >- The financial sector of the ticker. Empty if unknown or not applicable such as ETF/Index. enum: - Basic Materials - Communication Services - Consumer Cyclical - Consumer Defensive - Energy - Financial Services - Healthcare - Industrials - Real Estate - Technology - Utilities example: Technology title: Market General Sector type: string Option_Contract_Stock_Multi_Leg_Volume: description: > 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 title: Option Contract Stock Multi Leg Volume type: integer Stock_Close_Price: description: The close stock price of the ticker. example: '182.91' title: Stock Close Price type: string Option_Contract_Strike: description: The contract strike. example: '375' title: Option Contract Strike type: string Option_Contract_Sweep_Volume: description: | The amount of sweep volume. Sweep volume consists of all transaction that have the sweep trade code. example: 18260 title: Option Contract Sweep Volume type: integer Stock_Total_Volume: description: The total amount of options volume for the given ticker. title: Stock Total Volume type: integer Option_Contract_Total_Ask_Changes: description: >- The total count of changes to the NBBO ask during that day's trading session. example: 165 title: Option Contract Total Ask Changes type: integer Option_Contract_Total_Bid_Changes: description: >- The total count of changes to the NBBO bid during that day's trading session. example: 28 title: Option Contract Total Bid Changes type: integer Option_Contract_Total_Trades_Count: description: The amount of transaction for this contract. example: 39690 title: Option Contract Total Trades Count type: integer Option_Contract_Volume: description: The contract volume. example: 264899 title: Option Contract Volume type: integer securitySchemes: authorization: scheme: bearer type: http ````