Skip to main content
  • Futures prices come formatted as CME quotes them, for example 106’025 for ZN and 425’2 for corn, with the fractions CME’s security definition lists for the contract. main_fraction and sub_fraction are those fractions and are null when the prices show decimals.
    • /futures/flow adds price_display, nbbo_bid_display, nbbo_ask_display, quote_bid_display, quote_ask_display, main_fraction and sub_fraction.
    • /futures/{contract}/trades adds the same fields and tick_size.
  • Added Trading Journal endpoints that return the Trading Journal accounts of the user that owns the API token. Every active API token can call them. Accounts are linked in the Trading Journal on unusualwhales.com, which needs a Max or professional plan, so a token whose owner has linked no accounts gets empty results. account limits a request to one account by id or exact name.
  • Added MCP tools get_my_accounts, get_my_holdings, get_my_performance, get_my_trades, get_my_edge, get_my_ticker, get_my_catalysts and get_my_rank for the data of these endpoints.
  • Added next_earnings_confirmed to /stock/{ticker}/info. It is true if the company confirmed next_earnings_date and false if the date is an estimate.
  • exchange in /stock-directory/ticker-exchanges can be texas_stock_exchange for tickers whose primary listing is on the Texas Stock Exchange.
  • Added the @equity scope to the query language, also spelled @equities. It selects common stocks and ADRs, the same as @stock+adr, while @stock still selects common stocks only. It works in:
  • Added cursor pagination to /insider/transactions. Each response includes cursor.next, which is null on the last page. Pass it as cursor to fetch the next page. page is deprecated on this endpoint and will be removed.
  • Added min_volume_avg_7_day_volume_ratio, max_volume_avg_7_day_volume_ratio, min_volume_avg_30_day_volume_ratio and max_volume_avg_30_day_volume_ratio to three endpoints. They filter on the contract’s volume for the day divided by the underlying’s average daily option volume over the previous 7 or 30 trading days, calls plus puts, as of the row’s trading date. For example, min_volume_avg_30_day_volume_ratio=0.5 returns contracts whose volume is at least half of the underlying’s average daily option volume. A row does not match while the underlying has no average volume for that date.
  • Added volume_avg_7_day_volume_ratio and volume_avg_30_day_volume_ratio to the query language for the option_trade alert type, to /alerts/query/grammar?target=option_trade and to the query parameter of /option-trades. Option trade alert configurations on POST /alerts/configuration accept the same min_ and max_ filters.
  • Added /predictions/ticker/:ticker, the open prediction markets about a stock ticker, such as “Will Apple (AAPL) close above $270?” or “Apple Vision Pro 2 released before 2027?” for AAPL. Each market has an event_type (price, market_cap, earnings, product_release, corporate or other), and event_types=price,earnings filters on it. view=events returns one row per event with the number of its matching markets, and include_closed=true includes closed markets.
  • Added avg30d_volume, with the aliases avg30d_stock_volume and avg30d_share_volume, to the query language in input on POST /alerts/configuration for the option_trade, option_contract, option_contract_interval, flow_alert and multi_leg_trade alert types, and to /alerts/query/grammar for these targets. It is the 30-day average daily stock volume of the underlying in shares, rounded down and fixed for the trade’s trading date, from the same source as avg30d_volume on stock_trade. It works in comparisons and arithmetic, e.g. where abs(delta_impact) * 20 > avg30d_stock_volume. The query parameter of /option-trades accepts it as well. A comparison with it does not match while the underlying has no 30-day average volume for the trading date.
  • A limit that is not a whole number from 1 to 500 now returns HTTP 400 with the code invalid_query_parameters on three endpoints. These requests used to return a different number of rows than requested, or an HTTP 500. On Flow Alerts the default is 50 and the maximum is 500, which is what the endpoint already served.
  • Added /sec-filings, the REST counterpart of the sec:filings websocket channel. It returns SEC EDGAR filings newest first and filters by ticker, form, start_date and end_date. Pages use a cursor: pass next_cursor from a response as cursor to get the next page.
  • Added ticker_open_int, alias ticker_oi, to the query language in input on POST /alerts/configuration for the option_trade, option_contract, option_contract_interval, flow_alert and multi_leg_trade alert types, and to /alerts/query/grammar for these targets. It is the open interest of every option contract on the underlying, calls plus puts, from the latest published open interest. This is call_open_interest plus put_open_interest from /stock/:ticker/options-volume. It works in comparisons and arithmetic, e.g. where ticker_open_int < 50000 or where size > ticker_open_int * 0.02. A comparison with it does not match while the underlying has no published open interest.
  • Added ticker_avg_7_day_volume (alias ticker_avg_7d_vol) and ticker_avg_30_day_volume (alias ticker_avg_30d_vol) to the query language for the option_trade alert type and to /alerts/query/grammar?target=option_trade. They are the average daily option volume of the underlying over the previous 7 and 30 trading days, calls plus puts, from the latest open interest update.
  • The query parameter of /option-trades accepts ticker_open_int, ticker_avg_7_day_volume and ticker_avg_30_day_volume. Each trade carries the values of its underlying at the time it was published, so a comparison with them does not match trades published before this release.
  • The Kafka topic all-option-trades carries ticker_open_interest, ticker_avg_7_day_volume and ticker_avg_30_day_volume with the same values, each absent while unknown. ticker-oi-stats carries avg_30_day_call_volume and avg_30_day_put_volume.
  • The x-uw-req-per-minute-remaining and x-uw-req-per-minute-reset response headers are deprecated and will be removed after 2026-12-31. They always hold 1000000 and 60000 and do not reflect a limit, because the API has no per-minute cap. The limits that apply are described under Rate limits.
  • With include_agg_trades=true, /option-trades now returns a rolled up transaction for the report_flag[] values intermarket_sweep, cross_trade and futures_floor when any of the transactions it rolls up carries that flag, and leaves those transactions out of the response. Before, every one of them had to carry the flag, so a rolled up transaction that mixed sweeps with other transactions did not match report_flag[]=intermarket_sweep and its sweeps were returned one by one. For normal, a rolled up transaction matches when any of its trade codes is a trade_codes[] value other than a floor, cross or sweep code. The MCP tool get_option_trades matches rolled up transactions the same way when add_agg_trades is true.
  • Added min_created_at and max_created_at to /crypto/list_tokens. Both take an RFC 3339 time and include tokens created exactly at that time. Tokens whose created_at is null are left out when either filter is set.
  • Added created_at to /crypto/list_tokens and /crypto/token/:token, the time the token was created on chain in RFC 3339. It is null when the creation time is not known.
  • Added is_low_quality to /crypto/list_tokens and /crypto/token/:token. It is true for a token with fewer than 50 holders, a market cap of zero, or a market cap above $10,000,000 per holder, which is often a fake or spam token. /crypto/list_tokens takes hide_low_quality=true to leave these tokens out.
  • Added is_large_swap to /crypto/trades. It is true for a swap of $50,000 or more in USD, and always false for liquidity adds and removes.
  • /option-trades and the MCP tool get_option_trades now support ordering by premium and size. Set order to premium or size, and order_direction to asc or desc.
  • /crypto/token/:token and /crypto/list_tokens now compute price, price_change_24h and volume_24h from every pool the token trades in, not only its USDT pool. volume_24h is in USD, and price_change_24h is a percent change over the last 24 hours, or null when the price 24 hours ago is unknown. On /crypto/list_tokens, market_cap and fdv are now the circulating and total supply times price, as on /crypto/token/:token, and tokens that traded in the last 24 hours are listed even without a USDT pool.
  • Added min_capped_pnl and max_capped_pnl to /option-trades/multi-leg. They filter on the larger absolute value of max_loss and max_profit, so a long and a short strangle of the same size match the same filter. Both accept abs() like the other multi-leg filters, e.g. min_capped_pnl=abs(100000) is the same as min_capped_pnl=100000. Multi-expiration strategies such as calendars and diagonals have no computed max_loss or max_profit and are excluded. The MCP tool get_multi_trades accepts both filters.
  • Added the call_spread_collar and put_spread_collar strategies to /option-trades/multi-leg, in the strategy field and the strategy filter. A short put with a long call spread is a call_spread_collar, and a long put spread with a short call is a put_spread_collar. These three-leg structures were returned as risk_reversal before, and earlier trades keep that strategy.
  • Stock-tied multi-leg trades (trade codes tlat, tlet, tlct and tlft) are now grouped into strategies on /option-trades/multi-leg when two or more option legs trade together. Their code field holds the stock-tied trade code.
  • Added min_notional to futures_print alert configurations on POST /alerts/configuration, the smallest notional in USD a print must reach, price × size × multiplier. It combines with min_size, and one of the two is required. A print of a contract without a usable multiplier carries no notional and never satisfies a notional floor. Triggered alerts carry notional and multiplier in meta. Rates and grains notionals use the corrected multipliers from the first security definition sync after the 2026-10-21 release.
  • Added the futures_sweep alert type to POST /alerts/configuration: a CME match event that filled several price levels on one contract, "contract": "NQZ6", or on every contract of a product, "product": "NQ". min_levels is 2 by default and at least 2, min_size and min_notional are optional floors, side limits it to buy, sell or none and contracts to outrights, spreads or all, outrights by default. An event alerts each configuration once, at most once per minute per configuration and scope, and the alert is never paused. Triggered alerts carry side, levels, size, prints, low, high, notional and executed_at in meta. Needs the Advanced API tier or the futures add-on.
  • Added the futures_block alert type to POST /alerts/configuration: a new CME block trade on one contract, "contract": "ESZ6", or on every contract of a product, "product": "ES", with min_qty and min_notional as optional floors. Multi-leg blocks are left out unless "multi_leg": true, and they carry no notional, so a notional floor never matches one. Updates and deletes of a block never alert. Each block alerts once, at most once per minute per configuration and scope, and the alert is never paused. Triggered alerts carry price, qty, notional, legs, quote_bid, quote_ask, reported_at and trade_date in meta. Needs the Advanced API tier or the futures add-on.
  • Added the futures_roll alert type to POST /alerts/configuration: the lead contract of a product changed, for one product, "product": "ES", or for every product, "product": "all". The lead is the contract with the highest 5-day rolling volume, so it can flip back, which alerts again. One alert per roll per configuration, never paused. Triggered alerts carry product, from, to and trading_date in meta. Needs the Advanced API tier or the futures add-on.
  • Added the futures_expiry alert type to POST /alerts/configuration: one contract, "contract": "ESZ6", or the nearest unexpired contract of a product, "product": "ES". days_before lists the days before expiry that alert, 1, 3 and 7 by default and each once per contract, with a day the check missed alerting on its next run, and "settlement": true also alerts once the final settlement price is published. Checked hourly. Triggered alerts carry expiry, trigger, days and settlement in meta. Needs the Advanced API tier or the futures add-on.
  • The alert listing and configuration endpoints filter all futures alert types with noti_types[]=futures_price,futures_print,futures_sweep,futures_block,futures_roll,futures_expiry.
  • Added 2m and 3m to candle_size on /stock/:ticker/ohlc/:candle_size. The MCP tools get_ticker_candles_by_range, get_ticker_indicator_series and get_ticker_indicator_events accept the same values in range.
  • Added repeat and rearm_ticks to price_target and futures_price alert configurations on POST /alerts/configuration. With "repeat": true the configuration is not paused after a trigger. Each target re-arms once the price has come back inside it by rearm_ticks ticks, 2 by default and at least 1, never less than 0.1% of the target, and the next crossing triggers again, at most once a minute per target. After a restart, a target the price already sits beyond waits for the price to come back inside before it can trigger.
  • Added the futures_print alert type to POST /alerts/configuration. The config names one contract, "contract": "ESZ6", or a product, "product": "ES", which matches every contract of the product, plus min_size in contracts. side limits it to buy, sell or none prints and contracts to outrights, spreads or all, outrights by default. The alert fires on every matching print, at most once per minute per configuration and scope, and is never paused. Triggered alerts carry price, size and side in meta. Like futures_price, it needs the Advanced API tier or the futures add-on.
  • Futures display factors are versioned per contract symbol, because CME reuses a security_id for a new contract once the previous one expires.
  • /futures/flow prints carry event_ts_ns, event_levels and event_size once their CME match event is complete, and sweeps_only=true returns only prints of events that filled at least two price levels.
  • Starter-only accounts cannot create GEX, futures-price or prediction alerts through POST /alerts/configuration. Independent qualifying subscriptions or permissions retain access.
  • Request-limit errors now describe both daily and billing-month resets instead of assuming every allowance resets daily.
  • Full Tape now returns HTTP 403 for dates more than 30 calendar days old while an API subscription has status trialing.
  • Added combos to /predictions/user/:user_id. It values the user’s Polymarket Combos, which positions leaves out: count, settled_count and pnl, the PnL in USD before fees. Combos that have not settled yet count at cost. It is null for users with more than 20,000 Combo positions.
  • Added the futures_price alert type to POST /alerts/configuration. The config names either one CME futures contract, "contract": "ESZ6", or a product, "product": "ES", plus price_target_upper, price_target_lower or both, in the contract’s display price. A product alert follows the product’s current lead contract, which is the outright contract with the highest 5-day rolling volume, so it rolls on its own. The alert fires on the first print at or through a target and the configuration is then paused. Triggered alerts carry the product or contract in symbol and the contract that traded in meta.sym, and noti_types[]=futures_price selects them on /alerts.
  • Added min_profit, max_profit, min_loss and max_loss to /option-trades/multi-leg. They filter on the max_profit and max_loss fields and accept abs(). max_loss is negative, so min_loss=abs(100000) returns strategies that can lose at least $100,000. Strategies with an unbounded profit or loss are excluded by the matching filter.
  • Added the query parameter to /option-trades. It takes a Query language expression, such as where premium > 100k and strike > spot, and combines it with the other filters using and. The fields, operators and functions are listed by /alerts/query/grammar?target=option_trade.
  • /option-trades/flow-alerts: Default lookback is 7 days without a specified newer_than.
  • /predictions/user/:user_id now returns at most 20,000 positions, the ones with the highest total_invested_usd. The new positions_truncated field is true when the user has more positions than that.
  • Added earnings_report_time to /stock/:ticker/volatility/context. It is premarket, postmarket or unknown, or null when no report is scheduled or its time is not recorded. expiry.earnings_in_expiry is now false when the report is postmarket on the expiry date.
  • Whale Bundle Basic monthly and annual plans now include unlimited API requests.
  • Added chart and chart_member to each rev_breakdown row of /stock/:ticker/fundamental-breakdown. A filing often reports the same revenue in several breakdowns, and subtotals next to their parts. chart is product or region for the rows of the one breakdown picked for that chart, whose members add up to the report’s revenue where possible, and null for every other row. With period=all, each period of a report has its own chart rows. chart_member is the member to label the row with.
  • Added the period query parameter to /stock/:ticker/fundamental-breakdown. quarter, the default, returns the quarterly rev_breakdown rows and the rows without a period, plus the 12-month rows of annual_only tickers. annual returns only 12-month rows, including breakdowns that a company reports only in its annual report. all returns every row.
  • Added period_months to each rev_breakdown row of the same endpoint. It is the number of months the value covers, such as 3 for a quarter and 12 for a full fiscal year. null marks a count at a point in time, such as the number of stores, or a row stored before this field existed.
  • The rev_group documentation now lists country and continent, which the endpoint already returned.
  • Added FLEX option endpoints. FLEX option data always lags by one trading day:
    • /flex-options returns the FLEX option contracts of a date with their open interest and mark, next to the values of the previous trading day.
    • /flex-options/market returns the market-wide FLEX open interest per day and the FLEX open interest per ticker on a date.
    • /flex-options/chain/:chain returns the daily history of one FLEX option contract.
    • /flex-options/:ticker returns the daily FLEX open interest history of a ticker.
  • Added new SEC filing websocket channels: sec:filings (every filing), sec:insider_trades (insider trades, aggregated per filing and transaction type), sec:13f_alerts and sec:13f_filings (13F reports), sec:13dg_filings (Schedule 13D and 13G), sec:company_reports (10-Q, 10-K, 20-F and 40-F financial statements) and sec:497_filings (Rule 497 prospectuses). Each channel streams one message type of the Kafka topic sec-filings, with the same fields as the Kafka message. The channels cover every ticker at once and have no per-ticker variant.
  • Added a new websocket channel stock_screener. It streams the latest stock screener row of every ticker and is the live counterpart of /screener/stocks.
  • Added a new websocket channel ta_1d_live:{TICKER}. 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.
  • Added a global greeks websocket channel. It streams the same per-contract option greeks as greeks:<TICKER>, but for every underlying at once. This is a high volume firehose - prefer the per-ticker channel unless you need the full tape.
  • 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); and resources/list / resources/templates/list / resources/read for playbooks and example files.
  • Added a new websocket channel 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. The channel is global only; there is no per-ticker variant.
  • Updated /stock/:ticker/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 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.
