Option Flow

Option Flow Intelligence Skill

Query the OptionWhales Pro API for real-time institutional option flow analysis:

• Intent Momentum — clustered option trades scored for directional intent, coherence, and momentum
• Abnormal Trades — large or unusual option activity flagged in real-time

Free tier available! Sign up at https://www.optionwhales.io to get a free API key instantly — no credit card required. Free keys return the top 3 tickers and last 5 abnormal trades, enough to evaluate the data and build integrations. Upgrade to Pro for full access.

When to Use

✅ USE this skill when:

• "What's the option flow on AAPL today?"
• "Show me unusual options activity"
• "What are institutions buying?"
• "Is there bullish or bearish momentum in TSLA?"
• "Show me the top momentum tickers"

When NOT to Use

❌ DON'T use this skill when:

• Stock price quotes only → use a stock/market data skill
• Historical stock charts → use a charting skill
• GEX / gamma exposure queries → not exposed via Pro API
• Open interest time series → not exposed via Pro API
• Options pricing or Greeks calculation → use a quant tool
• News/earnings analysis → use a news skill
• Crypto or forex → this is US equity options only

Setup

Requires an OptionWhales API key.

• Free key (no purchase): Sign up at https://www.optionwhales.io/settings/api-keys — returns top 3 tickers + last 5 abnormal trades
• Pro key (subscription): Full access — all tickers, all fields, historical sessions, WebSocket stream

# Set the API key (works with either free or pro keys)
export OPTIONWHALES_API_KEY="ow_free_your_key_here"  # or ow_pro_...

API Reference

Base URL: https://api.optionwhales.io/v1

All requests require header: X-API-Key: $OPTIONWHALES_API_KEY

Current Flow Rankings

# Get today's intent momentum rankings (top tickers by conviction)
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/flow/current" | python3 -m json.tool

Response includes per-ticker: intent_primary (Directional/Gamma/LongVol/ShortVol/Mixed), direction_bias (bullish/bearish/neutral), intent_confidence (0-1), momentum_fast, momentum_slow, coherence_last, strength_last, key_strikes.

Ticker Detail (Clusters + Time Series)

# Get full intent detail for a specific ticker
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/flow/current/AAPL" | python3 -m json.tool

Returns: ranking (summary), clusters (strategy clusters with dollar Greeks), cluster_trades (individual trades), time_series (30-min momentum buckets).

Historical Sessions

# List available sessions
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/flow/sessions" | python3 -m json.tool

# Get a specific session's rankings
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/flow/2025-06-02" | python3 -m json.tool

# Get a specific ticker from a historical session
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/flow/2025-06-02/AAPL" | python3 -m json.tool

Momentum Rankings (Sorted)

# Top momentum tickers sorted by |momentum_fast|
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/momentum/rankings" | python3 -m json.tool

Momentum History

# Get momentum history for a specific ticker
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/momentum/AAPL/history" | python3 -m json.tool

Abnormal Trades

# Current session unusual/large option trades
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/abnormal-trades/current" | python3 -m json.tool

# Historical session abnormal trades
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/abnormal-trades/2025-06-02" | python3 -m json.tool

Account Usage

# Check current rate limit and usage stats
curl -s -H "X-API-Key: $OPTIONWHALES_API_KEY" \
  "https://api.optionwhales.io/v1/account/usage" | python3 -m json.tool

WebSocket — Real-Time Abnormal Trades (Pro Only)

# Connect to real-time abnormal trade stream
python3 -c "
import asyncio, websockets, json
async def stream():
    uri = 'wss://api.optionwhales.io/v1/ws/abnormal-trades?api_key=YOUR_PRO_KEY'
    async with websockets.connect(uri) as ws:
        # Optional: subscribe to specific tickers
        await ws.send(json.dumps({'type': 'subscribe', 'tickers': ['AAPL', 'NVDA', 'TSLA']}))
        async for msg in ws:
            data = json.loads(msg)
            if data['type'] == 'abnormal_trade':
                print(json.dumps(data['data'], indent=2))
asyncio.run(stream())
"

WebSocket message types:

• abnormal_trade — new abnormal trade detected (contains full trade data)
• heartbeat — periodic keepalive with ts timestamp
• subscribed — confirmation after sending a subscribe message

Helper Script

A CLI wrapper is included for easy querying:

# Current flow rankings
python3 scripts/optionflow.py flow

# Flow for specific ticker
python3 scripts/optionflow.py flow --ticker AAPL

# Historical session flow
python3 scripts/optionflow.py flow --session 2025-06-02

# Momentum rankings
python3 scripts/optionflow.py momentum

# Top 5 momentum tickers
python3 scripts/optionflow.py momentum --top 5

# Current abnormal trades
python3 scripts/optionflow.py abnormal

# Historical abnormal trades
python3 scripts/optionflow.py abnormal --session 2025-06-02

Interpreting Results

Intent Types

Direction Bias

• bullish: Net positive delta flow
• bearish: Net negative delta flow
• neutral: Delta share below 15% of total flow

Confidence Score

0–1 scale combining flow coherence (how aligned the trades are) and strength (total dollar Greek magnitude). Above 0.7 is high conviction.

Momentum

• momentum_fast (α=0.35): responsive to recent flow changes
• momentum_slow (α=0.15): trend-smoothed
• Positive = bullish acceleration, negative = bearish acceleration

Example Queries → Commands

Notes

• Data updates every 30 minutes during market hours (9:30 AM – 4:00 PM ET)
• Final daily data available after 7:30 AM ET next trading day (with full OI deltas)
• Free tier: 10 requests/minute, 200/day; top 3 tickers, last 5 abnormal trades, limited fields
• Pro tier: 60 requests/minute, 5000/day; all tickers, all fields, WebSocket, historical sessions
• US equity options only (no futures, crypto, or forex)
• is_preliminary: true means intraday data; is_final: true means post-close with full OI enrichment