unusual-whales-api

What this skill does

# Unusual Whales API

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
- Pricing starts at $50/week or $150/month

## Instructions

### Critical Rules (Anti-Hallucination Protocol)

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

**Authentication:** All requests MUST include the header:
```
Authorization: Bearer <API_TOKEN>
```

**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

- **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`

### 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."

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

url = "https://api.unusualwhales.com/api/option-trades/flow-alerts"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
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."

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

url = "https://api.unusualwhales.com/api/screener/option-contracts"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
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
    "vol_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?"

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

url = "https://api.unusualwhales.com/api/darkpool/NVDA"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
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?"

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

url = "https://api.unusualwhales.com/api/market/market-tide"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
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."

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

url = "https://api.unusualwhales.com/api/stock/RIVN/spot-exposures/strike"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
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."

```python
# unusual_whales_congress.py — Fetch politician trading disclosures
import httpx

url = "https://api.unusualwhales.com/api/congress/recent-trades"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
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, nev