Skill: ssidharhubble/options-flow-intelligence (version 1.0.0)

--- name: options-flow-intelligence description: | Real-time institutional options flow intelligence and momentum analysis for AI agents. Fetches live option flow data from OptionWhales API including current institutional flow, per-ticker momentum, abnormal trade detection, and direction bias indicators across major US equities. Built for volatility traders and algo systems decoding dark pool options activity. Commands: - optionflow.py flow Get current market-wide option flow - optionflow.py momentum View top momentum stock rankings - optionflow.py abnormal Detect unusual options activity - optionflow.py ticker SYMBOL Get specific ticker flow (e.g., AAPL, TSLA) Environment: OPTIONWHALES_API_KEY required. Python 3.7+, zero deps beyond stdlib. Example output includes intent_momentum scores, premium volumes, direction bias, and momentum rankings. Scores range from 0-100 with higher values indicating stronger institutional conviction. Useful for catching early signals before earnings events, identifying sector rotation through options flow, and building automated alerts for whale-sized option positions. compatibility: Created for Zo Computer metadata: author: ssyopros.zo.computer allowed-tools: Bash, Read --- # Options Flow Intelligence Fetches real-time institutional options flow data from the OptionWhales API to detect whale trades, momentum shifts, and abnormal activity across US equities. ## Setup Set your API key: ```bash export OPTIONWHALES_API_KEY="your_key_here" ``` ## Commands ```bash # Market-wide flow (top 20 by momentum) python scripts/optionflow.py flow # Top momentum stocks python scripts/optionflow.py momentum # Abnormal trades (potential insider activity) python scripts/optionflow.py abnormal # Specific ticker deep dive python scripts/optionflow.py ticker AAPL python scripts/optionflow.py ticker TSLA python scripts/optionflow.py ticker NVDA ``` ## Output Interpretation - **Signal scores** range from 0-100, higher = stronger institutional conviction - **Direction** shows whether smart money is buying calls (bullish) or puts (bearish) - **Premium** shows total dollar value of options activity - **Momentum rankings** show which stocks have the strongest options activity today ## Integration with Trading Systems The JSON output can be piped to other tools: ```bash python scripts/optionflow.py flow | grep "BULLISH" | head -5 ``` Use in automated alerting by setting up cron jobs or integrating with notification systems. ## Data Freshness Data refreshes every few minutes. For real-time streaming, consider the WebSocket API which is available on OptionWhales Pro plans. The current script focuses on REST API polling which is suitable for most use cases without requiring WebSocket infrastructure.

path: README.md
content: # Options Flow Intelligence Skill

Real-time institutional options flow intelligence that fetches live data from OptionWhales API to detect whale trades, momentum shifts, and abnormal options activity across major US equities.

## Features

- **Current Option Flow** - Market-wide view of institutional option activity
- **Ticker Analysis** - Deep dive into specific stock option flow
- **Momentum Rankings** - Top stocks by options momentum score
- **Abnormal Trade Detection** - Flags unusual options activity
- **Python 3.7+ Compatible** - Zero external dependencies

## Setup

```bash
# Set your OptionWhales API key
export OPTIONWHALES_API_KEY="your_api_key_here"

# Run the script
python scripts/optionflow.py flow
python scripts/optionflow.py momentum
python scripts/optionflow.py ticker AAPL
python scripts/optionflow.py abnormal
```

## Use Cases

- Filter high-signal unusual options activity (uOA)
- Build option flow trading dashboards
- Generate automated alerts for momentum shifts
- Backtest option flow signals against price action
- Incorporate into quantitative trading models

path: scripts/optionflow.py
content: #!/usr/bin/env python3
"""
Options Flow Intelligence Script
Fetches real-time option flow data from OptionWhales API including:
- Current institutional option flow
- Per-ticker flow details with momentum and abnormal trade signals
- Momentum rankings across the market
- Historical flow for trend analysis
"""

import json
import sys
import os
from datetime import datetime

[REDACTED_SECRET]"OPTIONWHALES_API_KEY", "")
BASE_URL = "https://api.optionwhales.com/v1"


def fetch_json(endpoint: str) -> dict:
    """Make authenticated API request to OptionWhales."""
    if not [REDACTED_SECRET]"ERROR: OPTIONWHALES_API_KEY environment variable not set")
        print("Get your API key at: https://optionwhales.com/api")
        sys.exit(1)

    import urllib.request
    url = f"{BASE_URL}{endpoint}"
    req = urllib.request.Request(url, headers={"X-API-Key": API_KEY})
    try:
        with urllib.request.urlopen(req, timeout=15) as resp:
            return json.loads(resp.read().decode())
    except Exception as e:
        print(f"ERROR: Failed to fetch {endpoint}: {e}")
        sys.exit(1)


