{"openapi":"3.1.0","info":{"title":"XFINLAB Intelligence API","version":"1.0.0","description":"Structured, real market intelligence for developers -- market events, FinBERT sentiment, multi-agent AI debate, an AI-structured intelligence feed, technical/market-structure analysis, Monte Carlo stress testing, and a regime-aware signal. Every response is traceable to a real computation -- never a fabricated number or confidence score. Get a free key instantly at https://www.xfinlab.com/intelligence-api.html#access"},"servers":[{"url":"https://api.xfinlab.com"}],"paths":{"/api/intelligence/v1/events":{"get":{"summary":"Intelligence Events","description":"`ticker` accepts a single symbol, no ticker (all headlines), or a\ncomma-separated list up to _MAX_BATCH_TICKERS (e.g. \"AAPL,MSFT,TSLA\")\nfor watchlist-style queries -- roadmap item #3, 2026-08-17. No-ticker\nand single-ticker requests return the exact same shape as before this\nchange; a multi-ticker request merges/dedupes results across all\nrequested symbols and adds a `tickers` field to each event.","operationId":"intelligence_events_intelligence_v1_events_get","parameters":[{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/sentiment":{"get":{"summary":"Intelligence Sentiment","description":"`ticker` accepts a single symbol or a comma-separated list up to\n_MAX_BATCH_TICKERS (e.g. \"AAPL,MSFT,TSLA\") -- roadmap item #3,\n2026-08-17. A single ticker returns the exact same shape as before\nthis change. A comma-separated list returns `results_by_ticker` keyed\nby symbol instead of one flat `results` array -- averaging sentiment\nscores across unrelated tickers into a single number would be a\nmisleading aggregate, not a real one.","operationId":"intelligence_sentiment_intelligence_v1_sentiment_get","parameters":[{"name":"ticker","in":"query","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Limit"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"},"503":{"description":"Upstream engine temporarily unavailable"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/debate":{"get":{"summary":"Intelligence Debate","description":"Wraps the existing 4-call Bull/Bear/Risk-Manager debate. This is the\nsingle most expensive endpoint in this router (see\nservices/agent_debate_service.py) -- weighted 5x in the quota counter,\nsame reasoning api/agent_debate.py already applies to logged-in users.","operationId":"intelligence_debate_intelligence_v1_debate_get","parameters":[{"name":"ticker","in":"query","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"},"503":{"description":"Upstream engine temporarily unavailable"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/intel/latest":{"get":{"summary":"Intelligence Latest","operationId":"intelligence_latest_intelligence_v1_intel_latest_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":5,"title":"Limit"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","default":"zh-HK","title":"Lang"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/intel/{ticker}":{"get":{"summary":"Intelligence Ticker","operationId":"intelligence_ticker_intelligence_v1_intel__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":5,"title":"Limit"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","default":"zh-HK","title":"Lang"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/technical/{ticker}":{"get":{"summary":"Intelligence Technical","description":"Confluence direction/confidence, trend, MACD, volume, chart patterns,\nand market-structure (BOS/CHOCH/liquidity-sweep/order-flow/volume-\nprofile/institutional-footprint) for one ticker -- everything\nai-analysis.html's dashboard shows, minus AI prose. `lang` reuses the\nsame site-wide per-language translation this endpoint's underlying\nfunction already does for the website (task #592's fix), so API\nconsumers get real localized labels too, not just en/zh.","operationId":"intelligence_technical_intelligence_v1_technical__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","default":"6mo","title":"Period"}},{"name":"interval","in":"query","required":false,"schema":{"type":"string","default":"1d","title":"Interval"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","default":"en","title":"Lang"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/stress-test":{"post":{"summary":"Intelligence Stress Test","description":"Real historical-bootstrap Monte Carlo (see services/monte_carlo_\nservice.py's module docstring for the honesty notes on method/\nlimitations -- returned verbatim in the `method`/`note` fields, never\nstripped out for API consumers). Same MAX_HORIZON_DAYS/MAX_N_SIMULATIONS\ncaps stress-lab.html's own callers get; POST (not GET) since this is\nthe heaviest-compute endpoint in this router after `debate`/`intel`.","operationId":"intelligence_stress_test_intelligence_v1_stress_test_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StressTestRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/regime-signal/{ticker}":{"get":{"summary":"Intelligence Regime Signal","description":"Current causal market regime for `ticker` (services/regime_router_\nservice.py's own causal-only classifier, see that module's docstring\nfor why it doesn't reuse the live Confluence/Regime Belief engines)\nplus whichever composed signal combo (services/formula_composer_\nservice.py) has historically performed best in that regime. If\n`regime` is omitted, the current regime is computed first and used\nfor the lookup -- the actual \"what should I use right now\" answer.","operationId":"intelligence_regime_signal_intelligence_v1_regime_signal__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"regime","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regime"}},{"name":"min_trades","in":"query","required":false,"schema":{"type":"integer","default":5,"title":"Min Trades"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/insider/{ticker}":{"get":{"summary":"Intelligence Insider","description":"SEC Form 4 insider-trading transactions for `ticker` (services/\nsec_form4_service.py -- non-derivative open-market transactions from\nthe most recent filings cross-indexed under the issuer's own CIK via\nEDGAR's browse-edgar feed, not just what the issuer itself filed).\n24h server-side cached, so repeat calls for the same ticker within a\nday don't re-hit EDGAR.","operationId":"intelligence_insider_intelligence_v1_insider__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/short-interest/{ticker}":{"get":{"summary":"Intelligence Short Interest","description":"FINRA bi-weekly equity short-interest for `ticker` (services/\nfinra_short_interest_service.py -- the genuinely free public\nsettlement-date flat file, distinct from FINRA's member-firm-gated\nQuery API). `available: false` with no reported short position is a\nreal, honest \"not currently shorted at reportable levels\" result, not\nan error.","operationId":"intelligence_short_interest_intelligence_v1_short_interest__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/energy/{ticker}":{"get":{"summary":"Intelligence Energy","description":"EIA energy-fundamentals context for `ticker` (services/eia_energy_\nservice.py -- WTI crude spot, Henry Hub nat-gas spot, and Lower-48\nworking nat-gas storage). Only populated for tickers with a real\ncrude/nat-gas linkage (currently USO/UNG, see that module's\n_TICKER_TO_SERIES) -- any other ticker returns `data: null`, never a\nfabricated reading for an unrelated symbol.","operationId":"intelligence_energy_intelligence_v1_energy__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/exchange/{ticker}":{"get":{"summary":"Intelligence Exchange","description":"Same crypto ticker's live 24h stats from two real spot exchanges --\nBinance (services/crypto_exchange_service.py) and Coinbase (services/\ncoinbase_exchange_service.py) -- side by side. Only populated for the\ntracked crypto tickers both services cover; any other ticker returns\n`data: null`, never a fabricated cross-exchange reading.","operationId":"intelligence_exchange_intelligence_v1_exchange__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/fundamentals/{ticker}":{"get":{"summary":"Intelligence Fundamentals","description":"Latest annual (10-K) financial-statement facts for `ticker`\n(services/sec_xbrl_service.py -- revenue, net income, diluted EPS,\ntotal assets/liabilities, operating cash flow, straight from SEC\nXBRL Company Facts). The first real fundamentals data in the\nIntelligence API -- every other endpoint here is positioning,\nevent-driven activity, or macro/commodity context, not the\ncompany's own reported financial statements. 24h server-side\ncached.","operationId":"intelligence_fundamentals_intelligence_v1_fundamentals__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/vix-term-structure":{"get":{"summary":"Intelligence Vix Term Structure","description":"CBOE VIX9D/VIX/VIX3M/VIX6M term structure (services/\ncboe_vix_service.py) -- the options market's own forward-looking\nvolatility curve, plus a contango/backwardation regime read. Not\nticker-specific -- one market-wide snapshot per call.","operationId":"intelligence_vix_term_structure_intelligence_v1_vix_term_structure_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/bank-health/{ticker}":{"get":{"summary":"Intelligence Bank Health","description":"FDIC Call Report health (ROA/ROE/assets/equity) for `ticker`'s\nlead bank subsidiary (services/fdic_banking_service.py). Only\npopulated for the handful of major publicly-traded bank holding\ncompanies this module explicitly maps to a real FDIC certificate\nnumber (see _TICKER_TO_CERT) -- any other ticker returns `data:\nnull`, never a guessed match. Reflects the regulated bank\nsubsidiary's own Call Report, not consolidated holding-company\nGAAP financials.","operationId":"intelligence_bank_health_intelligence_v1_bank_health__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/agriculture/{ticker}":{"get":{"summary":"Intelligence Agriculture","description":"USDA agricultural-commodity price-received context for `ticker`\n(services/usda_agriculture_service.py -- corn/wheat/soybean, pairs\nwith CORN/WEAT/SOYB the same way /v1/energy pairs with USO/UNG).\nOnly populated for tickers with a real commodity linkage; any other\nticker returns `data: null`.","operationId":"intelligence_agriculture_intelligence_v1_agriculture__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/webhooks/subscribe":{"post":{"summary":"Intelligence Webhooks Subscribe","description":"Pro-tier feature (2026-08-28, AJ: \"重有咩賺錢位\" -> Webhook Pro專屬):\npush notifications instead of polling, for 2 real Data Factory\nevents -- see services/webhook_service.py's VALID_EVENT_TYPES for\nthe exact list and why these two were chosen (both already backed by\na daily scheduled job, so this promises honest same-cadence delivery,\nnever a fabricated \"real-time\" claim). Does NOT spend quota -- this\nis a management action, not a data read.","operationId":"intelligence_webhooks_subscribe_intelligence_v1_webhooks_subscribe_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscribeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/webhooks":{"get":{"summary":"Intelligence Webhooks List","description":"Lists every webhook subscription owned by the caller's own API\nkey -- never another key's. Read-only, no quota spend.","operationId":"intelligence_webhooks_list_intelligence_v1_webhooks_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}},"/api/intelligence/v1/webhooks/{webhook_id}":{"delete":{"summary":"Intelligence Webhooks Unsubscribe","description":"Deletes a webhook subscription -- only if it belongs to the\ncaller's own API key (services/webhook_service.py's unsubscribe()\nchecks both id AND api_key in the same DELETE, so guessing another\nkey's id can never delete their subscription).","operationId":"intelligence_webhooks_unsubscribe_intelligence_v1_webhooks__webhook_id__delete","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"integer","title":"Webhook Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid X-API-Key header"},"429":{"description":"Daily quota exceeded for this key's tier"}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"StressTestRequest":{"properties":{"symbol":{"type":"string","title":"Symbol"},"amount":{"type":"number","title":"Amount"},"horizon_days":{"type":"integer","title":"Horizon Days","default":252},"n_simulations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N Simulations"},"lang":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang"}},"type":"object","required":["symbol","amount"],"title":"StressTestRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookSubscribeRequest":{"properties":{"event_type":{"type":"string","title":"Event Type"},"url":{"type":"string","title":"Url"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"}},"type":"object","required":["event_type","url"],"title":"WebhookSubscribeRequest"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}