# OptionWhales

> Options flow and stock market data for traders and AI agents. Real-time unusual activity detection, GEX engine, implied volatility, earnings signals, stock quotes and fundamentals — over an MCP server, a REST API and WebSockets.

## For AI agents (start here)

- MCP server: `https://api.optionwhales.io/mcp` (Streamable HTTP, JSON-RPC 2.0; protocol 2026-07-28 and earlier). `initialize`, `server/discover` and `tools/list` need no key.
- Sign-in (OAuth 2.1) URLs of the same server: `https://api.optionwhales.io/mcp/connect` (Claude, Claude Code and other OAuth clients) and `https://api.optionwhales.io/mcp/chatgpt` (ChatGPT apps). Authorization server: `https://www.optionwhales.io` (PKCE S256; client ID metadata documents or dynamic registration).
- Without credentials a small preview works: `gex_levels` for SPY and QQQ, the next 3 high-impact macro events, the next 3 earnings reporters (or one ticker's date), the top 3 options-flow tickers and the latest 3 unusual trades.
- Everything else needs an account or API key (free or Pro): OAuth sign-in, the `X-API-Key` header (or `Authorization: Bearer <key>`), or the `use_api_key` tool. Never put a key in a URL.
- No key? Call the MCP tool `register_free_key` (or `POST https://api.optionwhales.io/v1/account/register` with `{"email": "..."}`) using the email of the person you act for. The key works immediately for 24 hours; they receive "Confirm your OptionWhales API key" — confirm with `confirm_registration` / `POST /v1/account/confirm` and the code, or they click the link. Confirmed keys are permanent.
- Setup guide and client configs: https://optionwhales.io/for-ai-agents
- Data is for research and education, not investment advice.

## 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 and AI agents that want programmatic access to options market microstructure and stock data.

## Product Tiers

- **Free** — API access with rate-limited previews (10 req/min, 200/day). Top-3 ticker previews for flow and momentum endpoints. Over MCP: previews (top 3 flow / momentum / IV movers, latest 5 unusual trades), GEX levels for SPY and QQQ, IV term structure for SPY, QQQ, AAPL, MSFT, GOOGL, AMZN, NVDA, META, TSLA, and the full economic calendar. AI agents can self-register a free key.
- **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, stock quotes and fundamentals, every MCP tool, and real-time WebSocket streaming.

Pricing: https://optionwhales.io/pricing

## API

Base URL: `https://api.optionwhales.io`
Authentication: `X-API-Key` header (WebSockets also accept `?api_key=`; the MCP endpoints never do)
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 (connect free; tools follow your account's or key's tier)
- `POST /mcp` — Model Context Protocol JSON-RPC endpoint for options flow, gamma, volatility, events and stock-market data. `initialize` / `tools/list` need no key.
- `POST /mcp/connect`, `POST /mcp/chatgpt` — the same tools behind OAuth sign-in (Claude / ChatGPT); no key tools
- `GET /mcp` (and `/mcp/connect`, `/mcp/chatgpt`) — MCP discovery (protocol version, tool names, which tier can call each; no auth)
- `GET /.well-known/oauth-protected-resource/mcp/connect` (and `/mcp`, `/mcp/chatgpt`) — OAuth protected-resource metadata
- No-account preview: `gex_levels` (SPY, QQQ), `economic_calendar` (next 3 high-impact), `earnings_calendar` (one ticker or next 3), `intent_flow_current` (top 3), `abnormal_trades_current` (latest 3)
- Free tools: `intent_flow_current`, `momentum_rankings`, `abnormal_trades_current`, `volatility_movers` (previews); `gex_levels` (SPY, QQQ); `volatility_term_structure` (SPY, QQQ, mega-caps); `economic_calendar`; `earnings_calendar` (next 10)
- Interactive charts (MCP Apps): `gex_levels`, the flow tools and `volatility_term_structure` link `ui://optionwhales/...` views
- Pro tools: every other options tool plus `stock_quote`, `stock_candles`, `technical_indicator`, `financials`, `dividends`, `stock_splits`, `stock_news`, `short_interest`, `short_volume`, `insider_trades`, `seasonality`, `screener`
- Key tools (no key needed): `register_free_key`, `confirm_registration`, `use_api_key`
- AI skill: `https://optionwhales.io/skill.md`

#### Account & Streaming (All / Pro+)
- `GET /v1/account/usage` — API key usage stats
- `POST /v1/account/register` — agent self-registration: free key for `{"email": "..."}` (no key needed)
- `POST /v1/account/confirm` — confirm a self-registered key with `{"code": "..."}` from the email
- `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. AI agents can get one for the person they act for with `register_free_key` (MCP) or `POST /v1/account/register`.

**Can my AI assistant use OptionWhales?**
Yes. In ChatGPT add `https://api.optionwhales.io/mcp/chatgpt`, in Claude add `https://api.optionwhales.io/mcp/connect`, and sign in with your OptionWhales account. Other MCP clients (Claude Code, Codex, Cursor, VS Code, personal agents) can use `https://api.optionwhales.io/mcp` with an API key. Setup: https://optionwhales.io/for-ai-agents

## 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