Skip to content

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

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)

Filev1 ImportsKey Usage
internal/x402/config.gox402lib (root)ChainConfig constants (BaseMainnet, BaseSepolia, PolygonMainnet, etc.), ResolveChain()
internal/x402/verifier.gox402lib (root), x402httpNewUSDCPaymentRequirement(), NewX402Middleware() (ForwardAuth)
internal/x402/buyer/signer.gox402 (root)Implements x402.Signer interface (7 methods), uses PaymentRequirement, PaymentPayload, EVMPayload, EVMAuthorization, TokenConfig, ErrNoValidSigner
internal/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)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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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