# OptionWhales

> Options flow intelligence platform. Real-time unusual activity detection, GEX engine, earnings signals, and a Pro API for algorithmic traders.

## What is OptionWhales?

OptionWhales is a financial data platform that tracks institutional option order flow, detects abnormal trades, computes Gamma Exposure (GEX), and surfaces earnings-driven option signals. It is designed for traders who want programmatic access to options market microstructure data.

## Product Tiers

- **Free** — API access with rate-limited previews (10 req/min, 200/day). Top-3 ticker previews for flow and momentum endpoints.
- **Pro** — Full access to all endpoints (60 req/min, 5,000/day). Includes earnings, economic, GEX, directional score, implied-volatility analytics, open interest, dark pool, an MCP server for AI agents, and real-time WebSocket streaming.

Pricing: https://optionwhales.io/pricing

## API

Base URL: `https://api.optionwhales.io`
Authentication: `X-API-Key` header or `?api_key=` query parameter
Interactive docs: `https://api.optionwhales.io/docs`
Documentation: `https://optionwhales.io/developers`

### Endpoint Groups

#### Intent Flow (Free preview / Pro full)
- `GET /v1/flow/current` — current session intent rankings
- `GET /v1/flow/sessions` — list historical sessions (Pro+)
- `GET /v1/flow/{session}` — session rankings by date
- `GET /v1/flow/{session}/{ticker}` — full ticker detail (Pro+)

#### Momentum (Free preview / Pro full)
- `GET /v1/momentum/rankings` — momentum-sorted ticker list
- `GET /v1/momentum/{ticker}/history` — multi-session history (Pro+)

#### Abnormal Trades (Free preview / Pro full)
- `GET /v1/abnormal-trades/current` — current session abnormal trades
- `GET /v1/abnormal-trades/{session}` — historical session (Pro+)

#### Earnings Intelligence (Pro+ only)
- `GET /v1/earnings/current` — today's earnings signals across all tickers
- `GET /v1/earnings/sessions` — list of sessions with earnings data
- `GET /v1/earnings/{session}` — session-level earnings summary
- `GET /v1/earnings/{session}/{ticker}` — full ticker earnings detail

#### Economic Events & ETF Flow (Pro+ only)
- `GET /v1/economic/calendar` — economic events calendar (CPI, Fed, jobs, etc.) with impact levels
- `GET /v1/economic/etf-flow` — ETF option flow summary (SPY/QQQ/IWM/TLT)
- `GET /v1/economic/etf-flow/{symbol}` — full ETF flow detail
- `GET /v1/economic/etf-timeseries` — multi-session ETF flow trend

#### Directional Score (Pro+ only)
- `GET /v1/directional/current` — current session directional scores (-1 to +1) for all tickers
- `GET /v1/directional/{session}` — historical session directional snapshot
- `GET /v1/directional/{ticker}/history` — per-ticker score history (up to 90 sessions)

#### GEX — Gamma Exposure (Pro+ only)
- `GET /v1/gex/{session}/{ticker}` — full GEX profile (by-strike array, IV smile, flow overlay)
- `GET /v1/gex/{session}/{ticker}/levels` — key levels only: gamma flip, max pain, call/put wall
- `GET /v1/gex/{ticker}/timeseries` — day-by-day GEX evolution for trend analysis
- `GET /v1/gex/{session}/{ticker}/greek-exposure` — gamma + charm + vanna exposure by strike AND by expiry (call/put/net)

#### Implied Volatility (Pro+ only)
- `GET /v1/volatility/{ticker}/surface` — full IV surface (iv matrix over moneyness × DTE)
- `GET /v1/volatility/{ticker}/term-structure` — ATM-IV per expiry + mean ATM-IV
- `GET /v1/volatility/{ticker}/history` — historical ATM-IV(30d) series (from/to)
- `GET /v1/volatility/{ticker}/percentile` — IV percentile / z-score / bands at a (moneyness, DTE) cell
- `GET /v1/volatility/atm` — batch ATM-IV(30d) for many tickers (?symbols=A,B,C)
- `GET /v1/volatility/movers` — top ATM-IV(30d) movers vs prior close

