How It Works

Key0 uses a three-phase payment flow to gate API access behind on-chain USDC payments on Base. Every transaction follows the same pattern regardless of transport.

​

Sequence Diagram

​

Phase 1 — Discovery

The client calls GET /discover to retrieve the full plan catalog. The response contains one entry per configured plan with its planId, USDC amount, seller wallet, and chain ID. No challenge record is created.

​

Phase 2 — Challenge

The client sends POST /x402/access with a resourceId and planId. The server looks up the matching plan, creates a PENDING challenge record in the challenge store, and returns a 402 containing:

• amount — the USDC amount to pay (in base units)
• destination — the seller’s wallet address
• chainId — 8453 (Base mainnet) or 84532 (Base Sepolia)
• challengeId — a unique identifier for this payment session

​

Phase 3 — Settlement and Grant

The client signs an EIP-3009 authorization off-chain and retries POST /x402/access with the same planId + requestId plus a payment-signature header. The server then:

1. Verifies the ERC-20 Transfer event on Base matches the expected amount, destination, and chain.
2. Transitions the challenge from PENDING to PAID (atomic, prevents double-spend).
3. Calls the seller’s fetchResourceCredentials callback to issue a credential (JWT, API key, or any token).
4. Transitions from PAID to DELIVERED and returns an AccessGrant with the token and resource URL.

All state transitions go through ChallengeEngine, which enforces the state machine invariants and logs every transition for auditability.

​

Pay-Per-Call Variant

For paid routes, the flow differs slightly: no JWT is issued. Instead, Key0 returns the API response directly.

​

Standalone (proxy mode)

Add proxyTo (or fetchResource) to SellerConfig. Clients call the paid route directly, receive a 402 challenge, then retry the same route with payment-signature.

​

Embedded (inline settlement)

Use key0.payPerRequest(routeId) middleware on each route. No proxyTo needed — Key0 settles on-chain and calls next(), so your route handler runs as normal. Both variants share the same PENDING → PAID → DELIVERED lifecycle with automatic refunds if delivery fails after on-chain settlement. See Payment Flow for the full state machine.

​

Two Endpoints, One Engine

Both entry points share the same ChallengeEngine instance, so payment logic, state management, and security invariants are identical regardless of how the client connects.

​

Next Steps