For AI Agents

Market Intelligence for Autonomous Systems

An AI agent that can generate alpha pays for its own compute. OptionWhales provides the signal layer — validated, programmatic, continuously updated — so agents can act on institutional options flow without building the data infrastructure themselves.

The Opening Pressure signal survived a three-stage out-of-sample test across 188.5 million option orders and 1,250 trading sessions. It is not a hypothesis — it is a documented statistical finding available via API.

MCP server · ChatGPT · Claude · Claude Code · Codex · GitHub Copilot · any MCP client

Connect your assistant

Add OptionWhales to ChatGPT or Claude and sign in with your OptionWhales account — free or Pro. A small preview works before you sign in: SPY and QQQ gamma levels, the next macro events and earnings, and the top options-flow names. Gamma levels, flow tables and the volatility curve render as interactive charts.

ChatGPT (including dots)

https://api.optionwhales.io/mcp/chatgpt

Add a custom app (connector) in ChatGPT with this URL and choose OAuth sign-in.
Ask about options flow — ChatGPT asks you to sign in to OptionWhales when a tool needs your account.

Claude — claude.ai, Desktop and mobile

https://api.optionwhales.io/mcp/connect

Settings → Connectors → Add custom connector, and paste this URL.
Claude asks you to sign in to OptionWhales the first time a tool needs your account.

Claude Code

https://api.optionwhales.io/mcp/connect

claude mcp add --transport http optionwhales https://api.optionwhales.io/mcp/connect

Then run /mcp in Claude Code and choose Authenticate to sign in.

Microsoft 365 Copilot

Coming soon.

Signing in connects the app to your account: it reads market data with your plan’s access and never sees your password, payment details or API keys. Disconnect any time in Account → Connected AI apps.

Then just ask

“What are the gamma levels on SPY right now?”
“Check if there's unusual options activity in NVDA today”
“When does NVDA report earnings, and how is its IV term structure shaped?”
“What macro events are coming up this week?”

Other MCP clients: one URL and an API key

Codex, VS Code, Cursor, personal agents and anything else that speaks MCP can use the general endpoint with an API key header (clients that support MCP sign-in can use the Claude URL above instead). No key is needed to connect or for the preview.

https://api.optionwhales.io/mcp

No key yet? The assistant handles it

It calls register_free_key with your email — the key works immediately for 24 hours.
You get “Confirm your OptionWhales API key”. Click the link, or let an assistant with inbox access pass the code to confirm_registration.
Confirmed keys are permanent — and Pro, if your account is Pro.

Client setup

Claude Code

One command in your terminal:

claude mcp add --transport http optionwhales https://api.optionwhales.io/mcp \
  --header "X-API-Key: YOUR_KEY"

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "optionwhales": {
      "type": "http",
      "url": "https://api.optionwhales.io/mcp",
      "headers": { "X-API-Key": "YOUR_KEY" }
    }
  }
}

Codex (OpenAI)

~/.codex/config.toml:

[mcp_servers.optionwhales]
url = "https://api.optionwhales.io/mcp"
http_headers = { "X-API-Key" = "YOUR_KEY" }

Cursor, Windsurf & clients that send headers

mcp.json (or your client's equivalent):

{
  "mcpServers": {
    "optionwhales": {
      "url": "https://api.optionwhales.io/mcp",
      "headers": { "X-API-Key": "YOUR_KEY" }
    }
  }
}

Claude Desktop (config file)

claude_desktop_config.json, bridged with mcp-remote:

{
  "mcpServers": {
    "optionwhales": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.optionwhales.io/mcp",
               "--header", "X-API-Key:YOUR_KEY"]
    }
  }
}

Keys go in the X-API-Key header (or Authorization: Bearer) — never in a URL.

What each level gets

