{ "openapi": "3.0.3", "info": { "title": "Kronos x402 API", "version": "1.0.0", "description": "Pay-per-call crypto intelligence API designed for autonomous agents. Two paid endpoints: (1) /api/v1/forecast/btc — directional price forecast for BTC, ETH, and SOL (select via ?asset=) using the Kronos-small ML model with EMA/RSI/MACD/ATR fallback; (2) /api/v1/signals/btc — BTC derivatives intelligence: funding rate, open interest, basis, and derived signals from Bybit/OKX perpetual swap markets. Each paid call costs $0.001 USDC on Base mainnet (eip155:8453) via the x402 micropayment protocol. Public endpoints: /api/stats (aggregate service 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.001 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.001 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.001", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.001 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.001", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.001 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.001 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.001 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.001", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.001 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.001", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.001 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.001 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.001 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.001", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.001 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.001", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.001 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/btc": { "get": { "operationId": "getBtcSignals", "summary": "BTC derivatives intelligence (funding rate, OI, basis)", "description": "Returns BTC derivatives market intelligence sourced from Bybit/OKX perpetual swap markets. 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.001 USDC.", "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.001 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.001", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.001 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.001", "currency": "USDC", "network": "eip155:8453", "description": "EIP-3009 gasless micropayment via x402 protocol. Send 0.001 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/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": "Scored outcomes vs actual close direction and ATR range." }, "service": { "name": "Kronos x402 API", "asset": "BTC-USD, ETH-USD, SOL-USD", "price_usd": 0.001, "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.001" }, "currency": { "type": "string", "example": "USDC" }, "network": { "type": "string", "example": "eip155:84532" }, "scheme": { "type": "string", "example": "exact" } } } } } } } } } } } }