Skip to main content
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

MethodPathAuthDescription
GET/.well-known/agent.jsonNoneReturns the A2A Agent Card describing your agent’s capabilities, skills, and x402 extension. Only present when A2A is enabled.
GET/discoverNoneReturns all available plans and pricing (the plan catalog).
GET/llms.txtNoneGenerated machine-readable buyer onboarding guide. Standalone only.
GET/skills.mdNoneGenerated markdown workflow guide for buyers and agents. Standalone only.

​
Payment

MethodPathAuthDescription
POST/x402/accessNoneThe 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)

MethodPathAuthDescription
GET/.well-known/mcp.jsonNoneMCP discovery document. Returns the server name, description, version, and Streamable HTTP transport URL.
POST/mcpNoneMCP Streamable HTTP transport. Exposes discover_plans and request_access tools.

​
Health (standalone server only)

MethodPathAuthDescription
GET/healthNoneReturns { 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

HeaderDirectionDescription
payment-requiredResponseBase64-encoded X402PaymentRequiredResponse JSON. Present on all 402 responses.
www-authenticateResponseHTTP-standard authentication challenge header. Includes realm, accept, and optionally challenge parameters.
payment-signatureRequestBase64url-encoded X402PaymentPayload JSON. Sent by the client to complete payment.
payment-responseResponseBase64-encoded X402SettleResponse JSON. Present on successful settlement (200 responses).
x-a2a-extensionsRequestWhen 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.