{
  "openapi": "3.0.3",
  "info": {
    "title": "TraderDaddy Pro 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 TraderDaddy Pro'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. Three routes that would otherwise carry raw per-contract quotes are deliberately withheld (404): `/ticker/{symbol}/options`, `/ticker/{symbol}/tactical-grid`, and `/insider/quotes`.\n\nAn MCP tool-calling surface is also available at `POST /mcp` (not itself describable by OpenAPI) — 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"
    }
  },
  "servers": [
    {
      "url": "https://api.traderdaddy.pro/api/v1"
    }
  ],
  "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 TraderDaddy Pro 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",
                "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 range, e.g. 0-7"
          },
          {
            "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"
          },
          "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"
          }
        }
      }
    },
    "/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"
          }
        }
      }
    },
    "/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.",
        "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"
          }
        }
      },
      "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.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Screener not found"
          }
        }
      }
    },
    "/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"
          }
        }
      }
    },
    "/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}/dossier": {
      "get": {
        "summary": "Combined technicals + flow dossier for one ticker",
        "operationId": "getTickerDossier",
        "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"
                }
              }
            }
          }
        }
      }
    }
  }
}