{ "openapi": "3.1.0", "info": { "title": "dhawal.org Markets API", "version": "1.0.0", "description": "Public, key-less JSON endpoints powering the markets surfaces on dhawal.org. Composites (breadth, options analytics, the daily wire) and public-domain data (FRED macro, CFTC Commitments of Traders, SEC EDGAR filings + XBRL fundamentals, U.S. Treasury yield curve + auctions, EIA energy curves, GDELT) sit alongside a few delayed market-data passthroughs (quote, movers, dividends, earnings). No auth required; successful responses are edge-cached by endpoint policy. The first-party /api/proxy, /api/og-image, /api/symbol-rss, /api/agent-traffic, /api/ask, /api/waitlist, and /api/whales support routes are intentionally outside this documented read-only data contract. AI agents can also connect to the stateless Streamable HTTP MCP server at https://dhawal.org/mcp. Its canonical tools are get_quote, get_regime, run_screen, get_calendar, get_congress_trades, get_13f, get_dataset, and get_brief, with specialist tools for options, COT, insiders, seasonality, the yield curve, and news. get_regime is a compatibility alias for get_macro_regime.", "license": { "name": "MIT", "url": "https://dhawal.org" }, "contact": { "name": "dhawal.org", "url": "https://dhawal.org", "email": "dhawalrankawork@gmail.com" } }, "servers": [ { "url": "https://dhawal.org/api", "description": "Production" } ], "tags": [ { "name": "quote", "description": "Delayed and last-session prices with separate observation and retrieval times." }, { "name": "macro", "description": "FRED macro series accessor." }, { "name": "cot", "description": "CFTC weekly Commitments of Traders." }, { "name": "filings", "description": "SEC EDGAR submissions." }, { "name": "earnings", "description": "Earnings calendar window." }, { "name": "crude-curve", "description": "EIA-backed NYMEX WTI futures curve." }, { "name": "nat-gas-curve", "description": "EIA-backed NYMEX Henry Hub natural-gas futures curve." }, { "name": "wire", "description": "Daily editorial brief drafted via OpenRouter." }, { "name": "movers", "description": "Top gainers, losers, and most-active US names." }, { "name": "dividends", "description": "Dividend and split history per symbol." }, { "name": "breadth", "description": "In-house equal-weight vs cap-weight breadth composite." }, { "name": "yield-curve", "description": "U.S. Treasury nominal + TIPS constant-maturity curve." }, { "name": "auctions", "description": "U.S. Treasury auction results (FiscalData)." }, { "name": "econ-events", "description": "Curated U.S. economic-release schedule." }, { "name": "options", "description": "CBOE delayed options-chain analytics (composites)." }, { "name": "fundamentals", "description": "SEC EDGAR XBRL quarterly fundamentals." }, { "name": "news", "description": "Aggregated public-RSS news wire with story clustering." }, { "name": "gdelt", "description": "GDELT coverage-velocity for a topic query." }, { "name": "transcript-brief", "description": "LLM brief of a public earnings-call transcript." }, { "name": "quotes", "description": "Batched delayed quotes for up to 50 curated symbols." }, { "name": "congress", "description": "STOCK Act congressional trading disclosures." }, { "name": "insider", "description": "SEC Form 4 insider transactions, parsed transaction-level." }, { "name": "health", "description": "Pipeline self-check: the wire, the tape, the model leg." }, { "name": "statistics", "description": "Historical change, z-score, and percentile context." } ], "paths": { "/quote": { "get": { "tags": [ "quote" ], "summary": "Delayed quote for a curated symbol.", "description": "Yahoo primary, Finnhub equity fallback. Returns a normalised flat envelope with separate upstream observation and edge retrieval times. Edge cache TTL: 30s.", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "example": "ES=F", "description": "Yahoo-style symbol. Must be in the curated 191-symbol universe; returns 404 otherwise, unless uncurated=1 is set." }, { "name": "uncurated", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "example": "1", "description": "Set to 1 to resolve a raw Yahoo quote for a symbol outside the curated universe (the any-symbol view). Yahoo only, no Finnhub fallback, no editorial layer; 404 if Yahoo does not carry the symbol." } ], "responses": { "200": { "description": "Normalised quote envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamFailed" } } } }, "/macro": { "get": { "tags": [ "macro" ], "summary": "FRED macro series snapshots.", "description": "Pulls the most-recent observation and prior-observation delta for each requested series. Optional history and ALFRED first-print revision comparisons retain release dates, current values, revision size, and sample size. The asOf parameter uses a FRED vintage date, so values and history reflect what FRED reports was published by that date. asOf cannot be combined with revisions=1. Up to 10 series per call. Edge cache TTL: 6h.", "parameters": [ { "name": "series", "in": "query", "required": true, "schema": { "type": "string" }, "example": "VIXCLS,T10Y2Y,DTWEXBGS", "description": "Comma-separated FRED series ids (alphanumeric + underscore)." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 400 }, "description": "Calendar-day history window. Values above 400 are capped." }, { "name": "asOf", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "FRED vintage date in YYYY-MM-DD form. The response excludes observations and revisions not published by this date." }, { "name": "revisions", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Set to 1 for current versus first-print ALFRED comparisons." }, { "name": "vintageWindow", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 3650, "default": 3650 }, "description": "Calendar-day ALFRED comparison window when revisions=1." } ], "responses": { "200": { "description": "Series readings keyed by id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/NotConfigured" } } } }, "/cot": { "get": { "tags": [ "cot" ], "summary": "Commitments of Traders for one futures product.", "description": "Returns the CFTC Legacy Futures-Only history plus the correct institutional report: TFF categories for financial contracts and Disaggregated categories for physical commodities. Every category includes net, weekly change, 52-week percentile, and sample size. Edge cache TTL: 24h.", "parameters": [ { "name": "product", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "ES", "NQ", "YM", "RTY", "GC", "SI", "HG", "CL", "NG", "ZB", "ZN", "ZF", "EURUSD", "GBPUSD", "USDJPY", "BTC" ] }, "example": "ES" } ], "responses": { "200": { "description": "COT envelope with history + percentile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CotEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamFailed" } } } }, "/filings": { "get": { "tags": [ "filings" ], "summary": "Recent SEC EDGAR filings for a US-listed symbol.", "description": "Resolves ticker → CIK via SEC company_tickers.json, then fetches submissions. Material forms only by default. Edge cache TTL: 1h.", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "example": "AAPL" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 5 } }, { "name": "all", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ] }, "description": "Pass `1` to include every form type, not just material." }, { "name": "insider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ] }, "description": "Pass `1` to return ONLY insider forms (4, 144, 3, 5)." } ], "responses": { "200": { "description": "Filings envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingsEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/NotConfigured" } } } }, "/wire": { "get": { "tags": [ "wire" ], "summary": "Daily editorial brief for /today.", "description": "Drafted via OpenRouter (default model: nvidia/nemotron-3-super-120b-a12b:free, with a free-model fallback chain; override per-deploy with OPENROUTER_MODEL) and grounded in the dhawal.org markets data + macro-events config. Falls back to a deterministic, no-LLM composition (model: \"deterministic\") so the endpoint always returns 200. Edge cache TTL: 12h per date.", "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-05-14" } ], "responses": { "200": { "description": "Brief envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WireEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/NotConfigured" } } } }, "/crude-curve": { "get": { "tags": [ "crude-curve" ], "summary": "NYMEX WTI crude oil futures curve (4 contracts).", "description": "EIA-backed. Returns settlement prices for the front month plus three deferred contracts (PET.RCLC1..PET.RCLC4 daily series). The EIA republishes CME settlement data daily under a public-data-sharing agreement: no scraping, no rate limits, official source. Edge cache TTL: 6h.", "responses": { "200": { "description": "Crude curve envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrudeCurveEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "503": { "$ref": "#/components/responses/NotConfigured" } } } }, "/nat-gas-curve": { "get": { "tags": [ "nat-gas-curve" ], "summary": "NYMEX Henry Hub natural-gas futures curve (4 contracts).", "description": "EIA-backed sister to /crude-curve. Returns settlement prices for the front month plus three deferred contracts (NG.RNGC1..NG.RNGC4 daily series). Same shape, same edge cache TTL (6h).", "responses": { "200": { "description": "Natural-gas curve envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrudeCurveEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "503": { "$ref": "#/components/responses/NotConfigured" } } } }, "/earnings": { "get": { "tags": [ "earnings" ], "summary": "Earnings calendar for a date window.", "description": "Sources from Finnhub /calendar/earnings. Edge cache TTL: 6h.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-05-11" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2026-05-15" } ], "responses": { "200": { "description": "Earnings calendar window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EarningsEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/NotConfigured" } } } }, "/movers": { "get": { "tags": [ "movers" ], "summary": "Top US gainers, losers, and most-active names.", "description": "Yahoo predefined screeners (day_gainers / day_losers / most_actives), with a coverage-universe fallback when the screener is unreachable. Delayed data. Edge cache TTL: 5m.", "responses": { "200": { "description": "Three ranked mover lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoversEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "502": { "$ref": "#/components/responses/UpstreamFailed" } } } }, "/dividends": { "get": { "tags": [ "dividends" ], "summary": "Dividend and split history for a covered symbol.", "description": "Yahoo chart events (10y window). Derives trailing-12-month total, trailing yield, annual totals, and a growth streak counted over complete calendar years. Edge cache TTL: 12h.", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "example": "AAPL", "description": "Symbol from the curated universe; returns 404 otherwise." } ], "responses": { "200": { "description": "Dividend history envelope. Non-payers return empty arrays and null aggregates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DividendsEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamFailed" } } } }, "/breadth": { "get": { "tags": [ "breadth" ], "summary": "Equal-weight vs cap-weight breadth composite.", "description": "In-house composite: deviation of today's RSP/SPY ratio from its 90-day mean, normalised 0-100. One optional leg of the macro regime; degrades to a 200 with null fields when the upstream is unreachable (never 5xx). Edge cache TTL: 6h.", "responses": { "200": { "description": "Breadth envelope. All readings null in the degraded form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreadthEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } } } } }, "/yield-curve": { "get": { "tags": [ "yield-curve" ], "summary": "U.S. Treasury constant-maturity yield curve.", "description": "Parses the U.S. Treasury nominal + TIPS real par-yield XML feeds. Returns the latest curve plus month-ago and year-ago ghost curves, the TIPS real curve (5Y+), and the 2s10s / 3m10y spreads. Public-domain source. Edge cache TTL: 6h.", "responses": { "200": { "description": "Yield-curve envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YieldCurveEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "502": { "$ref": "#/components/responses/UpstreamFailed" } } } }, "/auctions": { "get": { "tags": [ "auctions" ], "summary": "U.S. Treasury auction announcements and results.", "description": "Treasury FiscalData auctions_query (public domain, fetched at build/edge). Returns announcements and bid-to-cover, high yield, allotment shares, and auction dispersion. True tail remains null because FiscalData does not publish the pre-auction when-issued yield. Degrades to empty arrays at 200 when unreachable. Edge cache TTL: 12h.", "responses": { "200": { "description": "Auctions envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuctionsEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } } } } }, "/econ-events": { "get": { "tags": [ "econ-events" ], "summary": "Curated U.S. economic-release schedule for a window.", "description": "Serves the in-house static MACRO_EVENTS schedule (FOMC, CPI, NFP, GDP, PCE, …). No upstream fetch, no key. This route cannot 5xx on an upstream. Edge cache TTL: 6h.", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-06-01" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-06-30" } ], "responses": { "200": { "description": "Economic-events envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EconEventsEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/options": { "get": { "tags": [ "options" ], "summary": "Options-chain analytics for a liquid underlying.", "description": "CBOE delayed quotes, all derivation server-side: put/call ratios, max pain, gamma exposure, ATM IV term structure, 25-delta skew, and put/call data by strike. Whitelisted underlyings only. Edge cache TTL: 30m.", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "_SPX", "_NDX", "_VIX", "SPY", "QQQ", "IWM", "DIA", "TLT", "HYG", "GLD", "SLV", "XLE", "XLF", "SMH", "AAPL", "AMZN", "GOOGL", "META", "MSFT", "NVDA", "TSLA" ] }, "example": "SPY", "description": "Underscore prefix (_SPX) denotes an index. Off-whitelist symbols return 404." } ], "responses": { "200": { "description": "Options-analytics envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptionsEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamFailed" } } } }, "/fundamentals": { "get": { "tags": [ "fundamentals" ], "summary": "Quarterly fundamentals for a US-listed symbol.", "description": "SEC EDGAR XBRL companyfacts (public domain). Revenue / EPS / net income quarterly + annual series, shares-outstanding trend, and YoY deltas. Requires the SEC_USER_AGENT env binding. Edge cache TTL: 24h.", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "example": "AAPL", "description": "Symbol from the curated CIK map; returns 404 otherwise." } ], "responses": { "200": { "description": "Fundamentals envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundamentalsEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/NotConfigured" } } } }, "/news": { "get": { "tags": [ "news" ], "summary": "Aggregated news wire for a category.", "description": "Aggregates free public RSS feeds, dedupes, and clusters related headlines (lead + also-covering outlets, developing flag). Every headline links to its original publisher. Edge cache TTL: 5m.", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "top", "markets", "economy", "companies", "world", "crypto", "commodities" ], "default": "top" }, "example": "markets" } ], "responses": { "200": { "description": "News-wire envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "502": { "$ref": "#/components/responses/UpstreamFailed" } } } }, "/gdelt": { "get": { "tags": [ "gdelt" ], "summary": "Coverage-velocity timeline for a topic query.", "description": "GDELT DOC 2.0 volume-intensity timeline (share of global coverage) for a sanitized query. Keyless public source. Edge cache TTL: 15m.", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 80 }, "example": "federal reserve", "description": "2-80 chars of [word, space, quote, apostrophe, hyphen] after trimming." } ], "responses": { "200": { "description": "GDELT volume envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GdeltEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "502": { "$ref": "#/components/responses/UpstreamFailed" } } } }, "/quotes": { "get": { "tags": [ "quotes" ], "summary": "Batched delayed quotes for up to 50 curated symbols.", "description": "Collapses the per-symbol quote fan-out into one request. Each quote separates upstream observation time from edge retrieval time. Non-curated or failed symbols are simply absent from the map. Edge cache TTL: 30s.", "parameters": [ { "name": "symbols", "in": "query", "required": true, "schema": { "type": "string" }, "example": "SPY,QQQ,^VIX", "description": "Comma-separated Yahoo-style symbols from the curated universe; up to 50 per call." } ], "responses": { "200": { "description": "Quote map keyed by canonical symbol.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotesEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/congress": { "get": { "tags": [ "congress" ], "summary": "Congressional trading disclosures, newest filing first.", "description": "STOCK Act periodic transaction reports from both chambers, parsed transaction-level by the open Congress Trading Monitor dataset (MIT, refreshed daily) and trimmed at the edge. Every row links to the primary government document (House Clerk / Senate eFD). Amounts are the statutory disclosure ranges, never exact figures. Edge cache TTL: 6h.", "parameters": [ { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "example": "NVDA", "description": "Uppercase ticker for the per-symbol record; 404 when the name has no disclosure record." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 250 } }, { "name": "tickeredOnly", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ] }, "description": "Pass `1` to drop non-ticker assets (bonds, funds)." } ], "responses": { "200": { "description": "Congressional trades envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CongressEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamFailed" } } } }, "/insider": { "get": { "tags": [ "insider" ], "summary": "Form 4 insider transactions for a US-listed symbol.", "description": "Opens the most recent Form 4 ownership documents on SEC EDGAR (up to 8 filings) and parses non-derivative transactions. Eligible open-market trades are ranked by transaction shares divided by holdings immediately before the trade, with explicit sample size. Edge cache TTL: 6h.", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "example": "AAPL" } ], "responses": { "200": { "description": "Insider transactions envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsiderEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/NotConfigured" } } } }, "/health": { "get": { "tags": [ "health" ], "summary": "Pipeline self-check.", "description": "Re-runs the news wire aggregation, one index quote resolve, and a minimal model probe, reporting each leg. Overall status is ok only when the wire and the tape both pass; the model leg is reported but non-fatal (the Daily Wrap has a deterministic backstop). Edge cache TTL: 60s.", "responses": { "200": { "description": "Health envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } } } } }, "/statistics": { "get": { "tags": [ "statistics" ], "summary": "Delta Layer statistics for a desk metric.", "description": "Computes 1-day, 1-week, and 1-month changes plus z-score and midrank percentile against prior final observations. The current observation never enters its own reference window. An optional date-level asOf cutoff selects the last retained final observation on or before that UTC date without admitting later observations. Macro and net-liquidity metrics use FRED vintage data. Regime, breadth, and _SPX options metrics use a verified content-addressed Machine Floor snapshot when the exact archive date exists. Other requests use observation-date mode over the latest available history, not upstream-vintage reconstruction. Every statistic reports sample size, temporal resolution, archive resolution, coverage, checksum provenance, and explicit missing-history state. Edge cache TTL: 15m.", "parameters": [ { "name": "metric", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "price", "macro", "regime", "breadth", "cot-commercial", "cot-large-spec", "cot-open-interest", "net-liquidity", "options-gex", "max-pain-distance" ] } }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required for price and options metrics." }, { "name": "series", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required for macro." }, { "name": "product", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required for COT metrics." }, { "name": "lookback", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 20, "maximum": 1260, "default": 252 } }, { "name": "asOf", "in": "query", "required": false, "description": "Inclusive UTC observation-date cutoff. Date-only YYYY-MM-DD values are accepted; future dates and timestamps are rejected. Exact Machine Floor archive dates are resolved for supported metrics.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Versioned statistics envelope, including explicit non-ready states.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatisticsEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/transcript-brief": { "get": { "tags": [ "transcript-brief" ], "summary": "LLM brief of a public earnings-call transcript.", "description": "Summarises a public earnings-call transcript (The Motley Fool, with attribution + source link; earningscall.biz fallback) into a tone label, three takeaways, and a guidance-changed flag via OpenRouter. Returns 404 when no public transcript is available. Edge cache TTL: 7d.", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "example": "AAPL" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Fiscal year hint; omit to take the latest published call." }, { "name": "quarter", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 4 } } ], "responses": { "200": { "description": "Call-brief envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallBriefEnvelope" } } }, "headers": { "X-Dataset-Version": { "$ref": "#/components/headers/DatasetVersion" }, "X-Content-SHA256": { "$ref": "#/components/headers/ContentSha256" }, "X-Data-As-Of": { "$ref": "#/components/headers/DataAsOf" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamFailed" }, "503": { "$ref": "#/components/responses/NotConfigured" } } } } }, "components": { "headers": { "DatasetVersion": { "description": "Version of the endpoint response contract or the payload schemaVersion when one is published.", "schema": { "type": "string" }, "example": "api-json-v1" }, "ContentSha256": { "description": "Lowercase SHA-256 of the exact response body bytes. Recompute over the received bytes before parsing to verify a cited payload.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "DataAsOf": { "description": "Top-level source or generation time when the payload publishes asOf, generatedAt, capturedAt, or fetchedAt.", "schema": { "type": "string" } } }, "schemas": { "FinancialFact": { "type": "object", "additionalProperties": false, "required": [ "canonicalId", "statement", "rawValue", "formattedValue", "unit", "sourceName", "sourceUrl", "artifactUrl", "productUrl", "methodologyId", "methodologyUrl", "apiUrl", "transformation", "period", "asOf", "observationDate", "observedAt", "capturedAt", "generatedAt", "freshness", "expectedCadence", "limitation" ], "properties": { "canonicalId": { "type": "string", "pattern": "^fact_[a-z0-9]{7}$", "description": "Stable identity for the exact sourced observation." }, "statement": { "type": "string" }, "rawValue": { "type": [ "string", "number", "boolean", "array", "object", "null" ], "description": "Source value before presentation formatting." }, "formattedValue": { "type": "string" }, "unit": { "type": "string" }, "sourceName": { "type": "string" }, "sourceUrl": { "oneOf": [ { "type": "null" }, { "type": "string", "pattern": "^https://" } ] }, "artifactUrl": { "type": [ "string", "null" ], "format": "uri-reference" }, "productUrl": { "type": "string", "format": "uri-reference" }, "methodologyId": { "type": "string" }, "methodologyUrl": { "type": [ "string", "null" ], "format": "uri-reference" }, "apiUrl": { "type": [ "string", "null" ], "format": "uri-reference" }, "transformation": { "type": "string" }, "period": { "type": "string" }, "asOf": { "type": [ "string", "null" ] }, "observationDate": { "type": [ "string", "null" ], "format": "date" }, "observedAt": { "type": [ "string", "null" ], "format": "date-time" }, "capturedAt": { "type": [ "string", "null" ], "format": "date-time" }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "freshness": { "type": "string", "enum": [ "live", "delayed", "build", "stale", "unavailable" ] }, "expectedCadence": { "type": "string" }, "limitation": { "type": [ "string", "null" ] } } }, "MoversEnvelope": { "type": "object", "required": [ "asOf", "source", "gainers", "losers", "actives" ], "properties": { "asOf": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "yahoo-screener", "coverage-universe" ] }, "gainers": { "type": "array", "items": { "$ref": "#/components/schemas/MoverRow" } }, "losers": { "type": "array", "items": { "$ref": "#/components/schemas/MoverRow" } }, "actives": { "type": "array", "items": { "$ref": "#/components/schemas/MoverRow" } } } }, "MoverRow": { "type": "object", "required": [ "symbol", "name", "last", "changePct" ], "properties": { "symbol": { "type": "string", "example": "NVDA" }, "name": { "type": "string" }, "last": { "type": "number" }, "changePct": { "type": "number" }, "volume": { "type": [ "number", "null" ] }, "marketCap": { "type": "number" } } }, "DividendsEnvelope": { "type": "object", "required": [ "symbol", "asOf", "windowFrom", "windowTo", "currency", "annual", "recent", "payments", "splits", "source", "fetchedAt", "ttlSeconds" ], "properties": { "symbol": { "type": "string", "example": "AAPL" }, "asOf": { "type": "string", "format": "date" }, "windowFrom": { "type": "string", "format": "date" }, "windowTo": { "type": "string", "format": "date" }, "currency": { "type": "string", "example": "USD" }, "lastClose": { "type": [ "number", "null" ] }, "ttmAmount": { "type": [ "number", "null" ] }, "ttmYieldPct": { "type": [ "number", "null" ] }, "growthStreakYears": { "type": [ "integer", "null" ] }, "annual": { "type": "array", "items": { "type": "object", "required": [ "year", "total" ], "properties": { "year": { "type": "integer", "example": 2025 }, "total": { "type": "number" } } } }, "recent": { "type": "array", "items": { "type": "object", "required": [ "date", "amount" ], "properties": { "date": { "type": "string", "format": "date" }, "amount": { "type": "number" } } } }, "splits": { "type": "array", "items": { "type": "object", "required": [ "date", "ratio" ], "properties": { "date": { "type": "string", "format": "date" }, "ratio": { "type": "string", "example": "4:1" } } } }, "source": { "type": "string", "enum": [ "yahoo" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "QuoteEnvelope": { "type": "object", "required": [ "symbol", "last", "change", "changePct", "prevClose", "currency", "source", "observedAt", "fetchedAt", "ttlSeconds" ], "properties": { "symbol": { "type": "string", "example": "ES=F" }, "display": { "type": "string", "example": "E-mini S&P 500" }, "kind": { "type": "string", "enum": [ "index", "future", "fx", "crypto", "equity", "etf" ] }, "last": { "type": "number" }, "change": { "type": "number" }, "changePct": { "type": "number" }, "prevClose": { "type": "number" }, "open": { "type": [ "number", "null" ] }, "dayHigh": { "type": [ "number", "null" ] }, "dayLow": { "type": [ "number", "null" ] }, "fiftyTwoWeekHigh": { "type": [ "number", "null" ] }, "fiftyTwoWeekLow": { "type": [ "number", "null" ] }, "volume": { "type": [ "number", "null" ] }, "currency": { "type": "string", "example": "USD" }, "source": { "type": "string", "enum": [ "yahoo", "finnhub" ] }, "observedAt": { "type": [ "integer", "null" ], "description": "Upstream market observation time in Unix seconds, when the provider reports it." }, "fetchedAt": { "type": "integer", "description": "Edge retrieval time in Unix seconds. This is not market observation time." }, "ttlSeconds": { "type": "integer", "example": 30 } } }, "StatisticsEnvelope": { "type": "object", "required": [ "schemaVersion", "metric", "metricId", "label", "unit", "value", "asOf", "observationDate", "observationState", "temporal", "status", "reason", "source", "sourceUrl", "artifactUrl", "artifactSha256", "methodologyUrl", "formula", "lookback", "changes", "distribution", "coverage", "fetchedAt", "ttlSeconds" ], "properties": { "schemaVersion": { "type": "integer", "const": 4 }, "metric": { "type": "string" }, "metricId": { "type": "string" }, "label": { "type": "string" }, "unit": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "asOf": { "type": [ "string", "null" ], "format": "date" }, "observationDate": { "type": [ "string", "null" ], "format": "date" }, "observationState": { "type": [ "string", "null" ], "enum": [ "final", "partial", null ] }, "temporal": { "type": "object", "required": [ "mode", "requestedAsOf", "resolvedAsOf", "archiveAsOf", "basis", "revisionPolicy" ], "properties": { "mode": { "type": "string", "enum": [ "latest", "historical" ] }, "requestedAsOf": { "type": [ "string", "null" ], "format": "date" }, "resolvedAsOf": { "type": [ "string", "null" ], "format": "date" }, "archiveAsOf": { "type": [ "string", "null" ], "format": "date" }, "basis": { "type": "string", "const": "observation-date" }, "revisionPolicy": { "type": "string", "enum": [ "latest-available-history", "as-published-by-vintage-date", "as-captured-by-archive-date" ] } } }, "status": { "type": "string", "enum": [ "ready", "insufficient_history", "no_observation", "upstream_failure" ] }, "reason": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "sourceUrl": { "type": [ "string", "null" ] }, "artifactUrl": { "type": [ "string", "null" ] }, "artifactSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "methodologyUrl": { "type": "string" }, "formula": { "type": "object" }, "lookback": { "type": "object" }, "changes": { "type": "object" }, "distribution": { "type": [ "object", "null" ] }, "coverage": { "type": "object" }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer", "example": 900 } } }, "MacroEnvelope": { "type": "object", "required": [ "series", "asOf", "temporal", "source", "fetchedAt", "ttlSeconds" ], "properties": { "series": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "last", "date" ], "properties": { "last": { "type": "number" }, "date": { "type": "string", "format": "date" }, "change": { "type": [ "number", "null" ] } } } ] } }, "history": { "type": "object", "description": "Series-keyed observation arrays when window is supplied." }, "vintages": { "type": "object", "description": "Series-keyed ALFRED first-print comparisons when revisions=1. Each series names observations, sampleSize, formula, and source." }, "asOf": { "type": [ "string", "null" ], "format": "date" }, "temporal": { "type": "object", "required": [ "mode", "requestedAsOf", "vintageDate", "latestObservationDate", "revisionPolicy" ], "properties": { "mode": { "type": "string", "enum": [ "latest", "vintage" ] }, "requestedAsOf": { "type": [ "string", "null" ], "format": "date" }, "vintageDate": { "type": [ "string", "null" ], "format": "date" }, "latestObservationDate": { "type": [ "string", "null" ], "format": "date" }, "revisionPolicy": { "type": "string", "enum": [ "latest-available-history", "as-published-by-vintage-date" ] } } }, "source": { "type": "string", "enum": [ "fred" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "CotEnvelope": { "type": "object", "required": [ "product", "weekEnding", "commercialNet", "largeSpecNet", "source", "fetchedAt" ], "properties": { "product": { "type": "string", "example": "ES" }, "contractCode": { "type": "string", "example": "13874A" }, "name": { "type": "string" }, "weekEnding": { "type": "string", "format": "date" }, "commercialLong": { "type": "number" }, "commercialShort": { "type": "number" }, "commercialNet": { "type": "number" }, "largeSpecLong": { "type": "number" }, "largeSpecShort": { "type": "number" }, "largeSpecNet": { "type": "number" }, "nonReportableLong": { "type": "number" }, "nonReportableShort": { "type": "number" }, "nonReportableNet": { "type": "number" }, "openInterest": { "type": "number" }, "history": { "type": "array", "items": { "type": "object", "properties": { "weekEnding": { "type": "string", "format": "date" }, "commercialNet": { "type": "number" }, "largeSpecNet": { "type": "number" }, "nonReportableNet": { "type": "number" }, "openInterest": { "type": "number" } } } }, "wowChange": { "type": "object", "properties": { "commercial": { "type": "number" }, "largeSpec": { "type": "number" } } }, "percentile52w": { "type": "object", "properties": { "commercial": { "type": "number", "minimum": 0, "maximum": 100 }, "largeSpec": { "type": "number", "minimum": 0, "maximum": 100 } } }, "institutional": { "type": [ "object", "null" ], "description": "TFF categories for financial contracts or Disaggregated categories for physical commodities.", "properties": { "report": { "type": "string", "enum": [ "tff-futures-only", "disaggregated-futures-only" ] }, "sampleSize": { "type": "integer" }, "formula": { "type": "string", "const": "net = long - short" }, "sourceUrl": { "type": "string", "format": "uri" }, "categories": { "type": "array", "items": { "type": "object" } } } }, "source": { "type": "string", "enum": [ "cftc" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "FilingsEnvelope": { "type": "object", "required": [ "symbol", "cik", "items", "source", "fetchedAt" ], "properties": { "symbol": { "type": "string" }, "cik": { "type": "string", "example": "0000320193" }, "name": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FilingEntry" } }, "source": { "type": "string", "enum": [ "sec" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "FilingEntry": { "type": "object", "required": [ "form", "filedAt", "accessionNumber", "url" ], "properties": { "form": { "type": "string", "example": "10-Q" }, "filedAt": { "type": "string", "format": "date" }, "periodOfReport": { "type": "string" }, "accessionNumber": { "type": "string" }, "primaryDocument": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "size": { "type": "integer" } } }, "EarningsEnvelope": { "type": "object", "required": [ "from", "to", "items", "source", "fetchedAt" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/EarningsRow" } }, "source": { "type": "string", "enum": [ "finnhub" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "EarningsRow": { "type": "object", "required": [ "symbol", "date" ], "properties": { "symbol": { "type": "string" }, "date": { "type": "string", "format": "date" }, "hour": { "type": "string", "enum": [ "bmo", "amc", "dmh", "" ] }, "quarter": { "type": [ "integer", "null" ] }, "year": { "type": [ "integer", "null" ] }, "epsEstimate": { "type": [ "number", "null" ] }, "epsActual": { "type": [ "number", "null" ] }, "revenueEstimate": { "type": [ "number", "null" ] }, "revenueActual": { "type": [ "number", "null" ] } } }, "CrudeCurveEnvelope": { "type": "object", "required": [ "contracts", "source", "fetchedAt", "ttlSeconds" ], "properties": { "contracts": { "type": "object", "required": [ "front", "m1", "m2", "m3" ], "properties": { "front": { "$ref": "#/components/schemas/CrudeContractReading" }, "m1": { "$ref": "#/components/schemas/CrudeContractReading" }, "m2": { "$ref": "#/components/schemas/CrudeContractReading" }, "m3": { "$ref": "#/components/schemas/CrudeContractReading" } } }, "source": { "type": "string", "enum": [ "eia" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer", "example": 21600 } } }, "WireEnvelope": { "type": "object", "required": [ "date", "body", "model", "generatedAt", "ttlSeconds" ], "properties": { "date": { "type": "string", "format": "date" }, "body": { "type": "string", "description": "Markdown brief: paragraphs only, no headings. 400-550 words." }, "model": { "type": "string", "example": "nvidia/nemotron-3-super-120b-a12b:free", "description": "OpenRouter slug that drafted the brief, or \"deterministic\" when the LLM was unavailable and the brief was composed from data alone." }, "generatedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer", "example": 43200 } } }, "CrudeContractReading": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "last", "date" ], "properties": { "last": { "type": "number", "description": "Settlement in USD/bbl." }, "date": { "type": "string", "format": "date" } } } ] }, "BreadthEnvelope": { "type": "object", "required": [ "value", "score", "ratioToday", "ratioMean", "date", "source", "fetchedAt", "ttlSeconds" ], "properties": { "value": { "type": [ "number", "null" ], "description": "Deviation (pp) of today's RSP/SPY ratio from its 90d mean." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "ratioToday": { "type": [ "number", "null" ] }, "ratioMean": { "type": [ "number", "null" ] }, "date": { "type": [ "string", "null" ], "format": "date" }, "source": { "type": "string", "enum": [ "yahoo-rsp-spy" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "YieldCurveEnvelope": { "type": "object", "required": [ "latest", "fetchedAt", "ttlSeconds" ], "properties": { "latest": { "$ref": "#/components/schemas/CurveSnapshot" }, "monthAgo": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CurveSnapshot" } ] }, "yearAgo": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CurveSnapshot" } ] }, "realLatest": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CurveSnapshot" } ] }, "spread2s10s": { "type": [ "number", "null" ], "description": "10Y minus 2Y (pp); negative = inverted." }, "spread3m10y": { "type": [ "number", "null" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "CurveSnapshot": { "type": "object", "required": [ "date", "points" ], "properties": { "date": { "type": "string", "format": "date" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/CurvePoint" } } } }, "CurvePoint": { "type": "object", "required": [ "tenor", "months", "yield" ], "properties": { "tenor": { "type": "string", "example": "2Y" }, "months": { "type": "integer", "example": 24 }, "yield": { "type": "number", "description": "Constant-maturity yield, percent." } } }, "AuctionsEnvelope": { "type": "object", "required": [ "upcoming", "results", "fetchedAt", "ttlSeconds" ], "properties": { "upcoming": { "type": "array", "items": { "$ref": "#/components/schemas/AuctionRecord" } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AuctionRecord" } }, "degraded": { "type": "boolean" }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "AuctionRecord": { "type": "object", "required": [ "cusip", "securityType", "securityTerm", "auctionDate" ], "properties": { "cusip": { "type": "string" }, "securityType": { "type": "string", "example": "Note" }, "securityTerm": { "type": "string", "example": "10-Year" }, "auctionDate": { "type": "string", "format": "date" }, "issueDate": { "type": [ "string", "null" ], "format": "date" }, "announcedDate": { "type": [ "string", "null" ], "format": "date" }, "bidToCover": { "type": [ "number", "null" ] }, "highYield": { "type": [ "number", "null" ] }, "highDiscountRate": { "type": [ "number", "null" ] }, "offeringAmt": { "type": [ "number", "null" ] }, "totalAccepted": { "type": [ "number", "null" ] }, "averageMedianYield": { "type": [ "number", "null" ] }, "indirectSharePct": { "type": [ "number", "null" ] }, "directSharePct": { "type": [ "number", "null" ] }, "primaryDealerSharePct": { "type": [ "number", "null" ] }, "auctionDispersionBps": { "type": [ "number", "null" ], "description": "High yield minus average median yield. Not the when-issued tail." }, "tailBps": { "type": "null", "description": "Null because FiscalData omits the pre-auction when-issued yield." }, "tailReason": { "type": "string" } } }, "EconEventsEnvelope": { "type": "object", "required": [ "from", "to", "items", "source", "fetchedAt", "ttlSeconds" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/EconEvent" } }, "source": { "type": "string", "enum": [ "faireconomy", "static-schedule" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "EconEvent": { "type": "object", "required": [ "date", "event", "country" ], "properties": { "date": { "type": "string", "format": "date" }, "time": { "type": "string", "description": "HH:MM ET if known, else empty." }, "event": { "type": "string", "example": "Non-Farm Payrolls" }, "country": { "type": "string", "example": "US" }, "impact": { "type": "string", "enum": [ "low", "medium", "high", "" ] }, "actual": { "type": [ "number", "null" ] }, "forecast": { "type": [ "number", "null" ] }, "previous": { "type": [ "number", "null" ] }, "dateStatus": { "type": "string", "enum": [ "published", "estimated" ] } } }, "OptionsEnvelope": { "type": "object", "required": [ "symbol", "spot", "source", "fetchedAt", "ttlSeconds" ], "properties": { "symbol": { "type": "string", "example": "SPY" }, "spot": { "type": "number" }, "putCallOiRatio": { "type": [ "number", "null" ] }, "putCallVolumeRatio": { "type": [ "number", "null" ] }, "maxPain": { "type": [ "number", "null" ] }, "topOiStrikes": { "type": "array", "items": { "type": "object", "required": [ "strike", "callOi", "putOi" ], "properties": { "strike": { "type": "number" }, "callOi": { "type": "number" }, "putOi": { "type": "number" } } } }, "gex": { "type": [ "number", "null" ], "description": "Naive dollar gamma exposure (calls +, puts -)." }, "atmIvFrontMonth": { "type": [ "number", "null" ] }, "expiriesAnalyzed": { "type": "integer" }, "ivTermStructure": { "type": "array", "items": { "type": "object" } }, "frontSkew25Delta": { "type": [ "object", "null" ] }, "putCallByStrike": { "type": "array", "items": { "type": "object" } }, "sampleSize": { "type": "object", "properties": { "contracts": { "type": "integer" }, "expiries": { "type": "integer" }, "frontExpiryStrikes": { "type": "integer" } } }, "source": { "type": "string", "enum": [ "cboe-delayed" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "FundamentalsEnvelope": { "type": "object", "required": [ "symbol", "source", "fetchedAt", "ttlSeconds" ], "properties": { "symbol": { "type": "string", "example": "AAPL" }, "entityName": { "type": [ "string", "null" ] }, "revenueQuarters": { "type": "array", "items": { "$ref": "#/components/schemas/QuarterPoint" } }, "revenueYears": { "type": "array", "items": { "$ref": "#/components/schemas/QuarterPoint" } }, "epsQuarters": { "type": "array", "items": { "$ref": "#/components/schemas/QuarterPoint" } }, "netIncomeQuarters": { "type": "array", "items": { "$ref": "#/components/schemas/QuarterPoint" } }, "sharesOutstanding": { "type": "array", "items": { "$ref": "#/components/schemas/QuarterPoint" } }, "revenueYoYPct": { "type": [ "number", "null" ] }, "epsYoYPct": { "type": [ "number", "null" ] }, "sharesChangePct1y": { "type": [ "number", "null" ] }, "source": { "type": "string", "enum": [ "sec-edgar-xbrl" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "QuarterPoint": { "type": "object", "required": [ "label", "end", "val" ], "properties": { "label": { "type": "string", "example": "FY26 Q2" }, "end": { "type": "string", "format": "date" }, "val": { "type": "number" } } }, "NewsEnvelope": { "type": "object", "required": [ "category", "items", "clusters", "sourcesOk", "sourcesTotal", "fetchedAt", "ttlSeconds" ], "properties": { "category": { "type": "string", "enum": [ "top", "markets", "economy", "companies", "world", "crypto", "commodities" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WireItem" } }, "clusters": { "type": "array", "items": { "$ref": "#/components/schemas/StoryCluster" } }, "sourcesOk": { "type": "integer" }, "sourcesTotal": { "type": "integer" }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "WireItem": { "type": "object", "required": [ "id", "title", "link", "source", "publishedAt" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "source": { "type": "string", "example": "Reuters" }, "publishedAt": { "type": "integer", "description": "Unix seconds." }, "image": { "type": "string", "format": "uri" }, "summary": { "type": "string", "description": "Feed-provided blurb, not article body." } } }, "StoryCluster": { "type": "object", "required": [ "lead", "also", "sources", "velocity", "score", "developing" ], "properties": { "lead": { "$ref": "#/components/schemas/WireItem" }, "also": { "type": "array", "items": { "$ref": "#/components/schemas/WireItem" } }, "sources": { "type": "integer", "description": "Distinct outlet count." }, "velocity": { "type": "integer", "description": "Distinct new sources in the last 60 min." }, "score": { "type": "number" }, "developing": { "type": "boolean" } } }, "GdeltEnvelope": { "type": "object", "required": [ "query", "points", "fetchedAt", "ttlSeconds" ], "properties": { "query": { "type": "string", "description": "The sanitized query actually sent upstream." }, "points": { "type": "array", "items": { "type": "object", "required": [ "t", "v" ], "properties": { "t": { "type": "integer", "description": "Unix seconds." }, "v": { "type": "number", "description": "Volume intensity (% of global coverage)." } } } }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "CallBriefEnvelope": { "type": "object", "required": [ "symbol", "year", "quarter", "tone", "bullets", "guidanceChanged", "model", "source", "fetchedAt", "ttlSeconds" ], "properties": { "symbol": { "type": "string", "example": "AAPL" }, "year": { "type": "integer", "example": 2026 }, "quarter": { "type": "integer", "minimum": 1, "maximum": 4 }, "conferenceDate": { "type": [ "string", "null" ] }, "tone": { "type": "string", "enum": [ "upbeat", "neutral", "cautious" ] }, "bullets": { "type": "array", "items": { "type": "string" }, "minItems": 3, "maxItems": 3 }, "guidanceChanged": { "type": "boolean" }, "model": { "type": "string" }, "source": { "type": "string", "enum": [ "motley-fool", "earningscall-biz" ] }, "transcriptUrl": { "type": [ "string", "null" ], "format": "uri" }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "QuotesEnvelope": { "type": "object", "required": [ "quotes", "fetchedAt", "ttlSeconds" ], "properties": { "quotes": { "type": "object", "description": "Keyed by canonical symbol; only symbols that resolved appear.", "additionalProperties": { "$ref": "#/components/schemas/QuoteEnvelope" } }, "fetchedAt": { "type": "integer", "description": "Unix seconds." }, "ttlSeconds": { "type": "integer", "example": 30 } } }, "CongressEnvelope": { "type": "object", "required": [ "trades", "count", "scanned", "asOf", "source", "fetchedAt", "ttlSeconds" ], "properties": { "trades": { "type": "array", "items": { "$ref": "#/components/schemas/CongressTrade" } }, "count": { "type": "integer", "description": "Rows returned after the limit." }, "scanned": { "type": "integer", "description": "Valid congressional rows seen upstream." }, "asOf": { "type": [ "string", "null" ], "format": "date", "description": "Latest filing date in the returned rows." }, "ticker": { "type": "string", "description": "Echoed on the per-symbol mode." }, "source": { "type": "string", "enum": [ "congress-trading-monitor" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "CongressTrade": { "type": "object", "required": [ "id", "transactionDate", "filingDate", "ticker", "assetName", "type", "side", "amountLabel", "member", "chamber", "late" ], "properties": { "id": { "type": "string" }, "transactionDate": { "type": "string", "description": "ISO date; empty when the filing omits it." }, "filingDate": { "type": "string" }, "ticker": { "type": [ "string", "null" ], "description": "Null for non-ticker assets (bonds, funds)." }, "assetName": { "type": "string" }, "type": { "type": "string", "example": "Sale (Partial)" }, "side": { "type": "string", "enum": [ "buy", "sell", "exchange", "other" ] }, "amountLow": { "type": [ "number", "null" ] }, "amountHigh": { "type": [ "number", "null" ] }, "amountLabel": { "type": "string", "example": "$15,001 - $50,000" }, "member": { "type": "string" }, "chamber": { "type": "string", "enum": [ "house", "senate" ] }, "party": { "type": [ "string", "null" ], "example": "D" }, "state": { "type": [ "string", "null" ], "example": "RI" }, "owner": { "type": [ "string", "null" ], "example": "Self" }, "daysToFile": { "type": [ "integer", "null" ] }, "late": { "type": "boolean", "description": "Filed outside the 45-day STOCK Act window." }, "docUrl": { "type": [ "string", "null" ], "format": "uri", "description": "The primary government filing." } } }, "InsiderEnvelope": { "type": "object", "required": [ "symbol", "cik", "name", "transactions", "summary", "source", "fetchedAt", "ttlSeconds" ], "properties": { "symbol": { "type": "string", "example": "AAPL" }, "cik": { "type": "string", "example": "0000320193" }, "name": { "type": "string" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/InsiderTransaction" } }, "summary": { "$ref": "#/components/schemas/InsiderSummary" }, "source": { "type": "string", "enum": [ "sec" ] }, "fetchedAt": { "type": "integer" }, "ttlSeconds": { "type": "integer" } } }, "InsiderTransaction": { "type": "object", "required": [ "date", "insider", "code", "url", "filedAt" ], "properties": { "date": { "type": "string", "format": "date" }, "insider": { "type": "string" }, "role": { "type": "string", "example": "Principal Accounting Officer" }, "code": { "type": "string", "example": "S", "description": "Form 4 transaction code (P, S, A, M, F, G, ...)." }, "acquiredDisposed": { "type": "string", "enum": [ "A", "D", "" ] }, "shares": { "type": [ "number", "null" ] }, "price": { "type": [ "number", "null" ], "description": "Null when the filing footnotes the price." }, "value": { "type": [ "number", "null" ] }, "sharesAfter": { "type": [ "number", "null" ] }, "holdingChangePct": { "type": [ "number", "null" ], "description": "Transaction shares divided by pre-trade holdings." }, "conviction": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", null ] }, "ownership": { "type": "string", "enum": [ "D", "I", "" ] }, "security": { "type": "string", "example": "Common Stock" }, "url": { "type": "string", "format": "uri" }, "filedAt": { "type": "string", "format": "date" } } }, "InsiderSummary": { "type": "object", "required": [ "window", "buyValue", "sellValue", "netShares", "buyers", "sellers" ], "properties": { "window": { "type": "string", "enum": [ "90d" ] }, "buyValue": { "type": "number", "description": "Open-market purchases (code P) only." }, "sellValue": { "type": "number", "description": "Open-market sales (code S) only." }, "netShares": { "type": "number" }, "buyers": { "type": "integer" }, "sellers": { "type": "integer" }, "conviction": { "type": "object", "properties": { "eligibleTransactions": { "type": "integer" }, "highBuys": { "type": "integer" }, "highSells": { "type": "integer" }, "mediumBuys": { "type": "integer" }, "mediumSells": { "type": "integer" } } } } }, "HealthEnvelope": { "type": "object", "required": [ "status", "checkedAt", "checks" ], "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "checkedAt": { "type": "integer", "description": "Unix seconds." }, "checks": { "type": "object", "required": [ "newsWire", "quote", "openrouter", "datasets" ], "properties": { "newsWire": { "type": "object", "properties": { "ok": { "type": "boolean" }, "state": { "$ref": "#/components/schemas/FreshnessState" }, "items": { "type": "integer" }, "clusters": { "type": "integer" }, "sourcesOk": { "type": "integer" }, "sourcesTotal": { "type": "integer" }, "observedAt": { "type": [ "integer", "null" ], "description": "Unix seconds for the newest surviving headline." }, "temporalWarning": { "type": [ "string", "null" ], "description": "Qualification when a source clock leads the health-check clock." } } }, "quote": { "type": "object", "properties": { "ok": { "type": "boolean" }, "symbol": { "type": "string", "example": "^GSPC" } } }, "openrouter": { "type": "object", "properties": { "ok": { "type": "boolean" }, "detail": { "type": "string", "description": "Upstream HTTP status on failure; never key material." } } }, "datasets": { "type": "object", "required": [ "crudeCurve", "thirteenF", "auctions", "yieldCurve", "news", "marketSnapshot" ], "properties": { "crudeCurve": { "$ref": "#/components/schemas/DatasetHealthCheck" }, "thirteenF": { "$ref": "#/components/schemas/DatasetHealthCheck" }, "auctions": { "$ref": "#/components/schemas/DatasetHealthCheck" }, "yieldCurve": { "$ref": "#/components/schemas/DatasetHealthCheck" }, "news": { "$ref": "#/components/schemas/DatasetHealthCheck" }, "marketSnapshot": { "$ref": "#/components/schemas/DatasetHealthCheck" } } } } }, "payments": { "type": "array", "description": "Complete paid dividend history in the verified window, oldest first.", "items": { "type": "object", "required": [ "date", "amount" ], "properties": { "date": { "type": "string", "format": "date" }, "amount": { "type": "number" } } } } } }, "FreshnessState": { "type": "string", "enum": [ "current", "stale", "no_observations", "upstream_failure", "not_covered" ] }, "DatasetHealthCheck": { "type": "object", "required": [ "ok", "state", "source", "observedAt", "observationDate", "capturedAt", "ageSeconds", "temporalWarning", "staleAfterSeconds", "lastKnownGood", "detail" ], "properties": { "ok": { "type": "boolean" }, "state": { "$ref": "#/components/schemas/FreshnessState" }, "source": { "type": "string" }, "observedAt": { "type": [ "integer", "null" ], "description": "Unix seconds for a true observation instant. Date-only datasets use observationDate instead." }, "observationDate": { "type": [ "string", "null" ], "format": "date", "description": "Source observation date when the publisher does not provide an instant." }, "capturedAt": { "type": [ "integer", "null" ], "description": "Unix seconds when dhawal.org retained or generated the checked artifact." }, "ageSeconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Non-negative age derived from capture time, or observation time when no capture is available." }, "temporalWarning": { "type": [ "string", "null" ], "description": "Explicit qualification for clock skew or another temporal-integrity issue." }, "staleAfterSeconds": { "type": "integer" }, "lastKnownGood": { "type": "string", "enum": [ "build-snapshot", "browser-cache", "edge-cache", "none" ] }, "detail": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } }, "responses": { "BadRequest": { "description": "Required parameter missing or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "The requested resource (symbol / product) is outside the curated coverage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UpstreamFailed": { "description": "Upstream provider returned a non-2xx status, was unreachable, or sent malformed data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotConfigured": { "description": "Required server-side credentials / env binding are not present in this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }