Context
The stack pins github.com/mark3labs/x402-go v0.13.0 (legacy v1 SDK). The official Go SDK inside coinbase/x402 is now at v2.7.0 with a complete rewrite. The v1 API surface has been moved to /legacy subfolders upstream and will eventually go stale.
Additionally, the repo is being renamed from coinbase/x402 → x402-foundation/x402 (#1912), which will eventually break the Go module path.
Current v1 Usage (6 production files + tests)
| File |
v1 Imports |
Key Usage |
internal/x402/config.go |
x402lib (root) |
ChainConfig constants (BaseMainnet, BaseSepolia, PolygonMainnet, etc.), ResolveChain() |
internal/x402/verifier.go |
x402lib (root), x402http |
NewUSDCPaymentRequirement(), NewX402Middleware() (ForwardAuth) |
internal/x402/buyer/signer.go |
x402 (root) |
Implements x402.Signer interface (7 methods), uses PaymentRequirement, PaymentPayload, EVMPayload, EVMAuthorization, TokenConfig, ErrNoValidSigner |
internal/x402/buyer/proxy.go |
x402 (root), encoding |
PaymentSelector, PaymentCallback, PaymentEvent, NewDefaultPaymentSelector(), NewPaymentError(), encoding.EncodePayment(), encoding.DecodeSettlement() |
internal/inference/gateway.go |
x402 (root), x402http |
ChainConfig, NewUSDCPaymentRequirement(), NewX402Middleware() |
cmd/obol/sell.go |
x402 (root) |
Chain validation references |
v2 Changes Relevant to the Stack
High Priority
- Go SDK v2 full rewrite — new architecture: mechanisms (EVM/SVM), extensions, hooks, builders. Module path:
github.com/coinbase/x402/go
- validAfter timing — EIP-3009 buffer increased 30s → 10min, fixes edge-case payment rejections
- HTTPFacilitatorClient 308 redirect fix — broken redirects could cause silent verification failures
- ERC-1271 / ERC-6492 smart contract wallet signatures — needed for EIP-7702 / Safe wallets
Medium Priority
- Payment-identifier extension — idempotent payments, prevents duplicate settlement
- Extensions field on VerifyResponse/SettleResponse — new metadata from facilitator
- New chains: Polygon (137), Arbitrum One (42161), Arbitrum Sepolia (421614), MegaETH (4326), Stable (988/2201), Monad (143)
Low Priority (future)
- Permit2 / Upto scheme support
- MCP transport integration
- Bazaar dynamic routing
Migration Surface
Types
ChainConfig → evm.NetworkConfig (CAIP-2 format: "eip155:8453")
PaymentRequirement → types.PaymentRequirements (MaxAmountRequired → Amount, Resource → ResourceInfo)
PaymentPayload → types.PaymentPayload (scheme/network move inside Accepted)
EVMPayload / EVMAuthorization → evm.ExactEIP3009Payload / ExactEIP3009Authorization
Interfaces
x402.Signer (7 methods) → SchemeNetworkClient + ClientEvmSigner
x402.PaymentSelector → built into x402Client.SelectPaymentRequirements()
x402http.NewX402Middleware() → http.NewServer() with RoutesConfig
Encoding
encoding.EncodePayment() / encoding.DecodeSettlement() — need v2 equivalents or inline
Approach
- Phase 1: Add
github.com/coinbase/x402/go v2 to go.mod, coexist with v1 via aliased imports
- Phase 2: Migrate
internal/x402/config.go (chain constants → CAIP-2)
- Phase 3: Migrate verifier (
NewX402Middleware → http.NewServer)
- Phase 4: Migrate buyer signer + proxy (Signer interface, encoding, PaymentSelector)
- Phase 5: Migrate standalone inference gateway
- Phase 6: Remove
mark3labs/x402-go from go.mod
Each phase should be a separate commit, all in one PR.
Context
The stack pins
github.com/mark3labs/x402-go v0.13.0(legacy v1 SDK). The official Go SDK insidecoinbase/x402is now at v2.7.0 with a complete rewrite. The v1 API surface has been moved to/legacysubfolders upstream and will eventually go stale.Additionally, the repo is being renamed from
coinbase/x402→x402-foundation/x402(#1912), which will eventually break the Go module path.Current v1 Usage (6 production files + tests)
internal/x402/config.gox402lib(root)ChainConfigconstants (BaseMainnet,BaseSepolia,PolygonMainnet, etc.),ResolveChain()internal/x402/verifier.gox402lib(root),x402httpNewUSDCPaymentRequirement(),NewX402Middleware()(ForwardAuth)internal/x402/buyer/signer.gox402(root)x402.Signerinterface (7 methods), usesPaymentRequirement,PaymentPayload,EVMPayload,EVMAuthorization,TokenConfig,ErrNoValidSignerinternal/x402/buyer/proxy.gox402(root),encodingPaymentSelector,PaymentCallback,PaymentEvent,NewDefaultPaymentSelector(),NewPaymentError(),encoding.EncodePayment(),encoding.DecodeSettlement()internal/inference/gateway.gox402(root),x402httpChainConfig,NewUSDCPaymentRequirement(),NewX402Middleware()cmd/obol/sell.gox402(root)v2 Changes Relevant to the Stack
High Priority
github.com/coinbase/x402/goMedium Priority
Low Priority (future)
Migration Surface
Types
ChainConfig→evm.NetworkConfig(CAIP-2 format:"eip155:8453")PaymentRequirement→types.PaymentRequirements(MaxAmountRequired→Amount,Resource→ResourceInfo)PaymentPayload→types.PaymentPayload(scheme/network move insideAccepted)EVMPayload/EVMAuthorization→evm.ExactEIP3009Payload/ExactEIP3009AuthorizationInterfaces
x402.Signer(7 methods) →SchemeNetworkClient+ClientEvmSignerx402.PaymentSelector→ built intox402Client.SelectPaymentRequirements()x402http.NewX402Middleware()→http.NewServer()withRoutesConfigEncoding
encoding.EncodePayment()/encoding.DecodeSettlement()— need v2 equivalents or inlineApproach
github.com/coinbase/x402/gov2 togo.mod, coexist with v1 via aliased importsinternal/x402/config.go(chain constants → CAIP-2)NewX402Middleware→http.NewServer)mark3labs/x402-gofromgo.modEach phase should be a separate commit, all in one PR.