openapi: 3.1.0 info: title: AgentCanary API description: | Market intelligence API with 4 layers: Raw Data → Signals → Composites → Intelligence. **Billing Live:** Deposit USDC/USDT on any major EVM chain (Base, Ethereum, Arbitrum, Optimism, Polygon). $5 minimum. 4 tiers: Explorer (free), Builder ($50+), Signal ($150+), Institutional ($500+). **4x daily briefs:** Radar, Signal, Pulse, Wrap. Credits never expire. No KYC. version: 1.0.0 contact: name: AgentCanary url: https://agentcanary.ai license: name: Proprietary servers: - url: https://api.agentcanary.ai description: Production security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key from POST /api/keys/create schemas: Error: type: object properties: error: type: string message: type: string code: type: integer Brief: type: object properties: session: type: string enum: - morning - midday - evening - intelligence - cycle date: type: string format: date time: type: string headline: type: string headlineColor: type: string desc: type: string tags: type: array items: type: object properties: t: type: string c: type: string panels: type: array items: type: object telegramText: type: string nullable: true telegramMessageId: type: integer nullable: true Regime: type: object properties: regime: type: string enum: - RISK_ON - CAUTIOUS - RISK_OFF - STAGFLATION - GOLDILOCKS riskGauge: type: number description: 0-100 composite risk gauge riskLevel: type: string enum: - low - medium - elevated - high - extreme growth: type: string enum: - UP - DOWN - FLAT inflation: type: string enum: - UP - DOWN - FLAT quadrant: type: string regimeLabel: type: string flags: type: array items: type: string updated: type: string format: date-time ScenarioProbabilities: type: object properties: date: type: string format: date probabilities: type: object properties: late_cycle: type: number recession: type: number goldilocks: type: number stagflation: type: number hegemony: type: number displacement: type: number dominant: type: string signalCount: type: integer activeSignals: type: array items: type: object properties: id: type: string value: oneOf: - type: number - type: string level: type: string threshold: type: string SingleScenario: type: object properties: id: type: string probability: type: number baseWeight: type: number delta: type: string activeSignals: type: array items: type: object description: type: string RiskScore: type: object properties: score: type: number description: 0-100 composite label: type: string enum: - LOW - MODERATE - ELEVATED - HIGH - EXTREME components: type: object additionalProperties: type: object properties: raw: type: number score: type: number weight: type: number Indicator: type: object properties: date: type: string format: date signal: type: string level: type: string timestamp: type: string format: date-time additionalProperties: true IndicatorSummary: type: object properties: date: type: string format: date indicators: type: array items: $ref: '#/components/schemas/Indicator' bullish: type: integer bearish: type: integer neutral: type: integer NarrativeScore: type: object properties: name: type: string score: type: integer minimum: 1 maximum: 5 thesis: type: string change: type: string nullable: true NarrativeDetail: type: object properties: name: type: string score: type: integer level: type: string enum: - UNCROWDED - LOW - NEUTRAL - CROWDED - EXTREME thesis: type: string inputs: type: object properties: etfMomentum: type: object properties: etfs: type: array items: type: string zScores: type: array items: type: number googleTrends: type: object properties: ratio: type: number velocity: type: string cftcCot: type: object properties: asset: type: string netLong: type: number bofaFms: type: object properties: crowdedRank: type: integer pct: type: number newsBuzz: type: integer interpretation: type: string CryptoReentry: type: object properties: score: type: integer maxScore: type: integer signal: type: string enum: - not_ready - approaching - ready - strong_buy factors: type: object additionalProperties: type: object properties: met: type: boolean detail: type: string MRSignal: type: object properties: asset: type: string timeframe: type: string direction: type: string enum: - BUY - SELL zScore: type: number rsi: type: number contextFilter: type: object properties: regimeAllowed: type: boolean newsOverride: type: boolean narrativeScore: type: integer MRStats: type: object properties: totalTrades: type: integer openTrades: type: integer closedTrades: type: integer winRate: type: number totalPnl: type: number monthlyPnl: type: object additionalProperties: type: number BofaFMS: type: object properties: surveyDate: type: string bullBear: type: number bullBearSignal: type: string cashLevel: type: number cashLevelSignal: type: string crowdedTrades: type: array items: type: object properties: label: type: string pct: type: number position: type: integer growthExpectations: type: string equityAllocation: type: string aiCapex: type: string NewsArticle: type: object properties: headline: type: string sentiment: type: string enum: - positive - negative - neutral sentimentScore: type: number source: type: string timestamp: type: string format: date-time relevance: type: string enum: - direct - indirect - sector SignalValue: type: object properties: value: type: number change: type: number nullable: true zScore: type: number nullable: true level: type: string signal: type: string updated: type: string format: date-time BusinessCycle: type: object properties: date: type: string format: date cowen: type: object properties: metric: type: number nullable: true inputs: type: object icsa: type: object creditStress: type: object properties: level: type: string flags: type: integer creditCards: type: object consumerLoans: type: object allLoans: type: object igv: type: object nullable: true properties: price: type: number goldenPocket: type: number distanceToPocket: type: number trend: type: string PeRatio: type: object properties: name: type: string example: Lido symbol: type: string example: LDO mcap: type: integer description: Market cap in USD rev24h: type: integer description: 24h revenue in USD rev7d: type: integer annRev: type: integer description: Annualized revenue (rev24h * 365) pe: type: number description: Price/Earnings ratio (mcap / annRev) prevPe: type: number nullable: true description: Yesterday's PE peChange: type: number nullable: true description: '% change in PE vs yesterday' category: type: string enum: - undervalued - fair - growth - overvalued YieldPool: type: object properties: symbol: type: string example: USDC chain: type: string example: Base project: type: string example: aave-v3 apy: type: number apyBase: type: number description: Base APY (organic, no rewards) apyReward: type: number description: Reward token APY tvl: type: integer YieldSummary: type: object properties: topPools: type: array items: $ref: '#/components/schemas/YieldPool' stableYields: type: array items: $ref: '#/components/schemas/YieldPool' avgStableApy: type: number PerpMarket: type: object properties: symbol: type: string example: ETH-USD project: type: string example: hyperliquid chain: type: string fundingRate: type: number description: Current funding rate (0.01 = 1%) funding7dAvg: type: number oi: type: integer description: Open interest in USD sentiment: type: string enum: - extreme-long - bullish - neutral - bearish - extreme-short StablecoinSummary: type: object properties: totalMcap: type: number description: Total tracked stablecoin market cap tracked: type: array items: type: object properties: symbol: type: string name: type: string mcap: type: integer price: type: number ChainTvl: type: object properties: name: type: string example: Ethereum tvl: type: integer change: type: number nullable: true description: '% change vs yesterday' TokenUnlock: type: object properties: name: type: string symbol: type: string unlockDate: type: string format: date tokensUnlocking: type: integer pctOfCirculating: type: number description: '% of circulating supply' estValueUsd: type: integer mcap: type: integer impact: type: string enum: - HIGH - MEDIUM - LOW DefiSignal: type: object properties: type: type: string enum: - STABLECOIN_FLOW - EXTREME_FUNDING - YIELD_SHIFT - PE_COMPRESSION - TOKEN_UNLOCK direction: type: string detail: type: string description: Human-readable explanation implication: type: string description: What this means for trading KeyInfo: type: object properties: keyId: type: string tier: type: string enum: - free - pro - enterprise balance: type: number rateLimit: type: object properties: perMinute: type: integer perDay: type: integer created: type: string format: date-time OiAtom: type: object description: | Open interest atom — coinglass-v2 cross-exchange OI snapshot. Aggregated across 45 tracked perps × 21 exchanges. Per-symbol fields include `oi_change_4h/24h/7d/30d_pct`, `volume_usd`, `oi_vol_ratio`, `funding_oi_weighted`. Refreshes ~hourly upstream. properties: schemaVersion: type: string example: 1.0.0 source: type: string example: coinglass-v2 open interest sourcePath: type: string sourceObservedAt: type: string format: date-time generatedAt: type: string format: date-time ageMs: type: integer freshnessState: type: string enum: - fresh - degraded - stale-served - inactive payload: type: object properties: ageHours: type: number description: Source data age in hours at atom build time pulledAt: type: string format: date-time totalOi: type: number description: Aggregate OI USD across qualifying symbols symbolCount: type: integer description: Count of symbols clearing MIN_OI_USD threshold topByOi: type: array description: Top-N symbols ranked by OI USD size items: type: object properties: symbol: type: string oiUsd: type: number topByOi4h: type: array description: Top-N symbols by absolute 4h OI Δ% (intraday shifters) items: type: object properties: symbol: type: string oiChg4hPct: type: number description: Signed % change in OI over 4h oiUsd: type: number lines: type: array description: Human-readable prose lines (rendered as the OPEN INTEREST section of the pulse brief) items: type: string LiquidationsAtom: type: object description: | Liquidations atom — coinglass-v2 24h aggregate + latest 4h breakdown. Surfaces directional pressure (long-dominant >=65%, short-dominant <=35%, balanced otherwise) with per-side USD + event counts. properties: schemaVersion: type: string example: 1.0.0 source: type: string example: coinglass-v2 liquidations sourcePath: type: string sourceObservedAt: type: string format: date-time generatedAt: type: string format: date-time ageMs: type: integer freshnessState: type: string enum: - fresh - degraded - stale-served - inactive payload: type: object properties: ageHours: type: number pulledAt: type: string format: date-time total24h: type: number description: Total liquidations USD over 24h latest4h: type: object description: Latest 4h breakdown — long vs short USD + per-side event counts + dominant label properties: long: type: number description: Long liquidations USD in last 4h short: type: number description: Short liquidations USD in last 4h total: type: number count: type: integer description: Combined event count longCount: type: integer nullable: true description: Long-side event count (null if upstream doesn't expose it) shortCount: type: integer nullable: true longPct: type: number nullable: true description: Long share of latest-4h total, 0-100 shortPct: type: number nullable: true dominant: type: string enum: - long-dominant - short-dominant - balanced line: type: string nullable: true description: Human-readable prose line as rendered in pulse brief parameters: IndicatorName: name: name in: path required: true schema: type: string enum: - 21ema-trend - alt-funding-spike - alt-volatility-spike - btc-dominance - btc-exchange-flows - btc-leverage-risk - btc-liquidation-heatmap - btc-momentum-reversal - btc-oi-funding - btc-orderbook-imbalance - btc-pi-cycle - btc-quintile-model - btc-whale-activity - bull-market-support-band - cross-asset-volatility - derivatives-structure-shift - ethbtc-ratio - global-safety-override - gold-btc-correlation - large-trades-whale-orders - liquidation-ranges - ma-trend-reversal - midtier-alt-crash - social-sentiment - stablecoin-composite - stablecoin-vs-tcmc - wyckoff-structure NarrativeName: name: name in: path required: true schema: type: string enum: - gold - ai-infrastructure - energy-power - uranium - btc-crypto - defi - defense - copper - income-dividend - biotech - macro - semiconductors - china-short - treasury-duration - displacement - europe - korea - brazil-latam ScenarioId: name: id in: path required: true schema: type: string enum: - late_cycle - recession - goldilocks - stagflation - hegemony - displacement DataName: name: name in: path required: true schema: type: string enum: - realtime-prices - market-quotes - yahoo-quotes # deprecated alias — use market-quotes - macro-snapshot - breaking-news - newsletters - funding-rates - signal-state - rsi-statistics - exchange-volumes - btc-orderbook-depth - btc-exchange-wallet - eth-exchange-wallet - hyperliquid-whales - whale-alerts-btc - market-structure - market-analysis - treasury-stats - financial-calendar - polymarket - xtg-messages - coingecko-global tags: - name: Briefs description: Layer 4 — Intelligence briefs (FREE) - name: Macro description: Layer 3 — Macro regime, risk score, business cycle (PRO) - name: Scenarios description: Layer 3 — Bayesian scenario probability engine (PRO) - name: Indicators description: Layer 3 — 27 AC technical/on-chain indicators (PRO) - name: Narratives description: Layer 3 — 18 narrative crowding scores (ENTERPRISE) - name: Signals description: Layer 2 — Individual metric endpoints (PRO) - name: Crypto description: Layer 3 — Crypto-specific composites (ENTERPRISE) - name: MR Scanner description: Layer 3 — Mean reversion scanner (ENTERPRISE) - name: News description: Layer 4 — Ticker-matched news intelligence (ENTERPRISE) - name: Data description: Layer 1 — Raw cached data (PRO) - name: DeFi description: 'Layer 3 — DeFi intelligence: PE ratios, yields, perps, unlocks, stablecoins (PRO)' - name: Keys description: API key management paths: /api/briefs/latest: get: tags: - Briefs summary: Latest intelligence brief security: [] responses: '200': description: Latest brief content: application/json: schema: $ref: '#/components/schemas/Brief' description: Most recent intelligence brief (whichever slot fired last — radar / signal / pulse / wrap). Returns full brief object with headline, panels, atom data, generated_at timestamp, and Telegram-formatted text. Useful for agents wanting the freshest market snapshot without filtering by slot. /api/briefs/feed: get: tags: - Briefs summary: Rolling 7-day brief feed (max 21) security: [] responses: '200': description: Array of briefs content: application/json: schema: type: array items: $ref: '#/components/schemas/Brief' description: Rolling 7-day brief feed, max 21 items. Returns chronological array of briefs with metadata + brief_text. Useful for agents building daily/weekly digests or running historical analysis over a recent window. /api/briefs/archive: get: tags: - Briefs summary: Full permanent brief archive with Telegram text security: [] responses: '200': description: Array of all briefs content: application/json: schema: type: array items: $ref: '#/components/schemas/Brief' description: Full permanent brief archive with pagination. Returns brief metadata + Telegram-formatted text for every published brief since archive start. Useful for backtesting agent strategies against historical brief content. /api/briefs/{type}: get: tags: - Briefs summary: Filter briefs by type security: [] parameters: - name: type in: path required: true schema: type: string enum: - morning - midday - evening - intelligence - cycle responses: '200': description: Filtered briefs content: application/json: schema: type: array items: $ref: '#/components/schemas/Brief' description: 'Filter the brief feed by type: morning / midday / evening / intelligence / cycle. Returns the most recent N briefs of that type. Useful for agents that specialize on a single brief cadence (e.g., end-of-day wrap consumers).' /api/macro/regime: get: tags: - Macro summary: Current macro regime classification responses: '200': description: Regime data content: application/json: schema: $ref: '#/components/schemas/Regime' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' description: 'Current macro regime classification — one of expansion / overheating / stagflation / late-cycle / recession / displacement / neutral — plus the underlying signals driving the classification and transition probabilities to adjacent regimes. Agent use: condition tactical decisions on current macro state.' /api/macro/snapshot: get: tags: - Macro summary: Full macro snapshot (all macro series + regime + business cycle) responses: '200': description: Full macro data content: application/json: schema: type: object description: 'Full macro dashboard in one call: regime, risk gauge (0-100), composite risk score, geopolitical risk, key prices (SPY/QQQ/VIX/TLT/DXY/OIL), 30+ FRED series (rates, inflation, employment, credit), business cycle position. Useful for agents needing the complete macro state before tactical reasoning.' /api/macro/signals: get: tags: - Macro summary: Active macro signals driving regime responses: '200': description: Active signals with weights content: application/json: schema: type: object properties: signals: type: array items: type: object properties: key: type: string reason: type: string weight: type: number description: Active macro signals currently driving the regime classification. Returns ranked list of triggered signals with thresholds, current values, and contribution weight. Useful for agents explaining "why" the regime is what it is. /api/macro/risk-score: get: tags: - Macro summary: Composite risk score (0-100) responses: '200': description: Risk score with component breakdown content: application/json: schema: $ref: '#/components/schemas/RiskScore' description: Composite risk score 0-100 derived from VIX, credit spreads, yield curve, geopolitical risk, and dispersion. Higher = riskier. Returns score + components + label (CALM / MODERATE / ELEVATED / HIGH). Useful for agents sizing risk exposure or triggering defensive rotations. /api/macro/business-cycle: get: tags: - Macro summary: Business cycle metric + ICSA + credit stress + IGV responses: '200': description: Business cycle data content: application/json: schema: $ref: '#/components/schemas/BusinessCycle' description: Business cycle metric blending LEI, initial claims (ICSA), 2s10s yield curve, IGV (intangible-asset growth), and credit stress. Returns the metric value, trend direction, recession probability, and component breakdown. Useful for agents that condition on cycle phase before trade entry. /api/macro/global-liquidity: get: tags: - Macro summary: Global central bank liquidity (Fed + ECB + BOJ balance sheets) description: | Aggregated central bank balance sheets as a proxy for global liquidity. Fed WALCL + ECB total assets + BOJ total assets, converted to USD. Includes US M2 money supply and YoY growth. parameters: - name: date in: query schema: type: string format: date responses: '200': description: Global liquidity data content: application/json: schema: type: object properties: date: type: string totalCBLiquidity: type: number description: Combined CB balance sheets in USD fed: type: object properties: balanceSheet: type: number unit: type: string ecb: type: object properties: balanceSheet: type: number unit: type: string boj: type: object properties: balanceSheet: type: number unit: type: string usM2: type: object properties: value: type: number yoy: type: number /api/macro/us-m2: get: tags: - Macro summary: US M2 money supply (latest value + YoY growth) parameters: - name: date in: query schema: type: string format: date responses: '200': description: US M2 data content: application/json: schema: type: object properties: date: type: string value: type: number description: M2 in trillions USD yoy: type: number description: Year-over-year growth % description: US M2 money supply latest value (trillions USD) + YoY growth rate + trend. Tracks Fed balance sheet expansion/contraction proxy. Useful for agents conditioning on liquidity regime. /api/macro/central-banks: get: tags: - Macro summary: Central bank policy rates + market expectations description: | Fed, ECB, BOJ policy rates. Includes effective rate, target range, 2Y/10Y/30Y yields, breakevens, and implied rate cuts priced in. parameters: - name: date in: query schema: type: string format: date responses: '200': description: Central bank watch data content: application/json: schema: type: object properties: date: type: string fed: type: object ecb: type: object boj: type: object yields: type: object breakevens: type: object impliedCuts: type: number description: Number of 25bp cuts priced /api/macro/supply-chain: get: tags: - Macro summary: Supply chain stress composite (BDI, oil, trade indicators) parameters: - name: date in: query schema: type: string format: date responses: '200': description: Supply chain stress data content: application/json: schema: type: object properties: date: type: string composite: type: object components: type: array items: type: object description: Supply chain stress composite combining Baltic Dry Index, oil supply tightness signals, refinery utilization, SPR levels, and trade-route disruption indicators. Returns composite score + per-component values. Useful for agents trading commodity-sensitive assets or detecting inflation-shock setups. /api/macro/calendar-high-impact: get: tags: - Macro summary: Upcoming high-impact economic events description: Upcoming high-impact economic events in the next 72h (FOMC, CPI, NFP, GDP, central bank meetings, key earnings). Returns ranked events with country, time, previous value, forecast, and impact tier. Useful for agents avoiding event-driven volatility or positioning ahead of catalysts. parameters: - name: date in: query schema: type: string format: date responses: '200': description: High-impact calendar events content: application/json: schema: type: object properties: date: type: string events: type: array items: type: object /api/scenarios/current: get: tags: - Scenarios summary: All 6 scenario probabilities responses: '200': description: Current probabilities content: application/json: schema: $ref: '#/components/schemas/ScenarioProbabilities' description: All 6 active scenario probabilities (late-cycle, recession, goldilocks, stagflation, hegemony, displacement) with current weight, recent delta, and supporting signals. Useful for agents running probability-weighted strategy ensembles. /api/scenarios/{id}: get: tags: - Scenarios summary: Single scenario with probability and signals parameters: - $ref: '#/components/parameters/ScenarioId' responses: '200': description: Single scenario content: application/json: schema: $ref: '#/components/schemas/SingleScenario' description: Single scenario detail by id (late-cycle, recession, goldilocks, stagflation, hegemony, displacement). Returns probability, recent delta, list of supporting signals + weights, and historical probability trend. Useful for agents drilling into a specific scenario thesis. /api/scenarios/signals: get: tags: - Scenarios summary: All active signals with scenario impacts responses: '200': description: Active signals content: application/json: schema: type: object description: All active signals driving the scenario probabilities, grouped by which scenario(s) they support. Useful for agents wanting to see the underlying evidence base, not just the aggregate probabilities. /api/scenarios/history: get: tags: - Scenarios summary: Historical scenario probabilities (JSONL) responses: '200': description: Daily history content: application/json: schema: type: array items: $ref: '#/components/schemas/ScenarioProbabilities' description: Historical scenario probability time-series (JSONL format). Returns daily probabilities for all 6 scenarios going back to archive start. Useful for agents backtesting scenario-conditional strategies or detecting regime-shift inflection points. /api/indicators: get: tags: - Indicators summary: List all available indicators responses: '200': description: Indicator list content: application/json: schema: type: array items: type: object properties: name: type: string description: type: string description: 'List all 36 available indicators with current signal state (buy / sell / neutral) + level (e.g., OVERSOLD, OVERBOUGHT, BALANCED). Returns full registry: name, category (crypto / macro / sentiment / technical / liquidity), tier, last update. Useful for agents discovering what is available.' /api/indicators/summary: get: tags: - Indicators summary: All 27 indicators with current signals responses: '200': description: Indicator summary content: application/json: schema: $ref: '#/components/schemas/IndicatorSummary' description: 'Dashboard view: all 36 indicators in one response with current signal + level + 1-line interpretation. Useful for agents wanting a complete signal sweep without 36 individual calls.' /api/indicators/{name}: get: tags: - Indicators summary: Single indicator detail parameters: - $ref: '#/components/parameters/IndicatorName' responses: '200': description: Indicator data content: application/json: schema: $ref: '#/components/schemas/Indicator' description: Single indicator detail by name (e.g., bull-market-support-band, btc-pi-cycle, wyckoff-structure). Returns current value, signal, level, threshold breaches, interpretation, and source citations. Useful for agents drilling into one specific indicator. /api/indicators/{name}/history: get: tags: - Indicators summary: Indicator historical values parameters: - $ref: '#/components/parameters/IndicatorName' responses: '200': description: Historical values content: application/json: schema: type: array items: $ref: '#/components/schemas/Indicator' description: Historical values for one indicator (?days=N). Returns daily time-series with signal + level + value. Useful for agents backtesting indicator-conditional strategies or detecting regime changes. /api/signals/vix: get: tags: - Signals summary: VIX with z-score and level responses: '200': description: "VIX (CBOE Volatility Index) latest value + z-score vs 30/90/365-day mean + level label (CALM / NORMAL / ELEVATED / PANIC). Useful for agents sizing risk or detecting volatility regime changes." content: application/json: schema: $ref: '#/components/schemas/SignalValue' /api/signals/dxy: get: tags: - Signals summary: Dollar index responses: '200': description: "US Dollar Index (DXY) latest value + daily change + 30d range + level label. Useful for agents conditioning on dollar strength regime (DXY rising = headwind for risk + commodities)." content: application/json: schema: $ref: '#/components/schemas/SignalValue' /api/signals/yield-curve: get: tags: - Signals summary: 2s10s spread with inversion status responses: '200': description: "2s10s Treasury yield spread (in bps) + inversion status + days since inversion + recession-signal context. Useful for agents tracking the most reliable recession leading indicator." content: application/json: schema: $ref: '#/components/schemas/SignalValue' /api/signals/oil: get: tags: - Signals summary: WTI + Brent with supply shock detection responses: '200': description: "WTI and Brent crude oil prices + daily move + supply-shock detection (signals: SUPPLY_TIGHTENING / OVERSUPPLY / BALANCED based on inventories + refinery util + SPR draws). Useful for agents trading energy or inflation-sensitive macros." content: application/json: schema: $ref: '#/components/schemas/SignalValue' /api/signals/icsa: get: tags: - Signals summary: Initial jobless claims — recession tripwire responses: '200': description: "Initial Continuing State Allowance (jobless claims) latest weekly print + 4-week MA + z-score + trend (RISING / FLAT / FALLING). Recession tripwire — sustained ICSA rises precede recessions reliably. Useful for agents with cycle-phase logic." content: application/json: schema: $ref: '#/components/schemas/SignalValue' /api/signals/credit-stress: get: tags: - Signals summary: Composite credit stress from FRED quarterly responses: '200': description: "Composite credit stress from HY OAS spreads, IG spreads, term premium, and credit-default-swap proxies. Returns 0-100 score + label + components. Useful for agents detecting risk-off rotations or sizing credit exposure." content: application/json: schema: type: object /api/signals/cape-ratio: get: tags: - Signals summary: Shiller CAPE with historical percentile responses: '200': description: "Shiller CAPE (Cyclically Adjusted PE) for the S&P 500 with current value, historical percentile (vs 1881-present), and % deviation from long-run mean. Useful for agents conditioning equity exposure on valuation extremes." content: application/json: schema: type: object /api/signals/hindenburg-omen: get: tags: - Signals summary: Market breadth divergence signal responses: '200': description: "Hindenburg Omen — market-breadth divergence signal (new highs + new lows + 10w MA + McClellan). Returns trigger state + confirmation count + days-since-last-trigger. Useful for agents wanting a contrarian peak-detection signal." content: application/json: schema: type: object /api/signals/geopolitical-risk: get: tags: - Signals summary: '[BETA] Geopolitical risk analysis with commodity impact scoring' description: | **BETA** — Transforms raw geopolitical/conflict data into actionable investment intelligence. Merges GDELT, UCDP, and news data, classifies by region, applies LLM distillation, and maps to commodity/ticker impacts with risk scoring. parameters: - name: date in: query schema: type: string format: date description: Date in YYYY-MM-DD format (defaults to latest) - name: region in: query schema: type: string description: Filter by region (e.g., "middle-east", "russia-ukraine", "africa") - name: commodity in: query schema: type: string description: Filter by affected commodity (e.g., "oil", "uranium", "shipping") - name: ticker in: query schema: type: string description: Filter by affected ticker (e.g., "USO", "URA") responses: '200': description: "Signal data returned with z-score and level" description: Geopolitical risk analysis with regional breakdown content: application/json: schema: type: object properties: timestamp: type: string format: date-time globalRisk: type: integer minimum: 0 maximum: 100 description: Global composite risk score globalSignal: type: string enum: - LOW - MODERATE - ELEVATED - HIGH summary: type: string description: LLM-generated global summary regions: type: array items: type: object properties: name: type: string risk: type: integer minimum: 0 maximum: 100 signal: type: string enum: - LOW - MODERATE - ELEVATED - HIGH eventCount: type: integer escalation: type: boolean summary: type: string commodityImpact: type: array items: type: object properties: commodity: type: string direction: type: string enum: - bullish - bearish mechanism: type: string affectedTickers: type: array items: type: string watchlist: type: array items: type: object properties: ticker: type: string reason: type: string regionSource: type: string metadata: type: object properties: sourcesUsed: type: integer totalEvents: type: integer classifiedEvents: type: integer unclassifiedEvents: type: integer dataAge: type: string /api/signals/dispersion: get: tags: - Signals summary: Sector dispersion regime responses: '200': description: "Sector dispersion regime — measures how far apart sector returns are (high dispersion = selective market, low = correlated). Returns dispersion score, regime label, breadth metric, % of sectors positive over 1w. Useful for agents detecting rotational vs broad-market phases." content: application/json: schema: type: object /api/signals/sector-rotation: get: tags: - Signals summary: Sector leaders/laggards and rotation phase responses: '200': description: "Current sector leaders + laggards (1d / 5d / 1m ranked), plus rotation-phase classification (risk-on / defensive / late-cycle). Useful for agents running sector-rotation strategies or detecting institutional positioning shifts." content: application/json: schema: type: object /api/signals/insider-activity: get: tags: - Signals summary: SEC insider filing analysis responses: '200': description: "SEC insider-trading filing analysis (Form 4) — buys vs sells, top filers, unusual cluster activity. Useful for agents using insider signal as an alpha source on individual names." content: application/json: schema: type: object /api/signals/btc-etf-flows: get: tags: - Signals summary: Bitcoin ETF flows with streak tracking responses: '200': description: "Bitcoin spot ETF flows (IBIT, FBTC, ARKB, BITB, GBTC + others). Returns daily net flow USD, per-issuer breakdown, 5-day trailing net, inflow/outflow streak length. Useful for agents tracking institutional BTC demand." content: application/json: schema: type: object /api/signals/fear-greed: get: tags: - Signals summary: Crypto Fear & Greed Index responses: '200': description: "Crypto Fear & Greed Index (0-100) — composite of volatility, momentum, social sentiment, dominance, and survey data. Returns current value, label, 7d/30d averages, trend direction. Useful for agents running contrarian crypto strategies." content: application/json: schema: $ref: '#/components/schemas/SignalValue' /api/signals/funding-rates: get: tags: - Signals summary: Aggregate perpetual funding rates (374 pairs) responses: '200': description: "Aggregate perpetual funding rates across 374 trading pairs and 5 exchanges (Binance, Bybit, Bitget, MEXC, OKX). Returns per-asset mean rate + cross-exchange dispersion + bias label. Useful for agents detecting leverage skew or trading funding-rate arbitrage." content: application/json: schema: type: object /api/signals/whale-positions: get: tags: - Signals summary: Hyperliquid whale positions (top 100) responses: '200': description: "Hyperliquid top-100 whale positions by notional. Returns per-asset long / short USD totals + net direction + PnL. Useful for agents reading on-chain positioning of large traders in real-time." content: application/json: schema: type: object /api/signals/stablecoin-dominance: get: tags: - Signals summary: USDT/USDC dominance as risk proxy responses: '200': description: "USDT + USDC stablecoin market-cap dominance vs total crypto market cap. High dominance = sidelined capital (risk-off proxy). Returns dominance %, 30d change, trend. Useful for agents detecting risk-on/off rotation in crypto." content: application/json: schema: $ref: '#/components/schemas/SignalValue' /api/signals/bofa-fms: get: tags: - Signals summary: Full BofA Fund Manager Survey responses: '200': description: "Full BofA Global Fund Manager Survey — cash levels, equity allocations, biggest tail risks, most crowded trades, regional preferences. Monthly cadence. Useful for agents conditioning on institutional positioning + sentiment." content: application/json: schema: $ref: '#/components/schemas/BofaFMS' /api/signals/bofa-crowded: get: tags: - Signals summary: BofA most crowded trades only responses: '200': description: "BofA most crowded trades only (from monthly FMS). Returns the top 5-7 crowded trades by manager survey response. Useful for agents using crowdedness as a contrarian setup signal." content: application/json: schema: type: object properties: crowdedTrades: type: array items: type: object properties: label: type: string pct: type: number position: type: integer /api/signals/cftc-cot: get: tags: - Signals summary: CFTC Commitments of Traders responses: '200': description: "CFTC Commitments of Traders — futures positioning by trader category (managed money, commercials, large speculators) across BTC, gold, copper, oil, S&P, treasuries, currencies. Returns weekly net positioning + delta + concentration. Useful for agents tracking professional futures positioning." content: application/json: schema: type: object /api/signals/sector/{ticker}: get: tags: - Signals summary: Individual sector ETF signal parameters: - name: ticker in: path required: true schema: type: string enum: - XLF - XLE - XLK - XLV - XLI - XLU - XLP - XLB - XLC - XLY - XLRE - XBI - SMH - URA - COPX - ITA - GLD - TLT responses: '200': description: "Individual sector ETF signal (XLE, XLK, XLF, XLV, etc.) — recent performance, relative strength vs SPY, dispersion contribution, rotation status. Useful for agents needing per-sector data for rotation strategies." content: application/json: schema: $ref: '#/components/schemas/SignalValue' /api/narratives: get: tags: - Narratives summary: All 18 narrative crowding scores responses: '200': description: All narrative scores content: application/json: schema: type: object properties: date: type: string format: date scores: type: array items: $ref: '#/components/schemas/NarrativeScore' description: All 18 narrative crowding scores (AI, defense, crypto, energy, healthcare, etc.) with momentum + lifecycle phase (BIRTH / EARLY / CORE / PEAK / FADE / DEAD). Useful for agents conditioning trades on narrative lifecycle. /api/narratives/{name}: get: tags: - Narratives summary: Single narrative with input breakdown parameters: - $ref: '#/components/parameters/NarrativeName' responses: '200': description: Narrative detail content: application/json: schema: $ref: '#/components/schemas/NarrativeDetail' description: Single narrative detail — score, momentum delta, input breakdown (news mentions, social mentions, ETF flows, options activity), lifecycle phase, related tickers. Useful for agents drilling into a specific narrative thesis. /api/signals/correlations: get: tags: - Signals summary: Cross-asset correlation breaks (10 asset pairs) description: | Monitors rolling correlations between key asset pairs (e.g. BTC/SPX, Gold/DXY). Flags when correlations deviate significantly from historical norms. Requires 10+ days of Yahoo cache data to produce results. parameters: - name: date in: query schema: type: string format: date responses: '200': description: "Signal data returned with z-score and level" description: Correlation break signals content: application/json: schema: type: object properties: date: type: string pairs: type: array items: type: object breaks: type: array items: type: object /api/signals/attention: get: tags: - Signals summary: Wikipedia pageview attention signals (15 assets) description: | Tracks Wikipedia pageview z-scores for financial assets. Sudden spikes in attention often precede or coincide with price moves. z > 2 = notable, z > 3 = extreme. parameters: - name: date in: query schema: type: string format: date responses: '200': description: "Signal data returned with z-score and level" description: Attention signals content: application/json: schema: type: object properties: date: type: string signals: type: array items: type: object properties: ticker: type: string article: type: string views: type: integer avgViews: type: number zScore: type: number alert: type: string enum: - NORMAL - ELEVATED - EXTREME /api/signals/attention/{ticker}: get: tags: - Signals summary: Attention signal for a specific ticker parameters: - name: ticker in: path required: true schema: type: string example: BTC - name: date in: query schema: type: string format: date responses: '200': description: "Attention signal for one ticker — Wikipedia pageview spike + Reddit mention rate + Google Trends + news velocity. Useful for agents detecting attention-driven crowding on individual names." description: Single ticker attention data content: application/json: schema: type: object properties: date: type: string ticker: type: string views: type: integer zScore: type: number alert: type: string /api/signals/insider-trades: get: tags: - Signals summary: SEC EDGAR Form 4 insider trades description: Recent insider buys and sells from SEC filings. 10 req/sec rate limit on SEC EDGAR. parameters: - name: date in: query schema: type: string format: date responses: '200': description: "Signal data returned with z-score and level" description: Insider trade filings content: application/json: schema: type: object properties: date: type: string filings: type: array items: type: object /api/signals/signal-stats: get: tags: - Signals summary: Crypto signal state distribution (buy/sell/neutral counts) description: 'Crypto signal-state distribution: how many of the tracked crypto pairs are currently in BUY vs SELL vs NEUTRAL states across 1d and 4h timeframes. Useful for agents reading overall crypto sentiment via signal-state breadth.' parameters: - name: date in: query schema: type: string format: date responses: '200': description: "Signal data returned with z-score and level" description: Signal state statistics content: application/json: schema: type: object properties: date: type: string /api/signals/treasury-rankings: get: tags: - Signals summary: BTC/crypto treasury leaderboard (public companies) parameters: - name: date in: query schema: type: string format: date responses: '200': description: "BTC + crypto treasury leaderboard for public companies (Strategy, Coinbase, Block, sovereign holdings). Ranked by BTC holdings + change rate. Useful for agents tracking corporate / sovereign accumulation trends." description: Treasury rankings content: application/json: schema: type: object properties: date: type: string /api/signals/treasury-concentration: get: tags: - Signals summary: Treasury concentration analysis parameters: - name: date in: query schema: type: string format: date responses: '200': description: "Treasury concentration analysis — what % of supply is held by top-N treasuries, how concentrated is corporate-vs-sovereign-vs-ETF ownership. Useful for agents detecting supply-side risk or accumulation breakouts." description: Concentration metrics content: application/json: schema: type: object properties: date: type: string /api/signals/btc-orderbook: get: tags: - Signals summary: BTC order book — wall changes + liquidity shifts description: 'Combined BTC wall changes, liquidity change, and market structure ' parameters: - name: date in: query schema: type: string format: date responses: '200': description: "Signal data returned with z-score and level" description: BTC orderbook intelligence content: application/json: schema: type: object properties: date: type: string wallChanges: type: object liquidityChange: type: object marketStructure: type: object /api/signals/market-structure: get: tags: - Signals summary: BTC market structure snapshot parameters: - name: date in: query schema: type: string format: date responses: '200': description: "BTC market structure snapshot: spot orderbook depth, basis, term-structure slope, perp-vs-spot deviation. Useful for agents detecting liquidity squeezes, basis-trade setups, or microstructure stress." description: Market structure data content: application/json: schema: type: object properties: date: type: string /api/crypto/reentry: get: tags: - Crypto summary: 9-factor crypto re-entry score responses: '200': description: Re-entry score content: application/json: schema: $ref: '#/components/schemas/CryptoReentry' description: 9-factor crypto re-entry score (0-100) — composite of capitulation signals, funding flush, ETF flow turnaround, sentiment extreme, dispersion, etc. Useful for agents timing re-entry after crypto drawdowns. /api/mr/signals: get: tags: - MR Scanner summary: Current mean reversion signals (context-filtered) responses: '200': description: Active signals + blocked content: application/json: schema: type: object properties: signals: type: array items: $ref: '#/components/schemas/MRSignal' blocked: type: array items: type: object properties: asset: type: string reason: type: string description: Current mean-reversion signals across the tracked universe, context-filtered by macro regime (no MR signals when regime is trending strongly). Returns ranked entries with entry / stop / target. Useful for agents running mean-reversion strategies. /api/mr/stats: get: tags: - MR Scanner summary: Paper trading performance statistics responses: '200': description: Stats content: application/json: schema: $ref: '#/components/schemas/MRStats' description: Paper-trading performance statistics for the MR signal book — win rate, average return per trade, max drawdown, profit factor, by signal type. Useful for agents evaluating signal quality before deployment. /api/mr/trades: get: tags: - MR Scanner summary: Current paper trade book responses: '200': description: Trades content: application/json: schema: type: object properties: trades: type: array items: type: object summary: $ref: '#/components/schemas/MRStats' description: Current open MR paper trade book — entries currently active with entry price, stop, target, unrealized PnL. Useful for agents replicating the live signal book in their own execution. /api/news: get: tags: - News summary: Breaking news with sentiment parameters: - name: ticker in: query schema: type: string description: Filter by ticker (e.g. BTC, ETH, NVDA) - name: tickers in: query schema: type: string description: Comma-separated tickers - name: limit in: query schema: type: integer default: 50 responses: '200': description: News articles content: application/json: schema: type: object properties: articles: type: array items: $ref: '#/components/schemas/NewsArticle' description: Breaking market news with sentiment classification (POSITIVE / NEGATIVE / NEUTRAL). Returns recent articles with title, summary, source, publish timestamp, ticker mentions, and sentiment label. Useful for agents tracking catalysts or feeding LLM summarization pipelines. /api/news/movers: get: tags: - News summary: News driving biggest price moves today responses: '200': description: Mover news content: application/json: schema: type: object description: News articles driving the biggest price moves today, correlated with intraday returns of mentioned tickers. Returns ranked articles by impact + the moves they correlate with. Useful for agents doing event-attribution analysis. /api/news/trending: get: tags: - News summary: Trending news articles parameters: - name: date in: query schema: type: string format: date responses: '200': description: Trending news content: application/json: schema: type: object properties: date: type: string description: Trending news articles by mention velocity + cross-source repetition. Returns top stories that multiple outlets are covering simultaneously. Useful for agents detecting the day's dominant narrative. /api/news/stats: get: tags: - News summary: News sentiment breakdown statistics description: News sentiment breakdown statistics — count of POSITIVE / NEGATIVE / NEUTRAL articles in the last 24h + per-ticker sentiment skew. Useful for agents conditioning on aggregate news mood. parameters: - name: date in: query schema: type: string format: date responses: '200': description: Sentiment stats content: application/json: schema: type: object properties: date: type: string /api/news/market-analysis: get: tags: - News summary: AI-generated market analysis parameters: - name: date in: query schema: type: string format: date responses: '200': description: Market analysis content: application/json: schema: type: object properties: date: type: string description: AI-generated market analysis — synthesis pass over the day's news identifying themes, contradictions, and emerging narratives. Useful for agents wanting pre-aggregated context vs raw articles. /api/news/xtg-analysis: get: tags: - News summary: Telegram channel analysis (XTG) parameters: - name: date in: query schema: type: string format: date responses: '200': description: Telegram channel intelligence content: application/json: schema: type: object properties: date: type: string description: Telegram channel analysis (XTG = aggregated Telegram intel) — sentiment + theme tagging across crypto-focused Telegram channels. Useful for agents tracking degens / alpha-source sentiment. /api/predictions/markets: get: tags: - Signals summary: Polymarket — financially relevant prediction markets description: | Filtered Polymarket data: only markets with financial keywords (Fed, rates, inflation, recession, crypto, Bitcoin, stocks, etc.). Tracks probability shifts vs yesterday. parameters: - name: date in: query schema: type: string format: date responses: '200': description: Prediction market data content: application/json: schema: type: object properties: date: type: string markets: type: array items: type: object properties: question: type: string probability: type: number volume: type: number probChange: type: number nullable: true /api/data: get: tags: - Data summary: List available raw data sources responses: '200': description: Available endpoints content: application/json: schema: type: array items: type: object properties: name: type: string description: type: string lastUpdated: type: string format: date-time description: List all available raw data sources by name. Returns registry of cached upstream data (market-quotes, breaking-news, funding-rates, macro-snapshot, etc.) with refresh cadence + last-updated. Useful for agents discovering available raw feeds. /api/data/{name}: get: tags: - Data summary: Raw cached data by source name parameters: - $ref: '#/components/parameters/DataName' responses: '200': description: Raw data content: application/json: schema: type: object description: Raw cached data by source name (e.g., market-quotes, breaking-news, funding-rates). Returns the unmodified upstream payload — same data the atom processors read. Useful for agents wanting unprocessed source data for custom analysis. /api/defi/intelligence: get: tags: - DeFi summary: Full DeFi daily snapshot — all sections in one call parameters: - name: date in: query schema: type: string format: date description: Date (YYYY-MM-DD). Defaults to latest. responses: '200': description: Complete DeFi intelligence content: application/json: schema: type: object properties: date: type: string peRatios: type: array items: $ref: '#/components/schemas/PeRatio' undervalued: type: array items: $ref: '#/components/schemas/PeRatio' yields: $ref: '#/components/schemas/YieldSummary' perps: type: array items: $ref: '#/components/schemas/PerpMarket' stablecoins: $ref: '#/components/schemas/StablecoinSummary' chains: type: array items: $ref: '#/components/schemas/ChainTvl' unlocks: type: array items: $ref: '#/components/schemas/TokenUnlock' signals: type: array items: $ref: '#/components/schemas/DefiSignal' description: Full DeFi daily snapshot in one call — TVL by protocol + chain, top yields, stablecoin flows, DEX volumes, PE ratios, perp funding, token unlocks. Useful for agents wanting comprehensive DeFi state without 8 individual calls. /api/defi/pe-ratios: get: tags: - DeFi summary: Protocol P/E ratios — revenue vs market cap description: | Unique composite: DeFiLlama provides revenue and mcap separately. We compute PE = mcap / annualized_revenue. Lower = cheaper. Categories: undervalued (<15x), fair (15-50x), growth (50-200x), overvalued (>200x). parameters: - name: date in: query schema: type: string format: date responses: '200': description: PE ratios for all tracked protocols content: application/json: schema: type: object properties: date: type: string total: type: integer undervalued: type: array items: $ref: '#/components/schemas/PeRatio' all: type: array items: $ref: '#/components/schemas/PeRatio' /api/defi/pe-ratios/{tier}: get: tags: - DeFi summary: Filter protocols by valuation tier parameters: - name: tier in: path required: true schema: type: string enum: - undervalued - fair - growth - overvalued - name: date in: query schema: type: string format: date responses: '200': description: Protocols in requested tier content: application/json: schema: type: object properties: tier: type: string count: type: integer protocols: type: array items: $ref: '#/components/schemas/PeRatio' description: DeFi protocols filtered by valuation tier (cheap / fair / expensive / extreme). Returns protocol list with revenue, market cap, P/S ratio, P/E ratio. Useful for agents running valuation-screen DeFi strategies. /api/defi/yields: get: tags: - DeFi summary: Filtered yield opportunities — watched assets only description: | Only pools with tracked underlyings (USDC, ETH, WBTC, SOL, stETH etc.), single exposure (no IL risk), >$10M TVL. parameters: - name: date in: query schema: type: string format: date responses: '200': description: Yield opportunities content: application/json: schema: $ref: '#/components/schemas/YieldSummary' /api/defi/yields/stable: get: tags: - DeFi summary: Best stablecoin yields (>$50M TVL, single exposure) parameters: - name: date in: query schema: type: string format: date responses: '200': description: Stablecoin yield pools content: application/json: schema: type: object properties: date: type: string avgApy: type: number pools: type: array items: $ref: '#/components/schemas/YieldPool' description: Best stablecoin yields with >$50M TVL and single-asset exposure (no LP risk). Returns top yields by APY with protocol + chain + risk tier + lockup. Useful for agents managing stablecoin allocations. /api/defi/perps: get: tags: - DeFi summary: Perpetual funding rates with sentiment labels description: | Cross-DEX funding rates for markets with >$10M open interest. Sentiment: extreme-long (>1%), bullish, neutral, bearish, extreme-short (<-1%). Extreme funding = contrarian signal. parameters: - name: date in: query schema: type: string format: date responses: '200': description: Perp funding data content: application/json: schema: type: object properties: date: type: string markets: type: array items: $ref: '#/components/schemas/PerpMarket' extremeFunding: type: array items: $ref: '#/components/schemas/PerpMarket' /api/defi/stablecoins: get: tags: - DeFi summary: Tracked stablecoin supply and market caps description: | Tracks USDT, USDC, USDS, USDe, DAI, FDUSD, PYUSD, GHO, crvUSD, LUSD. Rising total = liquidity entering crypto (bullish). Contracting = risk off. parameters: - name: date in: query schema: type: string format: date responses: '200': description: Stablecoin supply data content: application/json: schema: $ref: '#/components/schemas/StablecoinSummary' /api/defi/chains: get: tags: - DeFi summary: TVL for watched chains description: Ethereum, Solana, Base, Arbitrum, BSC, Polygon, Avalanche, Optimism, Bitcoin, Sui, Aptos parameters: - name: date in: query schema: type: string format: date responses: '200': description: Chain TVL data content: application/json: schema: type: object properties: date: type: string chains: type: array items: $ref: '#/components/schemas/ChainTvl' /api/defi/unlocks: get: tags: - DeFi summary: Token unlock events in next 30 days (>$1M value) description: | Impact: HIGH (>10% of circulating), MEDIUM (3-10%), LOW (<3%). Use for sell pressure alerts. parameters: - name: date in: query schema: type: string format: date responses: '200': description: Token unlock calendar content: application/json: schema: type: object properties: date: type: string events: type: array items: $ref: '#/components/schemas/TokenUnlock' highImpact: type: array items: $ref: '#/components/schemas/TokenUnlock' /api/defi/signals: get: tags: - DeFi summary: Composite DeFi signals — actionable alerts description: | Auto-generated when thresholds crossed: STABLECOIN_FLOW, EXTREME_FUNDING, YIELD_SHIFT, PE_COMPRESSION, TOKEN_UNLOCK parameters: - name: date in: query schema: type: string format: date responses: '200': description: Active signals content: application/json: schema: type: object properties: date: type: string count: type: integer signals: type: array items: $ref: '#/components/schemas/DefiSignal' /api/billing/pricing: get: tags: - Billing summary: Pricing info security: [] description: Public endpoint. Returns per-call cost ($0.02), tier structure, receiving address, and payment instructions. responses: '200': description: Pricing details content: application/json: schema: type: object properties: perCall: type: string example: $0.02 acceptedTokens: type: array items: type: string example: - USDC chain: type: string example: base receivingAddress: type: string minimumDeposit: type: string example: $10 USDC tiers: type: array items: type: object instructions: type: array items: type: string /api/billing/verify: post: tags: - Billing summary: Verify USDC payment description: Submit a Base transaction hash after sending USDC. Verifies on-chain, credits your account. Requires x-api-key header. requestBody: required: true content: application/json: schema: type: object required: - txHash properties: txHash: type: string description: Base transaction hash (0x + 64 hex chars) example: 0xabc123... responses: '200': description: Payment verified and credits added content: application/json: schema: type: object properties: success: type: boolean deposit: type: object properties: txHash: type: string amount: type: number token: type: string chain: type: string account: type: object properties: creditsAdded: type: number totalCredits: type: number tier: type: string tierUpgraded: type: boolean '202': description: Transaction found but pending confirmations '400': description: Invalid tx, wrong recipient, or no USDC transfer '409': description: Transaction already processed /api/keys/create: post: tags: - Keys summary: Create new API key security: [] description: Provide your wallet address. Returns API key (shown once) and the USDC receiving address on Base. requestBody: required: true content: application/json: schema: type: object required: - walletAddress properties: walletAddress: type: string description: Your EVM wallet address (0x...) responses: '201': description: Key created (shown once) content: application/json: schema: type: object properties: apiKey: type: string description: Your API key (shown once, save it) tier: type: string depositAddress: type: string description: Send USDC here on Base /api/keys/rotate: post: tags: - Keys summary: Rotate key (balance transfers) responses: '200': description: New key issued content: application/json: schema: type: object properties: newApiKey: type: string keyId: type: string description: Rotate an API key — generates a new key value, transfers remaining credit balance to the new key, revokes the old key. Useful for agents implementing key-rotation security policies. Requires authentication with the current key. /api/keys/balance: get: tags: - Keys summary: Check remaining credits responses: '200': description: Balance content: application/json: schema: type: object properties: balance: type: number tier: type: string description: Check remaining USDC credit balance + per-call cost burn rate. Returns balance + last-N-call cost history + projected runway. Useful for agents monitoring spend against deposit. /api/keys/info: get: tags: - Keys summary: Key metadata, tier, rate limits responses: '200': description: Key info content: application/json: schema: $ref: '#/components/schemas/KeyInfo' description: Current API key metadata — tier (Explorer / Builder / Signal / Institutional), rate limits, allowed endpoints, expiry, wallet address used to create the key. Useful for agents that adapt behavior based on their own tier. /api/cape: get: summary: Shiller CAPE Ratio description: Shiller CAPE Ratio for S&P 500 — current value, historical percentile (vs 1881-present), % deviation from long-run mean, valuation label (UNDERVALUED / FAIR / OVERVALUED / BUBBLE_TERRITORY). Useful for agents conditioning equity exposure on valuation. tags: - Signals /api/hindenburg: get: summary: Hindenburg Omen description: Hindenburg Omen current state — market-breadth divergence signal that historically precedes major declines. Returns trigger state, confirmation count, days since last trigger, McClellan oscillator state. tags: - Signals /api/hindenburg/history: get: summary: Hindenburg Omen History description: Hindenburg Omen historical trigger log — every past trigger with date, confirmation length, subsequent market move. Useful for agents calibrating the signal's historical hit rate. tags: - Signals /api/premiums: get: summary: Exchange Premiums description: Exchange premiums — BTC price differentials across major exchanges (Coinbase vs Binance, Kimchi premium on Upbit, Asian session premium). Returns spread map + extremes. Useful for agents detecting regional flow imbalances. tags: - Crypto /api/premiums/coinbase: get: summary: Coinbase Premium description: BTC price difference Coinbase vs Binance (institutional demand signal) tags: - Crypto /api/premiums/kimchi: get: summary: Kimchi Premium description: BTC price difference Upbit (Korea) vs Binance (retail FOMO signal) tags: - Crypto /api/btc-options: get: summary: BTC Options Intelligence description: 'Full options analysis: direction bias, max pain by expiry, 25-delta skew, put/call ratio, top strikes by OI. Data from Deribit (15min cache).' tags: - Crypto /api/btc-options/maxpain: get: summary: BTC Max Pain description: Max pain strike price for the nearest 4 BTC option expiries — the strike level minimizing option-seller payouts. Returns expiry-by-expiry max pain + distance from current spot. Useful for agents reading institutional positioning gravity. tags: - Crypto /api/btc-options/skew: get: summary: BTC Options Skew description: 25-delta put / call IV skew on BTC options + directional-bias signals (BEARISH / NEUTRAL / BULLISH). Returns skew, P/C ratio (OI + volume), put-skew-IV value. Useful for agents reading institutional hedging activity. tags: - Crypto /api/derivatives: get: summary: Derivatives Combined description: Combined OI + liquidations snapshot. Returns both atom envelopes in one call. Each section is null/no_fresh_data if its atom's source is missing or past MAX_AGE_HOURS. tags: - Crypto responses: '200': description: Combined derivatives snapshot content: application/json: schema: type: object properties: oi: $ref: '#/components/schemas/OiAtom' liquidations: $ref: '#/components/schemas/LiquidationsAtom' /api/derivatives/oi: get: summary: Open Interest description: Aggregate OI across 43 tracked perps + top-5 symbols by USD size + top-5 by absolute 4h Δ% (intraday OI shifters). Provenance-envelope wrapped. Refreshes hourly upstream. tags: - Crypto responses: '200': description: OI atom (full envelope) content: application/json: schema: $ref: '#/components/schemas/OiAtom' /api/derivatives/oi/top: get: summary: Open Interest — Top by USD description: Top-N symbols ranked by open-interest USD size (default top-5). Concise variant of /api/derivatives/oi for builders who only need the leaderboard. tags: - Crypto responses: '200': description: Aggregate OI + top symbols content: application/json: schema: type: object properties: totalOi: type: number description: Aggregate OI in USD across qualifying symbols symbolCount: type: integer topByOi: type: array items: type: object properties: symbol: type: string oiUsd: type: number sourceObservedAt: type: string format: date-time ageHours: type: number /api/derivatives/oi/shifters: get: summary: Open Interest — 4h Intraday Shifters description: Top-N symbols ranked by |Δ%| of OI over the last 4h. Surfaces positioning unwinds + new builds (e.g., DOGE -8% = forced deleveraging; QNT +8.7% = fresh longs/shorts). Pulse-identity signal. tags: - Crypto responses: '200': description: Intraday OI shifters content: application/json: schema: type: object properties: topByOi4h: type: array items: type: object properties: symbol: type: string oiChg4hPct: type: number description: Signed % change in OI over 4h oiUsd: type: number sourceObservedAt: type: string format: date-time ageHours: type: number /api/derivatives/liquidations: get: summary: Liquidations description: 24h liquidation total + latest-4h breakdown with long/short USD split, per-side event counts, long%/short%, and dominant-direction label (long-dominant >=65%, short-dominant <=35%, balanced otherwise). Sourced from coinglass-v2. tags: - Crypto responses: '200': description: Liquidations atom (full envelope) content: application/json: schema: $ref: '#/components/schemas/LiquidationsAtom' /api/expectations/rotation: get: summary: Narrative Rotation Signals description: Narrative rotation signals — which narratives capital is moving INTO and OUT OF, with magnitude + days-since-rotation-started. Useful for agents trading narrative rotation early. tags: - Composites /api/expectations/crowded: get: summary: Crowded Narratives description: Crowded narratives only — narratives scoring 4-5 (high consensus + high positioning). Useful for agents running contrarian setups against overcrowded positioning. tags: - Composites /api/expectations/early: get: summary: Early Narratives description: Early-stage narratives only — narratives scoring 1-2 (low consensus, possibly forming). Useful for agents wanting alpha from positioning before crowd arrives. tags: - Composites /api/narratives/history: get: summary: Narrative Score History description: Historical narrative score time-series. Returns daily scores for all 18 narratives over the archive period. Useful for agents backtesting narrative-momentum strategies or detecting narrative inflection points. tags: - Composites /api/defi/pe-ratios/apps-vs-l1s: get: summary: Apps vs L1s PE Comparison description: 'Comparative valuation: DeFi applications (DEXs, lenders, perps) vs Layer-1 protocols (chains). Returns aggregate P/S ratios for both buckets + relative-value signal. Useful for agents detecting app-vs-infra rotation.' tags: - DeFi /api/signals/whale-alerts: get: summary: Whale Alert Analysis description: Whale-alert analysis — large on-chain BTC transfers detected and classified by route (exchange-to-exchange, custody-to-exchange, accumulation). Returns top recent alerts + flow direction summary. tags: - Signals /api/signals/decision-engine: get: summary: Decision Engine description: Decision-engine output — aggregated signal-to-decision pipeline combining indicators, signals, and macro into actionable bias. Returns current bias + confidence + supporting signals. Useful for agents that want a pre-aggregated directional view. tags: - Signals /api/central-banks: get: summary: Central Bank Dashboard tags: - Central Banks description: Central-bank dashboard — overview of Fed / ECB / BOJ / PBOC balance sheets, sovereign gold + BTC reserves, stablecoin exposure, TIC flows. Returns aggregate view + per-CB summary. Useful for agents tracking sovereign macro positioning. /api/central-banks/balance-sheets: get: summary: Balance Sheets description: Major central-bank balance-sheet totals + YoY change + composition (treasuries, MBS, FX reserves). Returns Fed, ECB, BOJ, BOE, SNB, PBOC. Useful for agents conditioning on aggregate liquidity provision. tags: - Central Banks /api/central-banks/btc: get: summary: BTC Treasury Holdings tags: - Central Banks description: Sovereign BTC holdings — countries + entities holding BTC as reserve asset. Returns holdings + acquisition history + per-country reserve allocation %. Useful for agents tracking emerging BTC-as-reserve thesis. /api/central-banks/stablecoins: get: summary: Stablecoin Treasury Demand tags: - Central Banks description: Stablecoin treasury composition — USDT and USDC reserve backings (Treasury bills, cash, corporate paper). Returns issuer-level reserve breakdowns. Useful for agents assessing stablecoin systemic risk. /api/central-banks/gold: get: summary: Central Bank Gold Reserves tags: - Central Banks description: Central-bank gold reserves by country + recent accumulation/divestment activity. Returns ranked holdings + monthly purchase deltas. Useful for agents tracking de-dollarization or inflation-hedge accumulation. /api/central-banks/reserves: get: summary: Foreign Reserves (IMF COFER) tags: - Central Banks description: Foreign exchange reserve composition (IMF COFER data) — % allocated to USD, EUR, JPY, GBP, CNY, gold, others. Returns quarterly aggregate + trend. Useful for agents tracking long-term reserve currency shifts. /api/central-banks/tic: get: summary: Treasury International Capital Flows tags: - Central Banks description: Treasury International Capital flows — who is buying / selling US Treasuries by country. Returns monthly per-country net flows + holdings. Useful for agents reading sovereign Treasury demand signals. /api/regime: get: summary: Enhanced Regime State tags: - Regime description: Enhanced regime state — current classification (expansion / overheating / stagflation / late-cycle / recession / displacement / neutral) + confidence + driving signals + recent transitions. Useful for agents conditioning all decisions on macro phase. /api/regime/matrix: get: summary: Regime Positioning Matrix tags: - Regime description: Regime positioning matrix — for each regime, the historically favored vs unfavored asset classes + sector tilts. Useful for agents auto-rotating portfolios based on regime classification. /api/regime/history: get: summary: Regime Transition History tags: - Regime description: Regime transition history — chronological log of regime changes with timestamps, durations, and trigger signals. Useful for agents backtesting regime-conditional strategies or detecting cycle patterns. /api/expectations: get: summary: All Narrative Expectations description: All narrative expectations — every tracked narrative with current crowding score (1-5) + momentum delta + lifecycle phase. Useful for agents wanting the complete consensus map. tags: - Composites /api/expectations/{narrative}: get: summary: Single Narrative Detail tags: - Composites parameters: - name: narrative in: path required: true schema: type: string description: Single narrative expectations detail — crowding score, momentum, contributing signals, related tickers, historical score trajectory. Useful for agents drilling into one narrative thesis. /api/kill-conditions: get: summary: Thesis Kill Conditions description: Thesis kill conditions — pre-defined breakpoints that would invalidate the current macro / regime / scenario thesis. Returns active conditions with thresholds + current values + trigger status. Useful for agents that auto-exit when thesis breaks. tags: - Risk /api/crypto-reentry: get: summary: Crypto Re-entry Score description: Crypto re-entry composite score — current state across 9 factors with per-factor signal + threshold + contribution. Returns score, label (NO_ENTRY / WATCH / ENTRY), factor breakdown. Useful for agents with bottom-fishing logic. tags: - Crypto /api/crypto-reentry/history: get: summary: Re-entry Score History tags: - Crypto description: Historical re-entry score time-series — daily scores with regime context. Useful for agents backtesting re-entry strategies or studying past inflection points. /api/sentiment/reddit: get: summary: Reddit Sentiment description: Reddit sentiment aggregated across major investing/crypto subreddits — post sentiment + comment sentiment + mention velocity per ticker / theme. Useful for agents tracking retail mood. tags: - Sentiment /api/institutional/13f: get: summary: 13F Institutional Holdings description: 13F institutional holdings filings — recent SEC filings showing what institutions hold + position changes. Returns ranked filers + position deltas. Useful for agents tracking smart-money rotation. tags: - Institutional /api/news/{ticker}: get: summary: News for Ticker tags: - News parameters: - name: ticker in: path required: true schema: type: string description: News articles filtered to mentions of a specific ticker. Returns recent stories with sentiment + relevance score. Useful for agents doing single-name event monitoring. /api/predictions: get: summary: All Prediction Markets tags: - Predictions description: All tracked prediction markets (Polymarket + Kalshi) — top events by volume + implied probabilities. Useful for agents conditioning on real-money consensus on geopolitical / economic / market events. /api/predictions/movers: get: summary: Prediction Market Movers tags: - Predictions description: Prediction-market movers — events with the biggest probability shifts in the last 24h (top up + top down). Useful for agents detecting fast-changing consensus or breaking news pre-mentioned in markets. /api/predictions/{slug}: get: summary: Single Prediction Market tags: - Predictions parameters: - name: slug in: path required: true schema: type: string description: Single prediction market by slug — full event detail with current probabilities per outcome, recent trajectory, volume, market URL. Useful for agents tracking specific predictions. /api/billing/check: get: summary: Auto-detect Payment description: Auto-detect a recent USDC / USDT deposit to your wallet address across Base / Arbitrum / Optimism / Polygon / Ethereum. Returns detected deposits + credit applied to your API key. tags: - Billing