{"components":{"securitySchemes":{"bearerAuth":{"description":"API key as 'Authorization: Bearer <key>'. A demo subset (AAPL, VIX, KO, META, AMZN, XOM, GM, MCD) is accessible without a key by sending header 'X-TV-Demo: 1'.","scheme":"bearer","type":"http"}}},"info":{"contact":{"url":"https://stocks.tradingvolatility.net/api/v2/docs"},"description":"Agent-friendly options market-structure API. Provides canonical ticker state snapshots, deterministic interpretations, historical metric series, and strike-curve surfaces (gamma + GEX by strike). See /AGENTS.md and /api/v2/llm-spec for agent guidance.","title":"Trading Volatility API v2","version":"2.0.0"},"openapi":"3.0.3","paths":{"/agent/trade-setup/{ticker}":{"get":{"description":"Trader-facing recommendation: direction, thesis, risk framing, state labels.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Compact trade setup"}},"/tickers/{ticker}":{"get":{"description":"Compact normalized market-state snapshot. Default starting point.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"description":"Comma-separated add-ons (e.g. include=call_diag).","in":"query","name":"include","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Canonical ticker state snapshot"}},"/tickers/{ticker}/curves/gamma":{"get":{"description":"Net gamma curve by strike.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"description":"combined|nearest|first_weekly|first_monthly|YYYY-MM-DD.","in":"query","name":"exp","required":false,"schema":{"type":"string"}},{"in":"query","name":"realtime","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Net gamma per strike"}},"/tickers/{ticker}/curves/gamma/expirations":{"get":{"description":"Strike-aligned gamma decomposition by expiration bucket.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Gamma decomposition by expiration"}},"/tickers/{ticker}/curves/gex_by_strike":{"get":{"description":"Gamma-exposure curve by strike.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"GEX by strike"}},"/tickers/{ticker}/explain":{"get":{"description":"Deterministic plain-English read of the current regime and positioning.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Plain-English interpretation"}},"/tickers/{ticker}/levels":{"get":{"description":"Key levels for chart overlays or exported level lists.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Key price levels"}},"/tickers/{ticker}/market-structure":{"get":{"description":"Headline, bias, regime, key levels, drivers, and expected behavior.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"description":"include=state adds the raw snapshot; include=call_diag adds diagnostics.","in":"query","name":"include","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Assembled market-structure interpretation"}},"/tickers/{ticker}/options/volume":{"get":{"description":"Expiration-specific strike-by-strike option volume.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"in":"query","name":"exp","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Options volume by strike"}},"/tickers/{ticker}/series":{"get":{"description":"Time series for selected metrics.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"description":"Comma-separated metric keys.","in":"query","name":"metrics","required":false,"schema":{"type":"string"}},{"description":"Lookback window, e.g. 30d.","in":"query","name":"window","required":false,"schema":{"example":"30d","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Historical metric time series"}},"/tickers/{ticker}/signals":{"get":{"description":"Labels/scores for filtering and alert logic.","parameters":[{"description":"Equity or ETF symbol (uppercase recommended; server normalizes).","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Lightweight signals"}},"/top-setups":{"get":{"description":"Cross-sectional ranking by opportunity score; supports filter params.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Rank the universe by opportunity"}},"/top-setups/screener/{name}":{"get":{"parameters":[{"description":"Screener preset name.","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success. Envelope is { meta, data }."}},"summary":"Run a named screener preset"}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://stocks.tradingvolatility.net/api/v2"}]}