Go live with x402 + Coinbase CDP

The checkout core is zero-dependency — it never imports a chain library. To settle real USDC it does the cheap, structural part itself (verify the EIP-3009 envelope matches the quote) and hands the on-chain tail to an injected Facilitator that owns the viem / Coinbase CDP code. This guide takes you from a testnet settle to a live mainnet one, with the traps that bite everyone called out explicitly.

How settlement splits

agent ──signed EIP-3009 transferWithAuthorization──▶  POST /agent/checkout/{id}/settle
                                                          │
                          SDK x402 rail (zero-dep)        │  structural verify:
                          ├─ to === payTo                 │  value === amountBaseUnits
                          └─ validBefore in the future    │  signature present
                                                          ▼
                          injected Facilitator (your viem/CDP code)
                          ├─ ecrecover signer === authorization.from
                          └─ broadcast → CONFIRMED on-chain txHash  ◀── authoritative

The split is deliberate: the SDK stays installable with nothing, and all the secret-bearing, network-touching crypto lives in your facilitator where the dependencies already are.

1. Configure the x402 rail

import { createCheckout, x402Rail, BALANCED } from '@veto-protocol/checkout';

const checkout = createCheckout({
  merchant: { id: 'acme', name: 'Acme', domain: 'shop.acme.example' },
  catalog: [/* … */],
  receiving: { x402: { chain: 'base-sepolia', address: '0xYourReceivingAddr…', asset: 'USDC' } },
  policy: BALANCED(),
  rails: [x402Rail({ facilitator: myFacilitator })], // inject the on-chain settler
});

Start with chain: 'base-sepolia' (testnet). You'll flip it to base in the cutover.

2. The facilitator contract

A Facilitator receives the already-structurally-validated envelope plus the quote it must match, does the real verify + settle, and returns the outcome. It must never throw for an expected on-chain failure — it returns ok: false with reason codes so the gate can surface them as a clean 402 the agent can act on.

import type { Facilitator } from '@veto-protocol/checkout';

const myFacilitator: Facilitator = {
  async settle({ payment, requirement, session }) {
    // 1. resolve the network from requirement.chain (else UNSUPPORTED_CHAIN — never guess)
    // 2. ecrecover the EIP-3009 signer; assert it === authorization.from (else SIGNER_MISMATCH)
    // 3. broadcast transferWithAuthorization via CDP, idempotencyKey = the EIP-3009 nonce
    // 4. return the CONFIRMED txHash as the AUTHORITATIVE reference
    return { ok: true, txHash: '0x…', reasonCodes: ['OK'] };
  },
};

Coinbase ships the heavy lifting. The reference CDP facilitator wraps @coinbase/x402 + @x402/core, mints a per-request CDP JWT, and broadcasts transferWithAuthorization. You provide CDP_API_KEY_ID and CDP_API_KEY_SECRET; everything below is about getting the details right.

3. The traps (these are the ones that actually bite)

These are ported verbatim from a proven end-to-end harness. Each one fails silently if you get it wrong — a transfer that looks signed but never authorizes, or a "failure" that already moved money. Treat them as load-bearing.

Trap 1 — the EIP-712 domain name: "USD Coin" vs "USDC"

USDC reports a different EIP-712 domain name per chain:

If you sign (or verify) transferWithAuthorization with the wrong domain name, the signature recovers to the wrong address and the transfer silently fails to authorize.

Trap 2 — the txHash is authoritative; never blind-retry

The facilitator can report success: false while the transaction still confirms on-chain, or throw an error that nonetheless carries a txHash (broadcast happened, confirmation timed out). The rule:

• If a txHash exists, value moved (or is moving) — return it regardless of the success flag, and flag the outcome as "verify on-chain."
• Never auto-retry when a hash exists. A fresh broadcast risks a double-pay.

// On an ambiguous facilitator response:
if (txHash) {
  return { ok: false, txHash, reasonCodes: ['SETTLEMENT_FAILED'] /* verify the chain; do NOT retry */ };
}

Trap 3 — idempotency = the EIP-3009 nonce

Use the EIP-3009 nonce as the settle idempotency key. The USDC contract tracks authorizationState[from][nonce], so a given signed authorization settles at most once — a replay is a chain no-op, not a double-pay. This is also why a re-submitted settle is safe.

Trap 4 — integer base units, never floats

USDC has 6 decimals: $0.01 == 10000 base units. Do all amount math in integer/string base units. The quote carries amountBaseUnits as an exact string — settle against that, never a re-derived float.

4. Settle on testnet first

Stay on Base Sepolia until a real testnet USDC transfer confirms end to end.

CDP_API_KEY_ID=…
CDP_API_KEY_SECRET=…
X402_NETWORK=base-sepolia   # default; the live rail reads this when receiving pins no chain

https://sepolia.basescan.org/tx/<txHash>

5. The mainnet cutover

Once a Sepolia settle confirms cleanly, flip to Base mainnet:

receiving: { x402: { chain: 'base', address: '0xYourMainnetReceivingAddr…', asset: 'USDC' } }

Facilitator failure modes

When settlement fails, the facilitator surfaces a specific reason code. These appear only with a real injected facilitator — the default mock does structural validation and never emits them:

Go-live checklist

Then verify the receipt it produced and you're live.