Skip to content

chore: migrate x402-go from mark3labs v0.13.0 to coinbase/x402/go v2 #326

@bussyjd

Description

@bussyjd

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/x402x402-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

  • ChainConfigevm.NetworkConfig (CAIP-2 format: "eip155:8453")
  • PaymentRequirementtypes.PaymentRequirements (MaxAmountRequiredAmount, ResourceResourceInfo)
  • PaymentPayloadtypes.PaymentPayload (scheme/network move inside Accepted)
  • EVMPayload / EVMAuthorizationevm.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

  1. Phase 1: Add github.com/coinbase/x402/go v2 to go.mod, coexist with v1 via aliased imports
  2. Phase 2: Migrate internal/x402/config.go (chain constants → CAIP-2)
  3. Phase 3: Migrate verifier (NewX402Middlewarehttp.NewServer)
  4. Phase 4: Migrate buyer signer + proxy (Signer interface, encoding, PaymentSelector)
  5. Phase 5: Migrate standalone inference gateway
  6. Phase 6: Remove mark3labs/x402-go from go.mod

Each phase should be a separate commit, all in one PR.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions