Payment Flow

The x402 path is intentionally simple: request, receive 402, pay, replay, read the response.

Flow steps

Send the route request to /api/x402/*.
Receive 402 Payment Required with a PAYMENT-REQUIRED header.
Decode the x402 requirements and prepare the payment payload.
Replay the exact same request with PAYMENT-SIGNATURE.
On success, inspect PAYMENT-RESPONSE.

x402 headers

PAYMENT-REQUIRED comes from the server on the 402.
PAYMENT-SIGNATURE goes back on the replay.
PAYMENT-RESPONSE comes back on success.

Keep the HTTP method, path, query, body, and any idempotency token stable between the original request and the replay. Treat the replay as the same request with one new header, not a second request shape.

What MindSwap fixes at runtime

Scheme: exact
Network: eip155:8453 (Base mainnet)
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 env names: EXTERNAL_API_X402_CDP_API_KEY_ID / EXTERNAL_API_X402_CDP_API_KEY_SECRET with runtime fallbacks documented in the OpenAPI spec.
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.

Minimal example

1. Initial request

POST https://mindswap.fun/api/x402/quotes
Content-Type: application/json
Idempotency-Key: idem_x402_quote_1

{
  "fromCcy": "BTC",
  "toCcy": "ETH",
  "amount": "0.5",
  "direction": "from",
  "type": "fixed"
}

2. Challenge response

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64-encoded PaymentRequired>

3. Replay

POST https://mindswap.fun/api/x402/quotes
Content-Type: application/json
Idempotency-Key: idem_x402_quote_1
PAYMENT-SIGNATURE: <base64-encoded PaymentPayload>

{
  "fromCcy": "BTC",
  "toCcy": "ETH",
  "amount": "0.5",
  "direction": "from",
  "type": "fixed"
}

Do not hardcode price, recipient, or settlement details. Use the live PAYMENT-REQUIRED value as the source of truth for what the route is charging right now.

Onchain execution access

Onchain route resolution and execution reporting are wallet-bound paid routes, so send SIGN-IN-WITH-Xwith the x402 replay. Route resolution returns executionAccessToken. Continue sending it as X-Onchain-Execution-Access-Token on POST /api/x402/onchain/executions and GET /api/x402/onchain/executions/{executionPlanId}.

The read is still wallet-bound through SIWX. The access token is an additional guard, not a replacement for SIWX.

x402 API Overview

Endpoints