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 x402-go

Upstream Synchronization

This repository contains a subset of the x402 repository. To pull the latest changes from upstream while preserving your local modifications:

./sync_upstream.sh

This script will:

1. Configure the upstream remote if needed
2. Fetch the latest changes
3. Merge the go directory from upstream into your current branch using git subtree logic
4. Handle merge conflicts via standard git mechanisms

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

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

• CLIENT.md - Building payment-enabled clients
• SERVER.md - Building payment-accepting servers
• FACILITATOR.md - Building payment facilitators

Component Documentation

• signers/ - Signer helper utilities
• mechanisms/evm/ - EVM payment mechanisms
• mechanisms/svm/ - SVM payment mechanisms
• extensions/ - Protocol extensions

Examples

• examples/go/clients/ - Client implementation examples
• examples/go/servers/ - Server implementation examples
• examples/go/facilitator/ - Facilitator example

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.