{"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.","Use /top-setups to rank tickers cross-sectionally by opportunity_score and narrow the universe with the available filter params before drilling into a specific ticker.","Use /agent/trade-setup/{ticker} when you want the compact trader-facing recommendation payload for a single ticker, including trade direction, thesis, risk framing, and state labels."]},"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"},{"desc":"Annualized 20-day realized volatility from daily log returns.","key":"realized_vol_20d","type":"float","unit":"pct_annualized"},{"desc":"Signed trend strength from the market-state model.","key":"trend_score","type":"float","unit":"score"},{"desc":"Momentum score from the market-state model.","key":"momentum_score","type":"float","unit":"score"},{"desc":"Price extension vs trend anchor.","key":"extension_score","type":"float","unit":"score"},{"desc":"Realized-vol regime score.","key":"realized_vol_score","type":"float","unit":"score"},{"desc":"Agreement across trend/momentum/extension signals.","key":"trend_alignment_score","type":"float","unit":"score"},{"desc":"Composite opportunity score from the TradeSetup interpreter.","key":"opportunity_score","type":"float","unit":"0-10"}],"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"},{"errors":{"401":"Missing or invalid Bearer token.","404":"No snapshot found for ticker.","500":"Unexpected upstream failure."},"method":"GET","notes":["gamma_regime is derived from spot vs gamma_flip_price: positive when spot > flip, negative when spot < flip, neutral when equal, unknown when either input is missing.","ATM IV remains a decimal (0.28 means 28%), while dist_to_gex_flip_pct is expressed in percent units.","trade_recommendation is assembled from the full stored trade_setup blob when present; older rows fall back to the indexed scalar projection fields."],"params":{"ticker":"Ticker path param. Uppercase recommended; server normalizes."},"path":"/agent/trade-setup/{ticker}","purpose":"Compact trader-facing trade setup payload for the latest snapshot of a single ticker. Combines core market-state fields with the stored trade recommendation blob, and falls back to indexed projection scalars when older snapshots do not carry the full trade_setup.","returns":{"data":"{ ticker, asof, price, gamma_regime, speculation_score, gamma_flip_price, dist_to_gex_flip_pct, realized_vol_20d, atm_iv, iv_rank, put_call_iv_ratio_25delta, put_call_iv_spread, trend_state, momentum_state, extension_state, realized_vol_state, trend_alignment_state, trade_recommendation }","risk":"{ size_fraction, max_risk_pct, prefer_defined_risk }","trade_recommendation":"{ model_version, regime_label, regime_confidence, trade_bias, opportunity_score, opportunity_tier, trade_type, direction, structures, entry_trigger, stop_description, target_description, risk, caution_flags, agent_summary }"},"returns_schema":"tv.agent.trade_setup.v2"},{"caching":{"cache_control":"private, max-age=<ttl>, stale-while-revalidate=30","conditional_get":"Clients should send If-None-Match; server returns 304 on match.","etag":"Weak ETag keyed on schema, asof, limit, min_score, filters, count."},"enums":{"Direction":["long","short","neutral"],"OpportunityTier":["high","moderate","low","pass"],"RegimeLabel":["trending_low_vol","trending_high_vol","range_bound","choppy_volatile","trending_down_low_vol","trending_down_high_vol","flush_panic"],"TradeType":["directional","mean_reversion","vol_premium","pass"]},"errors":{"304":"Conditional GET match (no body).","401":"Missing or invalid Bearer token.","500":"Upstream ndb or interpreter failure."},"filter_rules":["Unknown params are ignored (no error).","Empty-string values are treated as not provided.","String filters accept CSV for IN semantics (regime=a,b).","All supplied filters are AND'd together.","Sort is fixed: opportunity_score desc (not client-configurable)."],"method":"GET","params":{"ivAtMaxDelta_max":"float, inclusive upper bound on ivAtMaxDelta.","ivAtMaxDelta_min":"float, inclusive lower bound on ivAtMaxDelta.","iv_rank_max":"float 0-100, inclusive upper bound on iv_rank.","iv_rank_min":"float 0-100, inclusive lower bound on iv_rank.","limit":"int, default 20, range 1-200.","min_score":"float, default 0.0, range 0-10. Drops rows with opportunity_score < min_score.","momentum_state":"CSV of string (IN).","price_max":"float, inclusive upper bound on TickerSnapshot.price.","price_min":"float, inclusive lower bound on TickerSnapshot.price.","realized_vol_state":"CSV of string (IN).","recommended_direction":"CSV of long|short|neutral (IN).","regime":"CSV of RegimeLabel (IN). Filters on TickerSnapshot.regime_label.","trade_bias":"CSV of string (IN). Filters on indexed TickerSnapshot.trade_bias.","trend_state":"CSV of string (IN).","ttl":"int 0-1800, cache TTL seconds (default 900)."},"path":"/top-setups","purpose":"Cross-ticker ranking of the most recent snapshot per ticker (within a 36h recency window) sorted by opportunity_score desc. Each item carries the full deterministic trade_setup blob plus indexed projections used for filtering. Read-only; no re-interpretation on the read path.","returns":{"data":"{ items[] }","items_item":"{ ticker, asof, opportunity_score, opportunity_tier, regime_label, recommended_trade_type, recommended_direction, trade_bias, price, iv_rank, ivAtMaxDelta, trend_state, momentum_state, realized_vol_state, trade_setup }","meta":"{ schema, asof, limit, min_score, recency_hours, count, filters (echo of honored filters; numeric ranges appear as <prefix>_range: [lo, hi]), model_versions }","trade_setup":"Full deterministic TradeSetup: { ticker, timestamp, interpreter_version, regime, regime_confidence, opportunity_score, opportunity_tier, trade_type, trade_bias, direction, structures[], entry_trigger, stop_description, target_description, size_fraction, max_risk_pct, prefer_defined_risk, caution_flags[], missing_fields[], signal_snapshot, agent_summary }"},"returns_schema":"tv.top_setups.v2"}],"name":"Trading Volatility API v2"}