Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.key0.ai/llms.txt

Use this file to discover all available pages before exploring further.

This page defines every domain-specific term you will encounter in the Key0 docs. Read it once before diving into protocols or architecture — or use it as a reference when you hit an unfamiliar term.

​
Roles

The API provider. You configure Key0 with your pricing plans, wallet address, and credential-issuance logic. Key0 mounts onto your server and handles the entire payment flow on your behalf. You never touch wallets or on-chain code.
The AI agent or autonomous client that wants to use a Key0-protected API. The buyer discovers your service, signs an on-chain payment authorization, and receives an access token in return. No human is in the loop.
An optional third party (such as Coinbase or a wallet provider) that submits the on-chain USDC transfer on behalf of the buyer. The buyer signs the authorization off-chain (EIP-3009) and the facilitator pays the gas. Key0’s gas wallet plays the facilitator role when you supply a gasWalletPrivateKey. See Settlement Strategies.

​
Payment Concepts

USD Coin — a fully-reserved US dollar stablecoin issued by Circle. Key0 uses USDC as the payment currency. One USDC equals one US dollar; amounts in the protocol are expressed in micro-units (1 USDC = 1,000,000 micro-units, following the ERC-20 6-decimal convention). You can test on Base Sepolia using free USDC from faucet.circle.com.
Base is an Ethereum Layer 2 network built by Coinbase. It uses Optimistic Rollups to provide fast, low-cost transactions while inheriting Ethereum’s security. Key0 supports both Base mainnet (chain ID 8453) and Base Sepolia testnet (chain ID 84532). Using L2 keeps per-transaction fees low enough for micropayments.
An Ethereum standard that lets the USDC owner sign a transfer authorization off-chain — no RPC call, no gas, just a cryptographic signature. A third party (the gas wallet or facilitator) then submits the signed authorization on-chain and pays the gas. This is how Key0 enables gasless payments for buyers: the buyer signs locally, the seller’s infrastructure pays gas.The authorization is an EIP-712 typed-data signature over:
  • from / to addresses
  • value (USDC micro-units)
  • validAfter / validBefore (Unix timestamps — the window during which the authorization is valid)
  • nonce (random 32-byte value to prevent replay)
A separate Ethereum wallet (controlled by the seller) whose sole purpose is to submit EIP-3009 authorizations on-chain and pay the gas fees. Configure it by passing gasWalletPrivateKey to SellerConfig. The gas wallet never holds USDC — it only pays ETH for gas. See Settlement Strategies.
The base64-encoded JSON blob the buyer sends as an HTTP header to prove payment. It wraps the EIP-3009 authorization (or a raw txHash) along with protocol metadata. Key0 decodes it, verifies the on-chain transfer, and issues credentials.
{
  "x402Version": 2,
  "network": "eip155:84532",
  "scheme": "exact",
  "payload": {
    "signature": "0x...",
    "authorization": { "from": "0x...", "to": "0x...", "value": "100000", ... }
  },
  "accepted": { "scheme": "exact", "network": "eip155:84532", ... }
}

​
Protocol Concepts

An open standard for HTTP payment-gating that repurposes the HTTP 402 Payment Required status code. When a client hits a gated endpoint without payment, the server responds 402 with machine-readable PaymentRequirements. The client pays and retries with proof. Key0 implements x402 version 2. See the x402 spec on GitHub.
A short-lived payment session created when a buyer requests access to a plan. A challenge has a unique challengeId, records the expected USDC amount, the destination wallet, and the expiry timestamp. It starts in the PENDING state and moves through the state machine as the payment progresses. See State Machine.
The response returned to the buyer after a successful subscription payment. It contains:
  • accessToken — a signed JWT (or other credential) for the protected resource
  • tokenType — always "Bearer"
  • resourceEndpoint — the URL to call with the token
  • txHash — the on-chain transaction hash as proof of payment
  • expiresAt — when the token expires
  • challengeId / requestId — for correlation and idempotency
