{ "openapi": "3.0.3", "info": { "title": "Kronos x402 API", "version": "1.0.0", "description": "Kronos pay-per-call crypto intelligence API for autonomous agents and trading bots. 14+ paid endpoints across 16 crypto assets. (1) /api/v1/forecast/{asset} — ML price forecasts for BTC/ETH/SOL ($0.01); (2) /api/v1/signals/{asset} — perpetual futures derivatives signals for 16 assets ($0.02); (3) /api/v1/alerts/btc — Bitcoin market-regime alerts ($0.02); (4) /api/v1/price/{asset} — spot price for 16 assets ($0.001); (5) /api/v1/snapshot/{asset} — full bundle: price + derivatives + forecast ($0.04); (6) /api/v1/funding-extremes — all 16 assets ranked by absolute funding rate ($0.02); (7) /api/v1/overview — market-wide snapshot for all 16 assets ($0.02); (8) /api/v1/fear-greed — Crypto Fear & Greed Index from alternative.me ($0.001); (9) /api/v1/ohlc/{asset} — OHLC candlestick data from Binance ($0.001); (10) /api/v1/volatility/{asset} — 7d/30d realized volatility ($0.01). All paid via x402 USDC micropayments on Base mainnet (eip155:8453). Public: /api/stats, /api/health.", "x-disclaimer": "All output is informational only and NOT financial advice. Forecasts are probabilistic model outputs; signals are heuristics derived from public market data. Past signals do not guarantee future returns. Use at your own risk.", "contact": { "url": "https://kronossignals.com" } }, "servers": [ { "url": "https://kronossignals.com", "description": "Production — Base mainnet (eip155:8453)" } ], "paths": { "/api/v1/forecast/btc": { "get": { "operationId": "getForecast", "summary": "Crypto directional forecast (BTC / ETH / SOL)", "description": "Returns a directional price forecast for the requested asset computed from live Binance OHLCV data. The primary model is Kronos-small (ML); if unavailable the fallback is a composite EMA(20/50)/RSI(14)/MACD(12,26,9)/ATR(14) vote-based heuristic. Requires an x402 EIP-3009 micropayment of $0.01 USDC. On the first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions; re-send with the X-PAYMENT header populated by an x402 client library.", "parameters": [ { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BTC-USD", "ETH-USD", "SOL-USD" ], "default": "BTC-USD" }, "description": "Asset to forecast. BTC-USD is the default and most reliable. ETH-USD and SOL-USD use the same model pipeline. Assets map to Binance symbols BTCUSDT / ETHUSDT / SOLUSDT." }, { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "1h" }, "description": "Forecast horizon: 1h uses 1-hour candles, 4h uses 4-hour candles, 24h uses daily candles. Defaults to 1h." } ], "responses": { "200": { "description": "Forecast data returned (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "description": "CORS wildcard header" } }, "content": { "application/json": { "example": { "asset": "BTC-USD", "horizon": "1h", "source": "Kronos-small", "generated_at": "2026-06-30T10:00:00.000Z", "price": { "close": 107500, "atr": 850.42 }, "forecast": { "up_prob": 0.62, "range_low": 106224.37, "range_high": 108775.63, "horizon_bars": 20, "confidence": 0.75, "expected_close": 107620.5, "pred_high": 108900, "pred_low": 106200, "pred_volatility": 0.0079, "prob_up": 0.62, "quantiles": { "p10": 106350, "p25": 107100, "p50": 107620.5, "p75": 108150, "p90": 108900 } }, "model": "Kronos-small", "inference_seconds": 0.23, "disclaimer": "Probabilistic forecast from the Kronos-small model. Not financial advice. Past signals do not guarantee future returns." }, "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" }, "timeframe": { "type": "string", "enum": [ "1h", "4h", "1d" ], "description": "Binance candle interval used (1d = daily, maps to 24h horizon). Present in composite-fallback responses only.", "example": "1h" }, "source": { "type": "string", "description": "Data or model 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.", "example": "2026-06-30T10:00:00.000Z" }, "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 — used to compute range_low/range_high.", "example": 850.42 } } }, "indicators": { "type": "object", "description": "Raw technical indicator values. Present in composite-fallback responses only (null in Kronos-small responses).", "properties": { "ema20": { "type": "number", "description": "EMA(20) in USD." }, "ema50": { "type": "number", "description": "EMA(50) in USD." }, "rsi14": { "type": "number", "minimum": 0, "maximum": 100, "description": "RSI(14)." }, "macd": { "type": "number", "description": "MACD line (EMA12 − EMA26)." }, "macd_signal": { "type": "number", "description": "MACD signal line (EMA9 of MACD)." }, "macd_hist": { "type": "number", "description": "MACD histogram (MACD − signal)." }, "atr14": { "type": "number", "description": "ATR(14) in USD." } } }, "signal": { "type": "object", "description": "Per-indicator votes. Present in composite-fallback responses only.", "properties": { "votes": { "type": "array", "items": { "type": "integer", "enum": [ -1, 0, 1 ] }, "description": "6-element array: +1 bullish, -1 bearish, 0 neutral. Order: [close>EMA20, close>EMA50, EMA20>EMA50, RSI, MACD, MACDhist]." }, "positives": { "type": "integer", "description": "Count of +1 votes." }, "negatives": { "type": "integer", "description": "Count of -1 votes." }, "neutral": { "type": "integer", "description": "Count of 0 votes." } } }, "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.0–1.0). In the composite fallback: fraction of bullish indicator votes.", "example": 0.62 }, "range_low": { "type": "number", "description": "Estimated lower bound of the price range: close − 1.5×ATR(14).", "example": 106224.37 }, "range_high": { "type": "number", "description": "Estimated upper bound of the price range: close + 1.5×ATR(14).", "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": "Indicator agreement score: max(positives, negatives) / total_votes in the composite fallback; model-specific confidence in Kronos-small.", "example": 0.75 }, "mean_path_closes": { "type": "array", "items": { "type": "number" }, "nullable": true, "description": "Optional mean simulated price path from Kronos-small ML model. Array of close prices at each horizon bar. Only present when the ML service returns it." }, "expected_close": { "type": "number", "nullable": true, "description": "Median predicted close for the next bar from the Kronos ML model. null on composite fallback (no ML-projected close available).", "example": 107620.5 }, "pred_high": { "type": "number", "nullable": true, "description": "P90 predicted bar high — upper extreme of the predicted price range. On composite fallback: approximated as range_high (close + 1.5×ATR).", "example": 108900 }, "pred_low": { "type": "number", "nullable": true, "description": "P10 predicted bar low — lower extreme of the predicted price range. On composite fallback: approximated as range_low (close − 1.5×ATR).", "example": 106200 }, "pred_volatility": { "type": "number", "nullable": true, "description": "Forward 1-bar volatility as a fraction of price (e.g. 0.008 = 0.8%). On composite fallback: approximated as ATR(14)/close.", "example": 0.0079 }, "prob_up": { "type": "number", "minimum": 0, "maximum": 1, "nullable": true, "description": "P(close > current price) from the Kronos ML model. On composite fallback: same as up_prob (fraction of bullish indicator votes).", "example": 0.62 }, "quantiles": { "type": "object", "nullable": true, "description": "Distribution of predicted close prices from the Kronos ML model. null on composite fallback (no distribution available).", "properties": { "p10": { "type": "number", "description": "10th percentile predicted close.", "example": 106350 }, "p25": { "type": "number", "description": "25th percentile predicted close.", "example": 107100 }, "p50": { "type": "number", "description": "50th percentile predicted close (median).", "example": 107620.5 }, "p75": { "type": "number", "description": "75th percentile predicted close.", "example": 108150 }, "p90": { "type": "number", "description": "90th percentile predicted close.", "example": 108900 } } } } }, "risk_state": { "type": "string", "enum": [ "elevated", "normal" ], "description": "Volatility flag from composite fallback: 'elevated' when ATR/close > 2%. Not present in Kronos-small responses.", "example": "normal" }, "directional_context": { "type": "object", "description": "Human-readable direction context from composite fallback only.", "properties": { "direction": { "type": "string", "enum": [ "positive", "negative", "neutral" ] }, "magnitude": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalised strength of direction (|up_prob − 0.5| × 2)." }, "magnitude_label": { "type": "string", "enum": [ "strong", "moderate", "weak" ] } } }, "model": { "type": "string", "description": "Model identifier used. 'Kronos-small' for the ML path; 'kronos-signal-composite-v1 (fallback)' for the EMA/RSI/MACD/ATR path.", "example": "Kronos-small" }, "inference_seconds": { "type": "number", "nullable": true, "description": "Wall-clock inference time in seconds from the Kronos ML service. Only present when the ML path was used.", "example": 0.23 }, "disclaimer": { "type": "string", "description": "Mandatory disclaimer. Not financial advice. Heuristic or probabilistic output only." } } } } } }, "402": { "description": "Payment required — x402 micropayment instructions. The response body and X-PAYMENT-REQUIRED header contain the payment requirements in x402 format. Submit 0.01 USDC on Base mainnet (eip155:8453) using an x402 client, then retry with the X-PAYMENT header.", "headers": { "X-PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded JSON payment requirements (amount, asset, network, payTo, scheme)." } }, "x-x402": { "scheme": "exact", "price": "$0.01", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.01 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "409": { "description": "Payment nonce already used (replay rejected).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Upstream data unavailable. Binance API is unreachable or returned an error; or the Kronos ML service timed out and the Binance fallback also failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "string" } } } } } } }, "x-x402": { "scheme": "exact", "price": "$0.01", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.01 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "forecastCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/forecast/eth": { "get": { "operationId": "getEthForecast", "summary": "ETH-USD directional forecast", "description": "Returns a directional price forecast for ETH-USD computed from live Binance OHLCV data. The primary model is Kronos-small (ML); if unavailable the fallback is a composite EMA(20/50)/RSI(14)/MACD(12,26,9)/ATR(14) vote-based heuristic. Requires an x402 EIP-3009 micropayment of $0.01 USDC. On the first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions; re-send with the X-PAYMENT header populated by an x402 client library.", "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "1h" }, "description": "Forecast horizon: 1h uses 1-hour candles, 4h uses 4-hour candles, 24h uses daily candles. Defaults to 1h." } ], "responses": { "200": { "description": "Forecast data returned (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "description": "CORS wildcard header" } }, "content": { "application/json": { "example": { "asset": "ETH-USD", "horizon": "1h", "source": "Kronos-small", "generated_at": "2026-06-30T10:00:00.000Z", "price": { "close": 2500, "atr": 45.5 }, "forecast": { "up_prob": 0.62, "range_low": 2431.75, "range_high": 2568.25, "horizon_bars": 20, "confidence": 0.75, "expected_close": 2515.5, "pred_high": 2580, "pred_low": 2425, "pred_volatility": 0.0182, "prob_up": 0.62, "quantiles": { "p10": 2440, "p25": 2475, "p50": 2515.5, "p75": 2548, "p90": 2580 } }, "model": "Kronos-small", "inference_seconds": 0.21, "disclaimer": "Probabilistic forecast from the Kronos-small model. Not financial advice. Past signals do not guarantee future returns." }, "schema": { "type": "object", "required": [ "asset", "horizon", "price", "forecast", "model", "disclaimer" ], "properties": { "asset": { "type": "string", "description": "Normalized asset identifier.", "example": "ETH-USD" }, "horizon": { "type": "string", "enum": [ "1h", "4h", "24h" ], "description": "Forecast horizon as requested.", "example": "1h" }, "timeframe": { "type": "string", "enum": [ "1h", "4h", "1d" ], "description": "Binance candle interval used (1d = daily, maps to 24h horizon). Present in composite-fallback responses only.", "example": "1h" }, "source": { "type": "string", "description": "Data or model source identifier.", "example": "Kronos-small" }, "generated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when this forecast was computed." }, "price": { "type": "object", "required": [ "close", "atr" ], "properties": { "close": { "type": "number", "description": "Last close price in USD.", "example": 2500 }, "atr": { "type": "number", "description": "ATR(14) in USD.", "example": 45.5 } } }, "indicators": { "type": "object", "description": "Raw indicator values. Present in composite-fallback responses only.", "properties": { "ema20": { "type": "number" }, "ema50": { "type": "number" }, "rsi14": { "type": "number", "minimum": 0, "maximum": 100 }, "macd": { "type": "number" }, "macd_signal": { "type": "number" }, "macd_hist": { "type": "number" }, "atr14": { "type": "number" } } }, "signal": { "type": "object", "description": "Per-indicator votes. Present in composite-fallback responses only.", "properties": { "votes": { "type": "array", "items": { "type": "integer", "enum": [ -1, 0, 1 ] } }, "positives": { "type": "integer" }, "negatives": { "type": "integer" }, "neutral": { "type": "integer" } } }, "forecast": { "type": "object", "required": [ "up_prob", "range_low", "range_high", "confidence" ], "properties": { "up_prob": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.62 }, "range_low": { "type": "number", "example": 2431.75 }, "range_high": { "type": "number", "example": 2568.25 }, "horizon_bars": { "type": "integer", "example": 20 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.75 }, "mean_path_closes": { "type": "array", "items": { "type": "number" }, "nullable": true }, "expected_close": { "type": "number", "nullable": true, "example": 2515.5 }, "pred_high": { "type": "number", "nullable": true, "example": 2580 }, "pred_low": { "type": "number", "nullable": true, "example": 2425 }, "pred_volatility": { "type": "number", "nullable": true, "example": 0.0182 }, "prob_up": { "type": "number", "minimum": 0, "maximum": 1, "nullable": true, "example": 0.62 }, "quantiles": { "type": "object", "nullable": true, "properties": { "p10": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" }, "p75": { "type": "number" }, "p90": { "type": "number" } } } } }, "risk_state": { "type": "string", "enum": [ "elevated", "normal" ] }, "directional_context": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "positive", "negative", "neutral" ] }, "magnitude": { "type": "number", "minimum": 0, "maximum": 1 }, "magnitude_label": { "type": "string", "enum": [ "strong", "moderate", "weak" ] } } }, "model": { "type": "string", "example": "Kronos-small" }, "inference_seconds": { "type": "number", "nullable": true, "example": 0.21 }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — x402 micropayment instructions. Submit 0.01 USDC on Base mainnet (eip155:8453) using an x402 client, then retry with the X-PAYMENT header.", "headers": { "X-PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded JSON payment requirements." } }, "x-x402": { "scheme": "exact", "price": "$0.01", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.01 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "409": { "description": "Payment nonce already used (replay rejected).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Upstream data unavailable. Binance API unreachable or Kronos ML timed out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "string" } } } } } } }, "x-x402": { "scheme": "exact", "price": "$0.01", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.01 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "ethForecastCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/forecast/sol": { "get": { "operationId": "getSolForecast", "summary": "SOL-USD directional forecast", "description": "Returns a directional price forecast for SOL-USD computed from live Binance OHLCV data. The primary model is Kronos-small (ML); if unavailable the fallback is a composite EMA(20/50)/RSI(14)/MACD(12,26,9)/ATR(14) vote-based heuristic. Requires an x402 EIP-3009 micropayment of $0.01 USDC. On the first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions; re-send with the X-PAYMENT header populated by an x402 client library.", "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "24h" ], "default": "1h" }, "description": "Forecast horizon: 1h uses 1-hour candles, 4h uses 4-hour candles, 24h uses daily candles. Defaults to 1h." } ], "responses": { "200": { "description": "Forecast data returned (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "description": "CORS wildcard header" } }, "content": { "application/json": { "example": { "asset": "SOL-USD", "horizon": "1h", "source": "Kronos-small", "generated_at": "2026-06-30T10:00:00.000Z", "price": { "close": 150, "atr": 3.5 }, "forecast": { "up_prob": 0.67, "range_low": 144.75, "range_high": 155.25, "horizon_bars": 20, "confidence": 0.67, "expected_close": 151.2, "pred_high": 156, "pred_low": 144, "pred_volatility": 0.0233, "prob_up": 0.67, "quantiles": { "p10": 145, "p25": 147.5, "p50": 151.2, "p75": 153.5, "p90": 156 } }, "model": "Kronos-small", "inference_seconds": 0.19, "disclaimer": "Probabilistic forecast from the Kronos-small model. Not financial advice. Past signals do not guarantee future returns." }, "schema": { "type": "object", "required": [ "asset", "horizon", "price", "forecast", "model", "disclaimer" ], "properties": { "asset": { "type": "string", "description": "Normalized asset identifier.", "example": "SOL-USD" }, "horizon": { "type": "string", "enum": [ "1h", "4h", "24h" ], "description": "Forecast horizon as requested.", "example": "1h" }, "timeframe": { "type": "string", "enum": [ "1h", "4h", "1d" ], "description": "Binance candle interval used (1d = daily, maps to 24h horizon). Present in composite-fallback responses only.", "example": "1h" }, "source": { "type": "string", "description": "Data or model source identifier.", "example": "Kronos-small" }, "generated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when this forecast was computed." }, "price": { "type": "object", "required": [ "close", "atr" ], "properties": { "close": { "type": "number", "description": "Last close price in USD.", "example": 150 }, "atr": { "type": "number", "description": "ATR(14) in USD.", "example": 3.5 } } }, "indicators": { "type": "object", "description": "Raw indicator values. Present in composite-fallback responses only.", "properties": { "ema20": { "type": "number" }, "ema50": { "type": "number" }, "rsi14": { "type": "number", "minimum": 0, "maximum": 100 }, "macd": { "type": "number" }, "macd_signal": { "type": "number" }, "macd_hist": { "type": "number" }, "atr14": { "type": "number" } } }, "signal": { "type": "object", "description": "Per-indicator votes. Present in composite-fallback responses only.", "properties": { "votes": { "type": "array", "items": { "type": "integer", "enum": [ -1, 0, 1 ] } }, "positives": { "type": "integer" }, "negatives": { "type": "integer" }, "neutral": { "type": "integer" } } }, "forecast": { "type": "object", "required": [ "up_prob", "range_low", "range_high", "confidence" ], "properties": { "up_prob": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.67 }, "range_low": { "type": "number", "example": 144.75 }, "range_high": { "type": "number", "example": 155.25 }, "horizon_bars": { "type": "integer", "example": 20 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.67 }, "mean_path_closes": { "type": "array", "items": { "type": "number" }, "nullable": true }, "expected_close": { "type": "number", "nullable": true, "example": 151.2 }, "pred_high": { "type": "number", "nullable": true, "example": 156 }, "pred_low": { "type": "number", "nullable": true, "example": 144 }, "pred_volatility": { "type": "number", "nullable": true, "example": 0.0233 }, "prob_up": { "type": "number", "minimum": 0, "maximum": 1, "nullable": true, "example": 0.67 }, "quantiles": { "type": "object", "nullable": true, "properties": { "p10": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" }, "p75": { "type": "number" }, "p90": { "type": "number" } } } } }, "risk_state": { "type": "string", "enum": [ "elevated", "normal" ] }, "directional_context": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "positive", "negative", "neutral" ] }, "magnitude": { "type": "number", "minimum": 0, "maximum": 1 }, "magnitude_label": { "type": "string", "enum": [ "strong", "moderate", "weak" ] } } }, "model": { "type": "string", "example": "Kronos-small" }, "inference_seconds": { "type": "number", "nullable": true, "example": 0.19 }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — x402 micropayment instructions. Submit 0.01 USDC on Base mainnet (eip155:8453) using an x402 client, then retry with the X-PAYMENT header.", "headers": { "X-PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded JSON payment requirements." } }, "x-x402": { "scheme": "exact", "price": "$0.01", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.01 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "409": { "description": "Payment nonce already used (replay rejected).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Upstream data unavailable. Binance API unreachable or Kronos ML timed out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "string" } } } } } } }, "x-x402": { "scheme": "exact", "price": "$0.01", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.01 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "solForecastCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/signals/{asset}": { "get": { "operationId": "getSignals", "summary": "Crypto derivatives intelligence for 16 assets (funding rate, OI, basis)", "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) sourced from Bybit/OKX. Raw fields: funding rate (raw 8-hour + heuristic annualised), mark price, index price, basis (perp premium/discount), open interest, 24h volume, next funding time. Derived signals: OI change over ~1 hour window (abs + pct), funding trend (rising/falling/flat vs prior half-window), and a human-readable heuristic read. Data is collected every 5 minutes by a background cron into the market_signals table; responses may lag by up to 5 minutes. Requires an x402 EIP-3009 micropayment of $0.02 USDC.", "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). Supports all 16 assets." } ], "responses": { "200": { "description": "Derivatives signals (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "description": "CORS wildcard header" } }, "content": { "application/json": { "example": { "available": true, "asset": "BTC-USD", "as_of": "2026-06-30T10:00:00.000Z", "data_source": "bybit", "samples": 12, "funding_rate": 0.0001, "funding_rate_annualized": 0.1095, "mark_price": 107510.5, "index_price": 107498.2, "basis": 0.0001144, "open_interest": 84320.15, "volume_24h": 2341089500, "next_funding_time": "2026-06-30T16:00:00.000Z", "oi_change_1h": { "abs": 120.34, "pct": 0.1429 }, "funding_trend": "flat", "read": "Positive funding (10.9% ann.) — longs paying shorts; carry favours short-basis trades. Heuristic only.", "disclaimer": "Heuristic signal derived from Bybit/OKX perpetual swap data. Not financial advice. Data lags by up to 5 minutes (cron cadence). Annualized rates assume the current funding rate persists indefinitely — it does not." }, "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). Reflects when the cron last collected data." }, "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 of data at 5-min cadence).", "example": 12 }, "funding_rate": { "type": "number", "nullable": true, "description": "Raw 8-hour funding rate from the latest row. Positive = longs pay shorts; negative = shorts pay longs. Example: 0.0001 = 0.01% per 8 h.", "example": 0.0001 }, "funding_rate_annualized": { "type": "number", "nullable": true, "description": "Heuristic annualised rate: funding_rate × 3 (settlements/day) × 365. Assumes the current rate persists — it does not. 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 = perpetual trading at a premium to spot (contango).", "example": 0.0001144 }, "open_interest": { "type": "number", "nullable": true, "description": "Open interest in the exchange's native unit (typically BTC or contracts) 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.", "example": "2026-06-30T16:00:00.000Z" }, "oi_change_1h": { "type": "object", "description": "Open interest change over the sample window (~1 h). Computed as latest OI minus oldest OI in the window.", "required": [ "abs", "pct" ], "properties": { "abs": { "type": "number", "nullable": true, "description": "Absolute OI change (same units as open_interest). Positive = OI growing; negative = OI shrinking.", "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 half-window average vs older half-window average with a ±5% relative threshold. 'insufficient_data' when fewer than 4 rows have funding data.", "example": "flat" }, "read": { "type": "string", "description": "Human-readable heuristic interpretation of the current derivatives market state. Not financial advice.", "example": "Positive funding (10.9% ann.) — longs paying shorts; carry favours short-basis trades. Heuristic only." }, "disclaimer": { "type": "string", "description": "Mandatory disclaimer. Heuristic signal only; not financial advice." } } } } } }, "402": { "description": "Payment required — x402 micropayment instructions. Submit 0.02 USDC on Base mainnet (eip155:8453) using an x402 client, then retry with the X-PAYMENT header.", "headers": { "X-PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded JSON payment requirements (amount, asset, network, payTo, scheme)." } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "409": { "description": "Payment nonce already used (replay rejected).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Derivatives data unavailable. No rows in market_signals yet, or Supabase is unreachable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "btcSignalsCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/alerts/btc": { "get": { "operationId": "getBtcAlerts", "summary": "BTC market-state alerts (regime events + live derived state)", "description": "Returns the CURRENT actionable market-state for BTC that an agent can poll: 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, and a short plain-language read). Regime events are detected on a ~15-minute cron; live state may lag by up to 5 minutes. Requires an x402 EIP-3009 micropayment of $0.02 USDC.", "responses": { "200": { "description": "Market-state alerts (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "description": "CORS wildcard header" } }, "content": { "application/json": { "example": { "available": true, "asset": "BTC-USD", "active_alerts": [ { "event_type": "funding_extreme", "severity": "high", "detected_at": "2026-06-30T11:45:00.000Z", "details": { "annualized_pct": 42.1, "sign": "longs_paying", "funding_rate_8h": 0.00096 } } ], "current_state": { "as_of": "2026-06-30T12:00:00.000Z", "funding_rate": 0.0001, "funding_annualized": 0.1095, "open_interest": 84320.15, "read": "BTC: elevated positive funding (10.9% ann.) — longs paying shorts, crowded-long / squeeze risk; 1 active regime alert(s) in the last 2h (funding_extreme). Heuristic only." }, "as_of": "2026-06-30T12:00:05.000Z", "disclaimer": "Heuristic market-state alerts derived from Bybit/OKX perpetual swap data and the Kronos regime engine. Not financial advice." }, "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 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 of the event.", "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 detail payload (e.g. range_ratio for squeeze, pct_move/direction for breakout, annualized_pct/sign for funding_extreme, pct_change/direction for oi_surge)." } } } }, "current_state": { "type": "object", "description": "Live derived state from the latest market_signals row for BTC.", "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). null if no live data is available." }, "funding_rate": { "type": "number", "nullable": true, "description": "Raw 8-hour funding rate from the latest row. Positive = longs pay shorts; negative = shorts pay longs.", "example": 0.0001 }, "funding_annualized": { "type": "number", "nullable": true, "description": "Heuristic annualised rate: funding_rate × 3 × 365. Assumes the current rate persists — it does not.", "example": 0.1095 }, "open_interest": { "type": "number", "nullable": true, "description": "Open interest in the exchange's native unit from the latest row.", "example": 84320.15 }, "read": { "type": "string", "description": "Short plain-language interpretation of the live derivatives state + active alerts. Not financial advice." } } }, "as_of": { "type": "string", "format": "date-time", "description": "UTC timestamp when this response was generated." }, "disclaimer": { "type": "string", "description": "Mandatory disclaimer. Heuristic alerts only; not financial advice." } } } } } }, "402": { "description": "Payment required — x402 micropayment instructions. Submit 0.02 USDC on Base mainnet (eip155:8453) using an x402 client, then retry with the X-PAYMENT header.", "headers": { "X-PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded JSON payment requirements (amount, asset, network, payTo, scheme)." } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "409": { "description": "Payment nonce already used (replay rejected).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Alerts data unavailable. Supabase is unreachable or a DB query failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "btcAlertsCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/price/{asset}": { "get": { "operationId": "getSpotPrice", "summary": "Real-time crypto spot price (16 assets) — $0.001/call", "description": "Returns the current spot price for any of the 16 supported assets from the Binance public API. Cheapest tool in the suite — $0.001 USDC per call. Supports BTC/ETH/SOL/BNB/XRP/DOGE/ADA/AVAX/LINK/DOT/LTC/TRX/BCH/ATOM/NEAR/APT. Requires an x402 EIP-3009 micropayment of $0.001 USDC.", "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 16 assets supported." } ], "responses": { "200": { "description": "Spot price returned (payment verified)", "content": { "application/json": { "example": { "asset": "BTC-USD", "price": 107500, "source": "Binance", "as_of": "2026-07-02T10:00:00.000Z", "disclaimer": "Real-time spot price from Binance public API. Informational only, not financial advice." }, "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 — 0.001 USDC via x402.", "x-payment-info": { "scheme": "exact", "price": "$0.001", "currency": "USDC" } }, "409": { "description": "Payment nonce already used." } }, "x-x402": { "scheme": "exact", "price": "$0.001", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.001 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "spotPriceCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/snapshot/{asset}": { "get": { "operationId": "getSnapshot", "summary": "Full crypto asset snapshot bundle (16 assets) — $0.04/call", "description": "Returns everything for the asset in one call: spot price, derivatives (funding rate, OI, basis, trend), market regime alerts (BTC only), the Kronos ML forecast for the 1h horizon (BTC/ETH/SOL only), options IV summary from Deribit (BTC/ETH only; available:false otherwise), liquidation squeeze_bias derived from funding rate + OI split, and Coinbase CEX premium (Coinbase-listed assets only; available:false otherwise). Supports all 16 assets (BTC/ETH/SOL/BNB/XRP/DOGE/ADA/AVAX/LINK/DOT/LTC/TRX/BCH/ATOM/NEAR/APT). Cheaper than buying each tool separately. Requires an x402 EIP-3009 micropayment of $0.04 USDC.", "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 16 assets supported." } ], "responses": { "200": { "description": "Full snapshot returned (payment verified)", "content": { "application/json": { "example": { "asset": "BTC-USD", "price": 107500, "derivatives": { "available": true, "funding_rate": 0.0001, "funding_rate_annualized": 0.1095, "open_interest": 84320.15, "basis": 0.000186, "funding_trend": "flat", "read": "Positive funding (10.9% ann.) — longs paying shorts. Heuristic only." }, "regime": { "available": true, "active_alerts": [], "current_state": { "funding_rate": 0.0001, "open_interest": 84320.15, "read": "BTC: neutral funding; no regime alerts in the last 2h. Heuristic only." } }, "forecast": { "available": true, "horizon": "1h", "up_prob": 0.62, "expected_close": 107620.5, "range_low": 106300, "range_high": 108700, "model": "kronos-base-60path-t1-v2", "cached": true, "cache_age_seconds": 180 }, "options_iv": { "available": true, "atm_iv": 52.4, "term_structure_shape": "contango", "data_source": "deribit", "as_of": "2026-07-02T10:00:00.000Z" }, "liquidations": { "available": true, "squeeze_bias": "long_squeeze_risk" }, "cex_premium": { "available": true, "coinbase_price": 107512.34, "composite_median": 107498, "premium_pct": 0.0133, "interpretation": "Coinbase +0.013% premium vs composite. Mild US/institutional demand bias.", "as_of": "2026-07-02T10:00:00.000Z" }, "as_of": "2026-07-02T10:00:00.000Z", "disclaimer": "Spot price from Binance. Derivatives from Bybit/OKX perp data. Options IV from Deribit (BTC/ETH only). Squeeze bias estimated from funding+OI. CEX premium Coinbase-listed assets only. Not financial advice." }, "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", "properties": { "available": { "type": "boolean" }, "funding_rate": { "type": "number", "nullable": true }, "funding_rate_annualized": { "type": "number", "nullable": true }, "open_interest": { "type": "number", "nullable": true }, "basis": { "type": "number", "nullable": true }, "funding_trend": { "type": "string" }, "read": { "type": "string" } } }, "regime": { "type": "object", "properties": { "available": { "type": "boolean" }, "active_alerts": { "type": "array", "items": { "type": "object" } }, "current_state": { "type": "object" } } }, "forecast": { "type": "object", "properties": { "available": { "type": "boolean" }, "horizon": { "type": "string" }, "up_prob": { "type": "number", "nullable": true }, "expected_close": { "type": "number", "nullable": true }, "range_low": { "type": "number", "nullable": true }, "range_high": { "type": "number", "nullable": true }, "model": { "type": "string", "nullable": true }, "cached": { "type": "boolean" }, "cache_age_seconds": { "type": "number", "nullable": true }, "generated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "options_iv": { "type": "object", "description": "ATM IV summary from Deribit. available:false for non-BTC/ETH assets.", "properties": { "available": { "type": "boolean" }, "atm_iv": { "type": "number", "nullable": true }, "term_structure_shape": { "type": "string", "enum": [ "contango", "backwardation", "flat", "insufficient_data" ] }, "data_source": { "type": "string", "nullable": true }, "reason": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" } } }, "liquidations": { "type": "object", "description": "Squeeze bias derived from funding rate + OI split. No external fetch.", "properties": { "available": { "type": "boolean" }, "squeeze_bias": { "type": "string", "enum": [ "long_squeeze_risk", "short_squeeze_risk", "balanced" ], "nullable": true }, "reason": { "type": "string" } } }, "cex_premium": { "type": "object", "description": "Coinbase price premium vs Binance+OKX composite. available:false for non-Coinbase-listed assets.", "properties": { "available": { "type": "boolean" }, "coinbase_price": { "type": "number", "nullable": true }, "composite_median": { "type": "number", "nullable": true }, "premium_pct": { "type": "number", "nullable": true }, "interpretation": { "type": "string" }, "reason": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" } } }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — 0.04 USDC via x402.", "x-payment-info": { "scheme": "exact", "price": "$0.04", "currency": "USDC" } }, "409": { "description": "Payment nonce already used." } }, "x-x402": { "scheme": "exact", "price": "$0.04", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.04 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "snapshotCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/funding-extremes": { "get": { "operationId": "getFundingExtremes", "summary": "Funding-rate extremes screener — all 16 assets ranked by |funding rate|", "description": "Scans all 16 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 (Bybit data). $0.02 USDC via x402.", "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 }, "captured_at": { "type": "string", "format": "date-time" } } } }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — 0.02 USDC via x402.", "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453" } }, "409": { "description": "Payment nonce already used." }, "503": { "description": "Supabase unavailable or no data." } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.02 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "fundingExtremesCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/overview": { "get": { "operationId": "getOverview", "summary": "Market-wide derivatives snapshot for all 16 assets", "description": "Returns funding rate, open interest, mark price, and 24h volume for all 16 perpetual futures markets in one call. One call replaces 16 separate signals calls. Real-time from Kronos market_signals. $0.02 USDC via x402.", "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", "description": "How many assets had live data." }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — 0.02 USDC via x402.", "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453" } }, "409": { "description": "Payment nonce already used." }, "503": { "description": "Supabase unavailable." } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.02 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "overviewCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/fear-greed": { "get": { "operationId": "getFearGreed", "summary": "Crypto Fear & Greed Index from alternative.me — $0.001/call", "description": "Returns the current Crypto Fear & Greed Index: score (0-100) and classification (Extreme Fear/Fear/Neutral/Greed/Extreme Greed) from alternative.me. Essential for contrarian signals and market sentiment analysis. $0.001 USDC via x402.", "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", "description": "Unix timestamp string from alternative.me." }, "source": { "type": "string", "example": "alternative.me" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — 0.001 USDC via x402.", "x-x402": { "scheme": "exact", "price": "$0.001", "currency": "USDC", "network": "eip155:8453" } }, "409": { "description": "Payment nonce already used." }, "503": { "description": "alternative.me upstream unavailable." } }, "x-x402": { "scheme": "exact", "price": "$0.001", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.001 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "fearGreedCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/ohlc/{asset}": { "get": { "operationId": "getOhlc", "summary": "OHLC candlestick data for 16 assets from Binance — $0.001/call", "description": "Returns OHLC candlestick data for any of the 16 supported assets from Binance. Supports ?interval=1h|4h|1d and ?limit=1-100 (default 24 candles). For technical analysis, backtesting, and AI agent decision-making. $0.001 USDC 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)." }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1h", "4h", "1d" ], "default": "1h" }, "description": "Candle interval. Default: 1h." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 }, "description": "Number of candles to return (1-100). Default: 24." } ], "responses": { "200": { "description": "OHLC candles returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "symbol", "interval", "candles", "count", "source", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "symbol": { "type": "string", "example": "BTCUSDT" }, "interval": { "type": "string", "enum": [ "1h", "4h", "1d" ] }, "candles": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "integer", "description": "Open time (Unix ms)." }, "o": { "type": "number", "description": "Open price." }, "h": { "type": "number", "description": "High price." }, "l": { "type": "number", "description": "Low price." }, "c": { "type": "number", "description": "Close price." }, "v": { "type": "number", "description": "Volume (base asset)." } } } }, "count": { "type": "integer" }, "gap_flags": { "type": "array", "description": "Gaps where abs(open vs prior close) exceeds 1%. Empty array = no gaps detected.", "items": { "type": "object", "properties": { "candle_index": { "type": "integer", "description": "Index within the returned candles array." }, "gap_pct": { "type": "number", "description": "Gap size in percent (signed, e.g. +1.5 = gap-up)." }, "t": { "type": "integer", "description": "Open time of the gapping candle (Unix ms)." } } } }, "baseline_insufficient": { "type": "boolean", "description": "true when fewer than 20 candles returned — rolling baseline cannot be established." }, "volume_anomaly": { "type": "object", "description": "Volume anomaly detection vs rolling mean of prior candles' USD volume.", "properties": { "detected": { "type": "boolean", "description": "true when last candle volume exceeds 3× rolling mean." }, "ratio": { "type": "number", "nullable": true, "description": "Last candle USD volume / rolling mean. null when baseline_insufficient." } } }, "source": { "type": "string", "example": "multi_exchange" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — 0.001 USDC via x402.", "x-x402": { "scheme": "exact", "price": "$0.001", "currency": "USDC", "network": "eip155:8453" } }, "409": { "description": "Payment nonce already used." }, "503": { "description": "Binance API unavailable." } }, "x-x402": { "scheme": "exact", "price": "$0.001", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.001 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "ohlcCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/volatility/{asset}": { "get": { "operationId": "getVolatility", "summary": "Realized volatility for 16 assets (7d/30d annualized) — $0.01/call", "description": "Computes 7-day and 30-day annualized realized volatility from Binance daily OHLC. Based on log returns of daily close prices, annualized by sqrt(365). Supports all 16 assets. Essential for risk management and position sizing. $0.01 USDC 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": "Realized volatility returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "symbol", "vol_7d_annualized", "vol_30d_annualized", "source", "as_of", "disclaimer" ], "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "symbol": { "type": "string", "example": "BTCUSDT" }, "vol_7d_annualized": { "type": "number", "nullable": true, "description": "7-day annualized realized vol (e.g. 0.62 = 62%)." }, "vol_30d_annualized": { "type": "number", "nullable": true, "description": "30-day annualized realized vol." }, "log_returns_count_7d": { "type": "integer", "description": "Number of log returns used for 7d vol." }, "log_returns_count_30d": { "type": "integer", "description": "Number of log returns used for 30d vol." }, "source": { "type": "string", "example": "Binance daily klines" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — 0.01 USDC via x402.", "x-x402": { "scheme": "exact", "price": "$0.01", "currency": "USDC", "network": "eip155:8453" } }, "409": { "description": "Payment nonce already used." }, "503": { "description": "Binance API unavailable." } }, "x-x402": { "scheme": "exact", "price": "$0.01", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.01 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "volatilityCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/methodology": { "get": { "operationId": "getMethodology", "summary": "Track-record methodology (public, no payment required)", "description": "Documents how Kronos forecasts are scored and returns the CURRENT live accuracy figures pulled directly from the database. Explains what is measured (directional hit-rate of cache-served forecasts), how outcomes are scored (evaluate cron vs realized Binance candle), and the honest caveats (thin sample, one-regime data, not financial advice). Links to /api/stats for full statistics.", "responses": { "200": { "description": "Track-record methodology and live accuracy", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "what_is_measured": { "type": "object" }, "how_scored": { "type": "object" }, "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" }, "generated_at": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } } } } }, "/api/stats": { "get": { "operationId": "getStats", "summary": "Aggregate service stats (public, no payment required)", "description": "Returns aggregate service statistics: total API requests, paid calls, USD earned, unique payer addresses, forecasts served, and outcome accuracy metrics scored from historical forecasts.", "responses": { "200": { "description": "Aggregate stats", "content": { "application/json": { "example": { "total_requests": 1024, "total_paid_calls": 847, "total_usd_earned": 0.847, "unique_payers": 31, "forecasts_served": 620, "accuracy": { "scored": 200, "hit_rate": 0.61, "in_range_rate": 0.74, "note": "Illustrative example only — not live accuracy. Call GET /api/stats for current figures computed from the database." }, "service": { "name": "Kronos x402 API", "asset": "BTC-USD, ETH-USD, SOL-USD", "price_usd": { "forecast": 0.01, "signals": 0.02 }, "network": "eip155:84532", "payTo": null }, "generated_at": "2026-06-30T10:00:00.000Z" }, "schema": { "type": "object", "properties": { "total_requests": { "type": "integer", "description": "Total HTTP requests received (paid + unpaid + 402s)." }, "total_paid_calls": { "type": "integer", "description": "Total x402 payments verified and forecasts returned." }, "total_usd_earned": { "type": "number", "description": "Total USD value of USDC micropayments received." }, "unique_payers": { "type": "integer", "description": "Distinct payer wallet addresses." }, "forecasts_served": { "type": "integer", "description": "Total forecast responses delivered." }, "accuracy": { "type": "object", "description": "Outcome accuracy from scored historical forecasts.", "properties": { "scored": { "type": "integer", "description": "Number of forecasts that have been scored." }, "hit_rate": { "type": "number", "nullable": true, "description": "Fraction of forecasts where the direction was correct (up_prob > 0.5 and price rose, or up_prob < 0.5 and price fell)." }, "in_range_rate": { "type": "number", "nullable": true, "description": "Fraction of forecasts where the actual close fell within the [range_low, range_high] band." }, "note": { "type": "string", "description": "Human-readable explanation of the accuracy metrics." } } }, "service": { "type": "object", "description": "Static service metadata.", "properties": { "name": { "type": "string" }, "asset": { "type": "string", "description": "Comma-separated list of supported assets." }, "price_usd": { "type": "number", "description": "Cost per paid API call in USD." }, "network": { "type": "string", "description": "EIP-155 chain identifier for payments." }, "payTo": { "type": "string", "nullable": true, "description": "Payment recipient address (null if not configured)." } } }, "generated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp of this stats snapshot." } } } } } } } } }, "/api/health": { "get": { "operationId": "healthCheck", "summary": "Health check (public, no payment required)", "description": "Lightweight liveness check. Returns {ok: true} when the service is up. Suitable for uptime monitors and agent pre-flight checks.", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "example": { "ok": true, "ts": "2026-06-30T10:00:00.000Z" }, "schema": { "type": "object", "required": [ "ok", "ts" ], "properties": { "ok": { "type": "boolean", "description": "Always true on a 200 response.", "example": true }, "ts": { "type": "string", "format": "date-time", "description": "Server UTC timestamp at response time." } } } } } } } } }, "/.well-known/x402": { "get": { "operationId": "x402WellKnown", "summary": "x402 discovery manifest (public)", "description": "Machine-readable x402 directory manifest. Lists all pay-gated endpoints with their price, currency, network, and payment scheme. Consumed by x402 client libraries and autonomous agent directories to discover payment requirements without triggering a 402.", "responses": { "200": { "description": "x402 manifest", "content": { "application/json": { "schema": { "type": "object", "description": "Map of path → payment requirements.", "additionalProperties": { "type": "object", "properties": { "price": { "type": "string", "example": "$0.01" }, "currency": { "type": "string", "example": "USDC" }, "network": { "type": "string", "example": "eip155:84532" }, "scheme": { "type": "string", "example": "exact" } } } } } } } } } }, "/api/v1/alerts/{asset}": { "get": { "operationId": "getAlertsAsset", "summary": "Market-regime alerts for any of the 16 supported crypto assets — $0.02/call", "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. Note: /api/v1/alerts/btc is a dedicated static route; this dynamic route handles all 16 assets. Requires an x402 EIP-3009 micropayment of $0.02 USDC.", "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 16 assets supported." } ], "responses": { "200": { "description": "Market-state alerts (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "description": "CORS wildcard header" } }, "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.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "supported": { "type": "array", "items": { "type": "string" } } } } } } }, "402": { "description": "Payment required — x402 micropayment instructions.", "headers": { "X-PAYMENT-REQUIRED": { "schema": { "type": "string" } } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "409": { "description": "Payment nonce already used (replay rejected).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Alerts data unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "alertsAssetCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/scan": { "get": { "operationId": "getScan", "summary": "Market-wide scan across all 16 assets — $0.04/call", "description": "Returns a market-wide scan across all 16 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), mark price, and regime event count in the last 2h. Optional ?assets=btc,eth,sol to scan a subset. Assets without data are flagged with available:false — never fabricated. Requires an x402 EIP-3009 micropayment of $0.04 USDC.", "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 16." } ], "responses": { "200": { "description": "Market scan returned (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" } }, "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 the 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", "description": "|funding_rate| > 0.001 threshold." }, "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 } } }, "unavailable_reason": { "type": "string", "description": "Only present when available:false." } } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Unknown slugs ignored from ?assets filter." }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — 0.04 USDC via x402.", "x-x402": { "scheme": "exact", "price": "$0.04", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.04 USDC on Base mainnet (eip155:8453) via x402." } }, "409": { "description": "Payment nonce already used." } }, "x-x402": { "scheme": "exact", "price": "$0.04", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.04 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "scanCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/macro": { "get": { "operationId": "getMacro", "summary": "TradFi macro context (VIX, DXY, US 10Y, SPX, gold) — $0.001/call", "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 with 15-minute caching. All fields null if sources are unreachable — never fabricated. BTC-SPX and BTC-DXY 30-day Pearson correlations are computed from daily returns (Binance + stooq historical) and returned when source data is available; null with btc_spx_correlation_available:false on upstream failure — never fabricated. Requires an x402 EIP-3009 micropayment of $0.001 USDC.", "responses": { "200": { "description": "Macro context returned (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" } }, "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", "description": "true if served from 15-min in-memory cache." }, "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 fewer than 10 aligned trading days or source fetch failed. Dropped entirely when BTC price history is unavailable." }, "btc_spx_correlation_available": { "type": "boolean", "description": "true when btc_spx_correlation was successfully computed. Present only when SPX history was fetchable." }, "btc_dxy_correlation": { "type": "number", "nullable": true, "description": "Pearson correlation of 30d daily returns (BTC vs DXY). Null when fewer than 10 aligned trading days or source fetch failed. Dropped entirely when BTC price history is unavailable." }, "btc_dxy_correlation_available": { "type": "boolean", "description": "true when btc_dxy_correlation was successfully computed. Present only when DXY history was fetchable." }, "correlation_note": { "type": "string", "description": "Present only when correlation fields are omitted due to upstream fetch failure. Explains why." }, "sources_status": { "type": "string", "description": "Present only when all sources are unreachable." }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — 0.001 USDC via x402.", "x-x402": { "scheme": "exact", "price": "$0.001", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.001 USDC on Base mainnet (eip155:8453) via x402." } }, "409": { "description": "Payment nonce already used." } }, "x-x402": { "scheme": "exact", "price": "$0.001", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.001 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "macroCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/forecast-ledger": { "get": { "operationId": "getForecastLedger", "summary": "Paginated resolved-forecast ledger — $0.001/call", "description": "Returns a paginated list of resolved forecasts (outcomes joined with forecasts). Each row shows the original prediction and actual outcome. Summary includes total, hit_rate (cache-source rows, matching /api/stats methodology), and a sample note. Requires an x402 EIP-3009 micropayment of $0.001 USDC.", "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 — 0.001 USDC via x402.", "x-x402": { "scheme": "exact", "price": "$0.001", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.001 USDC on Base mainnet (eip155:8453) via x402." } }, "409": { "description": "Payment nonce already used." } }, "x-x402": { "scheme": "exact", "price": "$0.001", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.001 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "forecastLedgerCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/digest/{asset}": { "get": { "operationId": "getDigest", "summary": "Structured market digest — deterministic bundle from live signals — $0.02/call", "description": "Returns a deterministic structured market digest for any of the 16 supported assets. Composes funding rate, basis, market regime, 30d realized volatility, Fear & Greed index, VIX macro context, and ML forecast probability (BTC/ETH/SOL only) into a single JSON bundle. Includes a templated thesis string and per-driver interpretations. No LLM involved — all logic is deterministic from live market data. The 'start here' endpoint for autonomous agents needing a full market snapshot. $0.02 USDC 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). All 16 Kronos assets supported." } ], "responses": { "200": { "description": "Market digest returned (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" } }, "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 signal: 'breakout', 'squeeze', 'funding_extreme', 'oi_surge', 'none', or 'insufficient_data' when <6 market_signals rows.", "example": "breakout" }, "thesis": { "type": "string", "description": "Deterministic summary string templated from live driver values. No LLM.", "example": "BTC shows positive funding (0.0100%); positive basis (0.0150%); breakout regime; 30d vol 45.2% (normal); fear-greed 72 (Greed); model assigns 64% upside probability over 24h horizon." }, "confidence": { "type": "number", "nullable": true, "description": "Forecast confidence from Kronos model. Null for watch assets (non BTC/ETH/SOL)." }, "up_prob_calibrated": { "type": "number", "nullable": true, "description": "Calibrated upside probability from Kronos ML model. Null for watch assets." }, "drivers": { "type": "array", "description": "Per-signal driver objects with value and human-readable interpretation.", "items": { "type": "object", "required": [ "name", "value", "interpretation" ], "properties": { "name": { "type": "string", "example": "funding_rate" }, "value": { "description": "Raw signal value (number, string, or null)." }, "interpretation": { "type": "string", "description": "Human-readable interpretation of this driver." } } } }, "caveats": { "type": "array", "items": { "type": "string" }, "description": "Honesty flags: unavailable sources, data limitations, non-financial-advice notice." }, "forecast_ref": { "type": "string", "nullable": true, "description": "Path to the full forecast endpoint for this asset. Null for watch assets.", "example": "/api/v1/forecast/btc" }, "disclaimer": { "type": "string" } } } } } }, "402": { "description": "Payment required — 0.02 USDC via x402.", "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.02 USDC on Base mainnet (eip155:8453) via x402." } }, "409": { "description": "Payment nonce already used." } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "Send 0.02 USDC on Base mainnet (eip155:8453) via x402." } }, "options": { "operationId": "digestCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/liquidations/{asset}": { "get": { "operationId": "getLiquidations", "summary": "Forward liquidation cluster map + recent prints (16 assets) — $0.02/call", "description": "Returns two things for any of the 16 supported assets: (1) A forward liquidation cluster map — estimated liq price levels for 5x/10x/25x/50x leverage bands, modeled from open interest and mark price (no new upstream source; reuses Bybit/OKX data already collected by the 5-min collect cron). Includes nearest long/short liq clusters (price + distance %) and squeeze_bias (long_squeeze_risk / short_squeeze_risk / balanced). (2) Recent liquidation prints from the OKX public API (no auth required), if reachable. If OKX is unreachable, recent_prints.available=false — never fabricated. Requires an x402 EIP-3009 micropayment of $0.02 USDC.", "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 16 assets supported." } ], "responses": { "200": { "description": "Liquidation cluster map returned (payment verified)", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64-encoded x402 settlement receipt" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "description": "CORS wildcard header" } }, "content": { "application/json": { "example": { "available": true, "asset": "BTC-USD", "as_of": "2026-07-02T10:00:00.000Z", "mark_price": 107500, "open_interest": 84320.15, "funding_rate": 0.0001, "cluster_map": { "disclaimer": "ESTIMATED clusters from OI + leverage-band modeling. NOT confirmed orders.", "model_note": "OI distributed: 5x=35%, 10x=30%, 25x=25%, 50x=10%. Long/short split adjusted by funding rate. Maint margin 0.5%.", "long_clusters": [ { "leverage": 50, "liq_price": 106425, "distance_pct": -0.98, "estimated_oi_fraction": 0.051 }, { "leverage": 25, "liq_price": 103375, "distance_pct": -3.84, "estimated_oi_fraction": 0.1275 }, { "leverage": 10, "liq_price": 97375, "distance_pct": -9.42, "estimated_oi_fraction": 0.153 }, { "leverage": 5, "liq_price": 86375, "distance_pct": -19.65, "estimated_oi_fraction": 0.1785 } ], "short_clusters": [ { "leverage": 50, "liq_price": 108575, "distance_pct": 1, "estimated_oi_fraction": 0.049 }, { "leverage": 25, "liq_price": 111625, "distance_pct": 3.84, "estimated_oi_fraction": 0.1225 }, { "leverage": 10, "liq_price": 117625, "distance_pct": 9.42, "estimated_oi_fraction": 0.147 }, { "leverage": 5, "liq_price": 128625, "distance_pct": 19.65, "estimated_oi_fraction": 0.1715 } ], "nearest_long_liq_cluster": { "liq_price": 106425, "distance_pct": -0.98 }, "nearest_short_liq_cluster": { "liq_price": 108575, "distance_pct": 1 }, "squeeze_bias": "long_squeeze_risk", "total_long_oi_estimate": 44571, "total_short_oi_estimate": 39749.15 }, "recent_prints": { "available": true, "source": "okx-public", "count": 5, "prints": [ { "side": "buy", "pos_side": "short", "size": 10.1, "price": 107600.5, "time": "2026-07-02T09:45:00.000Z" } ], "note": "side:buy = short position liquidated; side:sell = long position liquidated." }, "disclaimer": "Cluster map is estimated from OI and leverage-band modeling — NOT a live order book. Not financial advice." }, "schema": { "type": "object", "required": [ "available", "asset", "as_of", "mark_price", "open_interest", "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 price levels where leveraged positions would be liquidated. Based on OI + leverage-band modeling.", "required": [ "disclaimer", "model_note", "long_clusters", "short_clusters", "nearest_long_liq_cluster", "nearest_short_liq_cluster", "squeeze_bias" ], "properties": { "disclaimer": { "type": "string" }, "model_note": { "type": "string" }, "long_clusters": { "type": "array", "description": "Estimated long liquidation levels below current price (nearest first).", "items": { "type": "object", "properties": { "leverage": { "type": "integer", "description": "Leverage band (5, 10, 25, or 50)." }, "liq_price": { "type": "number", "description": "Estimated liquidation price (USD)." }, "distance_pct": { "type": "number", "description": "Distance from mark price (%, negative = below)." }, "estimated_oi_fraction": { "type": "number", "description": "Estimated fraction of total OI at this level." } } } }, "short_clusters": { "type": "array", "description": "Estimated short liquidation levels above current price (nearest first).", "items": { "type": "object", "properties": { "leverage": { "type": "integer" }, "liq_price": { "type": "number" }, "distance_pct": { "type": "number", "description": "Distance from mark price (%, positive = above)." }, "estimated_oi_fraction": { "type": "number" } } } }, "nearest_long_liq_cluster": { "type": "object", "nullable": true, "description": "Nearest long liquidation cluster (50x leverage band).", "properties": { "liq_price": { "type": "number" }, "distance_pct": { "type": "number" } } }, "nearest_short_liq_cluster": { "type": "object", "nullable": true, "description": "Nearest short liquidation cluster (50x leverage band).", "properties": { "liq_price": { "type": "number" }, "distance_pct": { "type": "number" } } }, "squeeze_bias": { "type": "string", "enum": [ "long_squeeze_risk", "short_squeeze_risk", "balanced" ], "description": "Which side has more estimated nearby liquidation exposure. 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", "description": "Estimated total long OI in exchange-native units (same as open_interest)." }, "total_short_oi_estimate": { "type": "number", "description": "Estimated total short OI in exchange-native units." } } }, "recent_prints": { "type": "object", "description": "Recent liquidation prints from OKX public API (best-effort). 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" ], "description": "Trade side: buy = short was liquidated; sell = long was liquidated." }, "pos_side": { "type": "string", "enum": [ "long", "short" ], "description": "The position side that was liquidated." }, "size": { "type": "number", "description": "Position size in contracts." }, "price": { "type": "number", "description": "OKX bankruptcy price (bkPx) at time of liquidation." }, "time": { "type": "string", "format": "date-time" } } } }, "note": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true, "description": "Why recent_prints is unavailable (when available=false)." } } }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Unsupported asset slug.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "supported": { "type": "array", "items": { "type": "string" } } } } } } }, "402": { "description": "Payment required — x402 micropayment instructions. Submit 0.02 USDC on Base mainnet (eip155:8453) using an x402 client, then retry with the X-PAYMENT header.", "headers": { "X-PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded JSON payment requirements." } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "409": { "description": "Payment nonce already used (replay rejected).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Derivatives data unavailable (market_signals not populated or Supabase unreachable).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } } } } } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "liquidationsCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/options-iv/{asset}": { "get": { "operationId": "getOptionsIv", "summary": "Implied volatility surface for BTC/ETH (Deribit) — $0.03/call", "description": "Returns the implied volatility surface for BTC or ETH from Deribit public options data (no auth required). Fields: ATM IV (annualized %), IV rank and IV percentile (from Kronos iv_history table, daily cron, null + iv_history_status:'accumulating' until ≥20 days), term structure (weekly/1m/3m ATM IV) with contango/backwardation/flat shape label, 25-delta risk reversal (put IV − call IV at BS-approximated 25-delta strikes), 10-delta wing IVs (wing_10d_call_iv / wing_10d_put_iv), max-pain strike across top-5 nearest expiries, and a vol-regime label (compression/normal/event-risk/expansion). Falls back to OKX options if Deribit is unreachable. Returns available:false (never fabricated) if both fail. 1-hour in-memory cache. $0.03 USDC via x402. BTC and ETH only.", "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth" ] }, "description": "Asset slug (lowercase). Only btc and eth supported." } ], "responses": { "200": { "description": "Options IV surface returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "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" ] }, "atm_iv": { "type": "number", "nullable": true, "description": "OI-weighted ATM IV, annualized %.", "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.", "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 or accumulating status." }, "iv_history_days": { "type": "integer", "nullable": true, "description": "Days of ATM IV history in iv_history table (trailing 1y).", "example": 45 }, "term_structure": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "enum": [ "weekly", "1m", "3m" ] }, "expiry": { "type": "string" }, "days_to_expiry": { "type": "integer" }, "atm_iv": { "type": "number", "nullable": true } } } }, "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 = front IV > back (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. Positive = put premium." }, "wing_10d_call_iv": { "type": "number", "nullable": true, "description": "IV at nearest call to BS-approximated 10-delta strike (front expiry).", "example": 38.5 }, "wing_10d_put_iv": { "type": "number", "nullable": true, "description": "IV at nearest put to BS-approximated 10-delta strike (front expiry).", "example": 49.2 }, "skew_note": { "type": "string" }, "max_pain_strike": { "type": "number", "nullable": true }, "vol_regime": { "type": "string", "enum": [ "compression", "normal", "event-risk", "expansion" ] }, "vol_regime_note": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Unsupported asset (only btc and eth)." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "503": { "description": "Both Deribit and OKX options APIs unreachable." } }, "x-x402": { "scheme": "exact", "price": "$0.03", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.03 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "optionsIvCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/gex/{asset}": { "get": { "operationId": "getGex", "summary": "Gamma Exposure (GEX) + max-pain options tool for BTC/ETH (Deribit) — $0.04/call", "description": "Returns dealer-convention Gamma Exposure (GEX) for BTC or ETH from Deribit public options data. Gamma is computed analytically from Black-Scholes (mark_iv + DTE, r=0). Fields: aggregate GEX strike ladder (netGex/callGex/putGex per strike, USD per 1% spot move), total net GEX, gamma flip level (strike where cumulative GEX crosses zero), spot regime (above_flip = vol-dampening; below_flip = vol-amplifying), max-pain strike for next ~3 weekly expiries + nearest monthly, expected-move cone (ATM-IV-derived ±1σ for front expiry), and a heuristic pin_risk score [0-1] per expiry. Dealer convention: assumed long calls / short puts. Returns available:false (never fabricated) if Deribit is unreachable. 15-minute in-memory cache. $0.04 USDC via x402. BTC and ETH only.", "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "btc", "eth" ] }, "description": "Asset slug (lowercase). Only btc and eth supported (Deribit's most liquid option markets)." } ], "responses": { "200": { "description": "GEX data returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "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" ] }, "dealer_convention": { "type": "string", "description": "Convention used for dealer gamma sign (long calls / short puts)." }, "gex_units": { "type": "string", "description": "Unit description: USD per 1% spot move per strike." }, "gex_ladder": { "type": "array", "description": "Per-strike GEX breakdown sorted by strike ascending.", "items": { "type": "object", "properties": { "strike": { "type": "number" }, "netGex": { "type": "number", "description": "Net dealer GEX at this strike (call + put contributions), USD per 1% spot move." }, "callGex": { "type": "number", "description": "Call GEX contribution (positive)." }, "putGex": { "type": "number", "description": "Put GEX contribution (negative)." } } } }, "gex_total": { "type": "number", "nullable": true, "description": "Sum of netGex across all strikes." }, "gamma_flip_level": { "type": "number", "nullable": true, "description": "Strike where cumulative GEX crosses zero (interpolated). null if no flip exists in the chain." }, "spot_regime": { "type": "string", "nullable": true, "enum": [ "above_flip", "below_flip", "at_flip" ], "description": "above_flip = dealers net long gamma (vol-dampening); below_flip = dealers net short gamma (vol-amplifying)." }, "spot_regime_note": { "type": "string" }, "max_pain": { "type": "array", "description": "Max-pain strike per selected expiry (next ~3 weekly + nearest monthly).", "items": { "type": "object", "properties": { "expiry": { "type": "string" }, "dte": { "type": "number" }, "max_pain_strike": { "type": "number", "nullable": true }, "label": { "type": "string", "enum": [ "weekly", "monthly", "quarterly" ] } } } }, "expected_move": { "nullable": true, "type": "object", "description": "ATM-IV-derived ±1σ expected move for the front expiry.", "properties": { "expiry": { "type": "string" }, "dte": { "type": "number" }, "atm_iv": { "type": "number", "nullable": true, "description": "OI-weighted ATM IV, annualized %." }, "atm_iv_note": { "type": "string" }, "spot": { "type": "number" }, "upper": { "type": "number", "nullable": true, "description": "spot + 1σ." }, "lower": { "type": "number", "nullable": true, "description": "spot − 1σ." } } }, "pin_risk": { "type": "array", "description": "Heuristic pin risk [0-1] per expiry. NOT a probabilistic forecast.", "items": { "type": "object", "properties": { "expiry": { "type": "string" }, "dte": { "type": "number" }, "max_pain_strike": { "type": "number", "nullable": true }, "spot_distance_pct": { "type": "number", "nullable": true }, "gamma_concentration": { "type": "number", "nullable": true }, "pin_risk_score": { "type": "number", "nullable": true }, "note": { "type": "string" } } } }, "as_of": { "type": "string", "format": "date-time" }, "disclaimers": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Unsupported asset (only btc and eth)." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "503": { "description": "Deribit options API unreachable." } }, "x-x402": { "scheme": "exact", "price": "$0.04", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.04 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "gexCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/funding-arb/{asset}": { "get": { "operationId": "getFundingArb", "summary": "Cross-venue funding arbitrage signal — 6 exchanges, net-of-fees — $0.02/call", "description": "Fetches real-time 8h-equivalent funding rates from 6 perpetual swap exchanges (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). Returns honest nulls when a venue fails — never fabricated. All 16 assets. $0.02 USDC 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). All 16 assets supported." } ], "responses": { "200": { "description": "Funding arbitrage signal returned (payment verified)", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "example": "BTC-USD" }, "short": { "type": "string", "example": "BTC" }, "as_of": { "type": "string", "format": "date-time" }, "best_short_venue": { "type": "string", "nullable": true }, "best_long_venue": { "type": "string", "nullable": true }, "best_short_rate8h": { "type": "number", "nullable": true }, "best_long_rate8h": { "type": "number", "nullable": true }, "gross_spread_bps": { "type": "number", "nullable": true }, "net_spread_bps": { "type": "number", "nullable": true }, "annualized_pct": { "type": "number", "nullable": true }, "actionability": { "type": "string", "enum": [ "not_actionable", "marginal", "actionable", "insufficient_data" ] }, "round_trip_fee_bps": { "type": "number", "example": 20 }, "methodology": { "type": "string" }, "caveats": { "type": "array", "items": { "type": "string" } }, "per_venue": { "type": "object", "description": "Per-venue rate8h and OI. Null = venue failed or asset not listed." }, "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." } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "fundingArbCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } }, "/api/v1/cex-premium/{asset}": { "get": { "operationId": "getCexPremium", "summary": "Coinbase cross-exchange price premium vs global composite — $0.02/call", "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. Covers assets listed on Coinbase (BTC/ETH/SOL/XRP/DOGE/ADA/AVAX/LINK/DOT/LTC/BCH/ATOM/NEAR). Assets not listed on Coinbase return available:false. Includes 30d z-score and 24h percentile from Kronos cex_premium_history (hourly cron); baseline_status:'accumulating' until ≥24 samples. $0.02 USDC via 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", "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." }, "premium_pct": { "type": "number", "description": "(coinbase / composite_median − 1) × 100. Positive = Coinbase premium." }, "interpretation": { "type": "string" }, "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" }, "z_score_30d": { "type": "number", "nullable": true, "description": "30-day z-score of premium_pct. null while accumulating.", "example": 1.4 }, "percentile_24h": { "type": "number", "nullable": true, "description": "% of last-24h samples with premium below current. null while accumulating.", "example": 78.3 }, "baseline_samples_30d": { "type": "integer", "description": "Hourly samples in trailing 30d.", "example": 312 }, "baseline_samples_24h": { "type": "integer", "description": "Hourly samples in trailing 24h.", "example": 22 }, "baseline_status": { "type": "string", "enum": [ "ready", "accumulating" ] }, "baseline_note": { "type": "string" }, "data_age_seconds": { "type": "integer" }, "as_of": { "type": "string", "format": "date-time" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Unsupported asset or not listed on Coinbase." }, "402": { "description": "Payment Required — x402 micropayment instructions in response body." }, "503": { "description": "Coinbase unavailable or no composite sources reachable." } }, "x-x402": { "scheme": "exact", "price": "$0.02", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.02 USDC on Base mainnet (eip155:8453). On first call (no X-PAYMENT header) the server returns HTTP 402 with payment instructions. Re-send with the X-PAYMENT header populated by an x402 client library (e.g. npm package `x402-fetch`)." } }, "options": { "operationId": "cexPremiumCors", "summary": "CORS preflight", "responses": { "204": { "description": "CORS preflight OK" } } } } } }