Skip to main content

​
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

MethodPathAuthDescription
GET/.well-known/agent.jsonNoneReturns the A2A Agent Card describing your agent’s capabilities, skills, and x402 extension.

​
Payment

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

MethodPathAuthDescription
POST{basePath}/jsonrpcx402 middlewareA2A 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}/restNoneA2A REST handler for non-JSON-RPC clients.

​
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. 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

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, 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.