def get_current_flow(limit: int = 20) -> None:
    """Fetch current institutional option flow across all tickers."""
    print(f"\n=== CURRENT OPTION FLOW (Top {limit}) ===")
    print(f"Fetched: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
    data = fetch_json(f"/flow/current?limit={limit}")
    for item in data.get("flow", [])[:limit]:
        ticker = item.get("ticker", "N/A")
        direction = item.get("direction", "N/A")
        volume = item.get("volume", 0)
        premium = item.get("premium", 0)
        signal = item.get("intent_momentum", "N/A")
        print(f"  [{signal}] {ticker} | {direction} | Vol: {volume:,} | Premium: ${premium:,.0f}")
    print()


def get_ticker_flow(ticker: str) -> None:
    """Get detailed option flow for a specific ticker."""
    print(f"\n=== OPTION FLOW: {ticker.upper()} ===\n")
    data = fetch_json(f"/flow/current/{ticker.upper()}")

    if not data.get("flow"):
        print(f"No active flow data for {ticker.upper()}")
        return

    item = data["flow"][0]
    print(f"Ticker:       {item.get('ticker')}")
    print(f"Direction:    {item.get('direction')}")
    print(f"Volume:       {item.get('volume', 0):,}")
    print(f"Premium:      ${item.get('premium', 0):,.0f}")
    print(f"Signal:       {item.get('intent_momentum', 'N/A')}")
    print(f"Momentum:     {item.get('momentum_rank', 'N/A')}")
    if item.get("abnormal_trade"):
        print(f"ABNORMAL:     Yes")
    print()


def get_momentum_rankings(limit: int = 20) -> None:
    """Get top momentum rankings - stocks with strongest option activity."""
    print(f"\n=== TOP {limit} MOMENTUM STOCKS ===\n")
    data = fetch_json(f"/momentum/rankings?limit={limit}")
    for rank, item in enumerate(data.get("rankings", [])[:limit], 1):
        ticker = item.get("ticker", "?")
        score = item.get("momentum_score", 0)
        bias = item.get("direction_bias", "N/A")
        vol = item.get("volume_change_pct", 0)
        print(f"  {rank:2d}. {ticker:6s} | Score: {score:.1f} | Bias: {bias:6s} | Vol Chg: {vol:+.0f}%")
    print()


def get_abnormal_trades(limit: int = 15) -> None:
    """Get abnormal options trades - potential insider activity."""
    print(f"\n=== ABNORMAL OPTIONS TRADES (Last {limit}) ===\n")
    data = fetch_json(f"/abnormal-trades/current?limit={limit}")
    for trade in data.get("trades", [])[:limit]:
        ticker = trade.get("ticker", "?")
        vol = trade.get("volume", 0)
        premium = trade.get("premium", 0)
        unusual = trade.get("unusual_size", False)
        flag = "⚠️ UNUSUAL" if unusual else ""
        print(f"  {ticker:6s} | Vol: {vol:,} | Premium: ${premium:,.0f} {flag}")
    print()


def main():
    if len(sys.argv) < 2:
        print("Usage: python optionflow.py <command> [args]")
        print("Commands:")
        print("  flow              - Show current market-wide option flow")
        print("  momentum          - Show top momentum stocks")
        print("  abnormal          - Show abnormal option trades")
        print("  ticker <SYMBOL>   - Get flow for specific ticker (e.g., AAPL)")
        print("\nEnvironment: OPTIONWHALES_API_KEY required")
        sys.exit(1)

    cmd = sys.argv[1].lower()

    if cmd == "flow":
        get_current_flow(int(sys.argv[2]) if len(sys.argv) > 2 else 20)
    elif cmd == "momentum":
        get_momentum_rankings(int(sys.argv[2]) if len(sys.argv) > 2 else 20)
    elif cmd == "abnormal":
        get_abnormal_trades(int(sys.argv[2]) if len(sys.argv) > 2 else 15)
    elif cmd == "ticker" and len(sys.argv) > 2:
        get_ticker_flow(sys.argv[2])
    else:
        print(f"Unknown command: {cmd}")
        sys.exit(1)


if __name__ == "__main__":
    main()

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)