papertrade-x402

x402 · USDC · Solana first

Pay per call.
Papertrade intelligence for agents.

Liquidation risk for any wallet, a live liquidation map, settlement estimates and top-trader stats, computed from live Papertrade data. No API keys and no accounts. Start with the free preview, connect your AI over MCP, or let your agent take an HTTP 402, sign a USDC payment and get the full answer.

Unofficial, not affiliated with Papertrade. High leverage can lose your whole margin. Nothing here is financial advice.

Try it live Connect your AI Read the docs

Works with

Works with

Live markets free

GET /api/v1/markets

Paid endpoints

Priced in USDC per successful call. You are charged only when the answer is delivered.

Free: /api/v1/health, /api/v1/markets, /openapi.json, /.well-known/x402.

Try it live

Sends one real request. Nothing is signed or charged.
A 0x HyperEVM address.

Connect your AI

One URL. Read-only tools. Connecting cannot spend money.
https://papertrade-x402.pages.dev/mcp
Claude Code 
claude mcp add --transport http papertrade-x402 https://papertrade-x402.pages.dev/mcp
Codex CLI 
codex mcp add papertrade-x402 --url https://papertrade-x402.pages.dev/mcp
Cursor: .cursor/mcp.json 
{
  "mcpServers": {
    "papertrade-x402": { "url": "https://papertrade-x402.pages.dev/mcp" }
  }
}
Gemini CLI: settings.json 
{
  "mcpServers": {
    "papertrade-x402": { "httpUrl": "https://papertrade-x402.pages.dev/mcp" }
  }
}

Claude Desktop and claude.ai: add a custom connector with the URL above. ChatGPT: developer mode connector. VS Code, Windsurf, Zed, Cline, Goose, Continue and the Claude and OpenAI APIs: full setup guide.

MCP tools

Schemas and examples

Free

  • get_markets
  • get_service_status
  • preview_wallet_risk
  • preview_liquidations_nearby
  • preview_estimate_position
  • preview_top_traders

Paid, requirements only

  • wallet_risk
  • liquidations_nearby
  • estimate_position
  • top_traders

These return the x402 payment requirements and never pay. Your agent pays with its own wallet over HTTP: how.

curl

Every paid route answers an unpaid request with a spec-correct 402.
curl -i https://papertrade-x402.pages.dev/api/v1/wallet/0x3f139ef9f371fbbfc299aa65b93534e177141b18/risk

# HTTP/2 402
# payment-required: eyJ4NDAyVmVyc2lvbiI6Mi4uLg==   (base64 JSON: x402Version, accepts[], resource)

# Decode the challenge
curl -si https://papertrade-x402.pages.dev/api/v1/liquidations/nearby?market=BTC\&pct=0.5 \
  | grep -i '^payment-required:' | cut -d' ' -f2 | base64 -d | jq '.accepts[] | {network, amount, payTo}'

# POST route
curl -i -X POST https://papertrade-x402.pages.dev/api/v1/estimate \
  -H 'content-type: application/json' \
  -d '{"market":"BTC","side":"long","marginUsd":100,"leverage":100,"exitMovePct":-0.5}'

TypeScript client

Example. You supply the signer; keys never leave your process.
Official x402 fetch wrapper with a Solana signer 
import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
import { registerExactSvmScheme } from '@x402/svm/exact/client';
import { createKeyPairSignerFromBytes } from '@solana/kit';
import { base58 } from '@scure/base';

// Your own key, from your own secret store.
const signer = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!),
);

const client = new x402Client();
registerExactSvmScheme(client, { signer });
const payFetch = wrapFetchWithPayment(fetch, client);

const res = await payFetch(
  'https://papertrade-x402.pages.dev/api/v1/wallet/0x3f139ef9f371fbbfc299aa65b93534e177141b18/risk',
);
console.log(await res.json());
papertrade-x402 helper, with a dry run 
import { PapertradeX402 } from 'papertrade-x402';

// Dry run: prints requirements, signs and pays nothing.
const preview = new PapertradeX402({ dryRun: true });
console.log(await preview.liquidationsNearby({ market: 'BTC', pct: 0.5 }));

// Live: pay with your signer, refuse anything above 0.10 USDC.
const api = new PapertradeX402({ svmSigner: signer, maxPriceUsdc: 0.1 });
const { data, receipt } = await api.tradersTop({ window: '7d' });

Agent quick start

  1. Discover. Fetch /.well-known/x402, /openapi.json or the MCP server card for prices, networks, payTo and input/output schemas. Check status first.
  2. Call. Request any paid route. You get 402 and a base64 PAYMENT-REQUIRED header listing Solana USDC first, then Base USDC.
  3. Pay. Sign the matching option and retry with the PAYMENT-SIGNATURE header. The x402 fetch wrapper does both steps for you.
  4. Receive. The facilitator verifies before the handler runs and settles only after a successful response. Errors (400, 502) are never charged. The receipt is in PAYMENT-RESPONSE.
  5. Preview first. Every paid route has a free live preview under /api/v1/preview/.
  6. Pair it. Use papertrade-ai (MCP server and CLI) for the trading side and this API for paid intelligence.