payments: BaseUsdcAdapter (Base + USDC + x402)

[willgriffin]

Parent

#1027

What to build

BaseUsdcAdapter implementation of the PaymentBackend interface. Targets USDC on Base (Coinbase's L2).

This is the agent-friendly path: fast L2 finality, native x402 support, sub-cent fees, USD-pegged stable settlement.

Shape

• Stable id: base-usdc
• Settlement currency: USDC (treated 1:1 with USD)
• Chain identifier: base
• x402Capable: true
• Typical confirmation latency: ~2 seconds (1 L2 confirmation)
• supportsRefunds: true (via reverse transfer)

Implementation details:

• Reads Base via an RPC provider (Alchemy or Infura free tier covers MVP)
• Subscribes to Transfer(address indexed from, address indexed to, uint256 value) events on the canonical Base USDC contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, filtered to operator's receiving addresses
• HD-derived child addresses per quote (BIP32 from a single operator-controlled master xpub; the master private key lives in cold-treasury Safe)
• Sweep helper to consolidate child balances into the hot wallet
• x402 verification: parses an X-Payment header (USDC transfer proof on Base) and confirms on-chain in the same request
• Payout: programmatic send from the operator's hot wallet to the supplier's payout address

Acceptance criteria

• BaseUsdcAdapter implements PaymentBackend and passes the conformance test suite from payments: new package skeleton + PaymentBackend interface #1028
• Watch path detects an incoming Transfer to a known quote address and surfaces it
• x402 proof verification works against a real Base USDC transfer (mainnet or testnet equivalent)
• HD-derived addresses are deterministic given the master xpub and a quote id
• Refund path can return a payment to the original sender
• Tests do not require live RPC for the bulk of the suite (use mocked RPC); a small integration suite hits a public RPC

Blocked by

• payments: new package skeleton + PaymentBackend interface #1028 (@happyvertical/payments package + interface)

[peterxing]

I put together a scoped implementation packet for this one, since it is now directly downstream of #1032 and can be planned against a concrete PaymentBackend interface rather than a moving target:

https://farmbot-platform-mvp.pages.dev/hire-agent/happyvertical-base-usdc-adapter/

The useful split I’d suggest for #1029:

1. Mock-first adapter seam — implement BaseUsdcAdapter against feat: add payments backend interface package #1032 with deterministic quote/address fixtures, mocked Base USDC Transfer logs, and no live RPC requirement in CI.
2. x402 proof boundary — keep X-Payment parsing, replay/idempotency checks, and on-chain confirmation as explicit seams instead of mixing them into the watch path.
3. Opt-in integration gate — one small public-RPC smoke test for Base USDC only when env is present; default tests stay offline.
4. Refund/hot-wallet safety notes — document what metadata is enough to support refunds without requiring private keys or hot-wallet authority in normal tests.

If useful, Peter/OpenClaw can do either a fixed A$690 readiness packet (acceptance matrix + test plan + PR decomposition) or a fuller A$2,400 implementation room for the adapter skeleton, mock tests, docs, and maintainer-ready PR plan. Payment can be USDC on Base/Polygon or invoice after scope confirmation.

No wallet signing, live transfer, RPC secret, private key, or hot-wallet access is needed for the readiness packet.

[willgriffin]

Closed by #1033. BaseUsdcAdapter shipped at packages/payments/src/adapters/base-usdc.ts with test coverage in base-usdc.test.ts.