Overview

All HTTP endpoints served by Key0 at a glance.

API Reference

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().

The default base path for A2A endpoints is /a2a. You can override this with basePath in your SellerConfig.

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.

Payment

Method	Path	Auth	Description
POST	/x402/access	None	The x402 HTTP payment endpoint. Handles three cases: plan discovery (no planId), challenge issuance (planId without PAYMENT-SIGNATURE), and settlement (planId with PAYMENT-SIGNATURE).

A2A Protocol

Method	Path	Auth	Description
POST	{basePath}/jsonrpc	x402 middleware	A2A JSON-RPC endpoint. The x402 HTTP middleware intercepts message/send calls and gates them behind payment unless the X-A2A-Extensions header is present.
POST	{basePath}/rest	None	A2A REST handler for non-JSON-RPC clients.

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. The flow works as follows:

1. Discovery — The client fetches the Agent Card or calls /x402/access without a planId to learn available plans and pricing.
2. Challenge — The client sends a request with a planId. The server responds with HTTP 402 and payment requirements (amount, wallet address, chain ID).
3. Settlement — The client signs an EIP-3009 authorization off-chain, encodes it as a PAYMENT-SIGNATURE header, and retries the same request. The server settles the payment on-chain and returns an AccessGrant containing a bearer token.
4. Access — The client uses the bearer token from the AccessGrant to call protected resource endpoints.

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, the x402 HTTP middleware passes the request through to the A2A JSON-RPC handler without interception. 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.