Datos e investigación · SKILL.md

unusual-whales-api

unusual-whales-api

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 hi…

Independent GitHub snapshot · Automated classification · Original documentation governs

Tterminalskills / skillsApache-2.0

Documentación de la Skill

GitHub

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

MAKE IT PART OF YOUR WORKFLOW

Instalar Skill

TERMINAL

npx skills add terminalskills/skills --skill unusual-whales-api

Ejecuta el comando en tu terminal. Revisa el código y la licencia antes de instalar.

ZIP · Complete skill directory with resources and licenses

SKILL.md · Instructions file only

Estrellas del repositorio: Not synced
Licencia: Apache-2.0
Versión / rama: HEAD · 9a5e2385
Repositorio actualizado: Not synced

Revisa los scripts y los permisos antes de instalar.

Código fuente