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
}

Response: /analyze/orderflow

Aggregates cross-exchange orderflow across 20 live exchanges. CVD, buy/sell pressure, whale bars, liquidation data, and a per-exchange breakdown. 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": null,
  "spot_perp_delta": 0.03,
  "volume_herfindahl": null,
  "exchange_breakdown": {
    "exchanges_accumulating": 15,
    "exchanges_distributing": 5,
    "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 15/20 live 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. No API key or wallet required — just npx and a config entry.

Install

npx -y @tunedforai/x402-mcp

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": "npx",
      "args": ["-y", "@tunedforai/x402-mcp"]
    }
  }
}

Restart Claude Desktop after saving the config. The x402 crypto market data tools will appear in the tool selector automatically. No API key or wallet private key required — the npm package connects directly to x402.tunedfor.ai.

Supported Tokens

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

ZEC may 404 on /data and /analyze/market — Pillar collection dropped 2026-04-03.

26 tokens — /analyze/orderflow

Historical endpoints (/data/history/*) retired 2026-04-15. All 17 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.