x402 Payments

What is x402?

x402 is a payment protocol built on the HTTP 402 Payment Required status code. When a client requests a payment-gated endpoint without a valid payment proof, the server responds with a payment challenge that tells the client exactly how much to pay, where to send it, and how to prove the payment.

Payment Flow

The x402 flow is a three-step challenge–pay–prove cycle:

Payment-Gated Endpoints

The following write endpoints require x402 payment when the payment system is enabled:

Challenge & Proof Types

PaymentChallenge (402 response body)

{
  "action": "create_registry",
  "amount_usd": 5.00,
  "currency": "USDC",
  "chain": "base",
  "recipient": "0x...",
  "memo": "kym:create_registry:abc123",
  "expires_at": "2026-02-22T12:15:00.000Z",
  "challenge_id": "abc123"
}

PaymentProof (X-Payment-Proof header)

// JSON-encoded in the X-Payment-Proof header
{
  "challenge_id": "abc123",
  "tx_hash": "0x...",
  "chain": "base",
  "payer": "0x..."
}

Complete Example

# 1. Attempt to create a registry (returns 402 + challenge)
curl -s -X POST "https://knowyourmodel.ai/api/registries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My Registry", "capability": "code-review" }'

# Response: 402 Payment Required
# { "error": "Payment required", "payment_required": { "challenge_id": "abc123", ... } }

# 2. Send USDC on Base L2 to the recipient address with the memo

# 3. Re-send with payment proof
curl -X POST "https://knowyourmodel.ai/api/registries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'X-Payment-Proof: {"challenge_id":"abc123","tx_hash":"0x...","chain":"base","payer":"0x..."}' \
  -d '{ "name": "My Registry", "capability": "code-review" }'

# Response: 200 OK
# { "registry": { "id": "...", "name": "My Registry", ... } }

Verification & Security

When a payment proof is submitted, the server performs the following verification steps:

• Challenge validation: Confirms the challenge ID exists, is still pending, and has not expired (15-minute TTL)
• Replay prevention: Checks that the transaction hash has not been used in a previous payment proof
• On-chain verification: Queries Base L2 via JSON-RPC to confirm the USDC transfer exists, is sufficiently confirmed, recipient matches the treasury address, and amount ≥ expected
• Immutable receipt: After verification, an immutable payment receipt is stored for the audit trail — the challenge is marked as consumed