x402-go-demo

A reference implementation of the x402 Payment Protocol in Go, demonstrating how HTTP 402 "Payment Required" enables machine-to-machine micropayments.

What is x402?

x402 is an open protocol that brings the HTTP 402 status code to life. It enables:

• Autonomous agent payments: AI agents can pay for API access without human intervention
• Micropayments: Pay-per-request pricing models (e.g., $0.01 per API call)
• Blockchain settlement: Payments settle on-chain using stablecoins like USDC

The protocol was developed by Coinbase to enable a new economy of paid APIs where machines transact directly with each other.

What This Demo Does

This is a complete working example showing the x402 payment flow:

┌──────────────────┐                              ┌──────────────────┐
│                  │  1. GET /premium-data        │                  │
│   Client         │ ───────────────────────────> │   Server         │
│   (Payer)        │                              │   (Payee)        │
│                  │  2. 402 Payment Required     │                  │
│                  │ <─────────────────────────── │                  │
│                  │     + payment requirements   │                  │
│                  │                              │                  │
│   Signs payment  │  3. GET + X-Payment header   │   Verifies &     │
│   authorization  │ ───────────────────────────> │   settles via    │
│                  │                              │   Facilitator    │
│                  │  4. 200 OK + premium data    │                  │
│                  │ <─────────────────────────── │                  │
│                  │     + X-Payment-Response     │                  │
└──────────────────┘                              └──────────────────┘

Components included:

• cmd/server/ - HTTP server with x402 middleware protecting endpoints
• cmd/client/ - CLI client that handles 402 responses and makes payments
• pkg/x402/ - Core types, middleware, and encoding utilities
• pkg/wallet/ - Mock wallet for signing payment authorizations
• pkg/facilitator/ - Mock facilitator for verify/settle operations

Note: This demo uses mock implementations for wallet signing and payment settlement. In production, you would integrate with real blockchain wallets and the Coinbase x402 facilitator service.

Quick Start

Prerequisites

• Go 1.21+

Build

go build ./...

Run the Demo

Terminal 1 - Start the server:

go run ./cmd/server

You'll see:

===========================================
x402 Demo Server starting on http://localhost:8080
===========================================

Endpoints:
  GET /          - Service info (free)
  GET /health    - Health check (free)
  GET /premium-data - Protected (requires payment)

Price: 10000 wei USDC on base-sepolia

Terminal 2 - Run the client:

go run ./cmd/client

The client will:

1. Request the protected endpoint (gets 402)
2. Parse payment requirements from the response
3. Sign a payment authorization
4. Retry with the X-Payment header
5. Receive the premium data

Test with curl

# Free endpoints
curl http://localhost:8080/
curl http://localhost:8080/health

# Protected endpoint (returns 402 without payment)
curl -i http://localhost:8080/premium-data

Protocol Details

402 Response Format

When a client requests a protected resource without payment:

{
  "x402Version": 1,
  "error": "Payment required to access this resource",
  "accepts": [{
    "scheme": "exact",
    "network": "base-sepolia",
    "maxAmountRequired": "10000",
    "resource": "http://localhost:8080/premium-data",
    "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "maxTimeoutSeconds": 60,
    "mimeType": "application/json",
    "description": "Access to premium data endpoint"
  }]
}

X-Payment Header

The client sends payment as a base64-encoded JSON payload:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base-sepolia",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x742d35Cc...",
      "to": "0x209693Bc...",
      "value": "10000",
      "validAfter": "1701648000",
      "validBefore": "1701648300",
      "nonce": "0x..."
    }
  }
}

X-Payment-Response Header

On successful payment, the server returns settlement details:

{
  "success": true,
  "transaction": "0xabc123...",
  "network": "base-sepolia",
  "payer": "0x742d35Cc..."
}

Configuration

Setting	Value	Description
Server Port	:8080	HTTP server port
Price	10000	0.01 USDC (6 decimals)
Network	base-sepolia	Target blockchain
USDC Address	0x036CbD53842c5426634e7929541eC2318f3dCF7e	Base Sepolia USDC

Project Structure

x402-go-demo/
├── cmd/
│   ├── server/main.go      # HTTP server with protected endpoints
│   └── client/main.go      # CLI client demonstrating payment flow
├── pkg/
│   ├── x402/
│   │   ├── types.go        # Protocol types (PaymentPayload, etc.)
│   │   ├── constants.go    # x402Version, header names
│   │   ├── encoding.go     # Base64 encode/decode helpers
│   │   └── middleware.go   # HTTP middleware for 402 enforcement
│   ├── wallet/
│   │   └── mock_wallet.go  # Mock wallet for signing
│   └── facilitator/
│       ├── mock_server.go  # Mock verify/settle implementation
│       └── client.go       # HTTP client for facilitator API
├── go.mod
├── Makefile
└── README.md

Extending This Demo

To use this with real payments:

1. Replace MockWallet - Integrate with a real Ethereum wallet (e.g., go-ethereum)
2. Replace MockFacilitator - Point to the Coinbase x402 facilitator service
3. Add real signature verification - Implement EIP-712 typed data signing

Resources

• x402 Protocol Specification
• x402 Documentation
• Coinbase x402 GitHub
• Coinbase Developer Platform

License

MIT