Tools	No account	Free account	Pro
Connect & list tools	✓	✓	✓
Gamma (GEX) levels	SPY, QQQ	SPY, QQQ	Any ticker
Options flow intent	Top 3 (ticker, direction)	Top 3	Full feed
Unusual options trades	Latest 3	Latest 5	Full feed
Economic calendar	Next 3 high-impact	Full	Full
Earnings calendar	One ticker or next 3	Next 10 + estimates	Full + flow intent
Momentum · IV movers	—	Top 3	Full
Implied-volatility term structure	—	SPY, QQQ + mega-caps	Any ticker
OI, dark pool, tide, Greeks, contracts	—	—	✓
Stock quotes, candles, technicals, news	—	—	✓
Fundamentals, short interest, insider trades	—	—	✓
Interactive charts in ChatGPT and Claude	✓	✓	✓

Plans

Free account

Previews of every flow tool, SPY and QQQ gamma levels, mega-cap implied volatility, and the full economic and earnings calendars.

Pro — $19/month

All 34 tools for any ticker: full flow feeds, open interest, dark pool, Greeks, contracts, stock quotes, technicals, fundamentals and news, plus the WebSocket streams.

Plans are managed on optionwhales.io; an assistant signed in to a Pro account gets Pro access.

Data is for research and education, not investment advice. See terms and privacy.

Signal Validation Summary — Out-of-Sample (416 sessions, ~20 months)

1.81

OOS Sharpe (best)

+107.9%

Cumulative L/S Return

Many → Few

Configs Tested

188.5M orders

Data Basis

Full methodology in Pan & Poteshman replication paper →

View all research →

Research backtest results, not a forecast. Past performance does not indicate future results; nothing here is investment advice.

What the API provides

Signal Quality

Validated Directional Signal

The Opening Pressure signal is derived from 188.5 million large option orders across 1,250 sessions. It uses proprietary filters to isolate institutional directional conviction from routine flow. It passed a three-stage out-of-sample validation framework — not curve-fitted, not back-tested to death. Surviving signals deliver OOS Sharpe ratios of 1.6–1.8.

Integration

REST API + WebSocket Streaming

