Pro API Documentation

Quick Start

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.optionwhales.io/v1/flow/current

Authentication

# Header (recommended)
curl -H "X-API-Key: ow_pro_abc123..." https://api.optionwhales.io/v1/flow/current

# Query parameter
curl "https://api.optionwhales.io/v1/flow/current?api_key=ow_pro_abc123..."

Rate Limits

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1700000060

X-FlowRows-Limit: 150000
X-FlowRows-Remaining: 148750
X-FlowRows-Reset: 1700006400

Data Freshness

"data": {
  "realtime": false,
  "delay_seconds": 900,
  "delay_reason": "policy_off_watchlist",
  "as_of": "2026-08-08T15:24:32Z"
}

Free vs Pro

Endpoints

Intent Flow

Momentum

Abnormal Trades

Account

Earnings Intelligence

Option order signals, BS Greeks, and directional intent for tickers with earnings events. Pro keys only — no free-tier preview.

Economic Events & ETF Flow

Macro event calendar and ETF option flow for SPY, QQQ, IWM, TLT. Pro keys only.

Directional Score

Composite bull/bear score derived from net notional, order clustering, and IV signals — the data behind the Market Intelligence scatter plot. Pro keys only.

GEX — Gamma Exposure

Per-strike gamma exposure profiles, key price levels (gamma flip, max pain, call/put wall), and multi-session GEX trends. Pro keys only.

# 0DTE gamma profile
curl -H "X-API-Key: $KEY"   "https://api.optionwhales.io/v1/gex/2026-08-14/SPY/greek-exposure?dte_filter=0dte"

# 0DTE intraday GEX, sampled every 30 minutes
curl -H "X-API-Key: $KEY"   "https://api.optionwhales.io/v1/gex/2026-08-14/SPY/intraday-exposures?dte_filter=0dte&step_min=30"

# note: 0+1 must be URL-encoded, a bare + decodes to a space
  "...?dte_filter=0%2B1"

Real-Time Stock Quotes & Candles

Live underlying prices and intraday OHLC candles, sourced from a direct market-data feed (sub-second spot). Pro keys only — free tier receives no real-time quotes. Real-time symbols are bounded by a per-key watchlist: the product is option-driven, so you stream the handful of underlyings you trade, not the whole market.

Implied Volatility

Implied-volatility analytics: the full IV surface, ATM-IV term structure, multi-session ATM-IV(30d) history, per-cell IV percentile / z-score / bands, batch ATM-IV, and top IV movers. Pro keys only.

Open Interest

Open-interest built from twice-daily (AM/PM ET) full-chain snapshots: per-ticker OI and volume timeseries, snapshot-to-snapshot OI change, latest snapshot, and per-contract OI lookups by OCC symbol. Pro keys only.

Net-Premium Tide

Signed net-premium flow — market-wide, per-sector, and per-ticker — split call/put, bucketed by DTE and moneyness, with an intraday cumulative curve. Built from large orders only (not the full tape); direction is an aggressor-NBBO classification (BUY = premium paid, SELL = premium received). Every response carries a basis block. Pro keys only.

Option Contracts

Per-contract addressability by OCC symbol: chain enumeration, ATM chains and expiry breakdown for an underlying, plus a contract profile, daily OHLC history and intraday minute bars. Chain / OI / IV / greeks are as-of the last snapshot (up to ~12h stale); daily bars reach ~1yr back, intraday is a recent window. Pro keys only.

Options Flow Tape — contract level

The recorded large-order tape at OCC-contract granularity. Every option order whose grouped size cleared 100 contracts, across the full listed universe — order-grouped, direction-classified and IV/delta-enriched. This is our own recording, not a raw vendor print feed.

MCP Server — AI Agents

A Model Context Protocol (MCP) endpoint that exposes the API as agent tools for Claude Desktop, Cursor, and other MCP clients — JSON-RPC 2.0 over Streamable HTTP. Authenticate with your Pro key in the X-API-Key header. Tools include intent flow, directional score, abnormal trades, GEX levels, dark-pool ranking, earnings, economic calendar, and IV analytics.

Seasonality

Average close-to-close return by calendar month, with the historical hit rate, computed over a multi-year window. Pro keys only.

Fundamentals & Corporate Actions

Company financial statements plus dividend, split, and IPO history. Pro keys only.

SEC Filings — Insider & 13F

SEC Form 4 insider transactions (ticker-centric) and 13F-HR institutional holdings (by filer CIK). Pro keys only.

Technical Indicators

SMA / EMA / RSI / MACD time series on adjusted closes. Pro keys only.

News & Sentiment

Recent ticker news, each article tagged with a pre-computed per-ticker sentiment (positive / negative / neutral) and a short reasoning. Pro keys only.

Short Selling

FINRA short-interest (bi-weekly settlement) and short-volume (daily, with a per-venue NYSE / Nasdaq / ADF split). Pro keys only.

