x402 top-up

Funding uses x402: an HTTP 402 challenge answered with an EIP-3009 exact payment in USDC on Base. Top-up requires a session, and the payer must match the signed-in wallet.

Flow

1. POST the desired amount:

curl -X POST "${PUBLIC_URL}/v1/x402/top-up" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{ "amountUsdc": 10000000 }'

2. With no payment attached, the server returns 402 with the requirements:

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "10000000",
    "payTo": "0x...",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 120,
    "extra": { "name": "USD Coin", "version": "2" }
  }],
  "amountUsdc": 10000000
}

3. Sign the EIP-3009 exact payment and build the base64 X-PAYMENT header.
4. Retry the same POST with X-PAYMENT. On success you get 200 and the top-up is recorded.

Amounts

Amounts are micro-USDC (1 USDC = 1,000,000).

	Value
Minimum	1,000,000 ($1)
Recommended	10,000,000 ($10)
Maximum	1,000,000,000 ($1,000)

Confirmation

Top-ups land as pending and confirm after the configured block depth (~20 blocks, ~40s on Base). Only confirmed balance funds inference. A reorg flips a pending top-up back out.

Payer must equal the session wallet

A payment from a different address than the signed-in wallet is rejected. Out-of-band transfers to the pay-to address are not credited.