How It Works

The x402 Protocol

x402 is a standard for machine-to-machine API payments using HTTP status code 402 (Payment Required).

Flow

1. Agent → API:  GET /api/data
2. API → Agent:  402 Payment Required
                 Headers: payment-required (base64 JSON)
                 {
                   "payTo": "0x...",
                   "network": "eip155:8453",
                   "maxAmountRequired": "0.001",
                   "asset": "USDC"
                 }
3. Agent:        Signs EIP-3009 authorization
4. Agent → API:  GET /api/data + payment proof header
5. API → Agent:  200 OK + data

x402 Relay’s Role

Phase 1: Directory (Current)

x402 Relay acts as a catalog and discovery layer:

Crawls the internet for x402-enabled APIs (via x402scan, GitHub, manifest files)
Indexes services with metadata (pricing, chains, categories)
Scores trustworthiness (protocol compliance, uptime, on-chain history)
Serves the catalog via REST API and MCP

Agents discover APIs through x402 Relay, then interact with them directly.

Phase 2: Payment Facilitator (Planned)

x402 Relay will also act as a payment proxy:

Agent sends URL + budget to x402 Relay
x402 Relay handles the 402 flow on behalf of the agent
Agent receives the API response without managing wallets

Discovery Engine

Data Sources

Source	Method	Coverage
x402scan	API polling	Base chain x402 endpoints
GitHub Scanner	Code search	Open-source x402 implementations
Manifest Scanner	`ai.txt` / `x402.json`	Self-declared API metadata
Prober v1	Direct HTTP probe	Protocol compliance verification
Prober v2	Deep header analysis	Payment parameter extraction

Trust Score

Each service receives a trust score (0-100) based on:

Factor	Weight	Description
Protocol compliance	30%	Valid 402 response with correct headers
Uptime	25%	Historical availability
On-chain activity	25%	Transaction count and volume
Community signals	20%	GitHub stars, usage metrics

Services are classified as:

verified (score ≥ 70) — Confirmed x402 support
unverified — Discovered but not yet validated
inactive — Previously active, now unreachable