GET /v1/flow/current, GET /v1/momentum/rankings, GET /v1/abnormal-trades/current — JSON, authenticated by API key, 60 req/min on Pro. WebSocket (wss://api.optionwhales.io/v1/ws/abnormal-trades) for event-driven agents that need tick-level alerts rather than polling.

Real-Time Data

Real-Time Price & OHLC Feed

Beyond options flow, Pro keys get live underlying prices and intraday OHLC candles from a direct market-data feed (sub-second spot). REST: GET /v1/quotes/{symbol} and GET /v1/quotes/{symbol}/candles; 1 Hz stream at wss://api.optionwhales.io/v1/stream/quotes. Real-time symbols are bounded by a per-key watchlist (25 on Pro) — an agent subscribes to the underlyings it trades and gets price plus flow from one provider.

Agent Runtime

OpenClaw Skill (Agent-Native)

Install the official OptionWhales skill in any OpenClaw-compatible agent runtime in one command: clawhub install option-flow. The skill surfaces real-time flow rankings, momentum, and abnormal trades as structured tool outputs — no parsing required.

Portfolio Signal

Daily Strategy Portfolio

Each session, the Opening Pressure pipeline materializes a ranked long/short portfolio based on proprietary institutional flow filters, tracked close-to-close and published the following day. The methodology and results are published in the research papers; the underlying ranked flow signal is available to agents via GET /v1/momentum/rankings.

Historical Data

Historical Session Archive

154+ sessions of structured option flow data with per-ticker intent scores, clustering labels, directional confidence, abnormal trade flags, and GEX levels. Available programmatically via API for agent fine-tuning, backtest replay, or retrieval-augmented context.

Auditability

Research-Grade Documentation

Two published research papers document the data provenance and signal validation methodology. An agent integrating this API can cite its reasoning: 'Signal based on 188.5M orders, OOS Sharpe 1.81, validated across 1,250 sessions from 2021–2026.'

The long-horizon thesis

A self-sustaining AI agent needs a signal that earns more than it costs

As AI agents become more autonomous — executing long-horizon tasks, managing resources, making real-world decisions — capital becomes a constraint. An agent that can generate consistent risk-adjusted returns from validated market signals can fund its own inference costs, storage, and compute without external subsidy.

This is not a hypothetical future. The signal exists today. The API is live. The research validation is published and citable. An agent integrating this as a tool in its action space gains access to a statistically grounded market edge — not a rule of thumb, not a heuristic, but a documented, reproducible finding derived from 188.5 million real orders.

The vision: AI systems that are financially self-sustaining because their decision-making is grounded in validated quantitative signals rather than synthetic reasoning alone.

Integration guide

01Get an API key — an agent can do it without a browserbash

# Free key for the person you act for (works immediately for 24h):
curl -X POST https://api.optionwhales.io/v1/account/register \
  -H "Content-Type: application/json" \
  -d '{"email": "person@example.com", "agent_name": "MyAgent"}'

# They get "Confirm your OptionWhales API key" — confirm with the code:
curl -X POST https://api.optionwhales.io/v1/account/confirm \
  -H "Content-Type: application/json" -d '{"code": "<code from the email>"}'

# Or register in a browser: https://optionwhales.io/register
# Free: 10 req/min, previews. Pro: 60 req/min, every endpoint.

02Fetch the day's ranked flow signalbash

curl "https://api.optionwhales.io/v1/momentum/rankings?top=50" \
  -H "X-API-Key: YOUR_KEY"

# Momentum-sorted ticker rankings.
# Free: top 3, limited fields. Pro: all tickers, full fields.

03Stream real-time abnormal trade alertspython

import websocket, json, os

API_KEY = os.environ["OW_API_KEY"]

# A WebSocket handshake cannot carry custom headers — WS auth is the
# ?api_key= query parameter, unlike the REST routes above.
ws = websocket.create_connection(
    f"wss://api.optionwhales.io/v1/ws/abnormal-trades?api_key={API_KEY}"
)
while True:
    trade = json.loads(ws.recv())
    # trade: { ticker, strike, expiry, premium, direction, signal_score }
    agent.process_signal(trade)

04Query intent momentum rankingstypescript

const res = await fetch(
  'https://api.optionwhales.io/v1/momentum/rankings',
  { headers: { 'X-API-Key': process.env.OW_API_KEY } }
);
const { rankings } = await res.json();
// rankings[0]: { ticker, score, direction, cluster, conviction }

05Stream real-time prices for your watchlistpython

# Set your real-time watchlist (Pro: up to 25 symbols)
curl -X PUT https://api.optionwhales.io/v1/quotes/watchlist \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"symbols": ["SPY", "NVDA", "QQQ"]}'

# Then stream 1 Hz quotes over WebSocket
ws = websocket.create_connection(
    "wss://api.optionwhales.io/v1/stream/quotes?api_key=YOUR_KEY")
ws.send(json.dumps({"type": "subscribe", "symbols": ["SPY", "NVDA"]}))
while True:
    msg = json.loads(ws.recv())  # {type:"quotes", data:[{symbol,price,...}]}
    agent.on_price(msg)

API tiers

Feature	Free	Pro ($19/mo)
Flow rankings	Top 3 tickers	All tickers
Abnormal trades	Top 5 per session	Full feed
Real-time quotes + OHLC candles	—	Watchlist (25 symbols)
Real-time quote stream (WS)	—	1 Hz push
Momentum rankings (/v1/momentum/rankings)	Top 3	All tickers
Historical flow sessions (/v1/flow/{session})	—	✓
WebSocket streaming	—	✓
Momentum rankings	Current only	Full + history
Rate limit	10 req/min / 200/day	60 req/min / 5,000/day
OpenClaw skill	Read-only preview	Full access

Start building

Free tier available immediately — no credit card, API key in under a minute. Full strategy portfolio and WebSocket access on Pro.

Get API Key Free Full API Docs Read the Research

Opening Pressure Signal Explained →Return Prediction Research Paper →Detecting Institutional Flow →Compare Flow Tools →