API Reference

Theta Vantage provides a REST API for programmatic access to options analytics. Live market data uses one tools catalog (GET /api/v1/tools + GET|POST /api/v1/tools/{name}) — the same executors as remote MCP and in-app Athena. Historical heatmaps, the daily report, and chat stay on dedicated REST routes.

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) across the data endpoints (status, tools, historical heatmap)
• 15 requests per minute for heavy tools (get_fundamentals, get_earnings_calendar, get_iv_rank, get_wheel_strategy, get_income_projections, search_x_discourse) in the mcp-heavy bucket — the same cadence as chat
• 15 requests per minute for POST /api/v1/chat, tracked in its own bucket — chat and data limits are independent
• Rate limit headers are included in every response:
  • X-RateLimit-Limit — the limit that applies to this endpoint
  • 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",
  "api_version": "v1",
  "user": {
    "email": "[email protected]",
    "name": "Your Name",
    "tier": "pro"
  },
  "rateLimit": { "limit": 60 },
  "timestamp": "2026-02-14T19:00:00.000Z"
}

Response fields:

Tools catalog

Lists the same gateway data tools as MCP tools/list and Athena chat. Chat and report are not in this catalog.

GET /api/v1/tools

Example:

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

Response: { "ok": true, "tools": [ { "name", "description", "parameters" } ], "timestamp" }

Live schemas come from the gateway. If the catalog is unreachable, the static snapshot is returned.

Tool execute

Runs one catalog tool. Query string (GET) or JSON body (POST) becomes execute arguments. Booleans, numbers, and JSON arrays/objects in the query string are coerced. Skip api_key — it is only for auth.

GET  /api/v1/tools/{name}?symbol=SPY&…
POST /api/v1/tools/{name}

Examples:

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

curl -X POST "https://thetavantage.com/api/v1/tools/get_stock_quote" \
  -H "X-API-Key: tvk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"SPY"}'

Success: { "ok": true, "tool": "get_greek_exposure", "data": { … }, "timestamp" }

data is the parsed gateway result string (JSON object, or { "text": "…" } if the result is not JSON).

Errors: UNKNOWN_TOOL (404), TOOL_ERROR (400), TOOL_TIMEOUT (504), RATE_LIMIT_EXCEEDED (429), INVALID_API_KEY (401), INSUFFICIENT_TIER (403), GATEWAY_ERROR / GATEWAY_UNAVAILABLE (502).

What replaced GEX / DEX / VEX / charm / live heatmap

Historical heatmaps remain on REST below. Chat and report remain on /api/v1/chat and /api/v1/report.

The catalog includes quotes, chains, flow, tide, history, fundamentals, news, IV rank, indicators, strategies, and X search. See MCP for the full tool table. Heavy tools share the 15/min mcp-heavy bucket.

Historical Heatmap

Returns a strike × expiration Greek exposure grid for a past trading date, using the same data pipeline as the Greek Heatmap playback feature. Historical option chains are fetched from the gateway, spot prices come from daily bars, and GEX/VEX/DEX are computed server-side. Live heatmaps use get_greek_heatmap on the tools catalog; this route is the historical export.

Note: trade_date must be a market session (weekday that is not a US equity holiday). Weekends and holidays return 404 NO_DATA (e.g. Memorial Day 2026 is 2026-05-25).

GET /api/v1/heatmap/historical?symbol=AAPL&trade_date=2026-05-26

Example (Header):

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/heatmap/historical?symbol=AAPL&trade_date=2026-05-26&greek=gamma&range=0.10"

Example with expiration range:

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/heatmap/historical?symbol=AAPL&trade_date=2026-05-26&expiration_date_gte=2026-05-26&expiration_date_lte=2026-05-29"

Response fields: A strike × expiration grid with symbol, greek, current_price, range, summary (totals, top cells), expirations, strikes, and grid cells (strike, expiration, gex, vex, dex, display_value, volumes, has_data), plus:

Historical Heatmap (Batch)

Load multiple trading dates in one request. Each date maps to a heatmap response or null when no options data exists for that session (weekends, holidays, or missing history).

GET /api/v1/heatmap/historical/batch?symbol=AAPL&trade_dates=2026-05-26,2026-05-27,2026-05-28

Example:

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/heatmap/historical/batch?symbol=AAPL&trade_dates=2026-05-26,2026-05-27,2026-05-28,2026-05-29"

Response fields:

