# 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 cross-exchange orderflow state across 20 exchanges, structured market regime data (bull/bear/risk_on/risk_off), 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, AMP, ZEC (17 tokens — ZEC unsupported on snapshot-backed endpoints, Pillar dropped 2026-04-03)
/analyze/orderflow: above + NEAR, TRX, BCH, SHIB, HBAR, TON, XLM, UNI, AAVE (26 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

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

Try GET /demo first — free cached example responses for all 6 paid endpoints. Validate output schema before paying.

### POST /data — 0.20 USDC
Curated crypto market snapshot. 16 reliably populated fields — no LLM, no gaps. Cross-exchange tick data aggregated across 20 exchanges — not a CoinGecko wrapper. Feed directly into models, signals, or strategy pipelines.
Does not include directional signals or macro regime — use /analyze/market for that.
Returns: price_usd, change_pct_24h, volume_24h_usd_primary_venue (primary-venue volume — not global CoinGecko total; ~$1-2B for BTC vs ~$66B global), market_cap_usd, funding_rate, open_interest_usd, cvd_1h (cumulative volume delta 1h), buy_ratio, whale_bar_count_1h (count of 5-minute bars in the last hour with an outsized single-order trade — 0 to 12, higher = more institutional activity), liquidation_buy_1h, liquidation_sell_1h, cvd_divergence (spot market CVD diverging from perpetuals CVD — positive = spot leading, signals directional move), spot_perp_delta (positive = spot buying ahead of perp futures), volume_herfindahl (HHI concentration, above 0.6 = volume concentrated in one venue — treat price move with skepticism), fear_greed, fear_greed_label.
field_ages: Map of field_name → seconds since last successful fetch. Missing key = fresh this tick. Large values indicate the upstream API failed and the value is carried forward from a prior cycle. Example: {"dex_volume_24h_usd": 28800} means Dune was unavailable for 8 hours. Use field_ages to decide whether to trust individual fields — a fresh funding_rate coexists with a stale dex_volume_24h_usd in the same response.
data_quality: 0.0–1.0 value surfacing Pillar coverage honestly: 1.0 = all 4 pillars live, 0.25 = only one pillar. x402 does NOT hard-reject responses below a threshold; the buyer sees every signal with its pillars_available list and degraded flag, and decides whether to act on degraded signals. Transparency over gating.
Input: {"token": "BTC"}
Optional: {"token": "BTC", "max_age_seconds": 300} — reject cached data older than N seconds
Use for: model input, signal generation, quantitative pipelines, any workflow needing curated multi-dimensional market state.
Data freshness: Pillar snapshots refresh every 5 minutes. Server cache TTL 1 hour (override with max_age_seconds).
17 tokens: Bitcoin BTC, Ethereum ETH, Solana SOL, XRP, Cardano ADA, Dogecoin DOGE, Avalanche AVAX, Chainlink LINK, BNB, Cosmos ATOM, Polkadot DOT, Arbitrum ARB, Sui SUI, Optimism OP, Litecoin LTC, Amp AMP, Zcash ZEC (ZEC unsupported on snapshot-backed endpoints — Pillar dropped 2026-04-03).

### POST /data/light — 0.05 USDC
Structured any-token coverage — replaces 3-4 API calls + signal math in one round trip. Returns ~50 fields organized by use-case: current (price, market cap, volume, supply, circulating_supply_pct), momentum (1h/24h/7d/14d/30d/1y change percentages), extremes (ATH/ATL with drawdown and recovery percentages, days_since_ath), ranking (market_cap_rank, rank_tier), project (description, categories, genesis_date, age_days, links), where_to_trade (chains, top_exchanges with volume share and trust score, exchange_count), community (watchlist_count, twitter_followers, sentiment_votes_up_pct), and 8 derived signals (momentum_tier, volume_state, volatility_grade, drawdown_phase, liquidity_tier, rank_tier, risk_flags, agent_priority). Data sourced from CoinGecko — Powered by CoinGecko.
response_schema_version: "data_light.v2" — envelope version. signals_spec_version: "2026-05-04" — threshold version. Both are stable contracts.
data_gaps[]: array of {field, reason} objects. reason enum: null_upstream | rate_limited | provider_unavailable | validation_failed | field_unsupported. Empty array means all scalars resolved.
Symbol disambiguation: automatic — top-by-volume match. 404 if no match.
Input: {"symbol": "PEPE"}
Optional: {"symbol": "PEPE", "max_age_seconds": 300} — cache freshness for price tier. Default 300 (5 min). Project/exchange data cached 24h/6h respectively.
Use for: any-token intelligence when /data's 17-token universe is insufficient — small caps, memecoins, long-tail listings. One call gives price + context + risk assessment. MCP free tier adds an LLM-synthesized brief.
Coverage: any token with a public market listing. Does not cover unlisted, pre-launch, or non-fungible assets.

### POST /analyze/market — 0.25 USDC
Pre-trade macro intelligence. Data-only, no LLM latency. The fastest way to check if macro conditions support a trade.
Returns: price_usd, price_change_24h, pulse_signal ("up"/"down"), signal_confidence (0.0-1.0), pillar_coverage {pillars_available[], data_quality (0-1), degraded (bool)} — disclosure of which of the 4 Pulse pillars (price, onchain, sentiment, orderflow) contributed to this composite; filter on degraded==false if you require full 4-pillar coverage. Added 2026-04-18. Pre-migration rows return pillar_coverage: null. Continued: macro_regime ("bull"/"bear"/"risk_on"/"risk_off"/"choppy"), macro_context (dxy, vix, treasury_10y, sp500, fear_greed_score, fear_greed_label), is_carry_forward (bool; TRUE when the macro snapshot was carried forward from a prior trading day — weekends, holidays — discount regime stability claims on carry-forward snapshots).
Pillar score convention: price_score, onchain_score, sentiment_score, orderflow_score, and composite_score are INVERTED percentile rankings: 0.0 = strongly bullish, 1.0 = strongly bearish. A score of 0.2 means the metric is at the 80th percentile relative to the scoring window (bearish extreme). This inversion normalizes contrarian signals across pillars — higher score = more bearish, not more bullish.
Input: {"token": "BTC"}
Optional: {"token": "BTC", "context": "7d"} — adds historical_context with percentile rankings for all key fields vs the last 7 days
Optional: {"token": "BTC", "max_age_seconds": 300} — freshness contract
Use for: pre-trade macro check, position entry timing, regime-based sizing, portfolio rebalancing decisions.
Answers: "Is the macro environment aligned for this trade?"
17 tokens: Bitcoin BTC, Ethereum ETH, Solana SOL, XRP, Cardano ADA, Dogecoin DOGE, Avalanche AVAX, Chainlink LINK, BNB, Cosmos ATOM, Polkadot DOT, Arbitrum ARB, Sui SUI, Optimism OP, Litecoin LTC, Amp AMP, Zcash ZEC (ZEC unsupported on snapshot-backed endpoints).

### POST /analyze/orderflow — 0.50 USDC
Cross-exchange orderflow verification. Data-only from 20 live exchanges — no LLM latency. Tells you if a price move is backed by real cross-exchange volume or a thin-book squeeze.
Returns: cvd_direction ("up"/"down"), cvd_value_usd (USD-notional cumulative volume delta), buy_ratio, whale_bar_count_1h (count of 5-minute bars in the last hour with an outsized single-order trade — 0 to 12, higher = more institutional activity), liquidation_buy_1h (long liquidation USD), liquidation_sell_1h (short liquidation USD), cvd_divergence (spot market CVD diverging from perpetuals CVD — positive = spot leading, signals directional move), spot_perp_delta (positive = spot buying ahead of perp futures), volume_herfindahl HHI (above 0.6 = volume concentrated in one venue, treat price move with skepticism), exchange_breakdown (exchanges_accumulating, exchanges_distributing, exchanges_total, dominant_direction, diverging_exchanges[]).
Data freshness: orderflow aggregated every 5 minutes from live exchange tick feeds.
Input: {"token": "ETH"}
Optional: {"token": "ETH", "context": "7d"} — adds historical_context with percentile rankings vs last 7 days
Use for: trade validation, momentum confirmation, pump/dump detection, pre-position orderflow checks.
Answers: "Is this price move backed by real cross-exchange volume, or is it a thin-book squeeze?"
26 tokens: Bitcoin BTC, Ethereum ETH, Solana SOL, XRP, Cardano ADA, Dogecoin DOGE, Avalanche AVAX, Chainlink LINK, BNB, Cosmos ATOM, Polkadot DOT, NEAR Protocol NEAR, Arbitrum ARB, Sui SUI, Optimism OP, Litecoin LTC, TRON TRX, Bitcoin Cash BCH, Shiba Inu SHIB, Hedera HBAR, Toncoin TON, Stellar XLM, Uniswap UNI, Aave AAVE, Amp AMP, Zcash ZEC.
Note: Call GET /data/coverage to verify historical depth for NEAR, TRX, BCH, SHIB, HBAR, TON, XLM, UNI, AAVE — newer tokens with variable coverage.

### POST /analyze/full — 0.75 USDC
Complete pre-trade due diligence in one payment. All data from /analyze/market and /analyze/orderflow plus a single grounded LLM call with all data in context simultaneously.
Returns everything from both endpoints plus: stance ("BULLISH"/"BEARISH"/"NEUTRAL"), orderflow_signal ("ACCUMULATION"/"DISTRIBUTION"/"NEUTRAL"), risk_level ("LOW"/"MODERATE"/"HIGH"/"CRITICAL"), warnings[] (string array of specific concerns), verdict (one sentence in plain English citing specific values, designed for direct relay to a non-technical user — e.g. "15 of 20 live exchanges are net buyers, buy volume outpaces sell 61/39, risk LOW"), synthesis_model (model used), pillar_coverage {pillars_available[], data_quality (0-1), degraded (bool)} — disclosure of which of the 4 Pulse pillars contributed (added 2026-04-18; pre-migration rows return null), is_carry_forward (bool; TRUE when the macro snapshot was carried forward from a prior trading day).
Pillar score convention: price_score, onchain_score, sentiment_score, orderflow_score, and composite_score are INVERTED percentile rankings: 0.0 = strongly bullish, 1.0 = strongly bearish. A score of 0.2 means the metric is at the 80th percentile relative to the scoring window (bearish extreme). This inversion normalizes contrarian signals across pillars — higher score = more bearish, not more bullish. The LLM synthesis in /analyze/full accounts for this inversion in its reasoning.
Input: {"token": "BTC"}
Optional: {"token": "BTC", "context": "7d"} — adds historical percentile context to LLM synthesis
Use for: autonomous trading decisions, pre-position risk checks, agent-to-agent market briefings, full situational awareness.
Answers: "What is the complete market state for this token and what action does the data support?"
Replaces 3 separate API calls plus an LLM synthesis step in a single payment.
17 tokens: Bitcoin BTC, Ethereum ETH, Solana SOL, XRP, Cardano ADA, Dogecoin DOGE, Avalanche AVAX, Chainlink LINK, BNB, Cosmos ATOM, Polkadot DOT, Arbitrum ARB, Sui SUI, Optimism OP, Litecoin LTC, Amp AMP, Zcash ZEC (ZEC unsupported on snapshot-backed endpoints).

### POST /analyze/address — 0.25 USDC
On-chain address risk profile. Auto-detects EVM Ethereum (0x...) or Solana (base58 format). Data-only, no LLM. Profile any wallet or contract before interacting with it.
Returns: address_type ("wallet"/"contract"), entity_label (if known — e.g. "Vitalik Buterin", "Binance 14"), is_contract (bool), is_verified (bool), account_age_days, last_active_days_ago, tx_count, native_balance (ETH or SOL), top_tokens (top 5 holdings: symbol, balance, value_usd), risk_level ("low"/"medium"/"high"/"unknown"), flags[].
Risk flags: new_account (under 30 days), low_activity (under 10 txs), unverified_contract, dormant (inactive over 1 year), high_throughput (over 1000 txs/day average).
Input (EVM): {"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}
Input (Solana): {"address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"}
Use for: counterparty risk checks, wallet profiling, smart contract due diligence, DeFi protocol auditing, pre-interaction safety screening.
EVM data source: Blockscout. Solana data source: Helius.

## Free Endpoints

GET /demo — Free cached example responses for all 6 paid endpoints (validate schema before paying)
GET /health — Service status + data freshness per source
GET /catalog — Machine-readable endpoint listing with prices, schemas, and use-when guidance
GET /coverage — Live data inventory: every token, every timeframe, historical depth and bar counts
GET /data/coverage — Same as /coverage but JSON format
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

## Data Freshness

How old is the data you're paying for? Per endpoint:
- /data — Pillar snapshots refresh every 5 minutes. Server cache: 1 hour TTL. Use max_age_seconds to enforce freshness.
- /analyze/market — same as /data (Pillar-sourced). Macro context (DXY, VIX) updated every 5 minutes.
- /analyze/orderflow — orderflow aggregated every 5 minutes from 20 live exchange tick feeds.
- /analyze/full — same as /analyze/market + /analyze/orderflow combined. LLM synthesis runs on current data each call.
- /analyze/address — on-demand fetch, cached 1 hour per address.

To reject stale cached data: add "max_age_seconds": 300 to any token request. The server will return a fresh fetch or a 422 if it cannot satisfy the freshness contract.

## 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 4-pillar composite scoring (price momentum, on-chain health, sentiment, orderflow), 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