For per-request plans Key0 returns a ResourceResponse (the backend API data) instead of an AccessGrant.
The response returned to the buyer after a successful per-request payment in standalone mode. Instead of a JWT, Key0 returns the actual backend response:
{
  "type": "ResourceResponse",
  "challengeId": "uuid",
  "requestId": "uuid",
  "planId": "weather-query",
  "txHash": "0x...",
  "resource": {
    "status": 200,
    "body": { "city": "London", "tempF": 65, "condition": "Cloudy" }
  }
}
If the backend returns a non-2xx status, the challenge stays in PAID state (awaiting refund) and the ResourceResponse still contains the backend’s error body so the client knows what went wrong.
The act of executing the USDC transfer on-chain and confirming it. After settlement, Key0 verifies the ERC-20 Transfer event matches the expected amount and destination, then transitions the challenge from PAID to DELIVERED. Settlement can happen via a gas wallet (EIP-3009) or a direct on-chain transfer (txHash proof). See Settlement Strategies.
The machine-readable payment instructions Key0 returns in a 402 response. They tell the buyer exactly what to pay: amount (in micro-units), asset (USDC), destination (payTo wallet address), network (eip155:84532), and maximum timeout. Buyers read these values to construct the EIP-3009 authorization.
The property that repeating the same payment request with the same requestId produces the same result without double-charging. If a buyer retries after a network failure, Key0 detects the existing challenge and returns the same AccessGrant rather than creating a second payment. Always pass a stable requestId (e.g., a UUID generated once per purchase intent).

​
Key0 Concepts

A configured pricing tier offered by the seller. Plans are defined in SellerConfig.plans and exposed via GET /discover and the agent card.
type Plan = {
  planId: string;       // Unique identifier, e.g. "basic"
  unitAmount: string;   // Dollar-formatted price, e.g. "$0.10"
  description?: string; // Human-readable description
};
A billing mode where each API call is paid for individually — no long-lived JWT is issued.How to enable it: define a paid endpoint in top-level SellerConfig.routes.
plans: [
  // Subscription plan (default) — agent pays once, receives a JWT
  { planId: "basic", unitAmount: "$0.10" },
]

routes: [
  {
    routeId: "weather-query",
    method: "GET",
    path: "/api/weather/:city",
    unitAmount: "$0.01",
    description: "Current weather — $0.01 per call.",
  },
]
Key0 supports two PPR deployment styles:
  • Embedded — use key0.payPerRequest(routeId) middleware on individual routes. After on-chain settlement the request is passed to your route handler. The handler receives payment metadata in req.key0Payment (Express/Fastify) or c.get("key0Payment") (Hono).
  • Standalone — set proxyTo.baseUrl (or fetchResource) on SellerConfig. Clients call the paid route directly. After payment Key0 proxies the request to your backend and returns a ResourceResponse with the API data directly.
