@tunedforai/x402-mcp

v1.1.5

Published

a month ago

MCP server for x402 crypto market structure data — camelCase tools, zero config, works everywhere

0High
0Medium
0Low

tunedforai

mcp crypto market-data bitcoin ethereum x402 modelcontextprotocol

x402-mcp

Cross-exchange crypto market structure for AI agents. 20 exchanges, 26 fixed Pillar tokens plus any-token light coverage, 7 tools - light coverage, snapshot, orderflow, macro regime, full analysis, address risk, and API info. Free via MCP.

x402-mcp is a stdio MCP server that exposes x402.tunedfor.ai - a real-time crypto market structure API - as 7 tools any MCP-compatible client (Claude Desktop, Cursor, Cline, Windsurf, Claude Code) can call. Free via MCP for testing and low-frequency queries; paid REST at the same endpoints for production agents that need higher throughput.

Install

Claude Desktop / Cursor / Windsurf

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, equivalent on other OS):

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["-y", "@tunedforai/x402-mcp"]
    }
  }
}

Claude Code

claude mcp add x402 -- npx -y @tunedforai/x402-mcp

Cline / Continue / other MCP clients

Use the same npx -y @tunedforai/x402-mcp invocation as the stdio command.

Manual

npm install -g @tunedforai/x402-mcp
x402-mcp  # runs the stdio server

Tools

All 7 tools are stateless. No API key, no auth, no setup. Just call them.

| Tool | What it returns | REST equivalent | Free via MCP / Paid REST | |---|---|---|---| | marketLight | Any-token CoinGecko-backed market coverage: price, momentum, rank, liquidity/exchange context, and risk flags. Defaults to brief=off; set brief=full for Kimi brief | POST /data/light | Free / $0.05 | | marketSnapshot | Free 16-field MCP subset: live price, funding, OI, buy/sell ratio, fear/greed | POST /data | Free / $0.20 | | marketAnalyze | Macro regime, DXY, VIX, directional signal + confidence | POST /analyze/market | Free / $0.25 | | marketOrderflow | Cross-exchange CVD, whale activity, liquidation pressure | POST /analyze/orderflow | Free / $0.50 | | marketFull | Snapshot + orderflow + LLM-synthesized analysis | POST /analyze/full | Free / $0.75 | | addressRisk | Wallet risk score (mixers, sanctions, counterparties). EVM + Solana | POST /analyze/address | Free / $0.25 | | apiInfo | Pricing, quick-start, migration details | GET /api_info | Free |

Token coverage

Major L1s and L2s on the snapshot tier: BTC, ETH, SOL, XRP, BNB, DOGE, ADA, AVAX, LINK, ATOM, DOT, ARB, SUI, OP, LTC.

Extended orderflow tier: the above plus NEAR, AAVE, BCH, HBAR, SHIB, TON, TRX, UNI, XLM.

marketLight supports listed CoinGecko symbols beyond the fixed Pillar token list. Use it for lightweight coverage of tokens such as WCT when the fixed snapshot/orderflow tools reject a symbol. It defaults to brief=off for lower latency; request brief=full when you specifically need the Kimi-generated prose brief.

Call apiInfo from any MCP client for the authoritative current list.

MCP subset contract

marketSnapshot returns a free 16-field MCP subset for agent context and routing. It is not the paid REST /data schema.

Expected top-level MCP keys:

as_of_utc
token
snapshot
data_freshness
presentation_hint
next_steps

The snapshot object carries the 16 market data fields plus metadata. token and fetched_at are metadata keys, so a raw JSON key count may show 17 keys under snapshot even though the product contract is the 16-field market-data subset.

Do not require schema_version or coverage from MCP. Those belong to the paid REST contract unless the MCP product contract is intentionally expanded.

Every marketSnapshot response must keep the REST CTA:

This is a 16-field MCP subset. Paid REST /data at x402.tunedfor.ai ($0.20 USDC) returns the full 70-field snapshot including on-chain metrics, sentiment, and historical percentiles. No API key, pay-per-call from any wallet.

Examples

Pre-trade check

You: marketSnapshot BTC
LLM: BTC at $74,180. Buy ratio 58% — bullish lean. Funding rate +0.012%
     (mild long bias). Open interest $14.2B. Fear & Greed: 32 (Fear).
     Snapshot 12 sec old.

Cross-exchange orderflow

You: marketOrderflow ETH
LLM: ETH cross-exchange CVD: -$1.2M last hour (sell-side dominant).
     Whale activity: 8 large bars across Binance/Coinbase/Bybit.
     Liquidations: $890K longs, $230K shorts. Pressure: bearish.

Free MCP vs Paid REST

The MCP wrapper is free with rate limits — perfect for testing, prototyping, low-frequency agent workflows, and personal use.

For production agents (24/7 polling, multi-token monitoring, backtesting at scale), use the paid REST endpoints at x402.tunedfor.ai. REST is:

Pay-per-call in USDC on Base or Solana via the x402 protocol
No API keys — your agent signs payment locally; the private key never leaves your machine
Rate-limited to 60 calls/minute and 200 calls/hour per wallet — prevents stripmining; 429 on breach
No subscriptions — no monthly minimums

Call apiInfo from any MCP client to get the current pricing schedule, migration guide, and SDK examples.

How x402 payment works (REST tier)

When your agent calls a paid REST endpoint:

First request returns HTTP 402 Payment Required with the price
Agent signs a USDC payment locally (private key never leaves the agent)
Agent retries with the payment header attached
Server verifies on-chain settlement and returns the data

No accounts, no API keys, no credit cards. Just USDC and a wallet.

Data sources

Price + ticker: OKX, Coinbase public APIs
Funding / OI / liquidations: Coinalyze (commercial license)
On-chain metrics, exchange flows, whale ratios: licensed third-party institutional data
Cross-exchange orderflow (CVD, whale bars, liq aggregations): WebSocket aggregator across 20 exchanges into InfluxDB, normalized into 1-minute bars
Macro context (DXY, VIX, Treasury yields): FRED + Finviz
Fear & Greed Index: alternative.me

We don't redistribute raw exchange data — we serve derived, computed aggregates. All raw source fields are transformed into our own composite signals before responses are returned.