x402 Payments

MangroveTrader uses the x402 payment protocol for pay-per-query access to premium data. Payments settle in USDC on Base. No subscriptions, no prepayment, no accounts required.

How It Works

1. Request without payment — call any paid endpoint without a payment parameter. The server responds with HTTP 402 Payment Required (REST) or PAYMENT_REQUIRED status (MCP).
2. Read the price — the response includes the exact price, payment address, network, and x402 header format.
3. Sign and retry — your client signs an x402 payment (ERC-3009 transferWithAuthorization) and retries with the payment attached.
4. Verify, fetch, settle — the server verifies the signature, fetches your data, then settles the payment on-chain. You receive the data plus a settlement receipt.

Verify-before-settle: If the data fetch fails after verification, the payment is NOT settled. You are never charged for a failed request.

Payment Details

Pricing

REST Payment Flow

For REST endpoints under /api/x402/, the Coinbase x402 middleware handles everything automatically:

# Step 1: Request without payment
POST /api/x402/leaderboard
→ HTTP 402 Payment Required
→ Headers: X-Payment-Required: {price, network, payTo, ...}

# Step 2: Client signs x402 payment
# Step 3: Retry with X-Payment header
POST /api/x402/leaderboard
X-Payment: <base64-encoded x402 signature>
→ HTTP 200 OK
→ Body: {data: [...], settlement: {txHash, payer, network}}

MCP Payment Flow

For MCP tools, payment is passed as a tool parameter:

// Step 1: Call without payment
{
  "tool": "trader_get_leaderboard",
  "args": {"timeframe": "all_time", "limit": 100}
}
→ {"status": "PAYMENT_REQUIRED", "price": "0.25", ...}

// Step 2: Call with payment
{
  "tool": "trader_get_leaderboard",
  "args": {
    "timeframe": "all_time",
    "limit": 100,
    "payment": "<base64-x402-signature>"
  }
}
→ {"leaderboard": [...], "settlement": {"txHash": "0x...", ...}}

API Key Bypass

API key holders bypass x402 payment entirely. Pass the key via the X-API-Key header:

POST /api/x402/leaderboard
X-API-Key: your-api-key
Content-Type: application/json

{"timeframe": "all_time", "limit": 100}
→ HTTP 200 (no payment required)

Settlement Receipt

Every paid response includes a settlement receipt:

{
  "settlement": {
    "txHash": "0xabc123...",
    "payer": "0xbf57B1...",
    "payee": "0xde9918...",
    "amount": "0.25",
    "token": "USDC",
    "network": "base"
  }
}