OptionWhales Intelligence Skill

Two capabilities in one skill:

1. 1. Option Flow — query the OptionWhales Pro API for real-time institutional

option flow analysis (intent momentum, abnormal trades, rankings).

1. 2. AI Reports — generate and retrieve AI-powered trade analysis reports via

a 22-node LLM pipeline (market analysis, flow, fundamentals, news, bull/bear debate, risk assessment, BUY/SELL/HOLD recommendation).

Free tier available! Sign up at https://www.optionwhales.io to get a free
API key instantly — no credit card required.

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"
• "Generate an AI report for TSLA"
• "What's the AI analysis on SPY today?"
• "Show my report history"
• "Check my report generation quota"

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 API
• Options pricing or Greeks calculation → use a quant tool
• Crypto or forex → this is US equity options only

Setup

Option Flow (required)

Requires an OptionWhales API key.

• - Free key: Sign up at https://www.optionwhales.io/settings/api-keys
• Pro key: Full access — all tickers, all fields, historical sessions

CODEBLOCK0

AI Reports (optional)

Requires an AI service Bearer token (contact system administrator).

CODEBLOCK1

---

Part 1 — Option Flow API

Base URL: INLINECODE0

All requests require header: INLINECODE1

Flow API Reference

Current Flow Rankings

CODEBLOCK2

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)

CODEBLOCK3

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

Historical Sessions

CODEBLOCK4

Momentum Rankings

CODEBLOCK5

Momentum History

CODEBLOCK6

Abnormal Trades

CODEBLOCK7

Account Usage

CODEBLOCK8

WebSocket — Real-Time Abnormal Trades (Pro Only)

CODEBLOCK9

Flow Helper Script

CODEBLOCK10

Interpreting Flow 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
• INLINECODE15 (α=0.15): trend-smoothed
• Positive = bullish acceleration, negative = bearish acceleration

---

Part 2 — AI Report Service

Base URL: INLINECODE16

All requests require header: INLINECODE17

Credit System

Tier	Credits/Day	Can Generate?
FREE	0	No — hard-blocked
TRIAL

5 | Yes | | PRO | 5 | Yes | | ADMIN | Unlimited | Yes |

Additional constraints:

• - 5-minute cooldown per ticker after a successful generation
• ≥10% premium increase required to regenerate for the same ticker
• Credits reset daily at 12:00 AM ET

AI Report API Reference

Generate a Report

CODEBLOCK11

Returns: INLINECODE18

Poll Job Status

CODEBLOCK12

Fetch Report (JSON)

CODEBLOCK13

Fetch Report (Markdown)

CODEBLOCK14

Report History

CODEBLOCK15

Per-Ticker Summary

CODEBLOCK16

Check Quota

CODEBLOCK17

Check Eligibility

CODEBLOCK18

Health Check

CODEBLOCK19

AI Report Helper Script

CODEBLOCK20

Interpreting AI Report Results

Decision Actions

Action	Meaning
BUY	Bullish — AI recommends long exposure on the underlying
SELL

Bearish — AI recommends short exposure / protective puts |

| HOLD | Neutral — no new directional exposure recommended |

Confidence Score

0–100 scale reflecting the AI pipeline's conviction. Above 70% = high conviction; below 50% = conflicting signals.

Report Sections

Section	Content
Option Flow	Institutional flow analysis, intent momentum, flow coherence
Abnormal Flow

Large/unusual trades flagged by the detection engine |

| Market Structure | GEX levels, call/put walls, max pain, key strike zones | | Market | Macro indicators, OHLCV, technical levels | | Fundamentals | Company fundamentals, valuation metrics | | News | Recent news sentiment analysis | | Debate | Bull vs Bear researcher arguments with judge decision | | Risk | Three-analyst risk assessment (aggressive, conservative, neutral) |

---

Example Queries → Commands

User asks	Tool
"What's the flow today?"	INLINECODE19
"Show TSLA option activity"

python3 {baseDir}/scripts/optionflow.py flow --ticker TSLA | | "Top momentum tickers" | python3 {baseDir}/scripts/optionflow.py momentum | | "Any unusual trades?" | python3 {baseDir}/scripts/optionflow.py abnormal | | "Is AAPL bullish or bearish?" | python3 {baseDir}/scripts/optionflow.py flow --ticker AAPL → check direction_bias | | "Generate AI report for TSLA" | python3 {baseDir}/scripts/aireport.py generate --ticker TSLA --user-id <user> --user-tier PRO | | "Show my report history" | python3 {baseDir}/scripts/aireport.py summary --user-id <user> --trading-day <today> | | "Check my report quota" | python3 {baseDir}/scripts/aireport.py quota --user-id <user> --tier PRO | | "Show my API usage" | python3 {baseDir}/scripts/optionflow.py usage |

Notes

• - Option flow 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
• Pro tier: 60 requests/minute, 5000/day; all tickers, all fields, WebSocket, historical sessions
• AI reports take 30–90 seconds to generate (22-node pipeline)
• US equity options only (no futures, crypto, or forex)