Public API Reference

Theta Vantage provides a REST API for programmatic access to options analytics data. Use it to integrate GEX, DEX, VEX, key levels, max pain, gamma profile, heatmap, and AI-generated daily report data into your own applications, scripts, or trading systems.

Authentication

All API requests require an API key. Generate one from your Account Settings page (PRO tiers only).

Method 1: Header Authentication (Recommended)

Include your key in every request using the X-API-Key header:

curl -H "X-API-Key: tvk_YOUR_KEY_HERE" \
  "https://thetavantage.com/api/v1/status"

Method 2: Query Parameter Authentication

Alternatively, pass it as a query parameter api_key:

curl "https://thetavantage.com/api/v1/status?api_key=tvk_YOUR_KEY_HERE"

Note: Both methods work identically. Query parameters are useful for browser testing or when HTTP headers are difficult to set. Header authentication is recommended for production applications.

Rate Limits

• 60 requests per minute per API key (sliding window)
• Rate limit headers are included in every response:
  • X-RateLimit-Remaining — requests left in the current window
  • X-RateLimit-Reset — seconds until the window resets

Base URL

https://thetavantage.com/api/v1

Status

Test your API key and check connectivity.

GET /api/v1/status

Example (Header):

curl -H "X-API-Key: tvk_YOUR_KEY" https://thetavantage.com/api/v1/status

Example (Query Parameter):

curl "https://thetavantage.com/api/v1/status?api_key=tvk_YOUR_KEY"

Response:

{
  "status": "ok",
  "user": { "email": "[email protected]", "tier": "pro" },
  "timestamp": "2026-02-14T19:00:00.000Z"
}

Gamma Exposure (GEX)

Returns strike-level gamma exposure analysis.

GET /api/v1/gex?symbol=SPY

Example (Header):

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/gex?symbol=SPY&expiration=2026-02-21"

Example (Query Parameter):

curl "https://thetavantage.com/api/v1/gex?symbol=SPY&expiration=2026-02-21&api_key=tvk_YOUR_KEY"

Response fields:

Delta Exposure (DEX)

Returns strike-level delta exposure analysis.

GET /api/v1/dex?symbol=SPY

Response fields:

Vanna Exposure (VEX)

Returns strike-level vanna exposure, measuring delta sensitivity to implied volatility.

GET /api/v1/vex?symbol=SPY

Response fields:

Charm Exposure

Returns strike-level charm exposure, measuring delta decay over time.

GET /api/v1/charm?symbol=SPY

Response fields:

Key Levels

Returns options-derived key price levels: Call Wall, Put Wall, Hedge Wall, Max Pain, Expected Move, and GEX walls.

GET /api/v1/key-levels?symbol=SPY

Example (Header):

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/key-levels?symbol=SPY"

Example (Query Parameter):

curl "https://thetavantage.com/api/v1/key-levels?symbol=SPY&api_key=tvk_YOUR_KEY"

Response fields:

Max Pain

Returns max pain analysis with per-strike pain breakdown.

GET /api/v1/max-pain?symbol=SPY

Response fields:

Gamma Profile

Returns the gamma exposure curve across theoretical spot prices, the zero gamma level, and market implications.

GET /api/v1/gamma-profile?symbol=SPY

Example (Header):

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/gamma-profile?symbol=SPY"

Example (Query Parameter):

curl "https://thetavantage.com/api/v1/gamma-profile?symbol=SPY&api_key=tvk_YOUR_KEY"

Response fields:

Heatmap

Returns a 2-D grid of Greek exposure per strike × expiration, with volume breakdown.

GET /api/v1/heatmap?symbol=SPY&greek=gamma

Example (Header):

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/heatmap?symbol=SPY&greek=gamma&range=0.05"

Example (Query Parameter):

curl "https://thetavantage.com/api/v1/heatmap?symbol=SPY&greek=gamma&range=0.05&api_key=tvk_YOUR_KEY"

Response fields:

Daily Report

Returns an AI-generated daily trading report with mode assessment, positioning guidance, alert levels, scenario pathing, strategist's narrative, multi-timeframe technical analysis, and a social-ready formatted text. The endpoint fetches live options and quote data, calculates key levels, then generates the report via AI.

Note: Response time is typically 5–15 seconds due to AI generation.

GET /api/v1/report?symbol=SPY

Example (Header):

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/report?symbol=SPY"

Example (Query Parameter):

curl "https://thetavantage.com/api/v1/report?symbol=SPY&api_key=tvk_YOUR_KEY"

Response fields:

price object:

report object:

key_levels object:

timeframe_analysis object (null if unavailable):

Each item in timeframes:

alignment object:

Example response (truncated):

