How to Use x402.tunedfor.ai
Integration Guide

What This Is

x402.tunedfor.ai is a pay-per-call REST API that delivers structured crypto market data to AI agents. Each HTTP call is paid in USDC on Base or Solana via the x402 protocol — no API keys, no accounts, no subscription required.

The server returns a 402 Payment Required response. The agent's x402 SDK client handles USDC settlement automatically (~200ms via Coinbase CDP) and retries the request with a payment header attached.

Responses are structured JSON your code can branch on directly. Fields like stance, orderflow_signal, and cvd_direction are enumerated strings — not prose summaries that require further parsing.

Prerequisites

• A funded EVM wallet on Base mainnet with USDC, or
• A funded Solana wallet with USDC
• Python 3.9+ (for the SDK approach)

Quick Start: Python SDK

The x402 Python client handles the full payment lifecycle. Your code calls the endpoint once — the SDK intercepts the 402, settles payment, and returns the data transparently.

import os
import asyncio
from x402.http.clients.httpx import x402HttpxClient
from x402.mechanisms.evm.signers import EthAccountSigner

signer = EthAccountSigner(private_key=os.environ["WALLET_PRIVATE_KEY"])
client = x402HttpxClient(signer=signer)

async def main():
    # Call any endpoint — payment handled automatically
    resp = await client.post(
        "https://x402.tunedfor.ai/analyze/orderflow",
        json={"token": "BTC"}
    )
    data = resp.json()
    print(f"CVD direction: {data['cvd_direction']}")
    print(f"Buy ratio: {data['buy_ratio']}")
    print(f"Exchanges accumulating: {data['exchange_breakdown']['exchanges_accumulating']}/20")

asyncio.run(main())

Install dependencies:

pip install "x402[httpx,evm]" eth-account

Set the WALLET_PRIVATE_KEY environment variable to your EVM private key (Base mainnet). Never hardcode keys or commit them to source control.

How x402 Payment Works

The x402 protocol is an HTTP extension that allows agents to pay per API call with on-chain USDC. The flow is fully automatic when using the SDK.

1. Agent POSTs to any paid endpoint. No auth header needed.
2. Server returns HTTP 402 Payment Required with a payment-required header containing the price (USDC amount), receiving wallet address, and network.
3. The x402 SDK reads the header, signs a USDC transfer from the agent's wallet, and sends the payment to the Coinbase CDP facilitator.
4. CDP confirms settlement (~200ms).
5. Agent retries the original request with an X-Payment header attached.
6. Server verifies payment and returns the data with HTTP 200.

No subscription. No minimum spend. Each call is independent. If payment verification fails, the server returns 402 again — no funds are deducted for failed settlements.

Endpoint Reference

All paid endpoints require a valid x402 payment. Free endpoints return immediately with no payment flow.

Request Format

All paid endpoints accept a JSON POST body. Only token is required:

{"token": "BTC"}

Optional parameters:

{
  "token": "ETH",
  "context": "7d",
  "max_age_seconds": 300
}

History endpoint parameters

History endpoints (/data/history/1h, /data/history/1d, /data/history/5m) also accept start, end, and limit:

{
  "token": "BTC",
  "start": "2022-01-01",
  "end": "2022-12-31",
  "limit": 5000
}

Maximum 5,000 bars per call. For /data/history/5m the window is limited to the last 17 days; start and end will be clamped to that range.

Response: /analyze/orderflow

Aggregates live orderflow from 20 exchanges. CVD, buy/sell pressure, whale bars, liquidation data, and a per-exchange breakdown. Data sourced from aggr-server, refreshed every 5 minutes.

{
  "token": "BTC",
  "timestamp": "2026-04-10T14:22:00Z",
  "cvd_direction": "up",
  "cvd_value": 14523.7,
  "buy_ratio": 0.61,
  "whale_bar_count_1h": 3,
  "liquidation_buy_1h": 12400.0,
  "liquidation_sell_1h": 89200.0,
  "cvd_divergence": 0.14,
  "spot_perp_delta": 0.03,
  "volume_herfindahl": 0.22,
  "exchange_breakdown": {
    "exchanges_accumulating": 14,
    "exchanges_distributing": 6,
    "exchanges_total": 20,
    "dominant_direction": "buy",
    "diverging_exchanges": []
  },
  "data_freshness": {
    "data_age_seconds": 120,
    "stale": false
  }
}

Key fields explained

Response: /analyze/full

Combines all market and orderflow data, then runs a single LLM synthesis pass. Returns enumerated classification fields you can branch on directly, plus a one-sentence verdict that cites specific data values.

{
  "token": "BTC",
  "stance": "BULLISH",
  "orderflow_signal": "ACCUMULATION",
  "risk_level": "LOW",
  "verdict": "Market stance BULLISH with signal_confidence 0.72. Orderflow ACCUMULATION across 14/20 exchanges. Risk LOW — funding_rate 0.0045 within normal range.",
  "warnings": [],
  "cvd_direction": "up",
  "buy_ratio": 0.61,
  "macro_regime": "risk_on",
  "data_freshness": {"data_age_seconds": 180, "stale": false}
}

Enumerated fields — branch on these

MCP Server (Claude Desktop / Cursor)

An MCP server wraps the x402.tunedfor.ai endpoints as callable tools for Claude Desktop, Cursor, and any other MCP-compatible host. Payment is handled transparently by the server process.

Install

pip install "x402[httpx,evm]" mcp eth-account

Claude Desktop configuration

Edit %APPDATA%\Claude\claude_desktop_config.json on Windows (or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "x402-crypto": {
      "command": "python",
      "args": ["/path/to/x402/mcp_server.py"],
      "env": {
        "X402_API_BASE_URL": "https://x402.tunedfor.ai",
        "PAYER_PRIVATE_KEY": "0x_YOUR_FUNDED_WALLET_KEY",
        "PAYER_NETWORK": "eip155:8453"
      }
    }
  }
}

Restart Claude Desktop after saving the config. The x402 crypto market data tools will appear in the tool selector automatically. The MCP server process holds the wallet key and handles payment signing — Claude itself never sees the private key.

Supported Tokens

15 tokens — /data, /analyze/market, /analyze/full

24 tokens — /analyze/orderflow, /data/history/*

All 15 above, plus:

Use GET /coverage to see per-token historical depth and exchange coverage before calling paid endpoints.

Free Endpoints

These endpoints return immediately with no payment required. Use them to preview output, discover available data, and check service health before spending USDC.

# Cached BTC responses from all paid endpoints
curl https://x402.tunedfor.ai/demo

# Machine-readable endpoint listing with schemas and pricing
curl https://x402.tunedfor.ai/catalog

# Data inventory — every token, every timeframe, historical depth and bar counts
curl https://x402.tunedfor.ai/coverage

# Service health
curl https://x402.tunedfor.ai/health

The /demo endpoint is useful for validating response parsing before a paid call. The /catalog endpoint is machine-readable JSON — agents can query it to enumerate available endpoints, prices, and request/response schemas at runtime.

Discovery

x402.tunedfor.ai is discoverable by AI agents and crawlers via standard discovery files. Agents that implement the x402 protocol or A2A spec can find this service automatically.