Added a new advanced-tier endpoint group. All routes below require API Advanced, Enterprise Startup, Enterprise Startup + Kafka, or Enterprise tier.

Company fundamentals

Macro

  • Added /commodities/:name 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 for US economic indicator series (GDP, GDP per capita, treasury yield, fed funds rate, CPI, inflation, retail sales, durables, unemployment, payrolls).

Forex

Digital currencies

Market intel and analytics

  • Added /market/movers for pre-ranked top gainers, top losers, and most actively traded US tickers.
  • Added /calendar/ipo for upcoming IPOs over the next 3 months.
  • Added /analytics/window for fixed-window statistical analytics across baskets of tickers (mean, stddev, correlation, drawdown, autocorrelation, covariance, and more).
  • Added /analytics/sliding for sliding-window statistical analytics.

Congressional unusual trades (scope unusual-trades)

Private markets (scope private-markets)

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 <catalog_id> or <catalog_id>.<command> form).
  • Enhanced MCP /api/mcp 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.
  • Added authenticated MCP endpoint /api/mcp to expose existing AI tools to API subscribers using the same Authorization: Bearer <API_TOKEN> flow.
  • Supports MCP initialize, tools/list, and tools/call methods backed by the existing internal tool registry and execution pipeline.
  • Added new websocket channels lit_trades and off_lit_trades to stream live lit (exchange-based) and off-lit (dark pool) trades respectively.
  • Added newer_than and older_than time filtering parameters to /alerts endpoint with 14-day maximum lookback period for custom alerts queries
  • Added /market/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).
  • Added /net-flow/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
  • Enhanced /market/correlations endpoint with new date filtering options: start_date and end_date parameters to specify custom date ranges, complementing the existing interval parameter
  • Updated /stock/{ticker}/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.
To migrate over replace all your /api/stock/:ticker/spot-exposures/:expiry/strike calls with /api/stock/:ticker/spot-exposures/expiry-strike?expirations[]=expiry
  • The endpoint /congress/recent-reports has been removed as it returns the same data as /congress/recent-trades.
  • Enhanced /market/fda-calendar with better FDA data, additional fields (notes, outcomes, sources), and filtering by company metrics
  • Updated dark pool/off lit endpoints to allow filtering for size, premium & consolidated volume
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
  • Improved all earnings endpoint
  • Added 2 new fields: days_of_oi_increases & days_of_vol_greater_than_oi to /market/oi-change
  • Added the ability to filter /darkpool/:ticker by timestamps through the two new query parameters older_than and newer_than
  • Added the channels gex:TICKER & gex_strike:TICKER to the websocket
  • Added the ability to filter /option-trades/flow-alerts by timestamps through the two new query parameters older_than and newer_than
  • The data returned by /stock/:ticker/option-contracts has been limited to 500 results
  • 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.
Last modified on November 13, 2026