{
  "openapi": "3.0.3",
  "info": {
    "title": "TraderMatrix Developer API",
    "version": "1.0.0",
    "description": "Options-flow, gamma exposure (GEX), dark pool, insider, congressional-trade, sector-rotation, screener, and earnings-flow data for US equities.\n\nThis API publishes TraderMatrix's DERIVED layer only — scores, tiers, levels, and rollups we compute ourselves. It does not redistribute raw vendor rows (per-contract bid/ask/last/greeks, option chains keyed by strike, underlying quote passthrough, or news article text/URLs) — those are licensed from Tradier/Alpaca/Finnhub or scraped from TradingView/ForexFactory/OpenInsider and cannot be redistributed to third parties. Five routes that would otherwise carry raw vendor data (per-contract quotes or intraday price bars) are deliberately withheld (404): `/ticker/{symbol}/options`, `/ticker/{symbol}/tactical-grid`, `/ticker/vopr-setups`, `/ticker/{symbol}/intraday-chart`, and `/insider/quotes`.\n\nAn MCP tool-calling surface is also available at `POST /mcp` (not itself describable by OpenAPI) with 51 tools: 44 read-only market-data tools and 7 for the key owner's own watchlists (6 of which write). The full list is under `info.x-mcp-tools` — see `https://tradermatrix.pro/llms.txt` or the `traderdaddy-pro` Agent Skill at `https://tradermatrix.pro/skills/traderdaddy-pro/SKILL.md`.",
    "contact": {
      "url": "https://tradermatrix.pro/developers"
    },
    "x-mcp-tools": [
      {
        "name": "get_market_stats",
        "access": "read",
        "description": "SPY/QQQ/IWM put/call ratios, sentiment, and the largest unusual options trade for the current trading date."
      },      {
        "name": "get_macro_regime",
        "access": "read",
        "description": "Macro regime from Treasury, Federal Reserve, FRED and CFTC series: yield curve and 10Y-2Y spread, 10Y real yield, breakeven, 5Y5Y forward inflation, fed funds, Fed net liquidity, and CFTC E-mini S&P 500 positioning. Units and asOf on every field, plus an interpretation sentence."
      },
      {
        "name": "get_market_internals",
        "access": "read",
        "description": "Derived market internals: S&P 500 breadth (percent above 20/50/200-day averages, advancers/decliners, net new 52-week highs, zones), 60-session stock/bond and dollar/equity correlations, cross-asset ratios (VIX/VIX3M term structure, gold, copper-to-gold, oil 20-session changes) and the equity-risk-premium zone with implied ERP. Percent, ratios and correlations only — no index, futures or volatility levels, no fair-value prices."
      },

      {
        "name": "get_gex_overview",
        "access": "read",
        "description": "Gamma exposure across tracked symbols — flip points and key walls."
      },
      {
        "name": "get_gex_ticker",
        "access": "read",
        "description": "Gamma exposure analysis for any single ticker, including a gamma-pocket flag when the name's dealer gamma diverges from the broad-market regime."
      },
      {
        "name": "get_apex_levels",
        "access": "read",
        "description": "Composite “magnet” strike ranking (OI walls + net gamma) with the gamma-flip level."
      },
      {
        "name": "get_gex_vex_ladder",
        "access": "read",
        "description": "Dealer gamma (USD) and vega (relative, -100..100) side by side for the 13 strikes nearest spot, with a role and a STRONG / MODERATE / OPPOSING alignment tag per strike."
      },
      {
        "name": "get_unusual_activity",
        "access": "read",
        "description": "Real-time unusual options activity feed with scoring and sentiment."
      },
      {
        "name": "run_screener",
        "access": "read",
        "description": "Run a named screener and return matching tickers with scoring."
      },
      {
        "name": "get_sector_flow",
        "access": "read",
        "description": "Options flow aggregated by GICS sector ETF with sentiment breakdown."
      },
      {
        "name": "get_put_call_ratios",
        "access": "read",
        "description": "Put/call ratio for a ticker from its nearest weekly expiration. Null when there is no call volume to divide by."
      },
      {
        "name": "get_earnings_flow",
        "access": "read",
        "description": "Pre-earnings unusual options positioning for tickers reporting soon."
      },
      {
        "name": "get_economic_calendar",
        "access": "read",
        "description": "Macroeconomic events — FOMC, CPI, NFP — with consensus estimates."
      },
      {
        "name": "get_ticker_snapshot",
        "access": "read",
        "description": "One-call derived snapshot of a ticker — quality score and label, gamma regime and spot-vs-flip relation, nearest Apex level, session flow bias and conviction, IV rank (out of 100, with zone and interpretation) and the Market Health headline. Each section settles independently; derived scores only, no quotes, volume, open interest, fundamentals or news."
      },
      {
        "name": "get_iv_rank",
        "access": "read",
        "description": "Self-relative IV rank — is a ticker's premium rich or cheap vs its own history? Labelled with its source; percentile accompanies a self-tracked reading."
      },
      {
        "name": "get_strategy_ideas",
        "access": "read",
        "description": "Ranked, auto-assembled multi-leg option structures priced off the live chain."
      },
      {
        "name": "get_edge_xray",
        "access": "read",
        "description": "Whole-chain rich/cheap grade for one expiration, with optional trade-archetype lens."
      },
      {
        "name": "get_hedge_analysis",
        "access": "read",
        "description": "Ranked downside-protection structures for a share position you specify — collars, puts, and spreads priced off the live chain."
      },
      {
        "name": "get_institutional_activity",
        "access": "read",
        "description": "Most actively-traded tickers by institutional options-flow volume today, with directional bias."
      },
      {
        "name": "get_directional_flow",
        "access": "read",
        "description": "The session's cumulative (from-open) delta-weighted flow lean per underlying — cumΔ, conviction, and a bullish/bearish/balanced bias. Pass a symbol or get the top-15 leaderboard."
      },
      {
        "name": "get_dark_pool",
        "access": "read",
        "description": "Rolled-up off-exchange (“dark pool”) equity BLOCK flow for a ticker: print count, gross and net notional, accumulation vs distribution split, largest print. Aggregates only, individual prints are not served. The lean is inferred, not confirmed direction — it describes months of desk positioning, so distribution means a patient seller (stalling/sideways), not a short signal."
      },
      {
        "name": "get_gap_continuation",
        "access": "read",
        "description": "Gap Continuation Scanner: large-cap names that gapped 2%+ and then broke the opening range in the SAME direction, graded A to D by how many of three checks agree (GEX regime, options flow, sector flow). Returns ticker, direction, grade, a coarse gap bucket (the exact gap size is not published), which confirmations agree, and whether it is an earnings gap. sessionDate names the ET trading day shown: before the open, on weekends and on holidays that is the last session that produced any."
      },
      {
        "name": "get_breakout_signals",
        "access": "read",
        "description": "Breaking Out scanner: the active daily breakout and continuation signals, newest first. Returns ticker, signal type, direction, the price at detection, stop and target (null when they would sit on the wrong side of entry) and detectedAt. Filter by ticker, direction, since (ISO timestamp) to poll only new signals, and limit."
      },
      {
        "name": "get_breakout_tape_confirmed",
        "access": "read",
        "description": "Breakout + Tape Confirmed: Breaking Out names the live options tape is also buying bullish this session. Returns ticker, conviction (0 to 1), firstSeenAt, relative strength vs SPY (percent) and gamma regime. Derived verdicts only; empty outside the session."
      },
      {
        "name": "get_politician_trades",
        "access": "read",
        "description": "Congressional / political stock-disclosure leaderboard — the “Power Players” most-active names."
      },
      {
        "name": "get_politician_trades_by_ticker",
        "access": "read",
        "description": "Every congressional / political stock-disclosure trade for a single ticker."
      },
      {
        "name": "get_insider_trades",
        "access": "read",
        "description": "Form 4 insider trades of $25k+ filed with the SEC over the past 21 days, market-wide or filtered to one ticker. `direction` defaults to buy; pass sell, other or all."
      },
      {
        "name": "get_ticker_news",
        "access": "read",
        "description": "Catalyst news for one ticker — the single most decision-relevant recent headline, a count of hard catalysts in the window, and recent categorized supporting headlines with source and link. Answers \"why is $X moving?\"; returns null rather than inventing a catalyst when only commentary exists."
      },
      {
        "name": "get_crypto_quote",
        "access": "read",
        "description": "Live USD spot for named coins (BTC, ETH, SOL, any ticker) — price, 1h/24h/7d/30d change, market cap, 24h volume, supply and rank. Returns notFound for symbols with no quote. Max 10 per call. Spot only: there is no options, gamma or flow data for crypto."
      },
      {
        "name": "get_crypto_market_overview",
        "access": "read",
        "description": "Market-wide crypto read — total market cap and 24h change, total 24h volume, BTC and ETH dominance, active-currency count, and the largest coins by market cap. Dominance describes rotation, not a price target."
      },
      {
        "name": "get_short_interest",
        "access": "read",
        "description": "Official FINRA short data for a ticker — bi-monthly short interest (days-to-cover, current short position) plus the latest daily Reg SHO short-volume ratio. Short activity is squeeze/positioning context, not a bearish signal."
      },
      {
        "name": "get_bounce_signals",
        "access": "read",
        "description": "Bounce Finder screener — recently detected oversold-bounce candidates with scoring."
      },
      {
        "name": "get_bounce_score",
        "access": "read",
        "description": "On-demand oversold-bounce composite score for a single ticker."
      },
      {
        "name": "get_premarket_gappers",
        "access": "read",
        "description": "5-pillar momentum gap scan (gap >=10%, price $1-$100, float <=100M, premarket volume >=50k; relative volume ranks the board and news is flagged), runnable on the pre-market or after-hours tape. A common day-trading screen pattern; independent implementation, not affiliated with or endorsed by Warrior Trading or Ross Cameron."
      },
      {
        "name": "get_conviction",
        "access": "read",
        "description": "Community Conviction gauge — a 0..100 blended read of how TD Pro traders are leaning on a ticker."
      },
      {
        "name": "get_market_health",
        "access": "read",
        "description": "Market Health confluence — 9 macro-regime detectors (risk appetite, credit, breadth, volatility, financial conditions, rotation) rolled into one read."
      },
      {
        "name": "get_market_health_history",
        "access": "read",
        "description": "Market Health history — 30 days of composite risk-score snapshots, derived per-detector line series (percent vs moving average, ratios, N-day changes) and status changes since the previous trading day. No raw prices, no calendar rows."
      },
      {
        "name": "get_market_valuation",
        "access": "read",
        "description": "S&P 500 valuation verdict from an equity-risk-premium model — implied ERP, distance from the Fair value band and five ERP bands, as percentages only (no index level or earnings inputs)."
      },
      {
        "name": "get_macro_liquidity",
        "access": "read",
        "description": "US-government macro and liquidity series — Fed net liquidity, real yield, breakevens, fed funds, Treasury yield curve and 10Y-2Y spread, CAPEX and CFTC E-mini S&P 500 positioning. No third-party-licensed credit spreads."
      },
      {
        "name": "get_cross_asset_regime",
        "access": "read",
        "description": "Derived cross-asset read — stock-bond and dollar-stock correlations, gold/copper/oil 20-session changes, VIX/VIX3M term structure and MOVE/VIX. No raw index or commodity levels."
      },
      {
        "name": "get_market_breadth",
        "access": "read",
        "description": "Derived S&P 500 breadth — percent of members above their 20/50/200-day averages, advancers/decliners, net new 52-week highs, breadth zones and a one-sentence read. Aggregates only: no index level or index change."
      },
      {
        "name": "get_long_term_quality",
        "access": "read",
        "description": "Fundamental quality + dividend screener across the optionable universe for long-term names."
      },
      {
        "name": "get_dividend_calendar",
        "access": "read",
        "description": "Upcoming ex-dividend calendar across the optionable universe with yields and pay dates."
      },
      {
        "name": "get_ipo_scanner",
        "access": "read",
        "description": "IPO Scanner — the pipeline from pre-IPO chatter to freshly-listed names."
      },
      {
        "name": "list_watchlists",
        "access": "read",
        "description": "Your own watchlists — every list with its tickers and notes, plus your list and ticker limits."
      },
      {
        "name": "add_to_watchlist",
        "access": "watchlist-write",
        "description": "Add a ticker (with an optional note) to one of your watchlists, or your default list. Re-adding just updates the note."
      },
      {
        "name": "remove_from_watchlist",
        "access": "watchlist-write",
        "description": "Remove a ticker from one of your watchlists, or from every list it's on."
      },
      {
        "name": "move_watchlist_ticker",
        "access": "watchlist-write",
        "description": "Move a ticker from one of your watchlists to another."
      },
      {
        "name": "create_watchlist",
        "access": "watchlist-write",
        "description": "Create a new named watchlist on your account."
      },
      {
        "name": "update_watchlist",
        "access": "watchlist-write",
        "description": "Rename one of your watchlists, change its category, or make it your default list."
      },
      {
        "name": "delete_watchlist",
        "access": "watchlist-write",
        "description": "Delete one of your watchlists and the tickers on it. Your default list can't be deleted."
      }
    ]
  },
  "servers": [
    {
      "url": "https://api.tradermatrix.pro/api/v1",
      "description": "Production"
    },
    {
      "url": "https://api.traderdaddy.pro/api/v1",
      "description": "Legacy hostname (same server, kept permanently for existing integrations)"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "ApiKeyBearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your td_live_ API key, generated at https://tradermatrix.pro/developers (Pro/Elite plan required)."
      },
      "ApiKeyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "td_live_...",
        "description": "Authorization: Bearer td_live_xxxxxxxxxxxxxxxxxxxx — equivalent to X-API-Key."
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limit exceeded (30 requests/minute per key). Back off; do not retry in a tight loop.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Withheld": {
        "description": "Deliberately withheld on the Developer API — this route would otherwise serve raw per-contract vendor quotes (bid/ask/last/greeks), which TraderMatrix does not have redistribution rights to. Not a bug. Use get_edge_xray (MCP) or the derived screener/GEX endpoints instead.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "example": "Not found"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "parameters": {
      "TickerPath": {
        "name": "ticker",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Ticker symbol, case-sensitive uppercase (e.g. NVDA)."
      },
      "SymbolPath": {
        "name": "symbol",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Ticker symbol, case-sensitive uppercase (e.g. NVDA)."
      }
    }
  },
  "paths": {
    "/unusual-activity": {
      "get": {
        "summary": "Scored unusual options flow",
        "operationId": "getUnusualActivity",
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minPremium",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50000
            }
          },
          {
            "name": "minScore",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 95
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "call",
                "put"
              ],
              "default": "all"
            }
          },
          {
            "name": "sentiment",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "bullish",
                "bearish"
              ],
              "default": "all"
            }
          },
          {
            "name": "timeFrame",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "hour",
                "today",
                "todayOrLastSession",
                "yesterday",
                "3days",
                "week",
                "month"
              ],
              "default": "today"
            }
          },
          {
            "name": "tier",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            }
          },
          {
            "name": "dte",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "DTE window: a range such as 0-7, or open-ended such as 8+ (more than 7 days out). Malformed values return 400."
          },
          {
            "name": "tradeType",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated trade types"
          },
          {
            "name": "flowAction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "opening",
                "closing",
                "all"
              ]
            }
          },
          {
            "name": "minOtmPct",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "minVsOI",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "minOI",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "marketCapTier",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "mega",
                "large",
                "mid",
                "small",
                "all"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Top-level `sessionDate` (YYYY-MM-DD, ET) names the trading session the rows were read from for timeFrame today / todayOrLastSession / yesterday (todayOrLastSession serves the last complete session until the market opens); null for rolling windows."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/unusual-activity/stats": {
      "get": {
        "summary": "Aggregate unusual-activity stats",
        "operationId": "getUnusualActivityStats",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/unusual-activity/repeats": {
      "get": {
        "summary": "Tickers with repeated opening flow in a window",
        "operationId": "getUnusualActivityRepeats",
        "parameters": [
          {
            "name": "hours",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 24,
              "maximum": 72
            },
            "description": "Capped server-side at 72; an out-of-range value returns HTTP 400, it is not silently clamped."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 40,
              "maximum": 100
            }
          },
          {
            "name": "openingOnly",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/unusual-activity/repeats/{ticker}": {
      "get": {
        "summary": "Repeat-flow history for one ticker",
        "operationId": "getUnusualActivityRepeatsForTicker",
        "parameters": [
          {
            "$ref": "#/components/parameters/TickerPath"
          },
          {
            "name": "hours",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 24,
              "maximum": 72
            }
          },
          {
            "name": "openingOnly",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/unusual-activity/{id}/translate": {
      "get": {
        "summary": "Plain-English translation of one flow alert",
        "operationId": "getUnusualActivityTranslate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "oneliner",
                "expanded",
                "learning"
              ],
              "default": "expanded"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/market-pulse": {
      "get": {
        "summary": "AI-generated market sentiment narrative",
        "operationId": "getMarketPulse",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/market-pulse/thermal": {
      "get": {
        "summary": "Thermal-only market pulse view",
        "operationId": "getMarketPulseThermal",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/market-pulse/vix": {
      "get": {
        "summary": "VIX snapshot",
        "operationId": "getMarketPulseVix",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/market-stats": {
      "get": {
        "summary": "Aggregate market stats (cached 30s open / 300s closed)",
        "operationId": "getMarketStats",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/market-health": {
      "get": {
        "summary": "Composite risk score + every detector's status and derived detail (same payload as the get_market_health MCP tool)",
        "operationId": "getMarketHealth",
        "responses": {
          "200": {
            "description": "OK"
          },
          "502": {
            "description": "This market health leg is temporarily unavailable"
          }
        }
      }
    },
    "/market-health/history": {
      "get": {
        "summary": "30-day risk-score snapshots, derived signal lines and status changes (get_market_health_history)",
        "operationId": "getMarketHealthHistory",
        "responses": {
          "200": {
            "description": "OK"
          },
          "502": {
            "description": "This market health leg is temporarily unavailable"
          }
        }
      }
    },
    "/market-health/valuation": {
      "get": {
        "summary": "S&P 500 equity-risk-premium valuation verdict, percentages only (get_market_valuation)",
        "operationId": "getMarketValuation",
        "responses": {
          "200": {
            "description": "OK"
          },
          "502": {
            "description": "This market health leg is temporarily unavailable"
          }
        }
      }
    },
    "/market-health/macro": {
      "get": {
        "summary": "US-government macro + liquidity series, yield curve, CFTC positioning (get_macro_liquidity)",
        "operationId": "getMacroLiquidity",
        "responses": {
          "200": {
            "description": "OK"
          },
          "502": {
            "description": "This market health leg is temporarily unavailable"
          }
        }
      }
    },
    "/market-health/cross-asset": {
      "get": {
        "summary": "Derived cross-asset correlations, ratio changes and VIX/VIX3M term structure (get_cross_asset_regime)",
        "operationId": "getCrossAssetRegime",
        "responses": {
          "200": {
            "description": "OK"
          },
          "502": {
            "description": "This market health leg is temporarily unavailable"
          }
        }
      }
    },
    "/market-health/breadth": {
      "get": {
        "summary": "S&P 500 breadth aggregates — percentages and counts only (get_market_breadth)",
        "operationId": "getMarketBreadth",
        "responses": {
          "200": {
            "description": "OK"
          },
          "502": {
            "description": "This market health leg is temporarily unavailable"
          }
        }
      }
    },
    "/scans/breakout-tape-confirmed": {
      "get": {
        "summary": "Breaking Out names the live options tape is also buying bullish — derived verdicts only (get_breakout_tape_confirmed)",
        "operationId": "getBreakoutTapeConfirmed",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/put-call-ratios": {
      "get": {
        "summary": "SPY/QQQ/IWM put-call ratios",
        "operationId": "getPutCallRatios",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/put-call-ratios/{ticker}": {
      "get": {
        "summary": "Put-call ratio for one ticker",
        "operationId": "getPutCallRatioForTicker",
        "parameters": [
          {
            "$ref": "#/components/parameters/TickerPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/sectors/flow": {
      "get": {
        "summary": "Sector-level options-flow rollup",
        "operationId": "getSectorFlow",
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1h",
                "4h",
                "1d",
                "1w"
              ],
              "default": "1d"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/sectors/heatmap": {
      "get": {
        "summary": "Sector heatmap for visualization",
        "operationId": "getSectorHeatmap",
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1h",
                "4h",
                "1d",
                "1w"
              ],
              "default": "1d"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/sectors/etfs": {
      "get": {
        "summary": "Sector ETF ticker mappings",
        "operationId": "getSectorEtfs",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/sectors/analysis": {
      "get": {
        "summary": "Sector ETF performance + oscillator/volume states (EOD, 30 min cache)",
        "operationId": "getSectorAnalysis",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/sectors/dashboard": {
      "get": {
        "summary": "Macro hero + sector grid + technicals + GEX wall breaks",
        "operationId": "getSectorDashboard",
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "5d",
                "1m"
              ],
              "default": "today"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/sectors/rotation": {
      "get": {
        "summary": "RRG-style sector rotation map vs SPY",
        "operationId": "getSectorRotation",
        "parameters": [
          {
            "name": "trail",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                5,
                10,
                20,
                40
              ],
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/sectors/{etf}/flows": {
      "get": {
        "summary": "Individual unusual-activity flows contributing to one sector ETF's net flow",
        "operationId": "getSectorEtfFlows",
        "parameters": [
          {
            "name": "etf",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sector ETF symbol, e.g. XLK, SMH, TAN"
          },
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "5d",
                "1m"
              ],
              "default": "today"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Not a recognized sector ETF"
          }
        }
      }
    },
    "/sectors/market-map": {
      "get": {
        "summary": "Per-ticker options-flow bubble canvas (top ~60 tickers by premium)",
        "operationId": "getSectorMarketMap",
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "5d",
                "1m"
              ],
              "default": "today"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/signals": {
      "get": {
        "summary": "Technical breakout/continuation/triangle signals",
        "operationId": "getSignals",
        "parameters": [
          {
            "name": "signalType",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "breakout",
                "continuation",
                "triangle"
              ],
              "default": "all"
            }
          },
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sectors",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated sectors"
          },
          {
            "name": "timeframe",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "daily"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/signals/stats": {
      "get": {
        "summary": "Aggregate signal stats",
        "operationId": "getSignalsStats",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/signals/{id}": {
      "get": {
        "summary": "One signal by id",
        "operationId": "getSignalById",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/signals/{id}/chart-data": {
      "get": {
        "summary": "Chart data backing one signal",
        "operationId": "getSignalChartData",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/politician-trades": {
      "get": {
        "summary": "Congressional trades (parsed from House Clerk + Senate eFD filings)",
        "operationId": "getPoliticianTrades",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "description": "Redistribution: the underlying disclosures are public record, but these rows are our compilation of them and remain covered by the no-resell terms — see the data-usage section of https://tradermatrix.pro/llms.txt."
      }
    },
    "/politician-trades/stats": {
      "get": {
        "summary": "Aggregate congressional-trade stats",
        "operationId": "getPoliticianTradesStats",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "90"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/politician-trades/by-ticker/{ticker}": {
      "get": {
        "summary": "Congressional trades for one ticker",
        "operationId": "getPoliticianTradesByTicker",
        "parameters": [
          {
            "$ref": "#/components/parameters/TickerPath"
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/earnings-flow/flow": {
      "get": {
        "summary": "Pre-earnings options flow buildup",
        "operationId": "getEarningsFlow",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 7,
              "maximum": 30
            }
          },
          {
            "name": "minFlows",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/earnings-flow/flow/{symbol}": {
      "get": {
        "summary": "Pre-earnings flow buildup for one ticker",
        "operationId": "getEarningsFlowForSymbol",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          },
          {
            "name": "date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. Paid keys get the flows, summary and expected move; a free-preview key gets only symbol, earningsDate and locked: true"
          }
        }
      }
    },
    "/earnings": {
      "get": {
        "summary": "Earnings calendar",
        "operationId": "getEarnings",
        "parameters": [
          {
            "name": "week",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "current",
                "next"
              ]
            }
          },
          {
            "name": "date_from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Overrides week if set"
          },
          {
            "name": "date_to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/gex/market/overview": {
      "get": {
        "summary": "Market-wide gamma bias snapshot",
        "operationId": "getGexMarketOverview",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/gex/{symbol}": {
      "get": {
        "summary": "Gamma exposure by strike for one ticker",
        "operationId": "getGexForSymbol",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          },
          {
            "name": "expiration",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/gex/{symbol}/historical": {
      "get": {
        "summary": "Historical GEX for one ticker (premium)",
        "operationId": "getGexHistorical",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          },
          {
            "name": "hours",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 24,
              "maximum": 168
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/gex/{symbol}/matrix": {
      "get": {
        "summary": "GEX matrix across expirations (premium)",
        "operationId": "getGexMatrix",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/gex/{symbol}/apex": {
      "get": {
        "summary": "Apex gamma-magnet levels (premium)",
        "operationId": "getApexLevels",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          },
          {
            "name": "expiration",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/gex/{symbol}/apex/evolution": {
      "get": {
        "summary": "Apex magnet strength across expirations (premium)",
        "operationId": "getApexEvolution",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          },
          {
            "name": "maxExpiries",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 5,
              "maximum": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/gex/{symbol}/apex/history": {
      "get": {
        "summary": "Apex level history (premium)",
        "operationId": "getApexHistory",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/gex/{symbol}/apex/trend": {
      "get": {
        "summary": "Apex trend over time (premium)",
        "operationId": "getApexTrend",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 90
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/flow/summary": {
      "get": {
        "summary": "Cross-market flow summary",
        "operationId": "getFlowSummary",
        "parameters": [
          {
            "name": "minPremium",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20000
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 500
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "tickers",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated tickers"
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 3,
              "minimum": 0,
              "maximum": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/flow/ticker/{ticker}": {
      "get": {
        "summary": "Flow summary for one ticker",
        "operationId": "getFlowForTicker",
        "parameters": [
          {
            "$ref": "#/components/parameters/TickerPath"
          },
          {
            "name": "minPremium",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20000
            }
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 3
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/bounce-finder": {
      "get": {
        "summary": "Oversold/overbought bounce candidates",
        "operationId": "getBounceFinder",
        "parameters": [
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "top",
                "bottom"
              ],
              "default": "all"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/screeners": {
      "get": {
        "summary": "List available screeners",
        "operationId": "listScreeners",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/screeners/{id}": {
      "get": {
        "summary": "Config/params for one screener",
        "operationId": "getScreener",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Screener not found"
          }
        }
      }
    },
    "/screeners/{id}/run": {
      "post": {
        "summary": "Run a screener (params in JSON body)",
        "operationId": "runScreenerPost",
        "description": "The only endpoint on this API that takes parameters in a JSON request body rather than a query string. Screener ids include bullish-pullback, momentum, volatility-squeeze, small-cap, volatility-surge, gamma-scan, csp-wheel, leaps, leveraged, daily-cuts, accumulation-watch, stage2-uptrend and momentum-leaders. stage2-uptrend and momentum-leaders: membership list only on the public API (symbol, name, direction, earningsSoon; no prices or market data).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Screener-specific params — see GET /screeners/{id} for the param list."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Screener not found"
          },
          "429": {
            "description": "Too many screener runs. Screener runs carry their own per-account rate limit on top of the per-key limit. Wait `retryAfter` seconds (also in the RateLimit headers) before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "retryAfter": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "The screener's data source failed, so the run produced no answer. This is an outage, not 'nothing matched' (an empty match is a 200 with an empty results list). Retry shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Screener unavailable"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Run a screener (params as query string)",
        "operationId": "runScreenerGet",
        "description": "GET alternative to POST /screeners/{id}/run — same screener, params passed as query string instead of a JSON body. Screener ids include bullish-pullback, momentum, volatility-squeeze, small-cap, volatility-surge, gamma-scan, csp-wheel, leaps, leveraged, daily-cuts, accumulation-watch, stage2-uptrend and momentum-leaders. stage2-uptrend and momentum-leaders: membership list only on the public API (symbol, name, direction, earningsSoon; no prices or market data).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Screener not found"
          },
          "429": {
            "description": "Too many screener runs. Screener runs carry their own per-account rate limit on top of the per-key limit. Wait `retryAfter` seconds (also in the RateLimit headers) before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "retryAfter": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "The screener's data source failed, so the run produced no answer. This is an outage, not 'nothing matched' (an empty match is a 200 with an empty results list). Retry shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Screener unavailable"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/economic-calendar": {
      "get": {
        "summary": "Macro economic calendar",
        "operationId": "getEconomicCalendar",
        "parameters": [
          {
            "name": "date_from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "week",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "current",
                "next"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/economic-calendar/predictions": {
      "get": {
        "summary": "Kalshi market-implied odds for cached high-impact events",
        "operationId": "getEconomicCalendarPredictions",
        "parameters": [
          {
            "name": "date_from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "week",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "current",
                "next"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/institutional/buys-sells": {
      "get": {
        "summary": "Institutional (13F) buy/sell aggregation",
        "operationId": "getInstitutionalBuysSells",
        "parameters": [
          {
            "name": "weeks",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 2,
              "minimum": 1,
              "maximum": 52
            }
          },
          {
            "name": "minConviction",
            "in": "query",
            "schema": {
              "type": "number",
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/institutional/{symbol}/history": {
      "get": {
        "summary": "Institutional buy/sell history for one ticker",
        "operationId": "getInstitutionalHistory",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30,
              "minimum": 1,
              "maximum": 365
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/institutional/sector-rotation": {
      "get": {
        "summary": "Institutional sector rotation",
        "operationId": "getInstitutionalSectorRotation",
        "parameters": [
          {
            "name": "weeks",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 4,
              "minimum": 1,
              "maximum": 52
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/institutional/divergences": {
      "get": {
        "summary": "Institutional buy/sell divergences",
        "operationId": "getInstitutionalDivergences",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 14,
              "minimum": 1,
              "maximum": 365
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/institutional/divergences/intrashop": {
      "get": {
        "summary": "Intra-shop divergence alerts",
        "operationId": "getInstitutionalIntrashopDivergences",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30,
              "minimum": 1,
              "maximum": 365
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/institutional/divergences/{symbol}/history": {
      "get": {
        "summary": "Divergence history for one ticker",
        "operationId": "getInstitutionalDivergenceHistory",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 90,
              "minimum": 1,
              "maximum": 365
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/institutional/etf-options": {
      "get": {
        "summary": "Institutional ETF options positioning",
        "operationId": "getInstitutionalEtfOptions",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/long-term/quality": {
      "get": {
        "summary": "Long-term quality/dividend screener",
        "operationId": "getLongTermQuality",
        "parameters": [
          {
            "name": "minScore",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "sector",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minDivYield",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "score",
                "divYield",
                "marketCap",
                "pe"
              ],
              "default": "score"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/long-term/quality/{symbol}": {
      "get": {
        "summary": "Long-term quality detail for one ticker",
        "operationId": "getLongTermQualityForSymbol",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/long-term/dividends": {
      "get": {
        "summary": "Upcoming dividend calendar",
        "operationId": "getLongTermDividends",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Default: today"
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 60,
              "maximum": 365
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 200,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/long-term/sectors": {
      "get": {
        "summary": "Sector list for the long-term quality screener",
        "operationId": "getLongTermSectors",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/long-term/quality-score": {
      "get": {
        "summary": "Every scored symbol's Quality Score, allow-listed fields only (symbol, sector, companyName, qualityScore, marketCapTier, updatedAt) — no fundamentals",
        "operationId": "getLongTermQualityScores",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/long-term/quality-score/{symbol}": {
      "get": {
        "summary": "One symbol's row from the same Quality Score allow-list",
        "operationId": "getLongTermQualityScoreForSymbol",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Symbol not scored"
          }
        }
      }
    },
    "/ticker/search": {
      "get": {
        "summary": "Ticker/company search",
        "operationId": "searchTicker",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/ticker/{symbol}": {
      "get": {
        "summary": "Ticker overview",
        "operationId": "getTickerOverview",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/ticker/{symbol}/options": {
      "get": {
        "summary": "WITHHELD — raw option chain (not available on this API)",
        "operationId": "getTickerOptionsWithheld",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "404": {
            "$ref": "#/components/responses/Withheld"
          }
        }
      }
    },
    "/ticker/{symbol}/tactical-grid": {
      "get": {
        "summary": "WITHHELD — VoPR tactical grid, raw per-contract quotes (not available on this API)",
        "operationId": "getTickerTacticalGridWithheld",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "404": {
            "$ref": "#/components/responses/Withheld"
          }
        }
      }
    },
    "/ticker/{symbol}/smart-money": {
      "get": {
        "summary": "Smart-money flow summary for one ticker",
        "operationId": "getTickerSmartMoney",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/ticker/{symbol}/fundamentals": {
      "get": {
        "summary": "Ticker fundamentals",
        "operationId": "getTickerFundamentals",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/insider/quotes": {
      "get": {
        "summary": "WITHHELD — underlying quote batch (not available on this API)",
        "operationId": "getInsiderQuotesWithheld",
        "responses": {
          "404": {
            "$ref": "#/components/responses/Withheld"
          }
        }
      }
    },
    "/insider": {
      "get": {
        "summary": "Form 4 insider trades",
        "operationId": "getInsiderTrades",
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "buy",
                "sell",
                "other",
                "all"
              ],
              "default": "buy"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100,
              "minimum": 1,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/llm-context/{symbol}": {
      "get": {
        "summary": "One ticker, everything, as plain markdown — built for pasting into an LLM context window",
        "operationId": "getLlmContext",
        "parameters": [
          {
            "$ref": "#/components/parameters/SymbolPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/crypto/quote": {
      "get": {
        "summary": "Live USD spot for up to 10 coins — price, 1h/24h/7d/30d change, market cap, 24h volume, supply, rank, lastUpdated; unknown symbols come back in notFound",
        "operationId": "getCryptoQuote",
        "parameters": [
          {
            "name": "symbols",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated coin tickers, max 10 (e.g. BTC,ETH). A malformed or over-long list is a 400, never truncated."
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Malformed or over-long symbols list"
          }
        }
      }
    },
    "/crypto/overview": {
      "get": {
        "summary": "Market-wide crypto read — total market cap and 24h change, total 24h volume, BTC/ETH dominance, active-currency count, top coins by market cap",
        "operationId": "getCryptoOverview",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 25
            },
            "description": "Number of top coins; clamped to 1-25"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/macro-regime": {
      "get": {
        "summary": "Macro regime from Treasury, Federal Reserve, FRED and CFTC series: yield curve and 10Y-2Y spread, 10Y real yield, breakeven, 5Y5Y forward inflation, fed funds, Fed net liquidity, and CFTC E-mini S&P 500 positioning. Units and asOf on every field, plus an interpretation sentence.",
        "operationId": "getMacroRegime",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/market-internals": {
      "get": {
        "summary": "Derived market internals: S&P 500 breadth (percent above 20/50/200-day averages, advancers/decliners, net new 52-week highs, zones), 60-session stock/bond and dollar/equity correlations, cross-asset ratios (VIX/VIX3M term structure, gold, copper-to-gold, oil 20-session changes) and the equity-risk-premium zone with implied ERP. Percent, ratios and correlations only — no index, futures or volatility levels, no fair-value prices.",
        "operationId": "getMarketInternals",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}