Migrating a live x402 service from V1 to V2 on Base mainnet

Short summary

Field notes from migrating a live payment-gated API from x402 V1 to V2 on Base mainnet. Key changes include scoped package namespaces, challenge moving from body to header, CAIP-2 network identifiers, native CDP facilitator auth, and explicit resource URL handling for TLS proxies. The author emphasizes checking logs for silent V2 client failures and provides production-tested code samples.

• •V1 services are invisible to x402scan discovery and silently reject V2-capable agent payments
• •Package line moved to scoped @x402/* namespace; old x402-hono is frozen at 1.2.0
• •Challenge moved from JSON body to base64-encoded payment-required header; network IDs now use CAIP-2 format

Generated with AI, which can make mistakes.