---

name: unusual-whales-api description: > Query the Unusual Whales API for unusual options flow, dark pool prints, market tide sentiment, gamma exposure, congressional trading, and stock greeks. Use when someone asks about "unusual options activity", "whale trades", "dark pool prints", "market sentiment", "gamma exposure", "GEX", "congressional trading", "insider trading", or needs real-time and historical market data for trading analysis and AI agent integration. license: Apache-2.0 compatibility: "Python 3.9+ with httpx, or any HTTP client; requires an Unusual Whales API token" metadata: author: terminal-skills version: "1.1.0" category: data-ai tags: - finance - options - trading - dark-pool - market-data

Unusual Whales API

Overview

Query the Unusual Whales API for institutional-grade market data — unusual options flow, dark pool prints, market tide sentiment, gamma exposure, congressional trading, and stock greeks.

When to Use

Use this skill when the user asks for financial data related to:

• Unusual options activity, "whale" trades, flow alerts, or "hottest chains"
• Dark pool prints, trades, or levels
• Market sentiment (Market Tide, Net Premium, Put/Call ratios)
• Insider trading, politician trading, or specific stock/option details (Greeks, IV)
• Gamma exposure (GEX) analysis
• Building AI-powered trading systems or market analysis tools

Prerequisites

• Unusual Whales API key (get one at https://unusualwhales.com/api_lander)
• Set UNUSUAL_WHALES_API_TOKEN in your environment
• Plans and prices change; check https://unusualwhales.com/public-api before quoting a price
• Official agent rules the vendor publishes: https://unusualwhales.com/skill.md (re-read it when an endpoint fails)

Instructions

Critical Rules (Anti-Hallucination Protocol)

Base URL: Always use https://api.unusualwhales.com

Authentication: All requests MUST include both headers:

Authorization: Bearer $UNUSUAL_WHALES_API_TOKEN
UW-CLIENT-API-ID: 100001

Method: All endpoints are GET requests. Never use POST, PUT, or DELETE.

Strict Whitelist: You may ONLY use endpoints listed in the "Valid Endpoint Reference" section below. If a URL is not on that list, it does not exist.

Hallucination Blacklist (NEVER USE THESE)

These endpoints are fake but commonly hallucinated by AI models:

• ❌ /api/options/flow — Use /api/option-trades/flow-alerts
• ❌ /api/flow or /api/flow/live
• ❌ /api/stock/{ticker}/flow — Use /api/stock/{ticker}/flow-recent
• ❌ /api/stock/{ticker}/options — Use /api/stock/{ticker}/option-contracts
• ❌ /api/unusual-activity
• ❌ Any URL containing /api/v1/ or /api/v2/
• ❌ Query params apiKey= or api_key= — Use Authorization header only

Concept Mapping

Translate user intent to the correct endpoint:

• "Live Flow" / "Whale Trades" / "Option Flow" → /api/option-trades/flow-alerts
• "Options Filter" / "Options Screener" / "Flow Filter" → /api/screener/option-contracts
• "Market Sentiment" → /api/market/market-tide
• "Dark Pool" → /api/darkpool/recent or /api/darkpool/{ticker}
• "Contract Greeks" → /api/stock/{ticker}/greeks
• "Spot Gamma" / "Spot GEX" / "GEX" / "Gamma Exposure" → /api/stock/{ticker}/spot-exposures/strike

Valid Endpoint Reference

Core Data & Flow

• Option Trades (tape prints, latest trading day): /api/option-trades
  • Params: limit, ticker_symbol, min_premium, max_premium, min_dte, max_dte, is_otm, opening, size_greater_oi, volume_greater_oi, newer_than/older_than (Unix seconds or ms), list params as tags[]=ask_side
• Flow Alerts (Unusual Activity): /api/option-trades/flow-alerts
  • Params: limit, is_call, is_put, is_otm, min_premium, ticker_symbol, size_greater_oi
• Options Screener (Hottest Chains): /api/screener/option-contracts
  • Params: limit, min_premium, type, is_otm, issue_types[], min_volume_oi_ratio
• Recent Ticker Flow: /api/stock/{ticker}/flow-recent
• Dark Pool (Ticker): /api/darkpool/{ticker}
• Dark Pool (Market Wide): /api/darkpool/recent
• Market Tide: /api/market/market-tide
• Net Premium Ticks: /api/stock/{ticker}/net-prem-ticks

Options, Greeks & IV

• Option Contracts List: /api/stock/{ticker}/option-contracts
• Greeks for Each Strike & Expiry: /api/stock/{ticker}/greeks
• Static Gamma Exposure (GEX) by Strike: /api/stock/{ticker}/greek-exposure/strike
• Spot Gamma Exposure (GEX) by Strike: /api/stock/{ticker}/spot-exposures/strike
• Interpolated IV and Percentiles: /api/stock/{ticker}/interpolated-iv
• Options Volume/PC Ratio: /api/stock/{ticker}/options-volume

Fundamentals & Technicals

• Financials: /api/stock/{ticker}/financials (also /income-statements, /balance-sheets, /cash-flows, /earnings with report_type)
• Technical indicator: /api/stock/{ticker}/technical-indicator/{function} (params interval, time_period, series_type)

Other Data

• Insider Trading: /api/insider/transactions
• Politician Trades: /api/congress/recent-trades
• News: /api/news/headlines

Examples

Example 1: Detect Smart Money Sweeps

User prompt: "Show me the latest unusual option trades for TSLA."

# unusual_whales_flow.py — Fetch unusual options flow alerts for a ticker
import os
import httpx

url = "https://api.unusualwhales.com/api/option-trades/flow-alerts"
headers = {
    "Authorization": f"Bearer {os.environ['UNUSUAL_WHALES_API_TOKEN']}",
    "UW-CLIENT-API-ID": "100001",
}
params = {
    "ticker_symbol": "TSLA",
    "min_premium": 50_000,       # Minimum $50K premium
    "size_greater_oi": True,     # Opening trades where size > open_interest
    "limit": 10,
    "is_otm": True               # Out-of-the-money only
}
response = httpx.get(url, headers=headers, params=params)
trades = response.json().get("data", [])

for trade in trades:
    print(f"{trade['ticker']} | {trade['type']} | ${trade['total_premium']:,.0f}")

Example 2: Screen for Unusually Bullish Activity

User prompt: "Show me unusually bullish option activity for today."

# unusual_whales_screener.py — Screen for bullish options activity
import os
import httpx

url = "https://api.unusualwhales.com/api/screener/option-contracts"
headers = {
    "Authorization": f"Bearer {os.environ['UNUSUAL_WHALES_API_TOKEN']}",
    "UW-CLIENT-API-ID": "100001",
}
params = {
    "limit": 150,
    "is_otm": True,
    "issue_types[]": ["Common Stock", "ADR"],
    "max_dte": 183,                    # Max 6 months to expiry
    "max_multileg_volume_ratio": 0.1,  # Filter out spread trades
    "min_ask_perc": 0.7,               # Aggressive buyers (paying near ask)
    "min_volume": 500,
    "min_premium": 250_000,            # $250K+ premium
    "type": "Calls",                   # Bullish = calls
    "volume_greater_oi": True,         # Volume exceeds open interest
}
response = httpx.get(url, headers=headers, params=params)
data = response.json().get("data", [])

for contract in data:
    print(f"{contract['ticker_symbol']} {contract['option_symbol']} | Vol: {contract.get('ask_side_volume')}")

Example 3: Monitor Dark Pool Activity

User prompt: "Any big dark pool prints on NVDA?"

# unusual_whales_darkpool.py — Fetch dark pool trades for a ticker
import os
import httpx

url = "https://api.unusualwhales.com/api/darkpool/NVDA"
headers = {
    "Authorization": f"Bearer {os.environ['UNUSUAL_WHALES_API_TOKEN']}",
    "UW-CLIENT-API-ID": "100001",
}
response = httpx.get(url, headers=headers)
prints = response.json().get("data", [])

for p in prints:
    notional = float(p['price']) * int(p['size'])
    print(f"${notional:,.0f} | {p['size']} shares @ ${p['price']} | {p['executed_at']}")

Example 4: Check Market Sentiment

User prompt: "What is the overall market sentiment right now?"

# unusual_whales_tide.py — Fetch market tide sentiment data
import os
import httpx

url = "https://api.unusualwhales.com/api/market/market-tide"
headers = {
    "Authorization": f"Bearer {os.environ['UNUSUAL_WHALES_API_TOKEN']}",
    "UW-CLIENT-API-ID": "100001",
}
params = {"interval_5m": False}  # Full day view
response = httpx.get(url, headers=headers, params=params)
data = response.json().get("data", [])

latest = data[-1] if data else {}
net_call = float(latest.get('net_call_premium', 0))
net_put = float(latest.get('net_put_premium', 0))
sentiment = "BULLISH" if net_call > net_put else "BEARISH"
print(f"Market Tide: {sentiment} | Calls: ${net_call:,.0f} | Puts: ${net_put:,.0f}")

Example 5: Gamma Exposure Analysis

User prompt: "Show me the gamma exposure for RIVN by strike."

# unusual_whales_gex.py — Fetch spot gamma exposure by strike
import os
import httpx

url = "https://api.unusualwhales.com/api/stock/RIVN/spot-exposures/strike"
headers = {
    "Authorization": f"Bearer {os.environ['UNUSUAL_WHALES_API_TOKEN']}",
    "UW-CLIENT-API-ID": "100001",
}
response = httpx.get(url, headers=headers)
data = response.json().get("data", [])

for level in sorted(data, key=lambda x: abs(float(x.get('call_gamma_oi', 0))), reverse=True)[:10]:
    print(f"Strike ${level['strike']} | Call GEX: {level.get('call_gamma_oi')} | Put GEX: {level.get('put_gamma_oi')}")

Example 6: Track Congressional Trading

User prompt: "Show me recent congressional stock trades."

# unusual_whales_congress.py — Fetch politician trading disclosures
import os
import httpx

url = "https://api.unusualwhales.com/api/congress/recent-trades"
headers = {
    "Authorization": f"Bearer {os.environ['UNUSUAL_WHALES_API_TOKEN']}",
    "UW-CLIENT-API-ID": "100001",
}
response = httpx.get(url, headers=headers)
trades = response.json().get("data", [])

for trade in trades[:20]:
    print(f"{trade.get('politician')} | {trade.get('ticker')} | {trade.get('type')} | {trade.get('amount')}")

Guidelines

• Always use the Authorization header, never query parameters for authentication
• Check the hallucination blacklist before generating any endpoint URL
• Use size_greater_oi=True to filter for opening positions (new money entering)
• Use is_otm=True to filter for out-of-the-money options (higher leverage bets)
• min_premium is in dollars — use 50000 for $50K, 500000 for $500K
• Market Tide with interval_5m=False gives full-day aggregated view
• Congressional trading data reflects filed disclosures, not real-time trades
• WebSocket streaming is a separate feature that depends on your plan; the vendor documents it at https://unusualwhales.com/skills/websocket.md
• Rate limits apply per plan; on HTTP 429 back off and retry, and read the vendor's usage-monitor skill (linked from skill.md) to inspect current usage
• Send both headers on every call; a missing UW-CLIENT-API-ID is a common cause of rejected requests
• Never paste the token into code or commits; keep it in UNUSUAL_WHALES_API_TOKEN
• Not investment advice: flow and disclosures describe what happened, not what will happen