> ## Documentation Index
> Fetch the complete documentation index at: https://mathematicalcompany.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Unusual Whales

> Options flow, dark pool, Congress trades, insider activity, Greek exposure, IV analytics, and market sentiment via the Unusual Whales API.

[Unusual Whales](https://unusualwhales.com) provides institutional-grade options flow data, dark pool prints, Congress and insider trading disclosures, Greek exposure analytics, and volatility surfaces.

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [unusualwhales.com/pricing](https://unusualwhales.com/pricing?product=api) and get your API key from the [API dashboard](https://unusualwhales.com/settings/api-dashboard).
  </Step>

  <Step title="Set environment variable">
    ```bash theme={null}
    export UNUSUAL_WHALES_API_KEY="your-api-key"
    ```
  </Step>

  <Step title="Start using">
    ```python theme={null}
    from horizon.providers import UnusualWhalesProvider as UW

    flow = UW.options_flow(ticker="AAPL", min_premium=100000)
    ```
  </Step>
</Steps>

## Options Flow

The core feature — detect unusual options activity, sweeps, and large premium prints.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from horizon.providers import UnusualWhalesProvider as UW

    # All unusual flow
    flow = UW.options_flow(limit=50)

    # Filtered: AAPL call sweeps, $100k+ premium
    flow = UW.options_flow(
        ticker="AAPL",
        is_sweep=True,
        is_call=True,
        min_premium=100000,
    )

    # Flow for a specific ticker
    recent = UW.stock_flow("TSLA", min_premium=50000)
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # All unusual flow
    horizon providers uw flow

    # Filtered
    horizon providers uw flow --ticker AAPL --sweep --calls --min-premium 100000

    # Per-ticker flow
    horizon providers uw stock-flow TSLA
    ```
  </Tab>
</Tabs>

**Filter parameters:**

| Parameter             | Description                    |
| --------------------- | ------------------------------ |
| `ticker`              | Filter by ticker symbol        |
| `min_premium`         | Minimum premium in dollars     |
| `is_sweep`            | Only sweep orders              |
| `is_call` / `is_put`  | Filter by option type          |
| `is_otm`              | Only out-of-the-money          |
| `min_dte` / `max_dte` | Days to expiration range       |
| `limit`               | Number of results (default 50) |

## Dark Pool

Institutional block trades executed off-exchange.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Market-wide dark pool prints
    prints = UW.dark_pool_recent()

    # Per-ticker with size filter
    nvda_dp = UW.dark_pool("NVDA", min_size=10000)
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Market-wide
    horizon providers uw dark-pool

    # Per-ticker
    horizon providers uw dark-pool NVDA --min-size 10000
    ```
  </Tab>
</Tabs>

## Congress Trades

Track stock trades disclosed by members of Congress (STOCK Act).

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Recent trades
    trades = UW.congress_trades(limit=20)

    # Filter by ticker
    nvda = UW.congress_trades(ticker="NVDA")

    # Specific member
    pelosi = UW.congress_trader("Pelosi")
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    horizon providers uw congress
    horizon providers uw congress --ticker NVDA
    horizon providers uw congress --name "Pelosi"
    ```
  </Tab>
</Tabs>

## Insider Transactions

SEC Form 4 filings — officer, director, and 10% owner trades.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Large insider buys
    insiders = UW.insider_trades(min_value=1000000, limit=20)

    # Per-ticker, officers only
    aapl = UW.insider_trades(ticker="AAPL", is_officer=True)
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    horizon providers uw insiders --min-value 1000000
    horizon providers uw insiders --ticker AAPL --officer
    ```
  </Tab>
</Tabs>

## Greek Exposure & IV

Options positioning analytics — gamma exposure (GEX), delta exposure (DEX), IV rank, and term structure.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Aggregate Greek exposure
    gex = UW.greek_exposure("SPY")

    # By strike
    gex_strikes = UW.greek_exposure_by_strike("SPY")

    # IV rank (percentile)
    iv = UW.iv_rank("TSLA")

    # Term structure
    term = UW.vol_term_structure("AAPL")

    # Max pain
    pain = UW.max_pain("SPY")
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    horizon providers uw greeks SPY
    horizon providers uw greeks SPY --by-strike
    horizon providers uw iv TSLA
    horizon providers uw max-pain SPY
    ```
  </Tab>
</Tabs>

## Short Interest

Short interest, short volume, and failures to deliver.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    si = UW.short_interest("GME")
    vol = UW.short_volume("AMC")
    ftds = UW.ftd("TSLA")
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    horizon providers uw shorts GME
    ```
  </Tab>
</Tabs>

## Market Sentiment

Proprietary market-wide indicators.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Market Tide (net premium flow)
    tide = UW.market_tide()

    # SPIKE volatility indicator
    spike = UW.spike()
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    horizon providers uw tide
    horizon providers uw spike
    ```
  </Tab>
</Tabs>

## Screeners

Scan stocks and option chains for setups.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Stock screener
    stocks = UW.screener_stocks()

    # Hottest option chains
    options = UW.screener_options(min_premium=500000, is_otm=True)
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    horizon providers uw screener --type stocks
    horizon providers uw screener --type options --min-premium 500000
    ```
  </Tab>
</Tabs>

## Calendars & Earnings

Economic events, FDA catalysts, and earnings schedules.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    econ = UW.economic_calendar()
    fda = UW.fda_calendar()
    earnings = UW.earnings("AAPL")
    premarket = UW.earnings_premarket()
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    horizon providers uw calendar --type economic
    horizon providers uw calendar --type fda
    horizon providers uw earnings AAPL
    horizon providers uw earnings --schedule premarket
    ```
  </Tab>
</Tabs>

## Additional Endpoints

| Function                           | Description                                   |
| ---------------------------------- | --------------------------------------------- |
| `UW.stock_info(ticker)`            | Stock information (price, market cap, sector) |
| `UW.stock_state(ticker)`           | Current stock state                           |
| `UW.option_chains(ticker)`         | Full option chains                            |
| `UW.institutions()`                | List tracked institutions                     |
| `UW.institution_holdings(name)`    | Holdings for an institution                   |
| `UW.institution_ownership(ticker)` | Institutional ownership of a ticker           |
| `UW.etf_holdings(ticker)`          | ETF holdings breakdown                        |
| `UW.etf_flow(ticker)`              | ETF inflow/outflow                            |
| `UW.seasonality(ticker)`           | Monthly return seasonality                    |
| `UW.news()`                        | Financial news headlines                      |
| `UW.prediction_whales()`           | Prediction market whales                      |
| `UW.prediction_unusual()`          | Unusual prediction market activity            |
| `UW.crypto_whales()`               | Recent crypto whale transactions              |

## Rate Limits

| Limit          | Value   |
| -------------- | ------- |
| Daily requests | 15,000  |
| Per-minute     | 120     |
| Daily reset    | 8 PM ET |

Rate limit headers are returned with every response: `x-uw-daily-req-count`, `x-uw-req-per-minute-remaining`.

## MCP Tools

All functions are available via the `unusual_whales` compound MCP tool with an `action` parameter:

```json theme={null}
// Example: get unusual options flow for AAPL
{"action": "options_flow", "params": "{\"ticker\": \"AAPL\", \"min_premium\": 100000}"}
```

Available actions: `options_flow`, `stock_flow`, `dark_pool`, `congress_trades`, `congress_trader`, `insider_trades`, `market_tide`, `spike`, `economic_calendar`, `fda_calendar`, `stock_info`, `stock_state`, `earnings`, `earnings_schedule`, `seasonality`, `greek_exposure`, `greek_exposure_by_strike`, `greek_exposure_by_expiry`, `iv_rank`, `vol_term_structure`, `max_pain`, `option_chains`, `short_interest`, `short_volume`, `ftd`, `screener_stocks`, `screener_options`, `etf_holdings`, `etf_flow`, `institutions`, `institution_holdings`, `institution_ownership`, `news`, `prediction_whales`, `prediction_unusual`, `crypto_whales`.