x402 Accepts Preflight Decoder

When to use

Before any agent wallet signs or transfers USDC for an HTTP 402 (Payment Required) challenge — especially stranger endpoints, skill marketplaces, and x402 buy doors.

Goal

Decode accepts[] from a 402 response, validate Base USDC rails fail-closed, and decide pay / skip / abort without leaking keys or overpaying.

Inputs

• Raw HTTP status + JSON body from a 402 response (or WWW-Authenticate / payment challenge payload your client already parsed)
• Your intended max USDC (human units, e.g. 1.00)
• Expected network: eip155:8453 (Base)
• Expected asset: Base USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (6 decimals)

Fail-closed checks (abort if any fail)

1. Status is 402 (or client maps payment challenge equivalently).
2. accepts is a non-empty array.
3. Pick accepts[0] unless you have an explicit scheme match; do not silently pick a higher amount.
4. network / chainId resolves to Base (eip155:8453 / 8453).
5. Token/asset address equals Base USDC (case-insensitive checksum compare).
6. payTo is a 42-char 0x address (reject ENS, empty, or contract-unknown placeholders if your policy requires EOA-only).
7. amount is integer atomic USDC (6 decimals). Convert: human = Number(amount) / 1e6. Reject NaN, negative, or scientific notation strings you cannot parse.
8. human <= maxUsdc you set before the call.
9. Optional: maxTimeoutSeconds present and sane (< 600) if your settle path needs it.
10. Do not pay if the resource URL host is unexpected vs the door you opened.

Decode sketch (JS)

function preflight402(body, { maxUsdc = 1, expectUsdc = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' } = {}) {
  const accepts = body?.accepts;
  if (!Array.isArray(accepts) || !accepts.length) return { ok: false, reason: 'NO_ACCEPTS' };
  const a = accepts[0];
  const network = String(a.network || a.chainId || '');
  if (!/8453/.test(network) && network !== 'eip155:8453') return { ok: false, reason: 'BAD_NETWORK', network };
  const asset = String(a.asset || a.token || a.currency || '').toLowerCase();
  if (asset && asset !== expectUsdc.toLowerCase()) return { ok: false, reason: 'BAD_ASSET', asset };
  const payTo = String(a.payTo || a.to || '');
  if (!/^0x[a-fA-F0-9]{40}$/.test(payTo)) return { ok: false, reason: 'BAD_PAYTO', payTo };
  const atomic = BigInt(String(a.amount ?? a.maxAmountRequired ?? ''));
  const human = Number(atomic) / 1e6;
  if (!(human > 0) || human > maxUsdc) return { ok: false, reason: 'BAD_AMOUNT', human, maxUsdc };
  return { ok: true, payTo, human, atomic: atomic.toString(), network: 'eip155:8453', asset: expectUsdc };
}

After a clean preflight

1. Transfer exactly atomic USDC on Base to payTo (or follow the marketplace's documented x402 retry headers — often X-Payment-Response with tx hash).
2. Retry the same resource URL.
3. If still 402 with a different payTo or higher amount — abort (challenge drift).
4. Persist receipt/tx hash locally before claiming success.

Skip / abort heuristics

• Amount above your pre-set ceiling
• Non-Base network
• Non-USDC asset
• Missing accepts
• Host mismatch vs the listing you clicked
• Second 402 after a successful-looking transfer (possible facilitator lag — poll once; do not double-pay)

What this is not

Not a facilitator, not a wallet, not financial advice. It is a fail-closed decode + decision checklist for agent buyers.

Success criteria

You can explain in one line: network, asset, payTo, human USDC, and go/no-go — before any signature.