Congress Trades

Congressional stock trades from House (Clerk PTR filings) and Senate disclosures. PTR transactions (not holdings) — bracketed amounts and a ~45-day disclosure lag; narrative/context, not a real-time signal. Pro keys only.

FDA / Catalyst Calendar

Upcoming pharma/biotech catalysts — Phase 2/3 clinical-trial readout dates (primary-completion) from ClinicalTrials.gov, joined to tickers via the SEC company spine. These are estimated readout dates (they slip), not PDUFA decision dates — a narrative/context calendar to cross-reference against options flow, not a real-time signal. Pro keys only.

Multi-Signal Screener

Rank and filter tickers across our signals in one call — options-flow net premium, day-over-day OI change, upcoming FDA catalysts, and recent congressional activity. The differentiator is the cross-signal filter ("bullish flow AND rising OI AND an FDA catalyst within 30 days") that no single endpoint does. Each result lists which signals fired. Pro keys only.

Dark Pool / Off-Exchange

Off-exchange (TRF-reported) equity prints and the analytics built on them: detected block trades with rolling-percentile baselines and %ADV, NBBO-location flow pressure (per window and cumulative intraday curves), options-confirmation alerts, whole-market rankings, and the raw print tape. ~90 days of history, ~400-ticker calibrated universe. Pro keys only.

WebSocket Streaming

wss://api.optionwhales.io/v1/ws/abnormal-trades?api_key=YOUR_PRO_KEY

{"type": "subscribe", "tickers": ["AAPL", "NVDA", "TSLA"]}

import asyncio
import json
import websockets

API_KEY = "ow_pro_your_key_here"
URL = f"wss://api.optionwhales.io/v1/ws/abnormal-trades?api_key={API_KEY}"

async def stream_trades():
    async with websockets.connect(URL) as ws:
        print("Connected! Waiting for trades...")
        async for message in ws:
            data = json.loads(message)
            if data.get("type") == "abnormal_trade":
                trade = data["data"]
                print(f"{trade['ticker']} {trade['side']} ${trade['premium']:,.0f}")
            elif data.get("type") == "heartbeat":
                print(".", end="", flush=True)

asyncio.run(stream_trades())

const API_KEY = "ow_pro_your_key_here";
const url = `wss://api.optionwhales.io/v1/ws/abnormal-trades?api_key=${API_KEY}`;

const ws = new WebSocket(url);

ws.onopen = () => console.log("Connected!");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === "abnormal_trade") {
    console.log(`${data.data.ticker} ${data.data.side} $${data.data.premium}`);
  }
};

ws.onerror = (err) => console.error("WebSocket error:", err);
ws.onclose = () => console.log("Disconnected");

Flow Tape WebSocket

wss://api.optionwhales.io/v1/ws/flow?api_key=YOUR_PRO_KEY

{"type": "subscribe", "tickers": ["SPY", "QQQ", "NVDA"]}

import asyncio
import json
import websockets

API_KEY = "ow_pro_your_key_here"
URL = f"wss://api.optionwhales.io/v1/ws/flow?api_key={API_KEY}"

async def stream_flow():
    async with websockets.connect(URL) as ws:
        await ws.send(json.dumps({"type": "subscribe",
                                  "tickers": ["SPY", "QQQ", "NVDA"]}))
        async for message in ws:
            msg = json.loads(message)
            if msg.get("type") == "flow_order":
                o = msg["data"]["order"]
                print(f"{msg['data']['ticker']} {o['option_ticker']} "
                      f"x{o['total_contracts']} {o['direction']} "
                      f"${o['premium']:,.0f}")
            elif msg.get("type") == "subscribed":
                print("streaming:", msg["tickers"], "rejected:", msg["rejected"])

asyncio.run(stream_flow())

{
  "type": "flow_order",
  "data": {
    "ticker": "SPY", "event_id": "327394957d78e1e5976e2d6b7c8fc74c",
    "session_date": "2026-08-10", "ts_ms": 1786392892183,
    "order": {
      "timestamp": "2026-08-10 20:14:52.183000+00:00",
      "option_ticker": "O:SPY260810C00721000", "option_type": "Call",
      "strike": 721.0, "expiration": "2026-08-10",
      "total_contracts": 301, "premium": 37625.0, "total_notional": 21716330.0,
      "avg_price": 1.25, "avg_bid": 1.24, "avg_ask": 1.26,
      "direction": "buy", "direction_confidence": 0.94, "order_type": "sweep",
      "spot_price": 721.4, "implied_volatility": 0.196, "delta": 0.329,
      "trade_count": 9, "exchange_count": 3, "time_span_ms": 412,
      "enrich_status": "complete"
    }
  }
}

Health Check

curl https://api.optionwhales.io/health

{
  "status": "healthy",
  "service": "pro-api",
  "version": "1.0.0",
  "ws_connections": 0
}

Error Codes