Each non-null value under results is a complete historical heatmap object (grid + summary), plus trade_date and current_price on the object itself. The map key always matches trade_date. Dates with no options data or no usable spot price are null. Per-entry heatmaps do not include summary.cache; cache metadata is aggregated in the batch-level summary above.

Example response (truncated):

{
  "symbol": "AAPL",
  "greek": "gamma",
  "range": 0.1,
  "results": {
    "2026-05-26": {
      "symbol": "AAPL",
      "greek": "gamma",
      "trade_date": "2026-05-26",
      "current_price": 198.42,
      "range": 0.1,
      "strikes": [195, 200, 205],
      "expirations": ["2026-05-30", "2026-06-06"],
      "grid": [
        {
          "strike": 200,
          "expiration": "2026-05-30",
          "gex": 1250000,
          "vex": 0,
          "dex": 0,
          "display_value": 1250000,
          "call_volume": 4200,
          "put_volume": 3100,
          "total_volume": 7300,
          "has_data": true
        }
      ],
      "summary": {
        "total_exposure": 4500000,
        "max_cell_exposure": 1250000,
        "total_volume": 18200,
        "strikes_count": 12,
        "expirations_count": 2,
        "cells_count": 24
      },
      "timestamp": "2026-06-14T12:00:00.000Z"
    },
    "2026-05-25": null
  },
  "summary": {
    "total_dates": 2,
    "dates_with_data": 1,
    "options_cache_hits": 1,
    "options_cache_misses": 1,
    "bars_cache_hits": 2,
    "bars_cache_misses": 0
  },
  "timestamp": "2026-06-14T12:00:00.000Z"
}

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", "long_term": 18.4, "short_term": 7.2 },
        "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"
}

AI Chat

Ask natural-language questions about the options market and get answers grounded in live Theta Vantage data. Behind the scenes the assistant decides which data it needs and pulls it — quotes, option chain, Greek exposure, market tide, options flow, IV rank, max pain, technical indicators, key levels, fundamentals, news, and price history — before answering. The tools_used field tells you which data sources were consulted.

This is the only POST endpoint in the API, and it is the only one that accepts a JSON request body.

Note: Response time is typically 5–30 seconds depending on how much data the assistant pulls. Responses are not streamed — the full answer is returned at once.

POST /api/v1/chat

Rate limit: 15 requests per minute per API key, tracked in a separate bucket from the 60/min data endpoints — chat usage does not consume your data endpoint allowance, and vice versa. The X-RateLimit-* headers on a chat response reflect the chat bucket.

Request body:

Example (Header):

curl -X POST "https://thetavantage.com/api/v1/chat" \
  -H "X-API-Key: tvk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is the current SPY market tide and does it support a bullish stance?",
    "symbol": "SPY"
  }'

Example (multi-turn):

curl -X POST "https://thetavantage.com/api/v1/chat" \
  -H "X-API-Key: tvk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "And where is the call wall?",
    "symbol": "SPY",
    "history": [
      { "role": "user", "content": "What is the SPY gamma environment?" },
      { "role": "assistant", "content": "SPY is in positive gamma above 598..." }
    ]
  }'

Response fields:

Response:

{
  "response": "SPY's market tide is net positive today — call premium is leading put premium by roughly 2:1 into the afternoon...",
  "model": "grok-4-fast",
  "tools_used": ["get_market_tide", "get_stock_quote"],
  "usage": { "prompt_tokens": 2418, "completion_tokens": 386 },
  "timestamp": "2026-02-14T19:00:00.000Z"
}

Endpoint-specific errors:

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. List tools, then execute one:

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

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

4. Get key levels for trading decisions:

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

5. Live strike×expiration heatmap via the catalog:

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

6. Load historical GEX by expiration for a past trading date:

curl -H "X-API-Key: tvk_YOUR_KEY" \
  "https://thetavantage.com/api/v1/heatmap/historical?symbol=AAPL&trade_date=2026-05-26"

7. Generate a daily report with AI analysis:

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

8. Ask the AI assistant a question grounded in live data:

curl -X POST "https://thetavantage.com/api/v1/chat" \
  -H "X-API-Key: tvk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Is SPY gamma positive or negative right now?","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 / Cursor MCP (Model Context Protocol) — Connect the remote MCP server with a Pro tvk_ key. Same tools catalog as /api/v1/tools: MCP. Chat and daily report are REST-only and are not MCP tools.

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/tools/get_greek_exposure?symbol={symbol}&greek=gamma",
        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: get_gamma_profile includes regime / zero-gamma fields that tell you whether dealers are in a positive or negative gamma regime — a key signal for volatility expectations.