{
  "symbol": "SPY",
  "price": {
    "current": 598.23,
    "change": 2.15,
    "change_percent": 0.36,
    "previous_close": 596.08,
    "open": 596.50,
    "high": 599.00,
    "low": 595.80,
    "volume": 45230000
  },
  "expiration": "2026-02-21",
  "report": {
    "mode": "yellow-improving",
    "modeLabel": "YELLOW (Improving)",
    "modeRationale": "Daily leading weekly recovery, but weekly trend still red.",
    "narrative": {
      "headline": "Gamma flip at $600 is the key pivot today.",
      "story": "Price is consolidating just below the key gamma strike...",
      "keyWatch": "$600 gamma strike",
      "invalidation": "Close below $593"
    },
    "scenarios": {
      "bull": { "probability": 30, "trigger": "Break above $600", "target": "$605", "action": "Add to longs" },
      "base": { "probability": 50, "trigger": "Chop $595-600", "target": "$597.50", "action": "Hold" },
      "bear": { "probability": 20, "trigger": "Lose $593", "target": "$588", "action": "Cut longs" }
    },
    "alertLevels": [
      { "price": 605, "level": "Call Wall", "type": "trim", "action": "Take 50% off", "tier": "T1" }
    ]
  },
  "key_levels": {
    "call_wall": 605.00,
    "put_wall": 593.00,
    "hedge_wall": 597.00,
    "max_pain": 597.00,
    "key_gamma_strike": 600.00,
    "expected_move": { "upper": 604.50, "lower": 591.50, "percent": 1.08 },
    "days_to_expiration": 5
  },
  "timeframe_analysis": {
    "timeframes": [
      {
        "timeframe": "Daily",
        "interval": "daily",
        "bx_trender": { "trend": "bullish", "signal": "buy", "oscillator": 1.23 },
        "rsi": { "value": 55.2, "status": "neutral" },
        "smi": { "value": 12.5, "signal": 8.3, "crossover": "bullish_cross", "zone": "above_zero" },
        "structure": { "pattern": "Higher Highs / Higher Lows", "trend": "bullish" },
        "ema": { "status": "above", "description": "Price above 8/21/55 EMA" },
        "verdict": { "bias": "bullish", "strength": "moderate" }
      }
    ],
    "alignment": {
      "isAligned": false,
      "bias": "mixed",
      "bullishCount": 3,
      "bearishCount": 2,
      "summary": "3/5 timeframes bullish"
    }
  },
  "formatted_text": "$SPY ▫️ $598.23 (+0.36%)\n🟡 YELLOW (Improving)\n\nGamma flip at $600 is the key pivot today.\n...",
  "timestamp": "2026-02-14T19:00:00.000Z"
}

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "ERROR_CODE",
  "message": "Human-readable description of the error."
}

Quick Start

1. Generate an API key from your Account Settings page (requires PRO tier)
2. Test connectivity with the status endpoint:

curl -H "X-API-Key: tvk_YOUR_KEY" https://thetavantage.com/api/v1/status

3. Fetch GEX data for any symbol:

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/gex?symbol=SPY"

4. Get key levels for trading decisions:

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/key-levels?symbol=AAPL"

5. Build a heatmap with the grid endpoint:

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/heatmap?symbol=QQQ&greek=gamma&range=0.05"

6. Generate a daily report with AI analysis:

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/report?symbol=SPY"

All responses include a timestamp field in ISO 8601 format. Data is live during market hours and cached briefly outside trading sessions.

Use Cases & Integrations

The Theta Vantage API returns standard JSON over HTTPS, making it easy to integrate with any language, framework, or platform.

🤖 AI Agents & LLM Tools

Feed real-time Greek exposure and key level data directly into AI agent frameworks:

• OpenClaw — Register Theta Vantage endpoints as tools for autonomous trading agents. Give your agent real-time GEX, key levels, and gamma profile data to make informed decisions.
• LangChain / LangGraph — Build custom tools that call the API and return structured market data to your LLM chains. Example: a tool that fetches key levels and gamma environment before generating a trade thesis.
• CrewAI — Equip your market analyst agents with live Greek exposure data. A "Risk Analyst" agent can monitor gamma profile shifts while a "Strategist" agent acts on key level changes.
• OpenAI Function Calling / GPTs — Define API endpoints as functions for ChatGPT or custom GPTs to call. Users can ask natural language questions like "What's the GEX picture for SPY right now?" and get live data.
• Claude MCP (Model Context Protocol) — Expose Theta Vantage endpoints as MCP tools so Claude can fetch live options analytics during conversations.

Example: OpenClaw tool definition

@tool("get_gamma_exposure")
def get_gex(symbol: str) -> dict:
    """Fetch real-time gamma exposure data for a stock symbol."""
    response = requests.get(
        f"https://thetavantage.com/api/v1/gex?symbol={symbol}",
        headers={"X-API-Key": os.environ["TV_API_KEY"]}
    )
    return response.json()

📊 Custom Dashboards & Alerts

• Grafana / Datadog — Poll endpoints on a schedule and visualize GEX trends, key level movements, and gamma profile shifts over time.
• Google Sheets / Excel — Use IMPORTDATA or Power Query to pull key levels and max pain into spreadsheets for tracking.
• Discord / Slack Bots — Post daily key levels or gamma environment alerts to your trading channels.
• Retool / Streamlit — Build internal tools that display heatmaps and exposure data alongside your portfolio.

🔧 Trading Systems

• Algorithmic Trading — Use gamma profile and key levels to set dynamic support/resistance zones for entries and exits.
• Risk Management — Monitor GEX and VEX shifts to adjust position sizing based on dealer hedging pressure.
• Backtesting — Pull current Greek data to compare against historical patterns and validate strategies.

Tip: The /api/v1/gamma-profile endpoint's gamma_environment field tells you whether the market is in a positive or negative gamma regime — a key signal for volatility expectations.