{"agent_guidance":{"field_semantics":["Fields ending in _pct are expressed in percent units (1.78 means 1.78%, not 0.0178).","IV fields such as atm_iv remain decimals (0.28 means 28%).","Ratio fields remain ratios unless a companion *_pct field is explicitly provided.For /curves/gamma/expirations, all_other_expiries is constructed as combined minus the named expiration buckets at each strike."],"recommended_flow":["Start with /tickers/{ticker} for the canonical normalized snapshot.","Use /tickers/{ticker}/market-structure when the task is to summarize what current options structure implies.","Use /tickers/{ticker}/signals for lightweight filtering or alert logic.","Use /tickers/{ticker}/series for historical trend and regime context.","Use /tickers/{ticker}/curves/gamma or /curves/gex_by_strike for strike-level analysis.","Use /tickers/{ticker}/curves/gamma/expirations when the task is to compare or graph expiration-bucket gamma contributions across strikes.","Use /tickers/{ticker}/levels for chart overlays or exported level lists.","Use /tickers/{ticker}/options/volume for expiration-specific strike-by-strike volume."]},"auth":{"format":"Bearer <key>","header":"Authorization","type":"header"},"base_url":"https://stocks.tradingvolatility.net/api/v2","conventions":{"exp_param":"For curve endpoints, use exp=combined|nearest|first_weekly|first_monthly|YYYY-MM-DD (gamma supports date + realtime).","ticker_format":"Uppercase recommended (server will normalize).","time_fields":{"data.asof":"Human-readable timestamp for display","meta.asof":"ISO-8601 UTC when available"}},"demo_access":{"description":"A small set of tickers can be queried without an API key to allow quick experimentation and agent prototyping.","notes":["Demo tickers require headers['X-TV-Demo'] = '1'.","Rate limits may still apply.","Full universe access requires an API key."],"tickers":["AAPL","VIX","KO","META","AMZN","XOM","GM","MCD"]},"description":"Agent-friendly market structure API. Provides canonical ticker state snapshots, deterministic explanations, historical metric series, and strike-curve surfaces (gamma + GEX by strike), including multi-bucket gamma decomposition by expiration.","endpoints":[{"method":"GET","params":{"include":"Optional: comma-separated add-ons (e.g. include=call_diag)."},"path":"/tickers/{ticker}","purpose":"Canonical compact ticker state snapshot. Use as the default starting point for any analysis.","returns_schema":"tv.ticker.state.v2"},{"method":"GET","params":{"include":"Optional comma-separated add-ons. include=state adds the canonical raw ticker snapshot. include=call_diag adds call regime diagnostic blobs."},"path":"/tickers/{ticker}/market-structure","purpose":"Finished market structure artifact for a single ticker. Returns the assembled interpretation layer built from current price, gamma structure, skew, put/call positioning, and call flow regime context.","response_fields":{"bias":"High-level market structure bias such as stabilizing, neutral, mixed, or fragile.","confidence":{"notes":"List of notes about data quality or interpretation confidence."},"drivers":{"flip_context":{"distance_pct":"Percent distance of spot from gamma flip.","label":"Human-readable description of flip context.","state":"Categorical state such as above_flip, below_flip, or at_flip."},"gamma_tone":{"label":"Human-readable gamma tone description.","state":"Categorical gamma state such as positive, negative, strong_positive, or strong_negative."},"sentiment":"Deterministic sentiment label.","skew_tone":{"label":"Human-readable skew description.","state":"Categorical skew state such as defensive, balanced, or upside_leaning.","tags":"List of skew-related interpretation tags."}},"expected_behavior":"Plain-English explanation of how structure may influence price behavior.","headline":"Short deterministic market structure summary.","key_levels":{"gamma_flip":"Gamma flip price level in USD.","minus_1sigma_1d":"1-day -1\u03c3 price level in USD.","minus_1sigma_1m":"1-month -1\u03c3 price level in USD.","minus_1sigma_1w":"1-week -1\u03c3 price level in USD.","plus_1sigma_1d":"1-day +1\u03c3 price level in USD.","plus_1sigma_1m":"1-month +1\u03c3 price level in USD.","plus_1sigma_1w":"1-week +1\u03c3 price level in USD.","spot":"Current underlying price in USD."},"signal":"Primary actionable interpretation label.","structure_regime":"Deterministic regime identifier for current structure state.","supporting_factors":{"call_regime":"Current call flow regime label.","distance_to_flip_pct":"Percent distance from spot to gamma flip.","expected_move_pct_1d":"1-day expected move in percent units.","expected_move_pct_1w":"1-week expected move in percent units.","gamma_flip":"Gamma flip price in USD.","gamma_notional_per_1pct_move_usd":"Net gamma notional in USD per 1% underlying move.","pcr_oi":"Put/call open interest ratio.","pcr_volume":"Put/call volume ratio.","pct_gamma_expiring_nearest_expiry":"Percent of total gamma expiring in the nearest expiry bucket.","put_call_25d_iv_premium_pct":"25-delta put IV premium over call IV, expressed in percent units.","speculative_interest_score":"0-1 score for speculative call interest.","spot":"Current underlying price in USD."},"tags":"List of compact regime / structure tags useful for filtering and routing."},"returns_schema":"tv.ticker.market_structure.v2"},{"method":"GET","params":{"view":"Optional view selector when available (defaults to a standard interpretation)."},"path":"/tickers/{ticker}/explain","purpose":"Deterministic interpretation of the current ticker regime and positioning (human-readable summary + tags).","returns_schema":"tv.ticker.explain.v2"},{"defaults":{"metrics":["price","iv_rank","gex_flip","pc_25d_ratio"],"window":"180d"},"method":"GET","metric_catalog":[{"desc":"Underlying last price.","key":"price","type":"float","unit":"usd"},{"desc":"IV rank percentile (0-100).","key":"iv_rank","type":"float","unit":"0-100"},{"desc":"ATM IV percent change vs prior period .","key":"iv_pct_chg","type":"float","unit":"pct"},{"desc":"ATM implied volatility (0.25 = 25%).","key":"atm_iv","type":"float","unit":"decimal"},{"desc":"25-delta put IV / 25-delta call IV.","key":"put_call_25d_iv_ratio","type":"float","unit":"ratio"},{"desc":"Put IV minus Call IV.","key":"put_call_iv_spread","type":"float","unit":"iv_points"},{"desc":"Put/Call ratio for open interest.","key":"pcr_oi","type":"float","unit":"ratio"},{"desc":"Put/Call ratio of day's volume.","key":"pcr_volume","type":"float","unit":"ratio"},{"desc":"30-day change in PCR (OI).","key":"put_call_ratio_oi_30day_change","type":"float","unit":"delta"},{"desc":"60-day change in PCR (OI).","key":"put_call_ratio_oi_60day_change","type":"float","unit":"delta"},{"desc":"Gamma flip price level.","key":"gex_flip","type":"float","unit":"usd"},{"desc":"Cumulative gamma notional per 1% move .","key":"gex_usd_per_1_pct_move","type":"float","unit":"usd_per_1pct_move"},{"desc":"Nearest-exp gamma notional per 1% move .","key":"nearest_gex_usd_per_1_pct_move","type":"float","unit":"usd_per_1pct_move"},{"desc":"Gamma-to-volume ratio .","key":"gex_volume_ratio","type":"float","unit":"ratio"},{"desc":"Percent of gamma expiring in nearest expiry bucket relative to total.","key":"pct_gamma_expiring","type":"float","unit":"percent"},{"desc":"Call flow regime label.","key":"call_regime","type":"string","unit":null},{"desc":"Speculative interest score. 1==highest.","key":"speculative_interest_score","type":"float","unit":"0-1"}],"params":{"metrics":"Comma-separated metric keys.","window":"Lookback window (e.g. 30d, 180d, 2y)."},"path":"/tickers/{ticker}/series","purpose":"Historical time series for one or more metrics for charting/regime context.","returns_schema":"tv.series.v2"},{"method":"GET","params":{"exp":"combined | nearest | first_weekly | first_monthly  | YYYY-MM-DD","realtime":"true/false (when true or exp is a date, requires trading hours)","view":"naive (reserved for future: sa-gex)"},"path":"/tickers/{ticker}/curves/gamma","purpose":"Gamma strike curve (net gamma per strike). Supports cached curves  and optional realtime single-exp pulls during market hours when exp is a date or realtime=true.","returns":{"data":"{ ticker, price, expiry, asof, points[] }","points_item":"{ strike, gamma }"},"returns_schema":"tv.curve.gamma.v2"},{"method":"GET","params":{},"path":"/tickers/{ticker}/curves/gamma/expirations","purpose":"Strike-aligned gamma decomposition by expiration bucket. Returns combined gamma, named cached expiration buckets, and an all_other_expiries residual constructed so users can sum the returned series back to the combined curve at each strike.","returns":{"construction":"{ all_other_expiries_formula: 'combined - nearest - first_weekly - first_monthly ' }","data":"{ ticker, price, asof, expiries, series_order, construction, points[] }","expiries":"{ combined, nearest, first_weekly, first_monthly, all_other_expiries }","points_item":"{ strike, combined, nearest, first_weekly, first_monthly, all_other_expiries }","series_order":"[nearest, first_weekly, first_monthly, all_other_expiries]"},"returns_schema":"tv.curve.gamma.expirations.v2"},{"method":"GET","params":{"exp":"combined | nearest | first_monthly (call/put contributions are only available for combined)"},"path":"/tickers/{ticker}/curves/gex_by_strike","purpose":"Net GEX strike curve with call/put contributions when available. Uses cached arrays (StrikeArray, GexCountArray, CallOiArray, PutOiArray). Best for identifying key strikes and call-vs-put dominance around price.","returns":{"data":"{ ticker, price, expiry, asof, points[], totals }","points_item":"{ strike, net, call?, put? }","totals":"{ gex_flip_price, gex_value_per_1pct, put_call_oi, ... }"},"returns_schema":"tv.curve.gex_by_strike.v2"}],"name":"Trading Volatility API v2"}