Overview - Key0

@key0ai/key0 is a single package that exposes everything you need to add payment-gated endpoints to your API. Import from the main entry point for core functionality, or use framework-specific subpath imports.

Install

npm install @key0ai/key0

pnpm add @key0ai/key0

bun add @key0ai/key0

RUN npm install @key0ai/key0

Main Import

Everything below is available from the top-level import:

import { createKey0, ChallengeEngine, X402Adapter /* ... */ } from "@key0ai/key0";

Core Classes

Export	Description
`ChallengeEngine`	State machine that drives the full challenge lifecycle.
`AccessTokenIssuer`	Issues and verifies JWTs (HS256 or RS256) with secret rotation.
`X402Adapter`	Verifies ERC-20 Transfer events on Base mainnet or Base Sepolia.

Storage

Export	Description
`RedisChallengeStore`	Redis-backed challenge store with Lua atomics.
`RedisSeenTxStore`	Redis-backed seen-transaction store (SET NX).
`RedisAuditStore`	Redis-backed append-only audit log.
`PostgresChallengeStore`	Postgres-backed challenge store.
`PostgresSeenTxStore`	Postgres-backed seen-transaction store.
`PostgresAuditStore`	Postgres-backed append-only audit log.

Factory

Export	Description
`createKey0`	Wires stores, adapter, and engine together. Returns `{ requestHandler, agentCard, engine, executor }`.

Executor

Export	Description
`Key0Executor`	Implements the A2A `AgentExecutor` interface for protocol flow.

Middleware

Export	Description
`validateToken`	Generic token-validation middleware.
`validateKey0Token`	Key0-specific token-validation middleware.

Auth Helpers

Export	Description
`noAuth`	Sends no auth headers (local dev / trusted networks).
`sharedSecretAuth`	Attaches a shared-secret header for service-to-service auth.
`signedJwtAuth`	Signs outbound requests with a JWT.
`oauthClientCredentialsAuth`	Fetches and attaches an OAuth2 client-credentials token.

Remote Helpers

Export	Description
`createRemoteTokenIssuer`	Wraps a remote Key0 endpoint for token issuance.

Pay-Per-Request Helpers

Export	Description
`resolveConfigFetchResource`	Returns the configured `fetchResource` callback (from `fetchResource` or `proxyTo`) or `undefined` if embedded mode. Used internally to detect the deployment mode at runtime.

Error Types

Export	Description
`Key0Error`	Base error class for all Key0 errors.

Constants

Export	Description
`CHAIN_CONFIGS`	Network configuration map (mainnet chain 8453, testnet chain 84532).
`USDC_DECIMALS`	USDC token decimal precision (6).

Subpath Imports

Framework-specific adapters are available as subpath imports. Each exposes a router/plugin and a validateAccessToken middleware for protecting routes.

Express

import { key0Router, validateAccessToken, key0PayPerRequest } from "@key0ai/key0/express";

Export	Description
`key0Router`	Express router that mounts challenge and proof endpoints. Returns the router with an attached `payPerRequest(planId, opts?)` factory method.
`validateAccessToken`	Express middleware that validates Bearer JWTs on protected routes.
`key0PayPerRequest`	Standalone per-request middleware factory for routes not managed by `key0Router`.

Hono

import { key0App, honoValidateAccessToken, honoPayPerRequest } from "@key0ai/key0/hono";

Export	Description
`key0App`	Hono app that mounts challenge and proof endpoints. Returns the app with an attached `payPerRequest(planId, opts?)` factory method.
`honoValidateAccessToken`	Hono middleware that validates Bearer JWTs on protected routes.
`honoPayPerRequest`	Standalone per-request middleware factory for routes not managed by `key0App`.

Fastify

import { key0Plugin, fastifyValidateAccessToken, fastifyPayPerRequest } from "@key0ai/key0/fastify";

Export	Description
`key0Plugin`	Fastify plugin that registers challenge and proof routes. Attaches `payPerRequest(planId, opts?)` via the `key0` Fastify decorator.
`fastifyValidateAccessToken`	Fastify hook that validates Bearer JWTs on protected routes.
`fastifyPayPerRequest`	Standalone per-request preHandler factory for routes not managed by `key0Plugin`.

MCP

import { createMcpServer, mountMcpRoutes } from "@key0ai/key0/mcp";

Export	Description
`createMcpServer`	Creates an MCP server exposing `discover_plans` and `request_access` tools.
`mountMcpRoutes`	Mounts `/.well-known/mcp.json` discovery and `POST /mcp` Streamable HTTP endpoints on an Express app.

​Install

​Main Import

​Core Classes

​Storage

​Factory

​Executor

​Middleware

​Auth Helpers

​Remote Helpers

​Pay-Per-Request Helpers

​Error Types

​Constants

​Subpath Imports

​Express

​Hono

​Fastify

​MCP