Build with Kronos

Start free

Discover products and test delayed BTC output without an account, API key or wallet.

curl https://kronos.seshat.markets/api/feeds/kronos/catalog

curl https://kronos.seshat.markets/api/feeds/kronos/sample/btc_usdt

curl https://kronos.seshat.markets/api/feeds/kronos/risk

Read the OpenAPI specification, agent registry and agent quickstart for the complete reference.

How x402 works

1. Your agent requests a paid endpoint.
2. Kronos returns HTTP 402 with a signed payment requirement: price, USDC asset, destination and network.
3. The buyer-controlled wallet signs an authorization.
4. The client retries with the payment payload and receives the result.

Node / TypeScript SDK pattern

Use a buyer wallet that you control. The private key remains in your local runtime and must never be committed, logged or pasted into chat.

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:84532', client: new ExactEvmScheme(account) }],
});

const response = await fetchWithPayment(
  'https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt?timeframes=1h'
);
const forecast = await response.json();

Use the exact network and asset advertised in the live 402 challenge. Never hardcode chain IDs or contract addresses — always read them from the payment requirement returned by Kronos.

Python

Use the official x402 Python SDK for automatic 402 handling, or handle the challenge manually with requests / httpx.

With x402 Python SDK (automatic)

# pip install x402-requests
from x402.requests import wrap_requests_with_payment
import os

# Buyer wallet private key — keep secret, never commit
session = wrap_requests_with_payment(os.environ["BUYER_PRIVATE_KEY"])

response = session.get(
    "https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt",
    params={"timeframes": "1h"}
)
forecast = response.json()
print(forecast["consensus"]["direction"])  # "LONG" or "SHORT"

Manual 402 handling with requests

import requests

url = "https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt"
params = {"timeframes": "1h"}

# Step 1: request the endpoint — get 402 challenge
resp = requests.get(url, params=params)
if resp.status_code == 402:
    challenge = resp.json()
    # challenge contains: price, accepts (asset, network, scheme),
    # payTo (destination address), x402-version, etc.
    print(f"Payment required: {challenge['price']}")

    # Step 2: sign payment with your wallet (EVM or Solana)
    # Use web3.py (EVM) or solana.py (Solana) to sign
    payment_header = sign_payment(challenge)  # your signing logic

    # Step 3: retry with X-PAYMENT header
    resp = requests.get(url, params=params, headers={
        "X-PAYMENT": payment_header,
        "X-REQUEST-ID": resp.headers.get("X-REQUEST-ID", "")
    })

if resp.status_code == 200:
    forecast = resp.json()
    print(forecast["consensus"]["direction"])

curl — paid endpoint end-to-end

Full flow: initial request → 402 challenge → sign payment → retry with payment header.

# 1. Request the endpoint — receive 402 challenge
curl -s https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt?timeframes=1h \
  -D headers.txt -o challenge.json
# headers.txt contains X-REQUEST-ID, challenge.json has payment requirements

# 2. Sign payment (use x402 CLI, your wallet, or SDK)
#    This produces a base64-encoded payment header
PAYMENT=$(x402 sign --challenge challenge.json --key $BUYER_PRIVATE_KEY)
REQUEST_ID=$(grep -i X-REQUEST-ID headers.txt | awk '{print $2}' | tr -d '\r')

# 3. Retry with payment header
curl -s https://kronos.seshat.markets/api/feeds/kronos/predict/btc_usdt?timeframes=1h \
  -H "X-PAYMENT: $PAYMENT" \
  -H "X-REQUEST-ID: $REQUEST_ID" \
  -H "Content-Type: application/json" | jq .consensus.direction

Free endpoints (catalog, sample, risk, accuracy-preview, regime preview) require no payment — just curl directly.

Use with MCP

No persistent local installation and no user-hosted server are required. Add the configuration below and npx automatically fetches and starts the lightweight kronos-mcp connector over stdio — there is no port, daemon or infrastructure for the user to maintain. Free tools work without a wallet: kronos_catalog, kronos_sample and kronos_risk. Paid tools can pay automatically only when the operator configures a local buyer signer.

{
  "mcpServers": {
    "kronos": {
      "command": "npx",
      "args": ["-y", "kronos-mcp"]
    }
  }
}

For automated x402 payments, set one or both variables in the local MCP process environment: KRONOS_X402_EVM_PRIVATE_KEY for Base-compatible EVM payments and KRONOS_X402_SOLANA_PRIVATE_KEY for Solana payments. These are buyer secrets; they are never sent to Kronos as private keys.

Prepare an agent wallet

This is a buyer-operated setup, not a Kronos service. Use a wallet or key-management system you already control.

Agent safety

• Review endpoint prices in the catalog before automation.
• Use a dedicated wallet and choose its funding level yourself; Kronos does not impose a restrictive daily budget.
• Keep the existing API rate limits in mind, especially for GPU playground calls.
• Monitor buyer-wallet activity independently and rotate its key if compromise is suspected.
• Treat forecasts as research signals, never as trading instructions.

Refunds & disputes

x402 payments are on-chain USDC transfers settled by the PayAI facilitator. Each payment is tied to a specific request via the X-Request-Id header echoed in the response.

• Successful delivery: If the endpoint returns HTTP 200 with valid data, the payment is final. No refund is available for forecasts that turn out to be incorrect — Kronos provides research signals, not guarantees.
• Handler failure after upfront payment: If the endpoint returns HTTP 5xx after the payment was settled (upfront flow), contact support with the X-Request-Id and transaction hash. We will refund the full amount to the payer's wallet within 5 business days.
• Facilitator settlement failure: If the PayAI facilitator fails to settle, the client is not charged. The 402 response includes the failure reason; no action is needed.
• Duplicate charges: If the same transaction hash is used for multiple requests, our system detects it and alerts the team. Contact support if you believe you were charged twice for the same request.
• Dispute window: Disputes must be submitted within 30 days of the payment. Include the X-Request-Id, transaction hash, and network (Solana or Base).

Refunds are manual on-chain transfers. Kronos cannot reverse a settled on-chain transaction; instead, we send an equivalent USDC transfer back to the payer's address.

Error catalog

Every API response uses standard HTTP status codes. Error bodies are JSON with error (machine-readable code) and optional detail (human-readable explanation).

Retry tokens (upfront flow only)

When a 5xx error occurs after an upfront payment was settled (predict, forecast-distribution, playground, market-brief, similar-markets, outcome-stats, behavioral-correlations, rationale-novelty), the response includes:

• retry_token — one-time use token, 1h TTL. Send in X-Retry-Token header on your next request to bypass payment.
• refund_reference — on-chain tx hash of the settled payment. Cite this when requesting a manual refund.

For authorization flow endpoints (data/analysis), payment only settles on successful (2xx) responses — no refund needed on 5xx.

API reference pages

Detailed documentation for each endpoint and topic: