Overview - Key0

Key0 exposes a set of HTTP endpoints for agent discovery, payment-gated access, and protocol interoperability. All endpoints are served by a single Express router created via key0Router().

Endpoints

Discovery

Method	Path	Auth	Description
`GET`	`/.well-known/agent.json`	None	Returns the A2A Agent Card describing your agent’s capabilities, skills, and x402 extension. Only present when A2A is enabled.
`GET`	`/discover`	None	Returns all available plans and pricing (the plan catalog).
`GET`	`/llms.txt`	None	Generated machine-readable buyer onboarding guide. Standalone only.
`GET`	`/skills.md`	None	Generated markdown workflow guide for buyers and agents. Standalone only.

Payment

Method	Path	Auth	Description
`POST`	`/x402/access`	None	The x402 HTTP payment endpoint. Handles challenge issuance (`planId` without `PAYMENT-SIGNATURE`) and settlement (`planId` with `PAYMENT-SIGNATURE`). Returns 400 if `planId` is missing.

MCP (when `mcp: true`)

Method	Path	Auth	Description
`GET`	`/.well-known/mcp.json`	None	MCP discovery document. Returns the server name, description, version, and Streamable HTTP transport URL.
`POST`	`/mcp`	None	MCP Streamable HTTP transport. Exposes `discover_plans` and `request_access` tools.

Health (standalone server only)

Method	Path	Auth	Description
`GET`	`/health`	None	Returns `{ status: "ok" }`. Only available when running the standalone server, not when mounting the router into an existing app.

Authentication Model

Key0 uses the x402 payment protocol instead of traditional API keys: discover a plan, request a challenge (402), sign an EIP-3009 authorization, settle on-chain, receive a Bearer token. For the full three-phase flow explanation and sequence diagram, see How It Works.

Base URL

All paths are relative to the host where you mount the Key0 router. For example, if your server runs at https://api.example.com, the agent card is at https://api.example.com/.well-known/agent.json.

Common Headers

Header	Direction	Description
`payment-required`	Response	Base64-encoded `X402PaymentRequiredResponse` JSON. Present on all 402 responses.
`www-authenticate`	Response	HTTP-standard authentication challenge header. Includes `realm`, `accept`, and optionally `challenge` parameters.
`payment-signature`	Request	Base64url-encoded `X402PaymentPayload` JSON. Sent by the client to complete payment.
`payment-response`	Response	Base64-encoded `X402SettleResponse` JSON. Present on successful settlement (200 responses).
`x-a2a-extensions`	Request	When present on `POST /x402/access` (Express only), routes the request to the A2A JSON-RPC handler instead of the standard x402 HTTP flow. Used by A2A-native clients.

Error Format

All errors follow a consistent JSON structure:

{
  "type": "Error",
  "code": "TIER_NOT_FOUND",
  "message": "Plan \"premium\" not found in plan catalog",
  "httpStatus": 400
}

See Data Models for the full list of error codes.