> ## Documentation Index
> Fetch the complete documentation index at: https://docs.key0.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Package exports, subpath imports, and install instructions for @key0ai/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

<CodeGroup>
  ```bash npm theme={null}
  npm install @key0ai/key0
  ```

  ```bash pnpm theme={null}
  pnpm add @key0ai/key0
  ```

  ```bash bun theme={null}
  bun add @key0ai/key0
  ```

  ```dockerfile Docker theme={null}
  RUN npm install @key0ai/key0
  ```
</CodeGroup>

## Main Import

Everything below is available from the top-level import:

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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. |