{ "openapi": "3.1.0", "info": { "title": "Kronos Crypto Data API", "version": "1.0.0", "description": "Kronos is a pay-per-call real-time crypto market-data API for autonomous agents and trading bots. Pay-per-call endpoints across 17 crypto assets (BTC/ETH/SOL/BNB/XRP/DOGE/ADA/AVAX/LINK/DOT/LTC/TRX/BCH/ATOM/NEAR/APT/HYPE; HYPE derivatives-only). Derivatives signals ($0.02), multi-source spot prices ($0.02), full snapshots ($0.08), market overview ($0.02), funding-rate screener ($0.02), Fear & Greed Index ($0.02), OHLC candles ($0.02), and realized volatility ($0.02). ML price-direction forecasts available as a premium add-on ($0.05). Payments are USDC on Base mainnet (eip155:8453) via the x402 protocol. Free teaser samples at /api/v1/sample/{btc,eth,sol}. Public accuracy stats at /api/stats.", "x-guidance": "HOW TO USE THIS API AS AN AGENT: (1) All paid endpoints require a one-time USDC micropayment on Base mainnet (eip155:8453) via the x402 protocol. Derivatives signals and regime alerts cost $0.02 USDC; spot price, OHLC, macro, and Fear & Greed cost $0.02 USDC; the premium ML forecast add-on costs $0.05 USDC. (2) Call any paid endpoint WITHOUT an X-PAYMENT header first — the server returns HTTP 402 with machine-readable payment instructions in the response body and X-PAYMENT-REQUIRED header. (3) Use an x402-compatible client library (e.g. npm 'x402-fetch') to complete the payment and retry the request with the X-PAYMENT header. The server settles the payment and returns the data in a single round-trip. (4) Start with the FREE sample endpoints (/api/v1/sample/{btc,eth,sol}) to preview the response format (coarse directional signal: up/down + confidence bucket) before spending. (5) Derivatives signals output includes: funding_rate, funding_rate_annualized, open_interest, oi_change_1h, basis, mark_price, index_price, funding_trend, and a plain-language read. (6) Premium forecast add-on: pass ?horizon=1h (default), 4h, or 24h. Forecast output includes up_prob, expected_close, range_low/range_high, p10-p90 quantiles, pred_volatility, and the model version (e.g. kronos-base-60path-t1-v2). (7) Check /api/stats for public aggregate accuracy metrics before deciding to pay.", "contact": { "email": "hello@kronossignals.com" } }, "paths": { "/api/v1/forecast/btc": { "get": { "operationId": "getForecastBtc", "summary": "BTC-USD directional price forecast", "tags": [ "forecast", "paid" ], "description": "Returns a directional price forecast for BTC-USD computed from live Binance OHLCV data. The primary model is Kronos-small (ML); fallback is a composite EMA(20/50)/RSI(14)/MACD(12,26,9)/ATR(14) heuristic. Costs $0.05 USDC on Base mainnet via x402. Returns probability of upward movement, price range (ATR-based), p10–p90 quantiles, and the model used.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "1h" }, "description": "Forecast horizon. 1h = 1-hour candles, 4h = 4-hour candles, 24h = daily candles. Defaults to 1h." } ], "responses": { "200": { "description": "Forecast returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "horizon", "price", "forecast", "model", "disclaimer" ], "properties": { "asset": { "type": "string", "description": "Normalized asset identifier (e.g. BTC-USD, ETH-USD, SOL-USD).", "example": "BTC-USD" }, "horizon": { "type": "string", "enum": [ "1h", "4h", "24h" ], "description": "Forecast horizon as requested.", "example": "1h" }, "source": { "type": "string", "description": "Model or data source identifier (e.g. 'Kronos-small', 'Binance').", "example": "Kronos-small" }, "generated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when this forecast was computed." }, "price": { "type": "object", "required": [ "close", "atr" ], "description": "Price snapshot at forecast time.", "properties": { "close": { "type": "number", "description": "Last close price in USD.", "example": 107500 }, "atr": { "type": "number", "description": "ATR(14) in USD.", "example": 850.42 } } }, "forecast": { "type": "object", "required": [ "up_prob", "range_low", "range_high", "confidence" ], "description": "Core forecast output.", "properties": { "up_prob": { "type": "number", "minimum": 0, "maximum": 1, "description": "Probability of upward price movement over the horizon (0–1).", "example": 0.62 }, "range_low": { "type": "number", "description": "Estimated lower bound of the price range (close − 1.5×ATR).", "example": 106224.37 }, "range_high": { "type": "number", "description": "Estimated upper bound of the price range (close + 1.5×ATR).", "example": 108775.63 }, "horizon_bars": { "type": "integer", "description": "Number of candles the horizon spans (e.g. 20).", "example": 20 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Model confidence score (0–1).", "example": 0.75 }, "expected_close": { "type": "number", "nullable": true, "description": "Median predicted close from the Kronos ML model. null on fallback.", "example": 107620.5 }, "pred_high": { "type": "number", "nullable": true, "description": "P90 predicted bar high. null on fallback.", "example": 108900 }, "pred_low": { "type": "number", "nullable": true, "description": "P10 predicted bar low. null on fallback.", "example": 106200 }, "pred_volatility": { "type": "number", "nullable": true, "description": "Forward 1-bar volatility as a fraction of price. null on fallback.", "example": 0.0079 }, "prob_up": { "type": "number", "minimum": 0, "maximum": 1, "nullable": true, "description": "P(close > current price) from the Kronos ML model.", "example": 0.62 }, "quantiles": { "type": "object", "nullable": true, "description": "Predicted close price distribution (p10–p90). null on fallback.", "properties": { "p10": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" }, "p75": { "type": "number" }, "p90": { "type": "number" } } } } }, "model": { "type": "string", "description": "Model used: 'Kronos-small' (ML) or 'kronos-signal-composite-v1 (fallback)' (indicator heuristic).", "example": "Kronos-small" }, "inference_seconds": { "type": "number", "nullable": true, "description": "Inference latency from the Kronos ML service. Only present on ML path.", "example": 0.23 }, "disclaimer": { "type": "string", "description": "Mandatory disclaimer. Probabilistic output only; not financial advice." } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/signals/{asset}": { "get": { "operationId": "getSignals", "summary": "Crypto derivatives intelligence for 17 assets (funding rate, OI, basis)", "tags": [ "signals", "paid" ], "description": "Returns perpetual swap market intelligence for any of the 16 supported assets (BTC/ETH/SOL/BNB/XRP/DOGE/ADA/AVAX/LINK/DOT/LTC/TRX/BCH/ATOM/NEAR/APT/HYPE) from OKX. Fields: raw 8-hour funding rate, heuristic annualised funding, mark/index price, basis (perp premium/discount), open interest, 24h volume, next funding time, OI change over ~1h, funding trend, and a plain-language heuristic read. Data is collected every 5 minutes by a background cron; may lag by up to 5 min. Costs $0.02 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol", "bnb", "xrp", "doge", "ada", "avax", "link", "dot", "ltc", "trx", "bch", "atom", "near", "apt" ] }, "description": "Asset slug (lowercase). All 17 assets supported." } ], "responses": { "200": { "description": "Derivatives signals returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "as_of", "data_source", "samples", "funding_rate", "funding_rate_annualized", "mark_price", "index_price", "basis", "open_interest", "oi_change_1h", "funding_trend", "read", "disclaimer" ], "properties": { "available": { "type": "boolean", "description": "Always true in a 200 response.", "example": true }, "asset": { "type": "string", "description": "Asset identifier.", "example": "BTC-USD" }, "as_of": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent market_signals row (UTC)." }, "data_source": { "type": "string", "description": "Exchange that provided the raw data (e.g. 'bybit', 'okx').", "example": "bybit" }, "samples": { "type": "integer", "description": "Number of market_signals rows used (up to 12, ~1 h at 5-min cadence).", "example": 12 }, "funding_rate": { "type": "number", "nullable": true, "description": "Raw 8-hour funding rate. Positive = longs pay shorts; negative = shorts pay longs.", "example": 0.0001 }, "funding_rate_annualized": { "type": "number", "nullable": true, "description": "Heuristic annualised rate: funding_rate × 3 × 365. Heuristic only.", "example": 0.1095 }, "mark_price": { "type": "number", "nullable": true, "description": "Perpetual swap mark price in USD.", "example": 107510.5 }, "index_price": { "type": "number", "nullable": true, "description": "Spot index price in USD.", "example": 107498.2 }, "basis": { "type": "number", "nullable": true, "description": "(mark_price − index_price) / index_price. Positive = contango.", "example": 0.0001144 }, "open_interest": { "type": "number", "nullable": true, "description": "Open interest in the exchange's native unit from the latest row.", "example": 84320.15 }, "volume_24h": { "type": "number", "nullable": true, "description": "24-hour trading volume (USD or exchange-native units).", "example": 2341089500 }, "next_funding_time": { "type": "string", "format": "date-time", "nullable": true, "description": "UTC timestamp of the next funding settlement." }, "oi_change_1h": { "type": "object", "description": "Open interest change over the ~1h sample window.", "required": [ "abs", "pct" ], "properties": { "abs": { "type": "number", "nullable": true, "description": "Absolute OI change. Positive = growing.", "example": 120.34 }, "pct": { "type": "number", "nullable": true, "description": "OI percentage change over the window.", "example": 0.1429 } } }, "funding_trend": { "type": "string", "enum": [ "rising", "falling", "flat", "insufficient_data" ], "description": "Heuristic funding rate trend: compares recent vs older half-window averages.", "example": "flat" }, "read": { "type": "string", "description": "Human-readable heuristic interpretation of the current derivatives state." }, "disclaimer": { "type": "string", "description": "Mandatory disclaimer. Heuristic signal only; not financial advice." } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/alerts/btc": { "get": { "operationId": "getAlertsBtc", "summary": "BTC market-state alerts (regime events + live derived state)", "tags": [ "alerts", "paid" ], "description": "Returns the current actionable market-state for BTC: recent regime events detected by the Kronos regime engine within the last ~2 hours (squeeze, breakout, funding_extreme, oi_surge) plus live derived state from the latest market_signals row (funding rate, heuristic annualised funding, open interest, plain-language read). Regime events run on a ~15-minute cron; live state may lag by up to 5 minutes. Costs $0.02 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "_t", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Optional Unix-millisecond timestamp cache-buster (ignored server-side)." } ], "responses": { "200": { "description": "BTC market-state alerts returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "active_alerts", "current_state", "as_of", "disclaimer" ], "properties": { "available": { "type": "boolean", "description": "Always true in a 200 response.", "example": true }, "asset": { "type": "string", "description": "Asset identifier.", "example": "BTC-USD" }, "active_alerts": { "type": "array", "description": "Recent regime events for BTC within the last ~2 hours, newest first. Empty array if no events were detected.", "items": { "type": "object", "required": [ "event_type", "severity", "detected_at" ], "properties": { "event_type": { "type": "string", "enum": [ "squeeze", "breakout", "funding_extreme", "oi_surge" ], "description": "Type of regime event detected.", "example": "funding_extreme" }, "severity": { "type": "string", "enum": [ "high", "notable", "info" ], "description": "Detected severity.", "example": "high" }, "detected_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the event was detected." }, "details": { "type": "object", "nullable": true, "description": "Event-type-specific payload (e.g. range_ratio for squeeze, annualized_pct/sign for funding_extreme)." } } } }, "current_state": { "type": "object", "description": "Live derived state from the latest market_signals row.", "required": [ "funding_rate", "funding_annualized", "open_interest", "read" ], "properties": { "as_of": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the market_signals row used (UTC)." }, "funding_rate": { "type": "number", "nullable": true, "description": "Raw 8-hour funding rate.", "example": 0.0001 }, "funding_annualized": { "type": "number", "nullable": true, "description": "Heuristic annualised rate (funding_rate × 3 × 365).", "example": 0.1095 }, "open_interest": { "type": "number", "nullable": true, "description": "Open interest in the exchange's native unit.", "example": 84320.15 }, "read": { "type": "string", "description": "Plain-language interpretation of live state + active alerts." } } }, "as_of": { "type": "string", "format": "date-time", "description": "UTC timestamp when this response was generated." }, "disclaimer": { "type": "string", "description": "Heuristic alerts only; not financial advice." } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/price/btc": { "get": { "operationId": "getPriceBtc", "summary": "BTC spot price — $0.02/call", "tags": [ "price", "paid" ], "description": "Returns the real-time BTC-USD spot price from the Binance public API. Cheapest tool in the suite at $0.02 USDC per call — ideal for high-frequency price ticks or pre-flight checks before purchasing a more expensive signal. Costs $0.02 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "Spot price returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "price", "source", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "price": { "type": "number", "example": 107500 }, "source": { "type": "string", "example": "Binance" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/price/eth": { "get": { "operationId": "getPriceEth", "summary": "ETH spot price — $0.02/call", "tags": [ "price", "paid" ], "description": "Returns the real-time ETH-USD spot price from the Binance public API. $0.02 USDC per call on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "ETH spot price returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "price", "source", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "ETH-USD" }, "price": { "type": "number", "example": 2500 }, "source": { "type": "string", "example": "Binance" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/price/sol": { "get": { "operationId": "getPriceSol", "summary": "SOL spot price — $0.02/call", "tags": [ "price", "paid" ], "description": "Returns the real-time SOL-USD spot price from the Binance public API. $0.02 USDC per call on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "SOL spot price returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "price", "source", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "SOL-USD" }, "price": { "type": "number", "example": 150 }, "source": { "type": "string", "example": "Binance" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/snapshot/btc": { "get": { "operationId": "getSnapshotBtc", "summary": "BTC full snapshot bundle (price + derivatives + regime + forecast + options_iv + liquidations + cex_premium) — $0.08/call", "tags": [ "snapshot", "paid" ], "description": "Returns everything for BTC in one call: spot price, derivatives signals (funding rate, OI, basis, trend), market regime alerts, the Kronos 1h ML forecast, options IV summary from Deribit, liquidation squeeze_bias, and Coinbase CEX premium. Cheaper than buying each tool separately. Costs $0.04 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.080000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "BTC full snapshot returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "derivatives", "regime", "forecast", "options_iv", "liquidations", "cex_premium", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "price": { "type": "number", "nullable": true, "example": 107500 }, "derivatives": { "type": "object", "description": "Derivatives signals (see /api/v1/signals/btc)." }, "regime": { "type": "object", "description": "Regime alerts (see /api/v1/alerts/btc)." }, "forecast": { "type": "object", "description": "Kronos 1h ML forecast summary (see /api/v1/forecast/btc)." }, "options_iv": { "type": "object", "description": "ATM IV summary from Deribit. available:true for BTC.", "properties": { "available": { "type": "boolean" }, "atm_iv": { "type": "number", "nullable": true }, "term_structure_shape": { "type": "string" } } }, "liquidations": { "type": "object", "description": "Squeeze bias from funding+OI split.", "properties": { "available": { "type": "boolean" }, "squeeze_bias": { "type": "string", "nullable": true } } }, "cex_premium": { "type": "object", "description": "Coinbase price premium vs Binance+OKX composite.", "properties": { "available": { "type": "boolean" }, "premium_pct": { "type": "number", "nullable": true } } }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/snapshot/eth": { "get": { "operationId": "getSnapshotEth", "summary": "ETH full snapshot bundle (price + derivatives + forecast + options_iv + liquidations + cex_premium) — $0.08/call", "tags": [ "snapshot", "paid" ], "description": "Returns everything for ETH in one call: spot price, derivatives signals, the Kronos 1h ML forecast, options IV summary from Deribit (ETH supported), liquidation squeeze_bias, and Coinbase CEX premium. Note: regime alerts are BTC-only; regime.available=false for ETH. Costs $0.04 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.080000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "ETH snapshot returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "derivatives", "regime", "forecast", "options_iv", "liquidations", "cex_premium", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "ETH-USD" }, "price": { "type": "number", "nullable": true, "example": 2500 }, "derivatives": { "type": "object" }, "regime": { "type": "object" }, "forecast": { "type": "object" }, "options_iv": { "type": "object", "properties": { "available": { "type": "boolean" }, "atm_iv": { "type": "number", "nullable": true }, "term_structure_shape": { "type": "string" } } }, "liquidations": { "type": "object", "properties": { "available": { "type": "boolean" }, "squeeze_bias": { "type": "string", "nullable": true } } }, "cex_premium": { "type": "object", "properties": { "available": { "type": "boolean" }, "premium_pct": { "type": "number", "nullable": true } } }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/snapshot/sol": { "get": { "operationId": "getSnapshotSol", "summary": "SOL full snapshot bundle (price + derivatives + forecast + liquidations + cex_premium) — $0.08/call", "tags": [ "snapshot", "paid" ], "description": "Returns everything for SOL in one call: spot price, derivatives signals, the Kronos 1h ML forecast, liquidation squeeze_bias, and Coinbase CEX premium. Note: regime alerts are BTC-only (regime.available=false). Options IV available:false (SOL not supported by Deribit options feed). Costs $0.04 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.080000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "SOL snapshot returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "derivatives", "regime", "forecast", "options_iv", "liquidations", "cex_premium", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "SOL-USD" }, "price": { "type": "number", "nullable": true, "example": 150 }, "derivatives": { "type": "object" }, "regime": { "type": "object" }, "forecast": { "type": "object" }, "options_iv": { "type": "object", "properties": { "available": { "type": "boolean", "example": false }, "reason": { "type": "string" } } }, "liquidations": { "type": "object", "properties": { "available": { "type": "boolean" }, "squeeze_bias": { "type": "string", "nullable": true } } }, "cex_premium": { "type": "object", "properties": { "available": { "type": "boolean" }, "premium_pct": { "type": "number", "nullable": true } } }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/funding-extremes": { "get": { "operationId": "getFundingExtremes", "summary": "Funding-rate extremes screener — all 17 assets ranked", "tags": [ "screener", "paid" ], "description": "Scans all 17 perpetual futures markets and returns assets ranked by absolute funding rate. Identifies crowded positions and squeeze risk across the market. Real-time from Kronos market_signals (OKX data). $0.02 USDC via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "Ranked funding rates (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "ranked", "disclaimer" ], "properties": { "as_of": { "type": "string", "format": "date-time" }, "ranked": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "asset": { "type": "string", "example": "BTC-USD" }, "short": { "type": "string", "example": "BTC" }, "funding_rate": { "type": "number", "nullable": true }, "funding_rate_annualized": { "type": "number", "nullable": true }, "mark_price": { "type": "number", "nullable": true }, "open_interest": { "type": "number", "nullable": true }, "next_funding_time": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the next funding settlement for this asset." }, "funding_interval_hours": { "type": "number", "nullable": true, "description": "Native funding settlement interval in hours, derived from the stored exchange payload.", "example": 8 }, "captured_at": { "type": "string", "format": "date-time" } } } }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/overview": { "get": { "operationId": "getOverview", "summary": "Market-wide derivatives snapshot for all 17 assets", "tags": [ "screener", "paid" ], "description": "Returns funding rate, open interest, mark price, and 24h volume for all 17 perpetual futures markets in one call. One call replaces 16 separate signals calls. $0.02 USDC via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "Market-wide snapshot (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "assets", "available_count", "disclaimer" ], "properties": { "as_of": { "type": "string", "format": "date-time" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "short": { "type": "string" }, "tier": { "type": "string", "enum": [ "core", "watch" ] }, "funding_rate": { "type": "number", "nullable": true }, "funding_rate_annualized": { "type": "number", "nullable": true }, "open_interest": { "type": "number", "nullable": true }, "mark_price": { "type": "number", "nullable": true }, "volume_24h": { "type": "number", "nullable": true }, "captured_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "available_count": { "type": "integer" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/briefing": { "get": { "operationId": "getBriefing", "summary": "Composite market briefing: forecasts + sentiment + macro + funding extremes — $0.10/call", "tags": [ "bundle", "paid" ], "description": "Assembles BTC/ETH/SOL ML forecasts (1h horizon), the Crypto Fear & Greed Index, TradFi macro context (VIX/DXY/US 10Y yield/S&P 500/gold), and top funding-rate extremes (|z|>=2 across 17 perpetual markets) into ONE response — saving four separate paid calls, each of which would otherwise cost its own signature and round-trip. Every section carries an `available` flag: partial responses are valid and still useful, and the call is only flagged unserved when all four sections fail together. Forecasts reuse the Kronos-base cached model (~20 min TTL). $0.10 USDC via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.100000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "Composite briefing (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "forecasts": { "type": "object", "description": "Per-asset 1h ML forecasts (BTC/ETH/SOL), each with up_prob, expected close and range." }, "fear_greed": { "type": "object", "description": "Crypto Fear & Greed Index score and classification." }, "macro": { "type": "object", "description": "TradFi context: VIX, DXY, US 10Y yield, S&P 500, gold." }, "funding_extremes": { "type": "object", "description": "Perpetual funding-rate outliers, |z|>=2 across 17 markets." }, "as_of": { "type": "string" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/market-pulse": { "get": { "operationId": "getMarketPulse", "summary": "Material-change feed for up to 5 assets — $0.02/call", "tags": [ "bundle", "paid" ], "description": "Material-change feed. Pass the cursor from your last call and receive ONLY what changed since: funding sign or band, funding trend, open-interest regime, alert set, and source stale/recovered, for up to 5 assets. Returns an explicit no-change packet rather than pretending, per-asset freshness, and a next-poll time derived from the real 5-minute collection cadence. An outage is reported as an outage, never as a market move. Market data, not financial advice. $0.02 USDC via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "assets", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated asset slugs, max 5. Defaults to btc." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from a previous call." } ], "responses": { "200": { "description": "Payment verified", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/trade-preflight": { "get": { "operationId": "getTradePreflight", "summary": "Pre-trade context pack for one asset — $0.05/call", "tags": [ "bundle", "paid" ], "description": "Pre-trade context pack for one asset in a single call: derivatives state (funding, annualised funding, basis, open interest and its 1h change), recent liquidation prints, implied-volatility surface for BTC/ETH, and active regime alerts. Replaces four separate paid calls. Each component is independently marked available, unavailable or stale and is never flattened into a neutral value. Facts and data-quality context only, no recommendation. $0.05 USDC via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Asset slug." }, { "name": "side", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "long", "short", "neutral" ] }, "description": "Orients factual context only." }, { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ] }, "description": "Holding horizon." } ], "responses": { "200": { "description": "Payment verified", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/fear-greed": { "get": { "operationId": "getFearGreed", "summary": "Crypto Fear & Greed Index from alternative.me — $0.03/call", "tags": [ "sentiment", "paid" ], "description": "Returns the current Crypto Fear & Greed Index: score (0-100) and classification (Extreme Fear/Fear/Neutral/Greed/Extreme Greed) from alternative.me. $0.03 USDC via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.030000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "Fear & Greed Index (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "value", "value_classification", "timestamp", "source", "as_of", "disclaimer" ], "properties": { "value": { "type": "integer", "minimum": 0, "maximum": 100, "example": 75 }, "value_classification": { "type": "string", "example": "Greed" }, "timestamp": { "type": "string" }, "source": { "type": "string", "example": "alternative.me" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/ohlc/{asset}": { "get": { "operationId": "getOhlc", "summary": "Consolidated OHLC candles for 16 assets (Binance + Coinbase) — $0.02/call", "tags": [ "price", "paid" ], "description": "Returns consolidated OHLC candlestick data for any of the 16 supported assets: Binance (primary) + Coinbase (secondary) per candle, with VWAP, dollar volume, body/wick % and doji flags, plus gap and volume-anomaly flags. Supports ?interval=1h|4h|1d (default 1h) and ?limit=1-200 (default 50). $0.02 USDC via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol", "bnb", "xrp", "doge", "ada", "avax", "link", "dot", "ltc", "trx", "bch", "atom", "near", "apt" ] }, "description": "Asset slug (lowercase)." }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "1d" ], "default": "1h" }, "description": "Candle interval." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of candles (1-200, default 50)." } ], "responses": { "200": { "description": "OHLC candles returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "interval", "candles", "count", "source", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "interval": { "type": "string" }, "consolidated": { "type": "boolean" }, "exchanges_used": { "type": "array", "items": { "type": "string" } }, "candles_consolidated": { "type": "integer" }, "candles": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "integer" }, "o": { "type": "number" }, "h": { "type": "number" }, "l": { "type": "number" }, "c": { "type": "number" }, "vwap": { "type": "number" }, "dollar_volume": { "type": "number" }, "candle_body_pct": { "type": "number" }, "upper_wick_pct": { "type": "number" }, "lower_wick_pct": { "type": "number" }, "doji": { "type": "boolean" }, "current_candle_is_forming": { "type": "boolean" } } } }, "count": { "type": "integer" }, "gap_flags": { "type": "array", "description": "Candle open vs prior close gaps exceeding 1%. Empty array = no gaps.", "items": { "type": "object", "properties": { "candle_index": { "type": "integer" }, "gap_pct": { "type": "number", "description": "Gap size in percent (signed)." }, "t": { "type": "integer", "description": "Open time of gapping candle (Unix ms)." } } } }, "baseline_insufficient": { "type": "boolean", "description": "true when <20 candles returned — rolling baseline cannot be established." }, "volume_anomaly": { "type": "object", "properties": { "detected": { "type": "boolean" }, "ratio": { "type": "number", "nullable": true, "description": "Last candle vol / rolling mean. null when baseline_insufficient." } } }, "source": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/volatility/{asset}": { "get": { "operationId": "getVolatility", "summary": "Realized volatility for 16 assets (7d/30d/90d annualized, three estimators) — $0.02/call", "tags": [ "risk", "paid" ], "description": "Computes 7-day, 30-day and 90-day annualized realized volatility from closed Binance daily candles for any of the 16 supported assets, with three estimators (close-to-close, Parkinson, Garman-Klass), annualized by sqrt(252), plus percentile context and a vol-regime label. $0.02 USDC via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol", "bnb", "xrp", "doge", "ada", "avax", "link", "dot", "ltc", "trx", "bch", "atom", "near", "apt" ] }, "description": "Asset slug (lowercase)." } ], "responses": { "200": { "description": "Realized volatility returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "symbol", "term_structure", "vol_7d_annualized", "vol_30d_annualized", "source", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "symbol": { "type": "string", "example": "BTCUSDT" }, "term_structure": { "type": "array", "items": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d", "90d" ] }, "n_candles": { "type": "integer" }, "close_to_close": { "type": "number", "nullable": true }, "parkinson": { "type": "number", "nullable": true }, "garman_klass": { "type": "number", "nullable": true }, "percentile": { "type": "number", "nullable": true }, "vol_regime": { "type": "string", "nullable": true }, "best_estimator": { "type": "string", "nullable": true } } } }, "percentile_context": { "type": "array", "items": { "type": "object" } }, "vol_7d_annualized": { "type": "number", "nullable": true }, "vol_30d_annualized": { "type": "number", "nullable": true }, "source": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/methodology": { "get": { "operationId": "getMethodology", "summary": "Track-record methodology (public, no payment required)", "tags": [ "public" ], "description": "Documents how Kronos forecasts are scored and returns CURRENT live accuracy figures from the database. Explains the directional hit-rate metric, the evaluate-cron scoring process, honest caveats (thin sample, one-regime data), and links to /api/stats.", "security": [], "parameters": [], "responses": { "200": { "description": "Methodology and live accuracy", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "accuracy": { "type": "object", "properties": { "available": { "type": "boolean" }, "sample_size": { "type": "integer", "nullable": true }, "hit_rate": { "type": "number", "nullable": true }, "note": { "type": "string" } } }, "caveats": { "type": "array", "items": { "type": "string" } }, "live_stats_url": { "type": "string", "format": "uri" }, "generated_at": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } } } } }, "/api/v1/sample/btc": { "get": { "operationId": "getSampleBtc", "summary": "BTC free sample signal (no payment required)", "tags": [ "sample", "free" ], "description": "Free teaser endpoint. Returns a coarse directional signal (up/down + confidence bucket) for BTC derived from the latest cached Kronos forecast row. Exact probability, price ranges, and quantiles are withheld — upgrade to /api/v1/forecast/btc ($0.05 via x402) for the full output. Rate-limited to 10 requests per minute per IP.", "security": [], "parameters": [], "responses": { "200": { "description": "BTC sample signal", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "horizon", "signal", "as_of", "upgrade", "disclaimer" ], "properties": { "available": { "type": "boolean", "description": "true when a cached forecast row exists; false when no data yet.", "example": true }, "asset": { "type": "string", "description": "Asset identifier.", "example": "BTC-USD" }, "horizon": { "type": "string", "enum": [ "1h", "4h", "24h" ], "description": "Horizon of the underlying forecast row (always '1h' for samples).", "example": "1h" }, "signal": { "type": "object", "description": "Coarse directional signal derived from the latest cached forecast row. Exact probability is withheld — upgrade to the paid endpoint for the full output.", "required": [ "direction", "confidence" ], "properties": { "direction": { "type": "string", "enum": [ "up", "down" ], "description": "Heuristic direction: 'up' when up_prob >= 0.5, 'down' otherwise.", "example": "up" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Coarse confidence bucket based on |up_prob − 0.5|: high ≥ 0.2, medium ≥ 0.1, low < 0.1.", "example": "medium" } } }, "as_of": { "type": "string", "format": "date-time", "description": "Timestamp of the underlying forecast row used." }, "upgrade": { "type": "object", "description": "Links to the paid endpoint and discovery manifest.", "properties": { "message": { "type": "string" }, "paid_endpoint": { "type": "string", "format": "uri" }, "discovery": { "type": "string", "format": "uri" } } }, "disclaimer": { "type": "string", "description": "Informational only; not financial advice." } } } } } } } } }, "/api/v1/sample/eth": { "get": { "operationId": "getSampleEth", "summary": "ETH free sample signal (no payment required)", "tags": [ "sample", "free" ], "description": "Free teaser endpoint. Returns a coarse directional signal (up/down + confidence bucket) for ETH derived from the latest cached Kronos forecast row. Rate-limited to 10 requests per minute per IP.", "security": [], "parameters": [], "responses": { "200": { "description": "ETH sample signal", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "horizon", "signal", "as_of", "upgrade", "disclaimer" ], "properties": { "available": { "type": "boolean", "description": "true when a cached forecast row exists; false when no data yet.", "example": true }, "asset": { "type": "string", "description": "Asset identifier.", "example": "ETH-USD" }, "horizon": { "type": "string", "enum": [ "1h", "4h", "24h" ], "description": "Horizon of the underlying forecast row (always '1h' for samples).", "example": "1h" }, "signal": { "type": "object", "description": "Coarse directional signal derived from the latest cached forecast row. Exact probability is withheld — upgrade to the paid endpoint for the full output.", "required": [ "direction", "confidence" ], "properties": { "direction": { "type": "string", "enum": [ "up", "down" ], "description": "Heuristic direction: 'up' when up_prob >= 0.5, 'down' otherwise.", "example": "up" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Coarse confidence bucket based on |up_prob − 0.5|: high ≥ 0.2, medium ≥ 0.1, low < 0.1.", "example": "medium" } } }, "as_of": { "type": "string", "format": "date-time", "description": "Timestamp of the underlying forecast row used." }, "upgrade": { "type": "object", "description": "Links to the paid endpoint and discovery manifest.", "properties": { "message": { "type": "string" }, "paid_endpoint": { "type": "string", "format": "uri" }, "discovery": { "type": "string", "format": "uri" } } }, "disclaimer": { "type": "string", "description": "Informational only; not financial advice." } } } } } } } } }, "/api/v1/sample/sol": { "get": { "operationId": "getSampleSol", "summary": "SOL free sample signal (no payment required)", "tags": [ "sample", "free" ], "description": "Free teaser endpoint. Returns a coarse directional signal (up/down + confidence bucket) for SOL derived from the latest cached Kronos forecast row. Rate-limited to 10 requests per minute per IP.", "security": [], "parameters": [], "responses": { "200": { "description": "SOL sample signal", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "horizon", "signal", "as_of", "upgrade", "disclaimer" ], "properties": { "available": { "type": "boolean", "description": "true when a cached forecast row exists; false when no data yet.", "example": true }, "asset": { "type": "string", "description": "Asset identifier.", "example": "SOL-USD" }, "horizon": { "type": "string", "enum": [ "1h", "4h", "24h" ], "description": "Horizon of the underlying forecast row (always '1h' for samples).", "example": "1h" }, "signal": { "type": "object", "description": "Coarse directional signal derived from the latest cached forecast row. Exact probability is withheld — upgrade to the paid endpoint for the full output.", "required": [ "direction", "confidence" ], "properties": { "direction": { "type": "string", "enum": [ "up", "down" ], "description": "Heuristic direction: 'up' when up_prob >= 0.5, 'down' otherwise.", "example": "up" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Coarse confidence bucket based on |up_prob − 0.5|: high ≥ 0.2, medium ≥ 0.1, low < 0.1.", "example": "medium" } } }, "as_of": { "type": "string", "format": "date-time", "description": "Timestamp of the underlying forecast row used." }, "upgrade": { "type": "object", "description": "Links to the paid endpoint and discovery manifest.", "properties": { "message": { "type": "string" }, "paid_endpoint": { "type": "string", "format": "uri" }, "discovery": { "type": "string", "format": "uri" } } }, "disclaimer": { "type": "string", "description": "Informational only; not financial advice." } } } } } } } } }, "/api/v1/alerts/{asset}": { "get": { "operationId": "getAlertsAsset", "summary": "Market-regime alerts for any of the 16 supported crypto assets — $0.02/call", "tags": [ "alerts", "paid" ], "description": "Returns the current actionable market-state for any of the 16 supported assets: recent regime events detected by the Kronos regime engine within the last ~2 hours (squeeze, breakout, funding_extreme, oi_surge) plus live derived state from the latest market_signals row (funding rate, heuristic annualised funding, open interest, plain-language read). Supports BTC/ETH/SOL/BNB/XRP/DOGE/ADA/AVAX/LINK/DOT/LTC/TRX/BCH/ATOM/NEAR/APT. Regime events run on a ~15-minute cron; live state may lag by up to 5 minutes. Costs $0.02 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol", "bnb", "xrp", "doge", "ada", "avax", "link", "dot", "ltc", "trx", "bch", "atom", "near", "apt" ] }, "description": "Asset slug (lowercase). All 17 assets supported." } ], "responses": { "200": { "description": "Market-state alerts returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "active_alerts", "current_state", "as_of", "disclaimer" ], "properties": { "available": { "type": "boolean", "example": true }, "asset": { "type": "string", "example": "ETH-USD" }, "active_alerts": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "squeeze", "breakout", "funding_extreme", "oi_surge" ] }, "severity": { "type": "string", "enum": [ "high", "notable", "info" ] }, "detected_at": { "type": "string", "format": "date-time" }, "details": { "type": "object", "nullable": true } } } }, "current_state": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date-time", "nullable": true }, "funding_rate": { "type": "number", "nullable": true }, "funding_annualized": { "type": "number", "nullable": true }, "open_interest": { "type": "number", "nullable": true }, "read": { "type": "string" } } }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Unsupported asset slug." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/scan": { "get": { "operationId": "getScan", "summary": "Market-wide scan across all 17 assets — $0.04/call", "tags": [ "screener", "paid" ], "description": "Returns a market-wide scan across all 17 crypto assets in one call. Per-asset: funding rate, annualized rate, OI 1h change (abs + pct), basis, funding trend, funding_extreme flag (|rate| > 0.001 threshold), mark price, and regime event count in the last 2h. Optional ?assets=btc,eth,sol to scan a subset (unknown slugs gracefully ignored). Assets without data are flagged with available:false rather than fabricated. Costs $0.04 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.040000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "assets", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated asset slugs to scan (e.g. btc,eth,sol). Omit to scan all 17." } ], "responses": { "200": { "description": "Market scan returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "scanned", "assets", "disclaimer" ], "properties": { "as_of": { "type": "string", "format": "date-time" }, "scanned": { "type": "integer", "description": "Number of assets in this response." }, "assets": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "short": { "type": "string", "example": "BTC" }, "tier": { "type": "string", "enum": [ "core", "watch" ] }, "available": { "type": "boolean" }, "stale": { "type": "boolean" }, "funding_rate": { "type": "number", "nullable": true }, "funding_rate_annualized": { "type": "number", "nullable": true }, "funding_extreme": { "type": "boolean" }, "oi_change_1h": { "type": "object", "properties": { "abs": { "type": "number", "nullable": true }, "pct": { "type": "number", "nullable": true } } }, "basis": { "type": "number", "nullable": true }, "funding_trend": { "type": "string", "enum": [ "rising", "falling", "flat", "insufficient_data" ] }, "mark_price": { "type": "number", "nullable": true }, "as_of": { "type": "string", "format": "date-time", "nullable": true }, "data_source": { "type": "string", "nullable": true }, "regime": { "type": "object", "properties": { "event_count": { "type": "integer" }, "latest_event_type": { "type": "string", "nullable": true } } } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/macro": { "get": { "operationId": "getMacro", "summary": "TradFi macro context (VIX, DXY, US 10Y, SPX, gold) — $0.02/call", "tags": [ "macro", "paid" ], "description": "Returns TradFi macro context for crypto risk assessment: VIX fear gauge, DXY (US Dollar Index), US 10-Year Treasury yield, S&P 500 (SPX), and gold spot price. Sourced from stooq.com and Yahoo Finance in parallel. 15-minute in-memory cache. A field is null when its source is unreachable — never fabricated; if every source is unreachable the call answers 503 and nothing is charged. BTC-SPX and BTC-DXY 30-day Pearson correlations are computed from daily returns (Binance + stooq historical) and included when source data is available; null with btc_spx_correlation_available:false when upstream fetch fails — never fabricated. Costs $0.02 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "Macro context returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "as_of", "vix", "dxy", "us_10y_yield", "spx", "gold", "disclaimer" ], "properties": { "as_of": { "type": "string", "format": "date-time" }, "cached": { "type": "boolean" }, "cache_age_seconds": { "type": "integer", "nullable": true }, "vix": { "type": "object", "properties": { "value": { "type": "number", "nullable": true }, "source": { "type": "string", "nullable": true }, "unavailable": { "type": "boolean" } } }, "dxy": { "type": "object", "properties": { "value": { "type": "number", "nullable": true }, "source": { "type": "string", "nullable": true }, "unavailable": { "type": "boolean" } } }, "us_10y_yield": { "type": "object", "properties": { "value": { "type": "number", "nullable": true }, "source": { "type": "string", "nullable": true }, "unavailable": { "type": "boolean" } } }, "spx": { "type": "object", "properties": { "value": { "type": "number", "nullable": true }, "source": { "type": "string", "nullable": true }, "unavailable": { "type": "boolean" } } }, "gold": { "type": "object", "properties": { "value": { "type": "number", "nullable": true }, "source": { "type": "string", "nullable": true }, "unavailable": { "type": "boolean" } } }, "btc_spx_correlation": { "type": "number", "nullable": true, "description": "Pearson correlation of 30d daily returns (BTC vs SPX). Null when <10 aligned days or fetch failed. Field omitted when BTC history unavailable." }, "btc_spx_correlation_available": { "type": "boolean", "description": "true when btc_spx_correlation was successfully computed." }, "btc_dxy_correlation": { "type": "number", "nullable": true, "description": "Pearson correlation of 30d daily returns (BTC vs DXY). Null when <10 aligned days or fetch failed. Field omitted when BTC history unavailable." }, "btc_dxy_correlation_available": { "type": "boolean", "description": "true when btc_dxy_correlation was successfully computed." }, "correlation_note": { "type": "string", "description": "Present only when correlation fields are omitted due to upstream fetch failure." }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/forecast-ledger": { "get": { "operationId": "getForecastLedger", "summary": "Paginated resolved-forecast ledger — $0.02/call", "tags": [ "ledger", "paid" ], "description": "Returns a paginated list of resolved forecasts (outcomes joined with forecasts). Each row shows the original ML prediction and its real-world result. Summary includes total count and hit_rate (cache-source rows, matching /api/stats methodology). Filterable by asset, horizon, date range, and source. Costs $0.02 USDC on Base via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by asset (e.g. btc or BTC-USD)." }, { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ] }, "description": "Filter by horizon." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO date lower bound (forecasts.created_at)." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO date upper bound (forecasts.created_at)." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cache", "paid" ] }, "description": "Filter by forecast source. Defaults to cache+paid (no internal)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500 }, "description": "Page size." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Page offset." } ], "responses": { "200": { "description": "Resolved forecast ledger (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "hit_rate": { "type": "number", "nullable": true, "description": "Cache-source hit rate, matching /api/stats methodology." }, "sample_note": { "type": "string" } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "forecast_id": { "type": "string", "format": "uuid" }, "made_at": { "type": "string", "format": "date-time" }, "asset": { "type": "string" }, "horizon": { "type": "string", "enum": [ "1h", "4h", "24h" ] }, "predicted_direction": { "type": "string", "enum": [ "up", "down" ] }, "up_prob": { "type": "number" }, "confidence": { "type": "number", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "actual_direction": { "type": "string", "enum": [ "up", "down" ], "nullable": true }, "hit": { "type": "boolean", "nullable": true }, "price_at_forecast": { "type": "number", "nullable": true }, "price_at_resolution": { "type": "number", "nullable": true }, "return_pct": { "type": "number", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } }, "disclaimer": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/liquidations/{asset}": { "get": { "operationId": "getLiquidations", "summary": "Forward liquidation cluster map + recent prints (17 assets) — $0.02/call", "tags": [ "liquidations", "derivatives", "paid" ], "description": "Returns a forward liquidation cluster map and recent liquidation prints for any of the 16 supported assets. Part A (always): estimated liq price levels for 5x/10x/25x/50x leverage bands, modeled from open interest and mark price — no new upstream source (reuses OKX data from the 5-min cron). Includes nearest_long/short liq clusters, squeeze_bias (long_squeeze_risk / short_squeeze_risk / balanced), and explicit disclaimer that these are model estimates, not real order book data. Part B (best-effort): recent liquidation prints from OKX public API (no auth). If OKX is unreachable: recent_prints.available=false — never fabricated. Supports BTC/ETH/SOL/BNB/XRP/DOGE/ADA/AVAX/LINK/DOT/LTC/TRX/BCH/ATOM/NEAR/APT. Costs $0.02 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol", "bnb", "xrp", "doge", "ada", "avax", "link", "dot", "ltc", "trx", "bch", "atom", "near", "apt" ] }, "description": "Asset slug (lowercase). All 17 assets supported." } ], "responses": { "200": { "description": "Liquidation cluster map returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "as_of", "cluster_map", "recent_prints", "disclaimer" ], "properties": { "available": { "type": "boolean", "example": true }, "asset": { "type": "string", "example": "BTC-USD" }, "as_of": { "type": "string", "format": "date-time" }, "mark_price": { "type": "number", "nullable": true, "example": 107500 }, "open_interest": { "type": "number", "nullable": true, "example": 84320.15 }, "funding_rate": { "type": "number", "nullable": true, "example": 0.0001 }, "cluster_map": { "type": "object", "description": "Forward liquidation cluster map. Estimated, not from order book. See disclaimer and model_note fields.", "properties": { "disclaimer": { "type": "string" }, "model_note": { "type": "string" }, "long_clusters": { "type": "array", "description": "Estimated long liq levels below mark price, nearest first.", "items": { "type": "object", "properties": { "leverage": { "type": "integer", "example": 50 }, "liq_price": { "type": "number", "example": 106425 }, "distance_pct": { "type": "number", "example": -0.98 }, "estimated_oi_fraction": { "type": "number", "example": 0.051 } } } }, "short_clusters": { "type": "array", "description": "Estimated short liq levels above mark price, nearest first.", "items": { "type": "object", "properties": { "leverage": { "type": "integer", "example": 50 }, "liq_price": { "type": "number", "example": 108575 }, "distance_pct": { "type": "number", "example": 1 }, "estimated_oi_fraction": { "type": "number", "example": 0.049 } } } }, "nearest_long_liq_cluster": { "type": "object", "nullable": true, "properties": { "liq_price": { "type": "number" }, "distance_pct": { "type": "number" } } }, "nearest_short_liq_cluster": { "type": "object", "nullable": true, "properties": { "liq_price": { "type": "number" }, "distance_pct": { "type": "number" } } }, "squeeze_bias": { "type": "string", "enum": [ "long_squeeze_risk", "short_squeeze_risk", "balanced" ], "description": "long_squeeze_risk = more long OI at risk (cascade if price drops); short_squeeze_risk = more short OI at risk (cascade if price rises)." }, "total_long_oi_estimate": { "type": "number" }, "total_short_oi_estimate": { "type": "number" } } }, "recent_prints": { "type": "object", "description": "Recent liquidation prints from OKX public API. Never fabricated.", "properties": { "available": { "type": "boolean" }, "source": { "type": "string", "nullable": true, "example": "okx-public" }, "count": { "type": "integer", "nullable": true }, "prints": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell" ] }, "pos_side": { "type": "string", "enum": [ "long", "short" ] }, "size": { "type": "number" }, "price": { "type": "number" }, "time": { "type": "string", "format": "date-time" } } } }, "note": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true } } }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Unsupported asset slug." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" }, "503": { "description": "Derivatives data unavailable (market_signals not populated)." } } } }, "/api/v1/digest/{asset}": { "get": { "operationId": "getDigest", "summary": "Structured market digest — deterministic bundle from live signals — $0.02/call", "tags": [ "digest", "paid" ], "description": "Deterministic structured market digest: funding rate, basis, regime, 30d realized vol, Fear & Greed, VIX, and ML forecast (BTC/ETH/SOL). Templated thesis string, per-driver interpretations, and honest caveats. No LLM. $0.02 USDC via x402.", "x-payment-info": { "scheme": "exact", "amount": 20000, "currency": "USDC", "decimals": 6, "network": "base", "description": "Send 0.02 USDC (20000 micro-USDC) on Base via x402." }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol", "bnb", "xrp", "doge", "ada", "avax", "link", "dot", "ltc", "trx", "bch", "atom", "near", "apt" ] }, "description": "Asset slug (lowercase)." } ], "responses": { "200": { "description": "Market digest returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "as_of", "regime", "thesis", "drivers", "caveats", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "as_of": { "type": "string", "format": "date-time" }, "regime": { "type": "string", "description": "Primary regime: breakout/squeeze/funding_extreme/oi_surge/none/insufficient_data." }, "thesis": { "type": "string", "description": "Deterministic summary templated from live driver values. No LLM." }, "confidence": { "type": "number", "nullable": true }, "up_prob_calibrated": { "type": "number", "nullable": true }, "drivers": { "type": "array", "items": { "type": "object", "required": [ "name", "interpretation" ], "properties": { "name": { "type": "string" }, "value": { "description": "Raw signal value (number, string, or null)." }, "interpretation": { "type": "string" } } } }, "caveats": { "type": "array", "items": { "type": "string" } }, "forecast_ref": { "type": "string", "nullable": true, "example": "/api/v1/forecast/btc" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/options-iv/{asset}": { "get": { "operationId": "getOptionsIv", "summary": "Implied volatility surface for BTC/ETH (Deribit) — $0.03/call", "tags": [ "options", "implied-volatility", "paid" ], "description": "Returns the implied volatility surface for BTC or ETH from Deribit public options data (no auth). Fields: ATM IV (annualized %), IV rank and IV percentile (from Kronos iv_history table, daily cron), term structure (weekly/1m/3m ATM IV) with contango/backwardation/flat shape label, proper 25-delta risk reversal (BS-approximated strikes, put IV − call IV), 10-delta wing IVs, max-pain strike across top-5 expiries, and a vol-regime label (compression/normal/event-risk/expansion). IV rank/percentile return null with iv_history_status:'accumulating' until ≥20 days of history. Falls back to OKX options if Deribit is unreachable. Returns available:false if both fail. 1-hour in-memory cache. $0.03 USDC on Base mainnet via x402. BTC and ETH only.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.030000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth" ] }, "description": "Asset slug (lowercase). Only btc and eth are supported (Deribit's most liquid option markets)." } ], "responses": { "200": { "description": "Options IV surface returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "data_source", "atm_iv", "term_structure", "vol_regime", "as_of", "disclaimer" ], "properties": { "available": { "type": "boolean", "example": true }, "asset": { "type": "string", "example": "BTC-USD" }, "underlying_price": { "type": "number", "nullable": true, "example": 61200 }, "data_source": { "type": "string", "enum": [ "deribit", "okx" ], "example": "deribit" }, "atm_iv": { "type": "number", "nullable": true, "description": "OI-weighted ATM implied volatility, annualized in %.", "example": 42.8 }, "iv_rank": { "type": "number", "nullable": true, "description": "Where current ATM IV sits within the trailing 1y min–max range (0–100). null while accumulating <20 days of history.", "example": 58.3 }, "iv_percentile": { "type": "number", "nullable": true, "description": "% of historical days with ATM IV strictly below current. null while accumulating.", "example": 61.2 }, "iv_rank_note": { "type": "string", "description": "Explains iv_rank/iv_percentile computation or the accumulating status." }, "iv_history_days": { "type": "integer", "nullable": true, "description": "Number of days of ATM IV history in iv_history table (trailing 1y). null if Supabase unavailable.", "example": 45 }, "term_structure": { "type": "array", "description": "ATM IV by expiry bucket (weekly ≤14d, 1m 15-50d, 3m 51-130d). Present buckets only.", "items": { "type": "object", "properties": { "label": { "type": "string", "enum": [ "weekly", "1m", "3m" ] }, "expiry": { "type": "string", "example": "5JUL26" }, "days_to_expiry": { "type": "integer", "example": 3 }, "atm_iv": { "type": "number", "nullable": true, "example": 44.2 } } } }, "term_structure_shape": { "type": "string", "enum": [ "contango", "backwardation", "flat", "insufficient_data" ], "description": "Shape of the ATM IV term structure. contango = longer-tenor IV > shorter (normal); backwardation = inverted (front IV elevated, event risk); flat = within ±1.5 vol pts.", "example": "contango" }, "skew_25d": { "type": "number", "nullable": true, "description": "25-delta risk reversal = put IV − call IV at BS-approximated 25-delta strikes for the front expiry. Positive = put-side premium (downside hedging demand). Falls back to OTM-band median if approximation fails.", "example": 3.8 }, "wing_10d_call_iv": { "type": "number", "nullable": true, "description": "IV at the nearest call strike to the BS-approximated 10-delta level (front expiry). null if insufficient data.", "example": 38.5 }, "wing_10d_put_iv": { "type": "number", "nullable": true, "description": "IV at the nearest put strike to the BS-approximated 10-delta level (front expiry). null if insufficient data.", "example": 49.2 }, "skew_note": { "type": "string", "description": "Describes how skew_25d was computed, including the strikes used and any approximation caveats." }, "max_pain_strike": { "type": "number", "nullable": true, "description": "Strike minimising total option-writer payout across top-5 nearest expiries.", "example": 60000 }, "vol_regime": { "type": "string", "enum": [ "compression", "normal", "event-risk", "expansion" ], "example": "normal" }, "vol_regime_note": { "type": "string" }, "realized_vol": { "type": "number", "nullable": true, "description": "Realized volatility (annualized %, same basis as atm_iv) from Binance 30d daily close-to-close log returns. null if Binance fetch fails.", "example": 39.6 }, "vrp": { "type": "number", "nullable": true, "description": "Variance risk premium: atm_iv − realized_vol (annualized percentage points). Positive = options priced above trailing realized vol.", "example": 3.2 }, "vol_regime_iv_band": { "type": "string", "enum": [ "LOW", "MID", "HIGH", "insufficient_data" ], "description": "Static-band heuristic classification of atm_iv level, distinct from vol_regime (term-structure based). See vol_regime_iv_band_note.", "example": "MID" }, "vol_regime_iv_band_note": { "type": "string", "description": "Explains the static thresholds used to classify vol_regime_iv_band." }, "methodology_vrp": { "type": "string", "description": "Explains the unit conversion between atm_iv (Deribit) and the realized-vol estimator used for vrp." }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Unsupported asset (only btc and eth are supported)." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "503": { "description": "Both Deribit and OKX options APIs were unreachable." } } } }, "/api/v1/implied-prob/{asset}": { "get": { "operationId": "getImpliedProb", "summary": "Options-implied probability ladder for BTC/ETH (Deribit) — $0.02/call", "tags": [ "options", "prediction-markets", "paid" ], "description": "Returns the options market's probability that BTC or ETH is above each of up to 25 prices at a target time, backed out of the Deribit option book: a skew-inclusive call-spread digital on the mark-IV smile, with total variance interpolated in time between listed expiries. It is the fair value of a prediction-market crypto threshold contract (Kalshi, Polymarket) — compare probability_above with the contract's YES price. Risk-neutral, not a forecast. Malformed input is refused with a free 400 before any payment. $0.02 USDC on Base mainnet via x402. BTC and ETH only.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth" ] }, "description": "Asset slug (lowercase). Only btc and eth (Deribit option markets)." }, { "name": "strikes", "in": "query", "required": false, "schema": { "type": "string", "examples": [ "85000,90000" ] }, "description": "Comma-separated prices, 1-25. Default: a ±1-10% ladder around the forward." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string", "examples": [ "2026-01-02T16:00:00Z" ] }, "description": "Target time: ISO-8601 with a timezone, or a Unix timestamp. Default: the nearest Deribit expiry (08:00 UTC)." } ], "responses": { "200": { "description": "Probability ladder returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "asset": { "type": "string" }, "target_time": { "type": "string", "format": "date-time" }, "hours_to_target": { "type": "number" }, "index_price": { "type": "number", "nullable": true }, "forward_at_target": { "type": "number" }, "ladder": { "type": "array", "items": { "type": "object", "properties": { "strike": { "type": "number" }, "probability_above": { "type": "number", "minimum": 0, "maximum": 1 }, "probability_below": { "type": "number", "minimum": 0, "maximum": 1 }, "iv_at_strike_pct": { "type": "number" }, "extrapolated": { "type": "boolean" } } } }, "warning": { "type": "string" }, "expiries_used": { "type": "array", "items": { "type": "object" } }, "defaults_applied": { "type": "object" }, "how_to_use": { "type": "string" }, "method": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "cache_ttl_sec": { "type": "integer" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Malformed request (asset, strikes or target time) — refused before payment, nothing charged." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "409": { "description": "Payment nonce already used (replay rejected)." }, "422": { "description": "Target after the last listed Deribit expiry, or a strike more than 5x from the forward — not charged." }, "503": { "description": "Deribit option book unreachable — not charged." } } } }, "/api/v1/cex-premium/{asset}": { "get": { "operationId": "getCexPremium", "summary": "Coinbase cross-exchange price premium vs global composite — $0.02/call", "tags": [ "cex-premium", "cross-exchange", "paid" ], "description": "Computes the Coinbase price premium vs the composite median of OKX, Kraken, and Binance spot prices. premium_pct = (coinbase_price / composite_median − 1) × 100. Positive = US/institutional demand bias; negative = global selling pressure or Coinbase supply imbalance. Covers all assets listed on Coinbase (BTC/ETH/SOL/XRP/DOGE/ADA/AVAX/LINK/DOT/LTC/BCH/ATOM/NEAR). Assets not listed on Coinbase (BNB, TRX, APT) return available:false. Includes 30d z-score and 24h percentile from Kronos cex_premium_history table (hourly cron record-cex-premium). Returns baseline_status:'accumulating' with sample count until ≥24 hourly samples exist. $0.02 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol", "xrp", "doge", "ada", "avax", "link", "dot", "ltc", "bch", "atom", "near" ] }, "description": "Asset slug (lowercase). Must be listed on Coinbase Exchange." } ], "responses": { "200": { "description": "CEX premium returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "coinbase_price", "composite_median", "premium_pct", "sources_used", "as_of", "disclaimer" ], "properties": { "available": { "type": "boolean", "example": true }, "asset": { "type": "string", "example": "BTC-USD" }, "coinbase_price": { "type": "number", "example": 61320.5 }, "composite_median": { "type": "number", "description": "Median of OKX + Kraken + Binance spot prices.", "example": 61198.3 }, "premium_pct": { "type": "number", "description": "(coinbase / composite_median − 1) × 100. Positive = Coinbase premium.", "example": 0.2 }, "interpretation": { "type": "string", "description": "Plain-language read of the premium magnitude and direction." }, "sources_used": { "type": "array", "items": { "type": "object", "properties": { "exchange": { "type": "string", "enum": [ "coinbase", "okx", "kraken", "binance" ] }, "price": { "type": "number" }, "role": { "type": "string", "enum": [ "reference", "composite", "unavailable" ] } } } }, "composite_source_count": { "type": "integer", "description": "Number of composite sources that responded.", "example": 3 }, "z_score_30d": { "type": "number", "nullable": true, "description": "30-day z-score: (current_premium − 30d_mean) / 30d_stddev. null while accumulating <24 samples.", "example": 1.4 }, "percentile_24h": { "type": "number", "nullable": true, "description": "% of 24h hourly samples with premium strictly below current. null while accumulating <12 samples.", "example": 78.3 }, "baseline_samples_30d": { "type": "integer", "description": "Hourly premium samples recorded in the trailing 30 days.", "example": 312 }, "baseline_samples_24h": { "type": "integer", "description": "Hourly premium samples recorded in the trailing 24 hours.", "example": 22 }, "baseline_status": { "type": "string", "enum": [ "ready", "accumulating" ], "description": "'ready' when ≥24 samples exist; 'accumulating' otherwise." }, "baseline_note": { "type": "string", "description": "Explains z-score computation or accumulating state." }, "data_age_seconds": { "type": "integer" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Unsupported asset or asset not listed on Coinbase." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "503": { "description": "Coinbase price unavailable or no composite sources reachable." } } } }, "/api/v1/stablecoins": { "get": { "operationId": "getStablecoins", "summary": "Stablecoin market cap + top stablecoins + 7d/30d flows from DeFiLlama — $0.02/call", "tags": [ "defi", "stablecoins", "paid" ], "description": "Returns total stablecoin market cap, top-10 breakdown by dominance %, and 7-day and 30-day supply flows (mint/burn) sourced from DeFiLlama. Shows total stablecoin market cap, per-coin dominance %, and net capital entering/leaving crypto. 15-minute cache. Never fabricated — returns available:false when sources are unreachable. $0.02 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "Stablecoin data returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_stablecoin_mcap": { "type": "number", "nullable": true, "description": "Total stablecoin market cap in USD." }, "top_stablecoins": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "symbol": { "type": "string" }, "circulating": { "type": "number" }, "dominance_pct": { "type": "number" } } } }, "flows": { "type": "object", "properties": { "flow_7d_usd": { "type": "number", "nullable": true }, "flow_7d_pct": { "type": "number", "nullable": true }, "flow_30d_usd": { "type": "number", "nullable": true }, "flow_30d_pct": { "type": "number", "nullable": true } } }, "interpretation": { "type": "string", "nullable": true }, "as_of": { "type": "string", "format": "date-time" }, "as_of_age_seconds": { "type": "integer" }, "stale": { "type": "boolean" }, "source": { "type": "string" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" }, "503": { "description": "DeFiLlama data unavailable or snapshot cache warming." } } } }, "/api/v1/unlocks": { "get": { "operationId": "getUnlocks", "summary": "Upcoming token unlocks for major tokens from DeFiLlama — $0.02/call", "tags": [ "defi", "unlocks", "paid" ], "description": "Returns upcoming token unlock events for a curated set of major tokens: the next scheduled cliff or linear unlock per protocol, tokens released, USD value at the current price, % of circulating supply, and the largest unlock within 7 days. DeFiLlama emissions + coins.llama.fi prices, refreshed hourly. Never fabricated — returns available:false when sources are unreachable. $0.02 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [], "responses": { "200": { "description": "Unlock schedule returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "upcoming_unlocks": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": "string" }, "unlock_date": { "type": "string", "format": "date-time" }, "tokens_unlocked": { "type": "number" }, "usd_value": { "type": "number", "nullable": true }, "pct_of_circulating_supply": { "type": "number", "nullable": true }, "category": { "type": "string" }, "unlock_type": { "type": "string" } } } }, "largest_imminent": { "type": "object", "nullable": true }, "count": { "type": "integer" }, "universe": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "as_of_age_seconds": { "type": "integer" }, "stale": { "type": "boolean" }, "source": { "type": "string" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" }, "503": { "description": "DeFiLlama data unavailable or snapshot cache warming." } } } }, "/api/v1/forecast/doge": { "get": { "operationId": "getForecastDoge", "summary": "DOGE-USD directional forecast [$0.05/call]", "tags": [ "forecast", "paid" ], "description": "Returns a directional price forecast for DOGE-USD. Kronos-base ML model (60-path Monte-Carlo, run hourly; composite heuristic when no recent run exists) — graduated from the composite heuristic 2026-07-10. model_type in the response says which model served. Per-asset served accuracy is published live at /api/stats (beta_accuracy.per_asset). Priced at $0.05 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "1h" }, "description": "Forecast horizon." } ], "responses": { "200": { "description": "DOGE forecast returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "example": "DOGE-USD" }, "horizon": { "type": "string", "example": "1h" }, "price": { "type": "object", "properties": { "close": { "type": "number" }, "atr": { "type": "number" } } }, "forecast": { "type": "object", "properties": { "up_prob": { "type": "number", "minimum": 0, "maximum": 1 }, "range_low": { "type": "number" }, "range_high": { "type": "number" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "model": { "type": "string", "description": "Kronos-base ML model version (e.g. 'kronos-base-60path-t1-v2'), or composite on cache-miss fallback." }, "beta": { "type": "boolean", "example": false, "description": "False since the 2026-07-10 Kronos-base graduation." }, "model_type": { "type": "string", "example": "kronos_ml", "description": "kronos_ml = Kronos-base Monte-Carlo model; composite = EMA/RSI/MACD/ATR fallback." }, "accuracy_note": { "type": "string", "description": "Measured record under the current model, plus the retained prior composite record." }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/forecast/xrp": { "get": { "operationId": "getForecastXrp", "summary": "XRP-USD directional forecast [$0.05/call]", "tags": [ "forecast", "paid" ], "description": "Returns a composite directional price forecast for XRP-USD from live Binance OHLCV data. Model: composite EMA(20/50)/RSI(14)/MACD(12,26,9)/ATR(14) heuristic — the Kronos ML model is not yet deployed for XRP. It has shown no directional edge; check the live per-asset figure at /api/stats (beta_accuracy.per_asset, free) before buying. Response includes model_type:'composite' and accuracy_note. Priced at $0.05 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "1h" }, "description": "Forecast horizon." } ], "responses": { "200": { "description": "XRP forecast returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "example": "XRP-USD" }, "horizon": { "type": "string", "example": "1h" }, "price": { "type": "object", "properties": { "close": { "type": "number" }, "atr": { "type": "number" } } }, "forecast": { "type": "object", "properties": { "up_prob": { "type": "number", "minimum": 0, "maximum": 1 }, "range_low": { "type": "number" }, "range_high": { "type": "number" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "model": { "type": "string", "description": "Always composite (fallback) for XRP." }, "beta": { "type": "boolean", "example": true, "description": "Always true for beta endpoints." }, "model_type": { "type": "string", "example": "composite", "description": "composite = EMA/RSI/MACD/ATR heuristic." }, "accuracy_note": { "type": "string", "description": "Honest disclosure: directional accuracy not yet established." }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/forecast/bnb": { "get": { "operationId": "getForecastBnb", "summary": "BNB-USD directional forecast [$0.05/call]", "tags": [ "forecast", "paid" ], "description": "Returns a directional price forecast for BNB-USD. Kronos-base ML model (60-path Monte-Carlo, run hourly; composite heuristic when no recent run exists) — graduated from the composite heuristic 2026-07-10. model_type in the response says which model served. Per-asset served accuracy is published live at /api/stats (beta_accuracy.per_asset). Priced at $0.05 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "1h" }, "description": "Forecast horizon." } ], "responses": { "200": { "description": "BNB forecast returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "example": "BNB-USD" }, "horizon": { "type": "string", "example": "1h" }, "price": { "type": "object", "properties": { "close": { "type": "number" }, "atr": { "type": "number" } } }, "forecast": { "type": "object", "properties": { "up_prob": { "type": "number", "minimum": 0, "maximum": 1 }, "range_low": { "type": "number" }, "range_high": { "type": "number" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "model": { "type": "string", "description": "Kronos-base ML model version (e.g. 'kronos-base-60path-t1-v2'), or composite on cache-miss fallback." }, "beta": { "type": "boolean", "example": false, "description": "False since the 2026-07-10 Kronos-base graduation." }, "model_type": { "type": "string", "example": "kronos_ml", "description": "kronos_ml = Kronos-base Monte-Carlo model; composite = EMA/RSI/MACD/ATR fallback." }, "accuracy_note": { "type": "string", "description": "Measured record under the current model, plus the retained prior composite record." }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/forecast/near": { "get": { "operationId": "getForecastNear", "summary": "NEAR-USD directional forecast [$0.05/call]", "tags": [ "forecast", "paid" ], "description": "Returns a directional price forecast for NEAR-USD. Kronos-base ML model (60-path Monte-Carlo, run hourly; composite heuristic when no recent run exists); new endpoint 2026-07-15, no prior serving history. model_type in the response says which model served. Per-asset served accuracy is published live at /api/stats (beta_accuracy.per_asset). Priced at $0.05 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "1h" }, "description": "Forecast horizon." } ], "responses": { "200": { "description": "NEAR forecast returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "example": "NEAR-USD" }, "horizon": { "type": "string", "example": "1h" }, "price": { "type": "object", "properties": { "close": { "type": "number" }, "atr": { "type": "number" } } }, "forecast": { "type": "object", "properties": { "up_prob": { "type": "number", "minimum": 0, "maximum": 1 }, "range_low": { "type": "number" }, "range_high": { "type": "number" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "model": { "type": "string", "description": "Kronos-base ML model version (e.g. 'kronos-base-60path-t1-v2'), or composite on cache-miss fallback." }, "beta": { "type": "boolean", "example": false, "description": "False — NEAR launched directly on Kronos-base 2026-07-15; never served as beta." }, "model_type": { "type": "string", "example": "kronos_ml", "description": "kronos_ml = Kronos-base Monte-Carlo model; composite = EMA/RSI/MACD/ATR fallback." }, "accuracy_note": { "type": "string", "description": "Measured internal-validation record under the current model; no prior paid-serving history for NEAR." }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/forecast/ada": { "get": { "operationId": "getForecastAda", "summary": "ADA-USD directional forecast [$0.05/call]", "tags": [ "forecast", "paid" ], "description": "Returns a directional price forecast for ADA-USD (Cardano). Kronos-base ML model (60-path Monte-Carlo, run hourly; composite heuristic when no recent run exists); new endpoint 2026-07-20, no prior serving history. model_type in the response says which model served. Served accuracy is published live at /api/v1/forecast-ledger and /api/stats. Priced at $0.05 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "1h" }, "description": "Forecast horizon." } ], "responses": { "200": { "description": "ADA forecast returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "example": "ADA-USD" }, "horizon": { "type": "string", "example": "1h" }, "price": { "type": "object", "properties": { "close": { "type": "number" }, "atr": { "type": "number" } } }, "forecast": { "type": "object", "properties": { "up_prob": { "type": "number", "minimum": 0, "maximum": 1 }, "range_low": { "type": "number" }, "range_high": { "type": "number" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "model": { "type": "string", "description": "Kronos-base ML model version (e.g. 'kronos-base-60path-t1-v2'), or composite on cache-miss fallback." }, "beta": { "type": "boolean", "example": false, "description": "False — ADA launched directly on Kronos-base 2026-07-20; never served as beta." }, "model_type": { "type": "string", "example": "kronos_ml", "description": "kronos_ml = Kronos-base Monte-Carlo model; composite = EMA/RSI/MACD/ATR fallback." }, "accuracy_note": { "type": "string", "description": "Measured internal-validation record under the current model; no prior paid-serving history for ADA." }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body" } } } }, "/api/v1/gex/{asset}": { "get": { "operationId": "getGex", "summary": "Gamma Exposure (GEX) and max-pain for BTC/ETH (Deribit) — $0.04/call", "tags": [ "gex", "options", "gamma-exposure", "paid" ], "description": "Gamma Exposure (GEX) and max-pain options tool for BTC and ETH from the Deribit public API. Returns an aggregate GEX strike ladder (dealer-convention net gamma per strike), gamma flip level (zero-cumulative-GEX strike), spot regime above or below flip, max-pain strikes for upcoming weekly and monthly expiries, an expected-move cone (ATM-IV-derived 1-sigma, front expiry), and a heuristic pin-risk score. 15-minute in-memory cache. $0.04 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.040000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth" ] }, "description": "Asset slug (lowercase). Only btc and eth are supported (Deribit's most liquid option markets)." } ], "responses": { "200": { "description": "GEX data returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "asset", "data_source", "gex_ladder", "spot_regime", "max_pain", "pin_risk", "as_of" ], "properties": { "available": { "type": "boolean", "example": true }, "asset": { "type": "string", "example": "BTC-USD" }, "underlying_price": { "type": "number", "nullable": true, "example": 61200 }, "data_source": { "type": "string", "example": "deribit" }, "gex_units": { "type": "string", "example": "USD per 1% spot move per strike" }, "gex_ladder": { "type": "array", "description": "Aggregate GEX per strike (dealer-convention net gamma).", "items": { "type": "object", "properties": { "strike": { "type": "number" }, "netGex": { "type": "number" }, "callGex": { "type": "number" }, "putGex": { "type": "number" } } } }, "gex_total": { "type": "number", "nullable": true, "description": "Sum of netGex across the ladder." }, "gamma_flip_level": { "type": "number", "nullable": true, "description": "Zero-cumulative-GEX strike." }, "spot_regime": { "type": "string", "enum": [ "above_flip", "below_flip" ], "description": "Spot price relative to the gamma flip level." }, "max_pain": { "type": "array", "description": "Max-pain strikes for the upcoming weekly and nearest monthly expiries.", "items": { "type": "object", "properties": { "expiry": { "type": "string", "example": "4JUL26" }, "dte": { "type": "number" }, "max_pain_strike": { "type": "number", "nullable": true }, "label": { "type": "string", "example": "weekly" } } } }, "expected_move": { "type": "object", "nullable": true, "description": "ATM-IV-derived 1-sigma expected-move cone for the front expiry.", "properties": { "expiry": { "type": "string" }, "dte": { "type": "number" }, "atm_iv": { "type": "number", "nullable": true }, "spot": { "type": "number" }, "upper": { "type": "number" }, "lower": { "type": "number" } } }, "pin_risk": { "type": "array", "description": "Heuristic pin-risk score per expiry. NOT a forecast.", "items": { "type": "object", "properties": { "expiry": { "type": "string" }, "max_pain_strike": { "type": "number", "nullable": true }, "pin_risk_score": { "type": "number", "minimum": 0, "maximum": 1 }, "note": { "type": "string" } } } }, "as_of": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Unsupported asset (only btc and eth are supported)." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "503": { "description": "GEX data unavailable (Deribit unreachable or insufficient options data)." } } } }, "/api/v1/funding-arb/{asset}": { "get": { "operationId": "getFundingArb", "summary": "Cross-venue funding arbitrage signal — up to 6 exchanges, net-of-fees — $0.02/call", "tags": [ "funding-arb", "paid" ], "description": "Queries up to 6 perpetual swap exchanges for real-time 8h-equivalent funding rates (Binance USDT-M, OKX, Bybit, KuCoin Futures, Bitget, Hyperliquid) and computes the gross and net-of-fees spread between the best short venue (highest rate8h) and the best long venue (lowest rate8h). gross_spread_bps = (best_short_rate8h − best_long_rate8h) × 10000. net_spread_bps = gross_spread_bps − 20 (ROUND_TRIP_FEE_BPS: 5 bps/side taker × 4 fills). annualized_pct = (net per-8h fraction) × 3 × 365 × 100. Actionability: not_actionable (net≤0), marginal (05 bps). Outcome recorded to Supabase funding_arb_signals (fire-and-forget). Returns honest nulls when a venue fails — never fabricated. All 17 assets. $0.02 USDC via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol", "bnb", "xrp", "doge", "ada", "avax", "link", "dot", "ltc", "trx", "bch", "atom", "near", "apt" ] }, "description": "Asset slug (lowercase). All 17 assets supported." } ], "responses": { "200": { "description": "Funding arbitrage signal returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "short", "as_of", "actionability", "round_trip_fee_bps", "methodology", "caveats", "per_venue", "dispersion" ], "properties": { "asset": { "type": "string", "description": "Asset label (e.g. BTC-USD).", "example": "BTC-USD" }, "short": { "type": "string", "description": "Short ticker.", "example": "BTC" }, "as_of": { "type": "string", "format": "date-time", "description": "Timestamp of the venue-rate snapshot." }, "best_short_venue": { "type": "string", "nullable": true, "description": "Venue with the highest rate8h (receiver of funding when short)." }, "best_long_venue": { "type": "string", "nullable": true, "description": "Venue with the lowest rate8h (pays least / receives when long)." }, "best_short_rate8h": { "type": "number", "nullable": true, "description": "8h-equivalent rate at the best short venue." }, "best_long_rate8h": { "type": "number", "nullable": true, "description": "8h-equivalent rate at the best long venue." }, "gross_spread_bps": { "type": "number", "nullable": true, "description": "(best_short_rate8h − best_long_rate8h) × 10000." }, "net_spread_bps": { "type": "number", "nullable": true, "description": "gross_spread_bps − ROUND_TRIP_FEE_BPS (20)." }, "spread_8h_normalized": { "type": "number", "nullable": true, "description": "Raw (non-bps) 8h-normalized rate spread that gross_spread_bps is derived from (gross_spread_bps = spread_8h_normalized × 10000).", "example": 0.0004 }, "venues_count": { "type": "integer", "description": "Number of the 6 venues that returned a usable rate.", "example": 6 }, "annualized_pct": { "type": "number", "nullable": true, "description": "(net per-8h fraction) × 3 × 365 × 100." }, "actionability": { "type": "string", "enum": [ "not_actionable", "marginal", "actionable", "insufficient_data" ], "description": "not_actionable: net≤0 bps. marginal: 05 bps." }, "round_trip_fee_bps": { "type": "number", "example": 20, "description": "Fee assumption used (5 bps/side taker × 4 fills)." }, "methodology": { "type": "string", "description": "Computation explanation." }, "caveats": { "type": "array", "items": { "type": "string" }, "description": "Honest limitations and disclaimers." }, "per_venue": { "type": "object", "description": "Per-venue rate8h and OI. Null = venue failed or asset not listed.", "additionalProperties": { "type": "object", "properties": { "rate8h": { "type": "number", "nullable": true }, "oi": { "type": "number", "nullable": true }, "funding_interval_hours": { "type": "number", "nullable": true, "description": "Venue's native funding settlement interval in hours (e.g. Hyperliquid = 1, most others = 8).", "example": 8 }, "error": { "type": "string", "description": "Present when venue fetch failed." } } } }, "dispersion": { "type": "object", "properties": { "max_min_spread": { "type": "number", "nullable": true }, "stdev": { "type": "number", "nullable": true }, "venues_reporting": { "type": "integer" } } }, "oi_weighted_avg_8h": { "type": "number", "nullable": true }, "simple_avg_8h": { "type": "number", "nullable": true } } } } } }, "400": { "description": "Unsupported asset slug." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "503": { "description": "All venue fetches failed — no rates available." } } } }, "/api/v1/forecast-path/{asset}": { "get": { "operationId": "getForecastPath", "summary": "3-horizon quantile fan for BTC/ETH/SOL — $0.08/call", "tags": [ "forecast", "paid" ], "description": "Real Monte-Carlo quantile fan (p10/p25/p50/p75/p90), expected close, and forward volatility at the three discrete horizons Kronos forecasts (1h/4h/24h), read from the cached forecasts-table rows (60-path Kronos-base Monte-Carlo, refreshed every 20 min). No interpolation between horizons. $0.08 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.080000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol" ] }, "description": "Asset slug. Only btc, eth, and sol supported." } ], "responses": { "200": { "description": "Forecast path fan returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "generated_at": { "type": "string", "format": "date-time" }, "price_close": { "type": "number" }, "anchors": { "type": "array", "items": { "type": "object", "properties": { "horizon": { "type": "string", "enum": [ "1h", "4h", "24h" ] }, "age_seconds": { "type": "integer" }, "expected_close": { "type": "number" }, "quantiles": { "type": "object", "properties": { "p10": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" }, "p75": { "type": "number" }, "p90": { "type": "number" } } }, "pred_high": { "type": "number", "nullable": true }, "pred_low": { "type": "number", "nullable": true }, "pred_volatility": { "type": "number", "nullable": true }, "range_low": { "type": "number" }, "range_high": { "type": "number" }, "n_paths": { "type": "integer", "nullable": true } } } }, "fresh_anchors": { "type": "integer" }, "max_age_minutes": { "type": "integer", "example": 25 }, "model": { "type": "string" }, "note": { "type": "string" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "404": { "description": "Unsupported asset — only btc, eth, and sol are supported." }, "503": { "description": "No fresh forecast anchors with quantiles available." } } } }, "/api/v1/target-prob/{asset}": { "get": { "operationId": "getTargetProb", "summary": "Empirical target-price probability for BTC/ETH/SOL — $0.05/call", "tags": [ "forecast", "paid" ], "description": "Empirical probability that the close will be above/below a caller-supplied target price at 1h, 4h, or 24h, computed directly from the 60 terminal prices of the cached Kronos-base Monte-Carlo run (refreshed every 20 min). Resolution ~1/60 ≈ 1.7 percentage points — an empirical sample frequency, not a market-implied probability. $0.05 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol" ] }, "description": "Asset slug. Only btc, eth, and sol supported." }, { "name": "target", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Target price to evaluate, e.g. 125000. Must be a finite number > 0." }, { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "24h" }, "description": "Forecast horizon." } ], "responses": { "200": { "description": "Target probability returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "horizon": { "type": "string", "example": "24h" }, "target": { "type": "number" }, "price_close": { "type": "number" }, "generated_at": { "type": "string", "format": "date-time" }, "age_seconds": { "type": "integer" }, "n_samples": { "type": "integer", "example": 60 }, "count_above": { "type": "integer" }, "prob_above": { "type": "number", "minimum": 0, "maximum": 1 }, "prob_below": { "type": "number", "minimum": 0, "maximum": 1 }, "clipped": { "type": "boolean" }, "quantiles": { "type": "object", "nullable": true }, "resolution_note": { "type": "string" }, "model": { "type": "string" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Invalid or missing target/horizon query param." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "404": { "description": "Unsupported asset — only btc, eth, and sol are supported." }, "503": { "description": "No fresh forecast row with terminal_closes available." } } } }, "/api/v1/forward-vol/{asset}": { "get": { "operationId": "getForwardVol", "summary": "Predicted vs realized forward volatility for BTC/ETH/SOL — $0.03/call", "tags": [ "forecast", "volatility", "paid" ], "description": "Model-predicted forward volatility at 1h, 4h, and 24h horizons, read directly from the cached Kronos-base 60-path Monte-Carlo dispersion (refreshed every 20 min), alongside a realized-volatility comparison (Binance daily OHLC: close-to-close, Parkinson, Garman-Klass). $0.03 USDC on Base mainnet via x402.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.030000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth", "sol" ] }, "description": "Asset slug. Only btc, eth, and sol supported." } ], "responses": { "200": { "description": "Forward volatility returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "price_close": { "type": "number" }, "anchors": { "type": "array", "items": { "type": "object", "properties": { "horizon": { "type": "string", "enum": [ "1h", "4h", "24h" ] }, "age_seconds": { "type": "integer" }, "pred_volatility": { "type": "number" }, "pred_volatility_pct": { "type": "number" } } } }, "realized": { "type": "object", "nullable": true, "properties": { "term_structure": { "type": "array", "items": { "type": "object", "properties": { "window": { "type": "string" }, "n_candles": { "type": "integer" }, "close_to_close": { "type": "number", "nullable": true }, "parkinson": { "type": "number", "nullable": true }, "garman_klass": { "type": "number", "nullable": true } } } }, "source": { "type": "string" }, "method": { "type": "string" } } }, "vol_premium_note": { "type": "string" }, "model": { "type": "string" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "404": { "description": "Unsupported asset — only btc, eth, and sol are supported." }, "503": { "description": "No fresh forecast anchors with pred_volatility available." } } } } } }