Next.js Integration

This section documents how a Next.js app integrates with a hosted x402 facilitator.

Required environment variables

Set these in your Next.js deployment:

• X402_FACILITATOR_URL=https://cohort-x402-go.vercel.app
• X402_FACILITATOR_API_KEY=cohort-10-rules
• X402_NETWORK=base
• USDC_BASE_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• SERVICE_RECIPIENT_ADDRESS=<your receiving address>
• PRICE_IN_USDC=0.0001

Server: payment requirements

When a request is unpaid, return 402 with a v2 exact payload:

{
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xYOUR_RECIPIENT",
    "amount": "100",
    "amountDecimal": "0.0001",
    "maxTimeoutSeconds": 600,
    "extra": { "name": "USD Coin", "version": "2" },
    "x402Version": 2
  }
}

Notes:

• amount is in raw token units (USDC has 6 decimals).
• amountDecimal is optional but helpful for UI display.
• extra.name must be USD Coin for Base USDC.
• Use network: eip155:8453 for Base.

Client: signing the EIP-712 authorization

1. Build the domain using extra.name and extra.version:
   • name: "USD Coin"
   • version: "2"
   • chainId: 8453
   • verifyingContract: asset
2. Sign TransferWithAuthorization via eth_signTypedData_v4.
3. Send the x402 payment object in the X-402-Payment header.

Payload shape:

{
  "x402Version": 2,
  "paymentPayload": {
    "accepted": { "scheme": "exact", "network": "eip155:8453" },
    "payload": {
      "authorization": {
        "from": "0xPAYER",
        "to": "0xRECIPIENT",
        "value": "100",
        "validAfter": "1730000000",
        "validBefore": "1730003600",
        "nonce": "0x..."
      },
      "signature": "0x..."
    }
  },
  "paymentRequirements": { }
}

Server: verify and settle

Call the facilitator:

• POST ${X402_FACILITATOR_URL}/verify with X-API-Key
• POST ${X402_FACILITATOR_URL}/settle with X-API-Key

If /verify returns isValid: true, call /settle.

Gotchas

• Invalid signature: EIP-712 domain name must be USD Coin, not USDC.
• Version mismatch: Use x402Version: 2 when network is eip155:8453.
• Nested payload: Do not wrap paymentPayload inside another paymentPayload.
• Recipient field: Facilitator expects payTo and asset.
• Address mismatch: authorization.from must match the signing address.
• Wrong chain: Ensure wallet is on Base (chainId 8453) before signing.

Example files

• app/api/secret/route.ts: builds payment requirements, verifies, settles
• app/secret/page.tsx: signs EIP-712 and sends X-402-Payment
• lib/facilitator.ts: verify and settle helpers with API key header