How It Works

x402 protocol flow

Agent → GET /api/data → Server
Agent ← 402 Payment Required (price, network) ← Server
Agent → signs USDC transfer on Base
Agent → GET /api/data + X-402-Payment header → Server
Agent ← 200 OK (data) ← Server

The payment is a USDC transfer on Base, signed by the agent's wallet and verified by the server via the 402.md API.

PROXY vs TICKET modes

402.md supports two verification modes for API skills:

PROXY mode

The agent's request is forwarded through 402.md's infrastructure:

Agent → 402.md proxy → Developer's API
Agent ← response ← 402.md proxy ← Developer's API

402.md verifies the payment and forwards the request to the developer's endpoint. The developer doesn't need to run any middleware.

TICKET mode

The agent calls the developer's API directly with a signed JWT ticket:

Agent → pays 402.md → receives ticket (JWT)
Agent → Developer's API + ticket header → Developer
Agent ← response ← Developer

The developer verifies the ticket using the gateway middleware. This gives the developer full control over request handling and avoids routing through 402.md.

Checkout widget flow

For browser-based payments (checkout widget):

1. User clicks "Pay" button on the merchant's website
2. Widget creates a checkout session via POST /api/v1/checkout/sessions
3. 402.md returns: sessionId, exactAmount, walletAddress, expiresAt
4. Widget displays QR code, wallet address, and exact amount with countdown timer
5. User sends USDC (via QR, manual transfer, or browser wallet)
6. 402.md monitors the blockchain for a matching USDC transfer
7. Payment confirmed → widget updates via WebSocket (with polling fallback)
8. Merchant's onSuccess callback fires with the PaymentResult

Unique amount matching

Each session gets a unique exact amount (e.g., 49.000037 for a $49 payment). The random suffix ensures 402.md can match incoming transfers to the correct session without needing a unique wallet address per session.

API gateway flow

For API paywalls using the gateway middleware:

1. Agent calls the merchant's API endpoint
2. Gateway middleware returns HTTP 402 with payment requirements
3. Agent signs a USDC transfer with its private key
4. Agent retries the request with an X-402-Payment header
5. Gateway verifies the payment via POST /api/verify on the 402.md API
6. If valid, the request proceeds to the merchant's handler with req.x402 populated

SKILL.md format

Every service on 402.md is described by a SKILL.md file. This file is auto-generated when you create a skill and add endpoints. It uses YAML frontmatter:

---
name: sentiment-api
base_url: https://api.402.md/api/v1/skills/sentiment-api
version: "1.0.0"
description: "Analyze sentiment of any text"
endpoints:
    - path: /analyze
      method: POST
      price: "$0.05"
      description: "Analyze text sentiment"
---

# Sentiment Analysis API

Analyze sentiment of any text

## How to pay

All endpoints below are protected by the **x402 payment protocol**...

## Endpoints

### POST /analyze — $0.05

Analyze text sentiment

The SKILL.md is regenerated whenever endpoints change. See Creating Skills for the full guide on registering skills, setting prices, and managing endpoints.

Authentication methods

On-chain monitoring

402.md watches USDC Transfer events on Base using viem:

• Filters transfers to the 402.md escrow wallet
• Matches transfer amounts to pending checkout sessions (using the unique amount suffix)
• Confirms payments within seconds of on-chain inclusion
• Notifies widgets via WebSocket and merchants via webhooks

Network

All payments happen on Base (Coinbase's L2 on Ethereum):

Testnet: Base Sepolia

Rate limiting

API requests are rate-limited to 60 requests per minute per wallet per skill.