{"openapi":"3.1.0","info":{"title":"Fahali Intelligence API","version":"1.0.0","description":"Structured market intelligence endpoints for AI agents, MCP tools, and institutional consumers. All responses conform to the canonical Fahali Intelligence schema family (legacy SpectraIntelligence shape)."},"servers":[{"url":"https://app.fahaliai.com","description":"Production"},{"url":"http://localhost:5000","description":"Local development"}],"paths":{"/agent/verdict":{"get":{"summary":"Get structured market verdict","description":"Returns direction (bullish/bearish/neutral), confidence score, reasoning chain, expected move percentage, and forecast horizon for one or more symbols. Optionally includes contagion risk data.","operationId":"getMarketVerdict","parameters":[{"name":"symbols","in":"query","description":"Comma-separated trading symbols (e.g. 'BTCUSDT,ETHUSDT'). Omitting returns top signals across all symbols.","required":false,"schema":{"type":"string"}},{"name":"includeContagion","in":"query","description":"If true, enriches response with contagion risk from tail_dependence table.","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Market verdict intelligence","headers":{"X-Fahali-Direction-Confidence":{"schema":{"type":"integer","enum":[1]}},"X-Fahali-Schema-Version":{"schema":{"type":"string","enum":["1.0"]}},"X-Fahali-Contagion-Included":{"schema":{"type":"integer","enum":[0,1]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"schemaVersion":{"type":"string","enum":["1.0"]},"updatedAt":{"type":"string","format":"date-time"},"count":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SpectraIntelligence"}}}}}}},"503":{"description":"Database not ready","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/agent/portfolio-risk":{"get":{"summary":"Get portfolio risk assessment","description":"Returns overall risk score, value-at-risk, expected drawdown, per-position risk breakdown, and contagion risk. Requires connected exchange accounts for personalized data.","operationId":"getPortfolioRisk","parameters":[],"responses":{"200":{"description":"Portfolio risk assessment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpectraPortfolioRiskAssessment"}}}}}}},"/agent/capital-flow":{"get":{"summary":"Get capital flow intelligence","description":"Returns net flow USD, direction (inflow/outflow/neutral), institutional vs retail breakdown, whale activity, and flow trend for a specific symbol.","operationId":"getCapitalFlow","parameters":[{"name":"symbol","in":"query","description":"Trading symbol (e.g. 'BTCUSDT'). Required.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Capital flow intelligence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpectraCapitalFlowResponse"}}}},"400":{"description":"Missing symbol parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/agent/contagion":{"get":{"summary":"Get contagion map","description":"Returns cross-asset contagion and tail dependence map: nodes (symbols with risk scores), edges (pairwise correlation strength), and clusters of correlated assets.","operationId":"getContagionMap","parameters":[],"responses":{"200":{"description":"Contagion map","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpectraContagionMap"}}}}}}}},"components":{"schemas":{"SpectraDirection":{"type":"string","enum":["bullish","bearish","neutral","unknown"]},"SpectraSeverity":{"type":"string","enum":["critical","high","moderate","low"]},"SpectraRiskLevel":{"type":"string","enum":["critical","high","moderate","low"]},"SpectraActionType":{"type":"string","enum":["hold","reduce","increase","exit","hedge","watch"]},"SpectraVerdict":{"type":"object","properties":{"direction":{"$ref":"#/components/schemas/SpectraDirection"},"confidence":{"type":"number","minimum":0,"maximum":1},"uncertainty":{"type":"number","minimum":0,"maximum":1},"expectedMovePct":{"type":"number","nullable":true},"forecastHorizon":{"type":"string","enum":["12h","24h","72h","7d","30d"]},"severity":{"$ref":"#/components/schemas/SpectraSeverity"},"urgencyScore":{"type":"number","minimum":0,"maximum":1}},"required":["direction","confidence","uncertainty","forecastHorizon","severity","urgencyScore"]},"SpectraReasoning":{"type":"object","properties":{"steps":{"type":"array","items":{"type":"string"}},"toolsUsed":{"type":"array","items":{"type":"string"}},"conflictScore":{"type":"number","minimum":0,"maximum":1},"missingSignals":{"type":"array","items":{"type":"string"}},"cycleCount":{"type":"integer","minimum":1}},"required":["steps","toolsUsed","conflictScore","missingSignals","cycleCount"]},"SpectraCapitalFlow":{"type":"object","properties":{"netFlowUsd":{"type":"number"},"direction":{"type":"string","enum":["inflow","outflow","neutral"]},"confidence":{"type":"number"},"institutionalRatio":{"type":"number"},"whaleCount":{"type":"integer"},"trend":{"type":"string","enum":["accelerating","decelerating","stable"]}},"required":["netFlowUsd","direction","confidence","institutionalRatio","whaleCount","trend"]},"SpectraContagion":{"type":"object","properties":{"risk":{"$ref":"#/components/schemas/SpectraRiskLevel"},"confidence":{"type":"number"},"affectedSymbols":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"correlation":{"type":"number"},"expectedImpactPct":{"type":"number"},"timeToMaterializeHours":{"type":"number"}}}}},"required":["risk","confidence","affectedSymbols"]},"SpectraAction":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/SpectraActionType"},"targetExposure":{"type":"number","nullable":true},"timeframe":{"type":"string","enum":["immediate","24h","72h","7d"]},"rationale":{"type":"string"}},"required":["type","timeframe","rationale"]},"SpectraProvenance":{"type":"object","properties":{"source":{"type":"string","enum":["predictions","alerts","agent_verdict","derived"]},"modelVersion":{"type":"string"},"engineNames":{"type":"array","items":{"type":"string"}},"walkForwardValidated":{"type":"boolean"},"dataAsOf":{"type":"string","format":"date-time"}},"required":["source","modelVersion","engineNames","walkForwardValidated","dataAsOf"]},"SpectraAiMetadata":{"type":"object","properties":{"schemaVersion":{"type":"string","enum":["1.0"]},"reasoningTrace":{"type":"boolean"},"confidenceNormalized":{"type":"boolean"},"schemaStable":{"type":"boolean"},"lastModelRetrain":{"type":"string","format":"date","nullable":true}},"required":["schemaVersion","reasoningTrace","confidenceNormalized","schemaStable"]},"SpectraIntelligence":{"type":"object","properties":{"symbol":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"verdict":{"$ref":"#/components/schemas/SpectraVerdict"},"reasoning":{"$ref":"#/components/schemas/SpectraReasoning"},"capitalFlow":{"$ref":"#/components/schemas/SpectraCapitalFlow"},"contagion":{"$ref":"#/components/schemas/SpectraContagion"},"action":{"$ref":"#/components/schemas/SpectraAction"},"provenance":{"$ref":"#/components/schemas/SpectraProvenance"},"aiMetadata":{"$ref":"#/components/schemas/SpectraAiMetadata"}},"required":["symbol","timestamp","verdict","reasoning","provenance","aiMetadata"]},"SpectraPortfolioRiskAssessment":{"type":"object","properties":{"portfolio":{"type":"object","properties":{"totalValue":{"type":"number"},"overallRiskScore":{"type":"number"},"overallRiskLevel":{"$ref":"#/components/schemas/SpectraRiskLevel"},"expectedDrawdownPct":{"type":"number"},"valueAtRisk95":{"type":"number"}},"required":["totalValue","overallRiskScore","overallRiskLevel","expectedDrawdownPct","valueAtRisk95"]},"positions":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"allocation":{"type":"number"},"riskScore":{"type":"number"},"riskLevel":{"$ref":"#/components/schemas/SpectraRiskLevel"},"expectedMovePct":{"type":"number"},"correlationToPortfolio":{"type":"number"},"recommendation":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/SpectraActionType"},"rationale":{"type":"string"}},"required":["action","rationale"]}},"required":["symbol","allocation","riskScore","riskLevel","expectedMovePct","correlationToPortfolio","recommendation"]}},"contagionRisk":{"type":"object","properties":{"highestRiskSymbol":{"type":"string"},"affectedCount":{"type":"integer"},"expectedPortfolioImpactPct":{"type":"number"}},"required":["highestRiskSymbol","affectedCount","expectedPortfolioImpactPct"]},"provenance":{"$ref":"#/components/schemas/SpectraProvenance"},"aiMetadata":{"$ref":"#/components/schemas/SpectraAiMetadata"}},"required":["portfolio","positions","contagionRisk","provenance","aiMetadata"]},"SpectraContagionMap":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"riskScore":{"type":"number"},"riskLevel":{"$ref":"#/components/schemas/SpectraRiskLevel"},"confidence":{"type":"number"}},"required":["symbol","riskScore","riskLevel","confidence"]}},"edges":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"strength":{"type":"number"},"correlation":{"type":"number"},"confidence":{"type":"number"},"timeToMaterializeHours":{"type":"number"}},"required":["source","target","strength","correlation","confidence","timeToMaterializeHours"]}},"clusters":{"type":"array","items":{"type":"object","properties":{"symbols":{"type":"array","items":{"type":"string"}},"riskLevel":{"$ref":"#/components/schemas/SpectraRiskLevel"},"leadSymbol":{"type":"string"},"lagHours":{"type":"number"}},"required":["symbols","riskLevel","leadSymbol","lagHours"]}},"provenance":{"$ref":"#/components/schemas/SpectraProvenance"},"aiMetadata":{"$ref":"#/components/schemas/SpectraAiMetadata"}},"required":["nodes","edges","clusters","provenance","aiMetadata"]},"SpectraCapitalFlowResponse":{"type":"object","properties":{"symbol":{"type":"string"},"windowHours":{"type":"integer"},"netFlowUsd":{"type":"number"},"direction":{"type":"string","enum":["inflow","outflow","neutral"]},"confidence":{"type":"number"},"breakdown":{"type":"object","properties":{"institutional":{"type":"number"},"retail":{"type":"number"},"whale":{"type":"number"}},"required":["institutional","retail","whale"]},"trend":{"type":"string","enum":["accelerating","decelerating","stable"]},"provenance":{"$ref":"#/components/schemas/SpectraProvenance"},"aiMetadata":{"$ref":"#/components/schemas/SpectraAiMetadata"}},"required":["symbol","windowHours","netFlowUsd","direction","confidence","breakdown","trend","provenance","aiMetadata"]}}}}