Both modes share the PENDING → PAID → DELIVERED lifecycle and are eligible for automatic refunds if delivery fails after payment.
The TypeScript object you pass to Key0 that defines everything about your service: identity (agentName, agentUrl), your wallet address, your plans, your fetchResourceCredentials callback, settlement mode, and optional hooks. It is the single source of truth for your Key0 deployment. See SellerConfig Reference.
The core class that orchestrates the entire payment flow. It creates challenges, validates payment proofs, enforces state machine transitions, calls fetchResourceCredentials, fires onPaymentReceived hooks, and manages idempotency. Both the x402 HTTP middleware and the MCP integration share the same ChallengeEngine instance. See ChallengeEngine Reference.
The persisted state of a single payment session, stored in the Challenge Store. It records the planId, requestId, challengeId, USDC amount, expiry, and current state. The state machine enforces valid transitions on this record atomically. See Data Models.
The lifecycle of a challenge, enforced atomically to prevent race conditions and double-spend. States and their meanings:
StateMeaning
PENDINGChallenge created, waiting for payment
PAIDOn-chain transfer confirmed, credentials being issued
DELIVEREDCredentials issued, AccessGrant returned to buyer
EXPIREDChallenge TTL passed before payment arrived
CANCELLEDManually cancelled
REFUND_PENDINGCredential issuance failed, refund queued
REFUNDEDOn-chain USDC refund confirmed
REFUND_FAILEDRefund attempt failed (needs manual review)
See State Machine for transition rules and atomic Lua scripts.
The component that creates the JWT returned in the AccessGrant. It supports HS256 (symmetric secret) and RS256 (RSA key pair) algorithms. The issued token embeds the planId, resourceId, walletAddress, and expiry. Sellers can also use their own fetchResourceCredentials callback to return any credential type. See Token Issuance.
A seller-supplied async callback invoked by Key0 after successful payment. It receives the planId, resourceId, and walletAddress of the buyer, and must return the credential (JWT, API key, signed URL, etc.) to include in the AccessGrant. This is the integration point between Key0 and your application’s auth system.

​
Transport Layers

The default transport. All interactions happen over standard HTTP: GET /discover, POST /x402/access, and GET /api/resource. Any HTTP client — curl, fetch, an AI agent — can participate. No special libraries required on the client side. See x402 HTTP Flow.
Google’s Agent-to-Agent protocol, which uses JSON-RPC over HTTP. In Key0, A2A requests arrive at POST /x402/access with an X-A2A-Extensions: x402/v2 header, routing them to the A2A JSON-RPC handler. The payment mechanics are identical to the x402 HTTP flow; only the message envelope differs. See A2A Flow.
Anthropic’s Model Context Protocol, which exposes server capabilities as callable tools. Key0 mounts an MCP server at POST /mcp (enabled via mcp: true in SellerConfig). Two tools are exposed: discover_plans (free) and request_access (payment-gated). Claude Code, Cursor, and other MCP clients use this to interact with Key0 services. See MCP Integration.
A JSON document served at GET /.well-known/agent.json that describes the Key0 service: its name, description, URL, available skills (plans), and supported extensions. Agent frameworks use it to auto-discover Key0 services and understand their pricing without any prior configuration. See Agent Card.

​
Infrastructure

The persistence layer for challenge records. Key0 requires a challenge store to create, read, and atomically update challenge state. Supported backends: Redis (RedisChallengeStore) and Postgres (PostgresChallengeStore). An in-memory store is available for testing. See Storage.
A deduplication index that records every transaction hash that has been used to settle a payment. Before accepting a payment proof, Key0 checks the seen TX store to ensure the same on-chain transaction cannot be reused for a second AccessGrant (double-spend protection). See Storage.
An optional append-only log of all payment events and state transitions. Useful for compliance, debugging, and analytics. Both Redis and Postgres implementations are available. See Storage.
A background job (typically run as a cron or BullMQ worker) that periodically scans for challenges in REFUND_PENDING state and executes on-chain USDC refunds back to the buyer’s wallet. Refunds are triggered when fetchResourceCredentials fails after a confirmed payment. See Refunds.
A buyer-supplied identifier (UUID recommended) that scopes a payment session. Key0 uses it to enable idempotency: the same requestId always maps to the same challenge and the same AccessGrant. If you omit it, Key0 auto-generates one — but you lose the ability to safely retry on network failure.
An optional identifier for the specific resource within a plan the buyer wants access to. Passed through to your fetchResourceCredentials callback so you can issue a credential scoped to a particular resource (e.g., a specific dataset or API endpoint). Defaults to "default" if omitted.

​
Next Steps

How It Works

See the full three-phase payment sequence diagram.

Quickstart: Embedded

Add Key0 to an Express, Hono, or Fastify server in minutes.

Paying for Access

How agents discover, pay, and call Key0-protected APIs.

SellerConfig Reference

Complete reference for every configuration option.