Overview

The x402 Facilitator is a production-ready server that implements the x402 payment protocol for multiple blockchain networks. It acts as a trusted third party that:

1. Verifies that a payment payload is cryptographically valid and meets the stated requirements.
2. Settles the payment on-chain by broadcasting the transaction.
3. Records per-client metrics for billing and observability.

Why a Facilitator?

The x402 protocol uses an HTTP 402 Payment Required flow. When a client hits a protected resource, the server returns payment requirements. The client constructs a signed payment payload and re-sends the request with that payload in the X-Payment header.

The resource server (your API) doesn't need to know how to talk to Base, Solana, or Cosmos - it delegates that complexity to the facilitator:

Client ──► Resource Server ──► Facilitator ──► Blockchain
              (your API)        (this server)

Key Capabilities

Capability	Details
Verification	Validates signatures, amounts, timeouts, and chain state
Settlement	Broadcasts signed transactions; returns tx hash and block number
Multi-chain	EVM (Base), Solana, Cosmos (Osmosis, CosmosHub, Noble)
Auth	JWT access + refresh tokens; scoped client API keys
Metrics	Per-client daily/monthly/summary roll-ups
Rate limiting	Configurable per-minute request limits
Admin API	User management, asset registry

Supported Assets

Chain	Asset	Symbol	Decimals	Settlement
Base	USDC	USDC	6	ERC-20 transfer
Solana	USDC	USDC	6	SPL transfer
Osmosis	USDC	USDC	6	IBC/native transfer
CosmosHub	USDC	USDC	6	IBC/native transfer
Noble	USDC	USDC	6	Native transfer

Architecture

┌──────────────┐    ┌──────────────────┐    ┌───────────────────────┐
│ Client Apps  │    │  Load Balancer   │    │   x402 Facilitator    │
│              │◄──►│  (Nginx/HAProxy) │◄──►│   (Gin + x402-go)    │
│ • Web Apps   │    │  • Rate Limiting │    │   • Verify / Settle   │
│ • AI Agents  │    │  • TLS           │    │   • Client Auth       │
│ • Services   │    └──────────────────┘    │   • Metrics           │
└──────────────┘                            └───────────┬───────────┘
                                                        │
                                         ┌──────────────┼──────────────┐
                                         ▼              ▼              ▼
                                    ┌─────────┐   ┌─────────┐   ┌──────────┐
                                    │Postgres │   │  Redis  │   │x402-go   │
                                    │         │   │  Cache  │   │(chainlib)│
                                    └─────────┘   └─────────┘   └────┬─────┘
                                                                      │
                                              ┌───────────────────────┼──────┐
                                              ▼                       ▼      ▼
                                         ┌────────┐           ┌────────┐ ┌───────┐
                                         │  EVM   │           │ Solana │ │Cosmos │
                                         │ (Base) │           │        │ │       │
                                         └────────┘           └────────┘ └───────┘

Tech Stack

• Language: Go 1.24+
• Framework: Gin HTTP framework
• Database: PostgreSQL 14+ (migrations via golang-migrate)
• Cache: Redis
• Chain library: x402-go - standalone Go library that handles EVM (EIP-3009), Solana (SPL), and Cosmos (MsgSend) verification and settlement
• Auth: JWT (access + refresh tokens), HMAC-signed client API keys

What's Next

• Quickstart - run the server in under 5 minutes.
• x402 Protocol - understand the payment flow end-to-end.
• Facilitator - deep-dive into configuration and deployment.
• API Reference - every endpoint documented.