x402-go Overview

x402-go is a Go implementation of the x402 protocol (v2) for verifiable on-chain payments. It enables payment-gated access to APIs using EIP-3009 TransferWithAuthorization for gasless token transfers on EVM chains.

What is x402?

The x402 protocol facilitates cryptographically verifiable payment transactions. It enables services to require and validate payments before granting resource access, using a facilitator to verify authorizations and submit settlement transactions. The protocol uses HTTP status code 402 (Payment Required) to signal payment requirements.

v2 Protocol

This implementation follows x402 protocol version 2. Key aspects:

• CAIP-2 network identifiers (e.g., eip155:8453 for Base, eip155:1 for Ethereum mainnet)
• EIP-3009 TransferWithAuthorization for gasless token transfers
• Transport headers: PAYMENT-SIGNATURE (client request), PAYMENT-REQUIRED (402 response), PAYMENT-RESPONSE (success response)
• Payment payload carries the accepted requirements and signed authorization as a base64-encoded JSON object

EIP-3009 TransferWithAuthorization

EIP-3009 enables gasless token transfers by allowing a token holder to authorize a transfer that can be executed by anyone. The payer signs an authorization off-chain, and the facilitator executes the on-chain transfer. This means:

• Payers sign off-chain; the facilitator submits the transaction and pays network gas fees
• The middleware buffers successful handler responses until settlement succeeds
• Authorization includes time windows for security

Payment settlement and off-chain work are not atomic. A handler may have side effects before settlement, and a settled payment does not guarantee that the client receives the response. Design retries and state changes accordingly.

CAIP-2 Network Identifiers

Networks are identified using the CAIP-2 standard:

Network	CAIP-2 ID
Ethereum mainnet	eip155:1
Base	eip155:8453
Base Sepolia	eip155:84532
Optimism	eip155:10

These identifiers do not enable networks by themselves. Configure the facilitator with an RPC endpoint and supported scheme for each network, and use a token that implements EIP-3009.

Transport Headers

Header	Direction	Description
PAYMENT-SIGNATURE	Client -> Server	Base64-encoded payment payload
PAYMENT-REQUIRED	Server -> Client	Base64-encoded payment requirements (on 402)
PAYMENT-RESPONSE	Server -> Client	Base64-encoded settlement response (on success)

Project Structure

x402-go/
├── cmd/
│   ├── facilitator/       # Facilitator service binary
│   └── x402cli/           # CLI tool for interacting with x402 resources
├── facilitator/           # Facilitator server, verification, and settlement logic
│   ├── client/            # Client library for interacting with a facilitator
│   └── config.example.yaml
├── resource/              # Resource server components
│   ├── client/            # Client library for accessing x402-protected resources
│   └── middleware/        # Gin middleware for protecting resources with x402
├── types/                 # Shared x402 protocol types
└── utils/                 # Shared utilities (EIP-712, CAIP-2 parsing, etc.)

Components

Facilitator Service

The backend payment processor that verifies and settles payments. It provides three main endpoints:

• GET /supported - Lists supported scheme-network combinations, extensions, and signer addresses
• POST /verify - Validates payment payloads against requirements
• POST /settle - Executes payments on-chain via EIP-3009 TransferWithAuthorization

Facilitator Client

A library for communicating with x402 facilitator services:

• Query supported payment schemes and networks
• Verify payment authenticity and validity
• Settle payments and obtain transaction confirmations

Resource Middleware

Gin-based middleware for protecting HTTP APIs with payment requirements:

• Drop-in Gin middleware for payment verification and settlement
• Flexible path protection using glob patterns
• Route-specific payment requirements
• Buffered response ensures payment before access
• Optional /.well-known/x402 discovery endpoint

Resource Client

Client library for accessing x402-protected resources with explicit control over the payment flow:

• Detect payment requirements
• Inspect requirements before deciding to pay
• Generate and sign EIP-3009 authorizations
• Send paid requests and return the HTTP response for the caller to inspect

The current Go resource client signs with the fixed EIP-712 domain name USDC and version 2. Use it only with a token whose domain matches; requirements.extra does not override these values. The CLI supports explicit domain settings.

CLI Tool

Command-line tool for interacting with x402-protected resources and facilitator services:

• Browse discovery endpoints
• Check payment requirements
• Generate and send payments
• Verify and settle via facilitator
• Generate ownership proofs

Discovery Endpoint

Resource servers can expose a /.well-known/x402 discovery endpoint that advertises protected resources:

{
  "version": 1,
  "resources": [
    "https://api.example.com/api/data",
    "https://api.example.com/api/premium"
  ],
  "ownershipProofs": ["0xabc123..."],
  "instructions": "This API provides premium data. Pay per request."
}

Payment Flow

1. FacilitatorClient requests resource -> Server returns 402 with payment requirements
2. FacilitatorClient inspects requirements -> Decides whether to pay
3. FacilitatorClient generates EIP-3009 authorization -> Signs with private key
4. FacilitatorClient sends request with PAYMENT-SIGNATURE header
5. Server verifies payment -> Validates signature, balance, amount, time window
6. Server executes handler -> Response is buffered
7. For a 2xx handler response, the server settles payment on-chain -> Calls TransferWithAuthorization
8. Server sends response with PAYMENT-RESPONSE header -> Contains transaction hash

Use Cases

• API Monetization - Require payment for API access without traditional subscription models
• Pay-per-Use Services - Charge users per request or resource access
• Content Gating - Require payment before serving premium content
• Microservices - Enable payment requirements between services
• AI Agent Commerce - Enable autonomous agents to pay for resources

Supported Schemes

Currently supported payment schemes:

• exact - Fixed-amount EIP-3009 TransferWithAuthorization

Source Code

View the source code and contribute on GitHub: vorpalengineering/x402-go

See the x402 specification for full protocol details.