SkillHub

optionwhales

v1.0.0

Query real-time option flow intelligence — intent momentum, trade clustering, and abnormal trade detection. Use when users ask about option flow, unusual options activity, institutional positioning, or market sentiment from derivatives.

Sourced from ClawHub, Authored by psdsam-NiuNiuKing

Installation

Please help me install the skill `optionwhales` from SkillHub official store. npx skills add psdsam-NiuNiuKing/optionwhales

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

Intent Meaning
Directional Net delta-dominant flow — strong directional bet
Gamma Gamma-dominant — positioning for rapid price moves
LongVol Buying volatility (long vega, positive theta risk)
ShortVol Selling volatility (short vega, positive theta)
Mixed No dominant Greek — conflicting signals

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

User asks Command
"What's the flow today?" GET /v1/flow/current
"Show TSLA option activity" GET /v1/flow/current/TSLA
"Top momentum tickers" GET /v1/momentum/rankings
"Any unusual trades?" GET /v1/abnormal-trades/current
"Is AAPL bullish or bearish?" GET /v1/flow/current/AAPL → check direction_bias
"What sessions are available?" GET /v1/flow/sessions
"Show my API usage" GET /v1/account/usage

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