Ryan R. Fox 484030b21e
chore(paywall): regenerate bundle + add recurrence guard (#2054)
The committed @x402/paywall bundle on main was last generated against an
older viem than the lockfile currently pins. pnpm install --frozen-lockfile
resolves viem 2.47.12 (via #2013), but the bundled src/evm/gen/template.ts
(and its Python + Go siblings) were built against an earlier resolution
that pre-dated chain definitions for Mezo, MegaETH, Stable, Radius (each
with a testnet variant), and 33 others. EvmPaywall.tsx throws
"Unsupported chain ID" at init for any eip155:<id> whose chain isn't in
the bundled viem/chains.

This PR:
  1. Regenerates all nine auto-generated template files (TypeScript,
     Python, and Go for EVM/SVM/AVM) against the current lockfile. No
     source changes on any runtime path.
  2. Teaches build:paywall to emit output matching the repo's formatters
     (prettier / ruff), so generated files stay clean under pnpm run
     format + uvx ruff format.
  3. Adds a PR-time drift check
     (.github/workflows/check_paywall_template.yml) so a future lockfile
     or @x402/evm change that invalidates the bundle fails loudly
     instead of shipping silently.

Scope is limited to @x402/paywall because it is the only package in this
repo that bakes viem chain definitions into a built artifact.

Verified on a fork-internal test PR running on ubuntu-latest
(Node 24, pnpm 10.7.0): check_format, check_lint, check_go, check_python,
check_package_lock, and the new check_paywall_template drift check all
pass. Additional local evidence:

  - Chain-presence in regenerated bundle: Mezo 31612/31611, MegaETH
    4326/6343, Stable 988/2201, Radius 723487/72344, Base/Arbitrum/
    Polygon all present (mainnet/testnet ordering).
  - Cross-platform determinism: a clean-slate rebuild on macOS produces
    byte-identical output to ubuntu-latest CI.
  - Tarball install into a throwaway consumer: all expected chain IDs
    present in the published dist/esm/evm/index.js.
  - Browser smoke test (Chrome, served from a local HTTP server):
    EvmPaywall mounts without Unsupported-chain throw for
    eip155:31611 (Mezo Testnet) and eip155:723487 (Radius); DOM
    renders the expected token/chain labels.

Fixes #1971.
2026-04-26 22:47:13 +09:00
..
2026-04-14 07:57:19 -07:00
2025-12-11 07:41:57 -08:00
2026-02-25 16:03:50 -08:00
2025-12-11 07:41:57 -08:00
2025-12-11 07:41:57 -08:00
2026-04-14 02:10:33 +09:00
2025-12-11 07:41:57 -08:00
2026-04-14 02:10:33 +09:00
2025-12-11 07:41:57 -08:00
2025-12-11 07:41:57 -08:00

x402 Go Package

Go implementation of the x402 protocol - a standard for HTTP 402 Payment Required responses with cryptocurrency micropayments.

What is x402?

x402 is a protocol that enables HTTP resources to require cryptocurrency payments. When a client requests a paid resource, the server responds with 402 Payment Required along with payment details. The client creates a payment, retries the request, and receives the resource after successful payment verification and settlement.

Installation

go get github.com/x402-foundation/x402/go

What This Package Exports

This package provides modules to support the x402 protocol in Go applications.

Core Classes

The package exports three core types that can be used by clients, servers, and facilitators:

  • x402.X402Client - Creates payment payloads for clients making paid requests
  • x402.X402ResourceServer - Verifies payments and builds requirements for servers accepting payments
  • x402.X402Facilitator - Verifies and settles payments for facilitator services

These core classes are framework-agnostic and can be used in any context (HTTP, gRPC, WebSockets, CLI tools, etc.).

HTTP Transport Wrappers

The package exports HTTP-specific wrappers around the core classes:

  • x402http.HTTPClient - Wraps http.Client with automatic payment handling for clients
  • x402http.HTTPServer - Integrates resource server with HTTP request processing
  • x402http.HTTPFacilitatorClient - HTTP client for calling facilitator endpoints

These wrappers handle HTTP-specific concerns like headers, status codes, and request/response serialization.

Middleware for Servers

Framework-specific middleware packages for easy server integration:

  • http/gin - Gin framework middleware

Additional framework middleware can be built using the HTTP transport wrappers as a foundation.

Client Helper Packages

Helper packages to simplify client implementation:

  • signers/evm - EVM signer helpers (creates signers from private keys)
  • signers/svm - SVM signer helpers (creates signers from private keys)

These eliminate 95-99% of boilerplate code for creating signers.

Mechanism Implementations (Schemes)

Payment scheme implementations that can be registered by clients, servers, and facilitators:

  • mechanisms/evm/exact - Ethereum/Base exact payment using EIP-3009

    • client/ - Client-side payment creation
    • server/ - Server-side payment verification
    • facilitator/ - Facilitator-side payment settlement
  • mechanisms/svm/exact - Solana exact payment using token transfers

    • client/ - Client-side payment creation
    • server/ - Server-side payment verification
    • facilitator/ - Facilitator-side payment settlement

Each role (client, server, facilitator) has its own mechanism implementation with appropriate functionality for that role.

Extensions

Protocol extension implementations:

  • extensions/bazaar - API discovery extension for making resources discoverable

Architecture

The package is designed with extreme modularity:

Layered Design

┌─────────────────────────────────────────┐
│         Your Application                │
└─────────────────────────────────────────┘
                  │
       ┌──────────┼──────────┐
       ▼          ▼          ▼
  [Client]   [Server]  [Facilitator]
       │          │          │
       ▼          ▼          ▼
┌─────────────────────────────────────────┐
│      HTTP Layer (Optional)              │
│  - HTTPClient wrapper                   │
│  - HTTPResourceServer                   │
│  - Middleware (Gin, etc.)               │
└─────────────────────────────────────────┘
                  │
       ┌──────────┼──────────┐
       ▼          ▼          ▼
┌─────────────────────────────────────────┐
│    Core Classes (Framework-Agnostic)    │
│  - X402Client                           │
│  - X402ResourceServer                   │
│  - X402Facilitator                      │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│         Mechanisms (Pluggable)          │
│  - EVM exact (client/server/facil.)    │
│  - SVM exact (client/server/facil.)    │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│         Signers (Helpers)               │
│  - EVM client signers                   │
│  - SVM client signers                   │
└─────────────────────────────────────────┘

Key Design Principles

  1. Framework-Agnostic Core - The core client/server/facilitator classes work independently of HTTP or any web framework

  2. HTTP as a Layer - HTTP functionality is isolated in the http package, making the core reusable for other transports

  3. Pluggable Mechanisms - Payment schemes are modular and can be registered independently by clients, servers, and facilitators

  4. Middleware Wraps Core - Framework middleware (like Gin) internally uses the core primitives, keeping framework concerns separate

This architecture enables:

  • Using core classes in non-HTTP contexts (gRPC, WebSockets, message queues)
  • Building custom middleware for any framework
  • Registering different mechanisms for different roles
  • Mixing and matching components as needed

Documentation by Role

This package serves three distinct roles. Choose the documentation for what you're building:

🔵 CLIENT.md - Building Payment-Enabled Clients

For applications that make requests to payment-protected resources.

Topics covered:

  • Creating payment-enabled HTTP clients
  • Registering payment mechanisms
  • Using signer helpers
  • Lifecycle hooks and error handling
  • Advanced patterns (concurrency, retry logic, custom transports)

See also: examples/go/clients/

🟢 SERVER.md - Building Payment-Accepting Servers

For services that protect resources with payment requirements.

Topics covered:

  • Protecting HTTP endpoints with payments
  • Route configuration and pattern matching
  • Using middleware (Gin and custom implementations)
  • Dynamic pricing and dynamic payment routing
  • Verification and settlement handling
  • Extensions (Bazaar discovery)

See also: examples/go/servers/

🟡 FACILITATOR.md - Building Payment Facilitators

For payment processing services that verify and settle payments.

Topics covered:

  • Payment signature verification
  • On-chain settlement
  • Lifecycle hooks for logging and metrics
  • Blockchain interaction
  • Production deployment considerations
  • Monitoring and alerting

See also: examples/go/facilitator/, e2e/facilitators/go/

Package Structure

github.com/x402-foundation/x402/go
│
├── Core (framework-agnostic)
│   ├── client.go              - x402.X402Client
│   ├── server.go              - x402.X402ResourceServer
│   ├── facilitator.go         - x402.X402Facilitator
│   ├── types.go               - Core types
│   └── *_hooks.go             - Lifecycle hooks
│
├── http/                      - HTTP transport layer
│   ├── http.go                - Type aliases and convenience functions
│   ├── client.go              - HTTP client wrapper
│   ├── server.go              - HTTP server integration
│   ├── facilitator_client.go  - Facilitator HTTP client
│   └── gin/                   - Gin middleware
│
├── mechanisms/                - Payment schemes
│   ├── evm/exact/
│   │   ├── client/            - EVM client mechanism
│   │   ├── server/            - EVM server mechanism
│   │   └── facilitator/       - EVM facilitator mechanism
│   └── svm/exact/
│       ├── client/            - SVM client mechanism
│       ├── server/            - SVM server mechanism
│       └── facilitator/       - SVM facilitator mechanism
│
├── signers/                   - Signer helpers
│   ├── evm/                   - EVM client signers
│   └── svm/                   - SVM client signers
│
├── extensions/                - Protocol extensions
│   └── bazaar/                - API discovery
│
└── types/                     - Type definitions
    ├── v1.go                  - V1 protocol types
    ├── v2.go                  - V2 protocol types
    ├── helpers.go             - Version detection utilities
    ├── raw.go                 - Raw type handling
    └── extensions.go          - Extension type definitions

Supported Networks

EVM (Ethereum Virtual Machine)

All EVM-compatible chains using CAIP-2 identifiers:

  • Ethereum Mainnet (eip155:1)
  • Base Mainnet (eip155:8453)
  • Base Sepolia (eip155:84532)
  • Optimism, Arbitrum, Polygon, and more

Use eip155:* wildcard to support all EVM chains.

SVM (Solana Virtual Machine)

All Solana networks using CAIP-2 identifiers:

  • Solana Mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
  • Solana Devnet (solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1)
  • Solana Testnet (solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z)

Use solana:* wildcard to support all Solana networks.

Supported Schemes

Exact Payment

Transfer an exact amount to access a resource:

  • EVM: Uses EIP-3009 transferWithAuthorization (USDC compatible tokens)
  • SVM: Uses Solana token transfers (USDC SPL token)

Features

  • ✅ Protocol v2 with v1 backward compatibility
  • ✅ Multi-chain support (EVM and SVM)
  • ✅ Modular architecture - use core primitives directly or with helpers
  • ✅ Type safe with strong typing throughout
  • ✅ Framework agnostic core
  • ✅ Concurrent safe operations
  • ✅ Context-aware with proper cancellation support
  • ✅ Extensible plugin architecture
  • ✅ Production ready with comprehensive testing
  • ✅ Lifecycle hooks for customization

Package Documentation

Core Documentation

Component Documentation

Examples

Testing

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run integration tests
go test ./test/integration/...

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

Apache 2.0 - See LICENSE for details.