#### Open Interest (Pro+ only)
- `GET /v1/oi/{ticker}/timeseries` — per-ticker OI + volume timeseries (AM/PM snapshots)
- `GET /v1/oi/{ticker}/change` — OI change between the two most-recent snapshots
- `GET /v1/oi/{ticker}/latest` — most recent OI snapshot summary
- `GET /v1/oi/contract/{occ}` — OI for a single option contract by OCC symbol
- `GET /v1/oi/health` — OI service health (Free)
- `GET /v1/oi/movers` — market-wide OI movers (tickers ranked by DAY-OVER-DAY total-OI change; as_of/prior_as_of carry the two oi_dates)

#### Net-Premium Tide (Pro+ only)
- `GET /v1/tide/market` — market-wide large-order net-premium tide (net call/put by DTE×moneyness + intraday curve + top tickers)
- `GET /v1/tide/sectors` — sector-level net-premium tide
- `GET /v1/tide/{ticker}` — per-ticker net-premium tide + intraday cumulative curve
  (large-order flow only, not the full tape; direction = aggressor NBBO)

#### Option Contracts (Pro+ only) — per-contract by OCC symbol
- `GET /v1/contracts/chain/{ticker}` — option chain (OI>0) from the last snapshot; filter by expiry/type/min_oi
- `GET /v1/contracts/atm/{ticker}` — near-spot (ATM) strikes grouped by expiry
- `GET /v1/contracts/expiries/{ticker}` — per-expiry OI breakdown
- `GET /v1/contracts/{occ}` — per-contract profile (OI/IV/greeks/quote as-of snapshot)
- `GET /v1/contracts/{occ}/historic?from=&to=` — daily OHLC bars (~1yr look-back)
- `GET /v1/contracts/{occ}/intraday?date=` — intraday minute bars (recent window)

#### Dark Pool / Off-Exchange (Pro+ only)
- `GET /v1/darkpool/blocks` — detected off-exchange block trades (with %ADV + baselines)
- `GET /v1/darkpool/ranking` — whole-market off-exchange share + per-ticker notional ranking
- `GET /v1/darkpool/pressure` — NBBO-location flow pressure windows + cumulative curve
- `GET /v1/darkpool/prints/{ticker}` — raw off-exchange (TRF) print tape (~15-min delayed)

#### MCP Server (Pro+ only)
- `POST /mcp` — Model Context Protocol JSON-RPC endpoint (AI-agent tools over the /v1 data)
- `GET /mcp` — MCP discovery (protocol version + tool names; no auth)
- AI skill: `https://optionwhales.io/skill.md`

#### Account & Streaming (All / Pro+)
- `GET /v1/account/usage` — API key usage stats
- `WSS /v1/ws/abnormal-trades` — real-time trade stream (Pro+)

### Key Data Concepts

**Intent Flow** — Classifies option order clusters as Accumulation, Distribution, Hedging, or Speculative based on strike, size, and timing patterns.

**Directional Score** — Composite signal (-1 to +1) derived from net notional, order clustering, and IV. Negative = bearish positioning. Positive = bullish.

**GEX (Gamma Exposure)** — Net gamma dealers carry across all strikes. Negative GEX → dealers sell to hedge → amplifies moves. Positive GEX → dealers buy dips → dampens volatility. Key levels: gamma flip (zero-cross), max pain, call wall, put wall.

**Abnormal Trade** — Option order flagged by volume/OI ratio threshold, sweep detection, unusual size, or cross-venue activity.

**Earnings Intelligence** — Combines earnings calendar events with session option flow to surface pre-earnings accumulation / distribution signals, IV rank, and Greek exposures.

## FAQ

**Does OptionWhales use real-time data?**
Yes. During market hours, option flow is captured in real time. Data is available via REST poll or WebSocket streaming (Pro).

**Which tickers are covered?**
All US equity options tickers with sufficient volume — typically 3,000–5,000 tickers per session.

**Can I use the API in an automated trading system?**
Yes. The Pro API is designed for programmatic access. Use the WebSocket for real-time streams and REST for historical lookups.

**What exchanges are covered?**
All US options exchanges: CBOE, BATS, MIAX, ISE, PHLX, ARCA, NOM, and others.

**Is there a free trial?**
Free API keys are available immediately after signup. No credit card required for the free tier.

## Links

- Website: https://optionwhales.io
- API docs: https://optionwhales.io/developers
- Interactive API explorer: https://api.optionwhales.io/docs
- Pricing: https://optionwhales.io/pricing
- Discord: https://discord.gg/mW6HbRuvXR