# x402.tunedfor.ai

x402.tunedfor.ai is a pay-per-call REST API that delivers live crypto market data to AI agents. Each HTTP call is paid automatically in USDC on Base or Solana via the x402 protocol — no API keys, no accounts, no subscription. The server returns a 402 Payment Required response; the agent's x402 client handles settlement and retries the request automatically.

Use this service when an agent needs: current orderflow state across 20 exchanges, structured market regime data (bull/bear/risk_on/risk_off), historical OHLCV bars for backtesting, or on-chain address risk profiling. All paid endpoints return structured JSON with deterministic field names your code can branch on directly.

## Supported Tokens

/analyze/market and /analyze/full: BTC, ETH, SOL, XRP, ADA, DOGE, AVAX, LINK, BNB, ATOM, DOT, ARB, SUI, OP, LTC (15 tokens)
/analyze/orderflow and /data/history/*: above + NEAR, TRX, BCH, SHIB, HBAR, TON, XLM, UNI, AAVE (24 tokens total)

## When to Use This Service

- **Before executing a crypto trade** → call /analyze/market for macro alignment and directional market reading
- **Before trusting a price move** → call /analyze/orderflow to verify cross-exchange volume evidence
- **Full pre-trade check** → call /analyze/full — all market information in one context, one payment
- **Before interacting with a wallet or contract** → call /analyze/address for on-chain risk profile
- **Historical OHLCV + orderflow** → call /data/history/1h or /data/history/1d for up to 7 years of data

## Paid Endpoints (x402 USDC on Base or Solana)

### POST /data — 0.20 USDC
Live Pillar token snapshot. 16 reliably populated fields — no nulls, no gaps.
Returns: price_usd, volume_24h_usd, market_cap_usd, change_pct_24h, funding_rate, open_interest_usd, cvd_1h, buy_ratio, whale_bar_count_1h, liquidation_buy_1h, liquidation_sell_1h, cvd_divergence, spot_perp_delta, volume_herfindahl, fear_greed, fear_greed_label.
Input: {"token": "BTC"}
Optional: {"token": "BTC", "max_age_seconds": 300} — freshness contract
Clean feed input for models and agents. All returned fields have live data. 15 tokens supported.

### POST /analyze/market — 0.25 USDC
Pre-trade macro check. Data-only, no LLM latency.
Returns: price_usd, price_change_24h, market_direction ("up"/"down"), confidence (0-1), macro_regime (bull/bear/risk_on/risk_off/choppy), macro_context (DXY, VIX, fear/greed score and label)
Input: {"token": "BTC"}
Optional: {"token": "BTC", "context": "7d"} — adds historical_context with percentile rankings vs last 7 days
Optional: {"token": "BTC", "max_age_seconds": 300} — freshness contract
Answers: "Is the macro environment aligned for this trade?" 15 tokens supported.

### POST /analyze/orderflow — 0.50 USDC
Cross-exchange orderflow information. Data-only, from 20 live exchanges.
Returns: cvd_direction, cvd_value, whale_bar_count_1h, liquidation_buy_1h, liquidation_sell_1h, buy_ratio, cvd_divergence (spot leading indicator), spot_perp_delta, volume_herfindahl (HHI, >0.6 = manipulation risk), exchange_breakdown (accumulating/distributing counts, dominant_direction, diverging_exchanges)
Input: {"token": "ETH"}
Optional: {"token": "ETH", "context": "7d"} — adds historical percentile rankings
Answers: "Is this pump backed by real cross-exchange volume, or a thin-book squeeze?" 24 tokens supported.

### POST /analyze/full — 0.75 USDC
Complete market picture. All data from /market and /orderflow, plus a single grounded LLM call.
Returns all data fields plus: stance (BULLISH/BEARISH/NEUTRAL), orderflow_direction (ACCUMULATION/DISTRIBUTION/NEUTRAL), risk_level (LOW/MODERATE/HIGH/CRITICAL), warnings[], verdict (one sentence citing specific data values)
Input: {"token": "BTC"}
Answers: "What is the current market state for this token?" 15 tokens supported.

### POST /analyze/address — 0.25 USDC
On-chain address profile. Auto-detects EVM (Blockscout) or Solana (Helius). Data-only, no LLM.
Returns: address_type (wallet/contract), is_contract, is_verified, entity_label, account_age_days, last_active_days_ago, tx_count, native_balance (ETH or SOL), top 5 tokens, risk_level, flags
Input: {"address": "0x... or base58..."}
Risk flags: new_account, low_activity, unverified_contract, dormant, high_throughput

### POST /data/history/1h — 5.00 USDC
Hourly OHLC + orderflow bars. Up to 5,000 bars per call. Up to 7 years of history for major tokens.
Returns: timestamp, open, high, low, close, vbuy (buy volume USD), vsell (sell volume USD), cvd (cumulative volume delta), buy_ratio, lbuy (long liquidation USD), lsell (short liquidation USD)
Input: {"token": "BTC"} — returns most recent 500 bars, newest-first
Date range: {"token": "BTC", "start": "2021-01-01", "end": "2021-12-31"} — returns oldest-first, up to limit bars in range
Paginate long ranges by shifting start date forward. 24 tokens supported.
Use for: backtesting, orderflow analysis, model training.

### POST /data/history/1d — 5.00 USDC
Daily OHLC + orderflow bars. Up to 7 years of history for major tokens.
Input: {"token": "ETH", "start": "2020-01-01", "end": "2024-12-31"}
Returns same fields as /data/history/1h.

### POST /data/history/5m — 1.00 USDC
5-minute bars. 17-day rolling window (live collection only, no historical backfill).
X-Data-Delay: 300 header confirms 5-minute delay on live data.
Input: {"token": "SOL", "limit": 288} — last 24 hours at 5m timeframe

## Free Endpoints

GET /health — Service status
GET /catalog — Machine-readable endpoint listing with prices and schemas
GET /demo — Free cached BTC response from each endpoint (validate before paying)
GET /coverage — Live data inventory: every token, every timeframe, historical depth and bar counts
GET /robots.txt — Crawler access policy
GET /sitemap.xml — URL index for crawlers and search agents
GET /llms.txt — This file
GET /.well-known/agent-card.json — A2A agent discovery card
GET /.well-known/x402.json — x402 protocol manifest

## Context Window (Unique Feature)

Add "context": "7d" (or "30d") to any /analyze/market, /analyze/orderflow, or /analyze/full request.
Returns historical_context with percentile rankings for all key fields vs the lookback period.
Example: {"token": "ETH", "context": "7d"} → cvd_1h percentile vs last 7 days

## Freshness Contract (Unique Feature)

Add "max_age_seconds": N to any token request to enforce a data freshness guarantee.
Set to 300 to reject any cached response older than 5 minutes and force a live fetch.
Default behavior uses server cache TTL (3600s / 1 hour).

## Payment

Network: Base (eip155:8453) + Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
Currency: USDC (no API keys, no subscriptions, no accounts)
Facilitator: Coinbase CDP
Settlement: <2 seconds

## Data Sources (NOT wrappers)

- Live Exchange Grid — 20 exchanges, 421 pairs, tick-level orderflow aggregated to 5-min bars, 17-day rolling window
- Token Composite Engine — 62-field snapshots from 10+ integrated sources, 5-minute refresh, 7-day historical depth
- Pulse Engine — proprietary 5-pillar composite scoring (price momentum, on-chain health, sentiment, orderflow, smart money), walk-forward validated
- Macro Context — DXY, VIX, 10Y yield, S&P500, gold, fed funds rate, fear/greed from multiple institutional sources

Docs: https://x402.tunedfor.ai/catalog