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, creating a trustless payment verification system. 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 spender 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 don't need ETH for gas
• Payments can be settled atomically with resource access
• Authorization includes time windows for security

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

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
• Execute paid requests with settlement confirmation

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. Client requests resource -> Server returns 402 with payment requirements
2. Client inspects requirements -> Decides whether to pay
3. Client generates EIP-3009 authorization -> Signs with private key
4. Client sends request with PAYMENT-SIGNATURE header
5. Server verifies payment -> Validates signature, balance, amount, time window
6. Server executes handler -> Response is buffered
7. 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.