x402 API›Payment Headers

Payment Headers

MindSwap documents one payment contract for /api/x402: the official x402 v2 headers.

Required headers by phase

  • Initial request: your normal HTTP headers plus any route-specific inputs
  • Challenge response: server returns PAYMENT-REQUIRED
  • Replay: client sends PAYMENT-SIGNATURE
  • Success: server returns PAYMENT-RESPONSE

Route input shape

Quote-like inputs stay aligned with the Business API: fromCcy, toCcy, amount, plus optional direction and type.

Resolve, onchain, order, and market-intel bodies remain route-specific. Use the OpenAPI spec for the exact shape once the backend contract is stable.

GET /api/x402/routes

Route discovery is now a paid GET. Keep the query string stable across the first request and the replay.

Keep walletAddress bound to the source signer or principal. Use recipientAddress as the destination recipient for cross-namespace onchain routes. Mayan discovery requires recipientAddresswhen the destination wallet namespace differs from the source signer namespace, such as an EVM signer with a Solana recipient.

Paid GET route discovery
GET https://mindswap.fun/api/x402/routes?fromCcy=BTC&toCcy=ETH&amount=0.5&direction=from&type=fixed&walletAddress=0x0000000000000000000000000000000000000001&walletChainNamespace=eip155
Idempotency-Key: idem_x402_routes_1
Paid GET cross-namespace discovery
GET https://mindswap.fun/api/x402/routes?fromCcy=ETH&toCcy=SOL&amount=0.5&direction=from&type=fixed&walletAddress=0x0000000000000000000000000000000000000001&walletChainNamespace=eip155&recipientAddress=So11111111111111111111111111111111111111112
Idempotency-Key: idem_x402_routes_1

Production defaults

  • Scheme: exact
  • Network: Base mainnet eip155:8453
  • Production Coinbase CDP facilitator URL: https://api.cdp.coinbase.com/platform/v2/x402
  • Facilitator URL env names: EXTERNAL_API_X402_FACILITATOR_URL, fallback X402_FACILITATOR_URL
  • Seller address env names: EXTERNAL_API_X402_PAYTO, fallback X402_PAYTO
  • CDP API key ID env names: EXTERNAL_API_X402_CDP_API_KEY_ID, fallback X402_CDP_API_KEY_ID, CDP_API_KEY_ID, CDP_KEY_ID, KEY_ID, KEY_NAME
  • CDP API key secret env names: EXTERNAL_API_X402_CDP_API_KEY_SECRET, fallback X402_CDP_API_KEY_SECRET, CDP_API_KEY_SECRET, CDP_KEY_SECRET, KEY_SECRET
  • Access-token signing secret: ONCHAIN_EXECUTION_ACCESS_TOKEN_SECRET or ORDER_ACCESS_TOKEN_SECRET when x402 order/onchain routes are enabled

The x402.org facilitator is testnet-only. Do not use https://facilitator.x402.org for Base mainnet production settlement.

Pricing

Current runtime pricing is $0.05 for each paid x402 route. Wallet-bound paid mutations and reads use SIGN-IN-WITH-X; wallet-bound reads are not charged again.

Wallet-bound routes and quotas

Runtime currently limits paid route attempts to 60/hour per client and route, and wallet-bound authenticated reads to 30/minute per client, route, and resource.

Paid order creation, paid emergency actions, onchain route resolve, onchain execution reporting, and market-intel job creation also require SIGN-IN-WITH-X. Onchain execution report/status routes also require X-Onchain-Execution-Access-Token.

Previous
Endpoints
Next
SIWX Reads