@wtflabs/x402-server 0.0.1-beta.10 → 0.0.1-beta.11

package/README.md

@@ -1,61 +1,140 @@
 # @wtflabs/x402-server
 
-Server SDK for the x402 Payment Protocol. Handles payment verification and settlement with automatic token detection.
+完整的服务端 SDK，用于 x402 支付协议。提供支付验证、结算和自动 Token 检测功能。
 
-## Features
+## ✨ 特性
 
-✅ **Simple API** - Just 2 required parameters to get started  
-✅ **Automatic Token Detection** - Built on `@wtflabs/x402-detector`  
-✅ **Payment Processing** - Verify and settle payments via `@wtflabs/x402-facilitator`  
-✅ **Dynamic Requirements** - Create payment requirements on-the-fly  
-✅ **Performance Optimized** - Built-in caching, non-blocking initialization  
-✅ **Framework Middlewares** - Ready-to-use Express and Hono middlewares  
-✅ **Zod Validation** - Runtime type safety for all data  
-✅ **Decoupled Design** - Facilitator and Server are independent
+- 🚀 **简洁 API** - 仅需 2 个必填参数即可开始
+- 🔍 **自动 Token 检测** - 基于 `@wtflabs/x402-detector` 自动识别支付类型
+- 💰 **支付处理** - 通过 `@wtflabs/x402-facilitator` 验证和结算支付
+- ⚡ **动态需求** - 实时创建支付要求
+- 🎯 **性能优化** - 内置缓存、非阻塞初始化
+- 🔌 **框架中间件** - Express 和 Hono 中间件开箱即用
+- ✅ **Zod 验证** - 运行时类型安全
+- 🔒 **100% 类型安全** - 零 `any` 类型，完整 TypeScript 支持
+- 🎨 **解耦设计** - Facilitator 和 Server 独立运行
 
-## Installation
+## 📦 安装
 
 ```bash
-npm install @wtflabs/x402-server viem
+npm install @wtflabs/x402-server @wtflabs/x402-facilitator viem
 ```
 
-## Quick Start
+**可选依赖**（根据框架选择）：
+```bash
+# 使用 Express
+npm install express
+
+# 使用 Hono
+npm install hono
+```
+
+## 🚀 快速开始
+
+### 方式 1：使用中间件（推荐）
 
-### Option 1: Using Middleware (Easiest)
+#### Express 中间件
 
 ```typescript
 import express from "express";
 import { createExpressMiddleware, X402Server } from "@wtflabs/x402-server";
 import { Facilitator } from "@wtflabs/x402-facilitator";
+import { createPublicClient, http } from "viem";
+import { bscTestnet } from "viem/chains";
 
 const app = express();
 
-// 1. Create facilitator
+// 1. 创建 viem client
+const client = createPublicClient({
+  chain: bscTestnet,
+  transport: http(),
+});
+
+// 2. 创建 facilitator
 const facilitator = new Facilitator({
   recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
+  waitUntil: "confirmed",
 });
 
-// 2. Create server
+// 3. 创建 server
 const server = new X402Server({
-  client: createPublicClient({ chain: bscTestnet, transport: http() }),
+  client,
   facilitator,
 });
 
-// 3. Create middleware
+// 4. 创建中间件
 const paymentMiddleware = createExpressMiddleware({
   server,
   getToken: () => "0x25d066c4C68C8A6332DfDB4230263608305Ca991", // USDC
-  getAmount: () => "1000",
+  getAmount: () => "1000000", // 1 USDC (6 decimals)
 });
 
-// 4. Use middleware
-app.post("/api/resource", paymentMiddleware, (req, res) => {
+// 5. 使用中间件
+app.post("/api/premium", paymentMiddleware, (req, res) => {
   const { payer, txHash } = req.x402!;
-  res.json({ data: "resource", payer, txHash });
+  res.json({
+    success: true,
+    data: "Premium content",
+    payer,
+    txHash,
+  });
+});
+
+app.listen(3000, () => {
+  console.log("Server running on http://localhost:3000");
+});
+```
+
+#### Hono 中间件
+
+```typescript
+import { Hono } from "hono";
+import { createHonoMiddleware, X402Server } from "@wtflabs/x402-server";
+import { Facilitator } from "@wtflabs/x402-facilitator";
+import { createPublicClient, http } from "viem";
+import { bscTestnet } from "viem/chains";
+
+const app = new Hono();
+
+// 1. 创建 viem client
+const client = createPublicClient({
+  chain: bscTestnet,
+  transport: http(),
+});
+
+// 2. 创建 facilitator
+const facilitator = new Facilitator({
+  recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
+});
+
+// 3. 创建 server
+const server = new X402Server({
+  client,
+  facilitator,
 });
+
+// 4. 创建中间件
+const paymentMiddleware = createHonoMiddleware({
+  server,
+  getToken: () => "0x25d066c4C68C8A6332DfDB4230263608305Ca991",
+  getAmount: () => "1000000",
+});
+
+// 5. 使用中间件
+app.post("/api/premium", paymentMiddleware, (c) => {
+  const x402 = c.get("x402") as { payer: string; txHash: string };
+  return c.json({
+    success: true,
+    data: "Premium content",
+    payer: x402.payer,
+    txHash: x402.txHash,
+  });
+});
+
+export default app;
 ```
 
-### Option 2: Manual Processing
+### 方式 2：手动处理
 
 ```typescript
 import { X402Server } from "@wtflabs/x402-server";
@@ -63,37 +142,42 @@ import { Facilitator } from "@wtflabs/x402-facilitator";
 import { createPublicClient, http } from "viem";
 import { bscTestnet } from "viem/chains";
 
-// 1. Create facilitator
+// 1. 创建 viem client
+const client = createPublicClient({
+  chain: bscTestnet,
+  transport: http(),
+});
+
+// 2. 创建 facilitator
 const facilitator = new Facilitator({
   recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
   waitUntil: "confirmed",
 });
 
-// 2. Create server instance
+// 3. 创建 server
 const server = new X402Server({
-  client: createPublicClient({
-    chain: bscTestnet,
-    transport: http(),
-  }),
+  client,
   facilitator,
+  network: "bsc-testnet", // 可选
 });
 
-// 3. Optional: Pre-warm cache (non-blocking)
+// 4. 可选：预热缓存（非阻塞）
 server.initialize([
   "0x25d066c4C68C8A6332DfDB4230263608305Ca991", // USDC
 ]);
 
-// 4. Handle payment in your route
+// 5. 在路由中处理支付
 app.post("/api/resource", async (req, res) => {
-  // Create payment requirements
+  // 创建支付要求
   const requirements = await server.createRequirements({
     asset: "0x25d066c4C68C8A6332DfDB4230263608305Ca991",
-    maxAmountRequired: "1000", // wei
+    maxAmountRequired: "1000000",
+    description: "Premium API access",
   });
 
-  // Process payment (parse → verify → settle)
+  // 处理支付（parse → verify → settle）
   const result = await server.process(
-    req.headers["x-payment"],
+    req.headers["x-payment"] as string,
     requirements
   );
 
@@ -101,108 +185,131 @@ app.post("/api/resource", async (req, res) => {
     return res.status(402).json(result.response);
   }
 
-  // Payment successful!
+  // 支付成功
   res.json({
     message: "Access granted",
     payer: result.data.payer,
     txHash: result.data.txHash,
-    data: "your protected resource",
+    data: "Your protected resource",
   });
 });
 ```
 
-## API Reference
+## 📚 API 参考
 
-### Constructor
+### X402Server 构造函数
 
 ```typescript
 const server = new X402Server(config: X402ServerConfig)
 ```
 
-**Required:**
-- `client: PublicClient` - Viem PublicClient instance
-- `facilitator: Facilitator` - Facilitator instance (handles payment processing)
+#### 参数
+
+**必填：**
+- `client: PublicClient` - Viem PublicClient 实例
+- `facilitator: Facilitator` - Facilitator 实例（处理支付）
+
+**可选：**
+- `network?: string` - 网络名称（默认从 client 自动检测）
 
-**Optional:**
-- `network?: string` - Network name (auto-detected from client if not provided)
+#### 示例
 
-**Example:**
 ```typescript
 import { Facilitator } from "@wtflabs/x402-facilitator";
 import { createPublicClient, http } from "viem";
 import { bscTestnet } from "viem/chains";
 
-// 1. Create viem client
 const client = createPublicClient({
   chain: bscTestnet,
   transport: http(),
 });
 
-// 2. Create facilitator first
 const facilitator = new Facilitator({
   recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
-  waitUntil: "confirmed", // optional: "confirmed" | "finalized" 
+  waitUntil: "confirmed",
 });
 
-// 3. Create server with client and facilitator
 const server = new X402Server({
   client,
   facilitator,
-  network: "bsc-testnet", // optional
+  network: "bsc-testnet", // 可选
 });
 ```
 
-### Methods
+### 核心方法
 
 #### `initialize(tokens: string[]): Promise<InitResult>`
 
-Pre-warm the token detection cache. Non-blocking, can run in background.
+预热 Token 检测缓存。非阻塞，可以在后台运行。
 
 ```typescript
-// Wait for initialization
+// 等待初始化完成
 await server.initialize([tokenAddress]);
 
-// Or run in background
+// 或在后台运行
 server.initialize([tokenAddress]).then(result => {
-  if (result.success) console.log("✅ Cache ready");
+  if (result.success) {
+    console.log("✅ Cache ready");
+  }
 });
 ```
 
 #### `createRequirements(config): Promise<PaymentRequirements>`
 
-Create payment requirements. Supports dynamic amounts and auto-detection.
+创建支付要求。支持动态金额和自动检测。
 
-```typescript
-const requirements = await server.createRequirements({
-  // Required
-  asset: "0x...",             // Token contract address
-  maxAmountRequired: "1000",  // Amount in wei (as string)
+**参数：**
 
-  // Optional - network and scheme
-  network?: "bsc-testnet",    // Network name (overrides server config)
-  scheme?: "exact",           // Payment scheme (currently only "exact")
-  outputSchema?: {},          // Output schema (for validation)
-
-  // Optional - payment type
-  paymentType?: "permit" | "eip3009" | "permit2" | "auto",
+```typescript
+interface CreateRequirementsConfig {
+  // 必填
+  asset: string;              // Token 合约地址
+  maxAmountRequired: string;  // 金额（wei，字符串格式）
+
+  // 可选 - 网络和方案
+  network?: string;           // 网络名称（覆盖全局配置）
+  scheme?: "exact";           // 支付方案（目前仅支持 "exact"）
+  outputSchema?: Record<string, unknown>;
+
+  // 可选 - 支付类型
+  paymentType?: "permit" | "eip3009" | "permit2" | "auto";
+
+  // 可选 - 资源描述
+  resource?: string;          // 资源 URL
+  description?: string;       // 描述
+  mimeType?: string;          // MIME 类型
+  maxTimeoutSeconds?: number; // 超时时间（秒）
+
+  // 可选 - 额外元数据
+  extra?: Record<string, unknown>;
+
+  // 可选 - 性能控制
+  autoDetect?: boolean;       // false = 快速模式（需手动指定 paymentType）
+}
+```
 
-  // Optional - resource description
-  resource?: "https://api.example.com/data",
-  description?: "Premium API access",
-  mimeType?: "application/json",
-  maxTimeoutSeconds?: 300,
+**示例：**
 
-  // Optional - extra metadata
-  extra?: {},                 // Additional metadata
+```typescript
+// 自动检测（默认）
+const requirements = await server.createRequirements({
+  asset: "0x25d066c4C68C8A6332DfDB4230263608305Ca991",
+  maxAmountRequired: "1000000",
+  description: "Premium access",
+});
 
-  // Optional - performance
-  autoDetect?: true,          // Set to false for fast mode (requires manual paymentType)
+// 快速模式（跳过检测）
+const requirements = await server.createRequirements({
+  asset: "0x25d066c4C68C8A6332DfDB4230263608305Ca991",
+  maxAmountRequired: "1000000",
+  paymentType: "permit",
+  autoDetect: false, // <1ms
 });
 ```
 
 #### `process(paymentHeader, requirements): Promise<ProcessResult>`
 
-Complete payment processing (parse → verify → settle).
+完整的支付处理流程（解析 → 验证 → 结算）。
 
 ```typescript
 const result = await server.process(
@@ -215,20 +322,22 @@ if (result.success) {
   console.log("TxHash:", result.data.txHash);
 } else {
   console.log("Error:", result.response.error);
-  // Return 402 with result.response
+  // 返回 402 状态码和 result.response
 }
 ```
 
-#### Advanced: Step-by-Step Processing
+#### 分步处理（高级用法）
+
+如需更细粒度的控制，可以分步处理：
 
 ```typescript
-// 1. Parse payment header
+// 1. 解析支付头
 const parsed = server.parse(paymentHeader, requirements);
 if (!parsed.success) {
   return res.status(402).json(parsed.response402);
 }
 
-// 2. Verify payment
+// 2. 验证支付
 const verified = await server.verify(parsed.data);
 if (!verified.success) {
   return res.status(402).json(
@@ -237,7 +346,7 @@ if (!verified.success) {
 }
 console.log("Payer:", verified.payer);
 
-// 3. Settle payment (optional - you can skip this for verify-only mode)
+// 3. 结算支付（可选 - 仅验证模式可跳过）
 const settled = await server.settle(parsed.data);
 if (!settled.success) {
   return res.status(402).json(
@@ -247,53 +356,59 @@ if (!settled.success) {
 console.log("TxHash:", settled.txHash);
 ```
 
-### Utility Methods
+### 工具方法
 
 ```typescript
-// Generate 402 response
+// 生成 402 响应
 const response402 = server.get402Response(requirements, error?);
 
-// Clear token cache
-await server.clearCache(tokenAddress?); // specific or all
+// 清除 Token 缓存
+await server.clearCache(tokenAddress?); // 指定地址或清除全部
 
-// Get cache stats
+// 获取缓存统计
 const stats = server.getCacheStats();
 console.log(stats.size, stats.keys);
 
-// Get underlying instances (for advanced usage)
+// 获取底层实例（高级用法）
 const facilitator = server.getFacilitator();
 const detector = server.getDetector();
 const client = server.getClient();
 ```
 
-## Usage Examples
+## 💡 使用示例
 
-### Example 1: Fixed Amount
+### 示例 1: 固定金额
 
 ```typescript
+import express from "express";
 import { X402Server } from "@wtflabs/x402-server";
 import { Facilitator } from "@wtflabs/x402-facilitator";
 
-// 1. Create facilitator
+const app = express();
+
+// 创建 facilitator
 const facilitator = new Facilitator({
   recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
 });
 
-// 2. Create server
+// 创建 server
 const server = new X402Server({ client, facilitator });
 
-// 3. Pre-warm cache (optional)
+// 预热缓存（可选）
 await server.initialize(["0xUSDC"]);
 
-// 4. Fixed requirements
+// 固定要求
 const requirements = await server.createRequirements({
   asset: "0xUSDC",
-  maxAmountRequired: "1000",
+  maxAmountRequired: "1000000",
   description: "Access to premium API",
 });
 
 app.post("/premium-api", async (req, res) => {
-  const result = await server.process(req.headers["x-payment"], requirements);
+  const result = await server.process(
+    req.headers["x-payment"] as string,
+    requirements
+  );
   
   if (!result.success) {
     return res.status(402).json(result.response);
@@ -303,57 +418,60 @@ app.post("/premium-api", async (req, res) => {
 });
 ```
 
-### Example 2: Dynamic Pricing
+### 示例 2: 动态定价
 
 ```typescript
 app.post("/api/compute", async (req, res) => {
   const { complexity } = req.body;
   
-  // Calculate price based on complexity
+  // 根据复杂度计算价格
   const price = calculatePrice(complexity);
   
-  // Dynamic requirements
+  // 动态创建要求
   const requirements = await server.createRequirements({
     asset: "0xUSDC",
     maxAmountRequired: price,
-    description: `Compute task (${complexity})`,
+    description: `Compute task (complexity: ${complexity})`,
   });
   
-  const result = await server.process(req.headers["x-payment"], requirements);
+  const result = await server.process(
+    req.headers["x-payment"] as string,
+    requirements
+  );
   
   if (!result.success) {
     return res.status(402).json(result.response);
   }
   
-  // Execute computation
+  // 执行计算
   const computeResult = await performComputation(complexity);
   res.json({ result: computeResult, paid: price });
 });
 ```
 
-### Example 3: Multiple Tokens
+### 示例 3: 多 Token 支持
 
 ```typescript
-import { X402Server } from "@wtflabs/x402-server";
-import { Facilitator } from "@wtflabs/x402-facilitator";
-
-// 1. Create facilitator
-const facilitator = new Facilitator({
-  recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
-});
-
-// 2. Create server
 const server = new X402Server({ client, facilitator });
 
-// 3. Pre-warm multiple tokens
+// 预热多个 Token
 await server.initialize(["0xUSDC", "0xDAI", "0xUSDT"]);
 
 app.get("/premium-api", async (req, res) => {
-  // Return multiple payment options
+  // 返回多个支付选项
   const accepts = await Promise.all([
-    server.createRequirements({ asset: "0xUSDC", maxAmountRequired: "1000" }),
-    server.createRequirements({ asset: "0xDAI", maxAmountRequired: "1000" }),
-    server.createRequirements({ asset: "0xUSDT", maxAmountRequired: "1000" }),
+    server.createRequirements({ 
+      asset: "0xUSDC", 
+      maxAmountRequired: "1000000" 
+    }),
+    server.createRequirements({ 
+      asset: "0xDAI", 
+      maxAmountRequired: "1000000000000000000" 
+    }),
+    server.createRequirements({ 
+      asset: "0xUSDT", 
+      maxAmountRequired: "1000000" 
+    }),
   ]);
   
   res.status(402).json({
@@ -363,39 +481,51 @@ app.get("/premium-api", async (req, res) => {
 });
 
 app.post("/premium-api", async (req, res) => {
-  // User pays with their chosen token
-  const parsed = server.parse(req.headers["x-payment"], accepts[0]);
+  // 用户使用选定的 Token 支付
+  const parsed = server.parse(
+    req.headers["x-payment"] as string, 
+    accepts[0]
+  );
+  
   if (!parsed.success) {
     return res.status(402).json(parsed.response402);
   }
   
-  // Detect which token was used
+  // 检测使用的 Token
   const tokenUsed = parsed.data.payload.payload.authorization.token;
   
-  // Create matching requirements
+  // 创建匹配的要求
   const requirements = await server.createRequirements({
     asset: tokenUsed,
-    maxAmountRequired: "1000",
+    maxAmountRequired: "1000000",
   });
   
-  const result = await server.process(req.headers["x-payment"], requirements);
-  // ...
+  const result = await server.process(
+    req.headers["x-payment"] as string,
+    requirements
+  );
+  
+  if (!result.success) {
+    return res.status(402).json(result.response);
+  }
+  
+  res.json({ data: "premium content" });
 });
 ```
 
-### Example 4: Fast Mode (Skip Detection)
+### 示例 4: 快速模式（跳过检测）
 
 ```typescript
-// For maximum performance, skip auto-detection
+// 为获得最大性能，跳过自动检测
 const requirements = await server.createRequirements({
   asset: "0xUSDC",
-  maxAmountRequired: "1000",
-  paymentType: "permit", // Manually specify
-  autoDetect: false, // Skip detection (<1ms)
+  maxAmountRequired: "1000000",
+  paymentType: "permit",  // 手动指定
+  autoDetect: false,      // 跳过检测 (<1ms)
 });
 ```
 
-## Framework Integration
+## 🔌 框架集成
 
 ### Express
 
@@ -408,27 +538,27 @@ import { bscTestnet } from "viem/chains";
 
 const app = express();
 
-// Create client
 const client = createPublicClient({
   chain: bscTestnet,
   transport: http(),
 });
 
-// Create facilitator
 const facilitator = new Facilitator({
   recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
 });
 
-// Create server
 const server = new X402Server({ client, facilitator });
 
 app.post("/api/resource", async (req, res) => {
   const requirements = await server.createRequirements({
     asset: "0xUSDC",
-    maxAmountRequired: "1000",
+    maxAmountRequired: "1000000",
   });
   
-  const result = await server.process(req.headers["x-payment"], requirements);
+  const result = await server.process(
+    req.headers["x-payment"] as string,
+    requirements
+  );
   
   if (!result.success) {
     return res.status(402).json(result.response);
@@ -449,27 +579,27 @@ import { bscTestnet } from "viem/chains";
 
 const app = new Hono();
 
-// Create client
 const client = createPublicClient({
   chain: bscTestnet,
   transport: http(),
 });
 
-// Create facilitator
 const facilitator = new Facilitator({
   recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
 });
 
-// Create server
 const server = new X402Server({ client, facilitator });
 
 app.post("/api/resource", async (c) => {
   const requirements = await server.createRequirements({
     asset: "0xUSDC",
-    maxAmountRequired: "1000",
+    maxAmountRequired: "1000000",
   });
   
-  const result = await server.process(c.req.header("x-payment"), requirements);
+  const result = await server.process(
+    c.req.header("x-payment"),
+    requirements
+  );
   
   if (!result.success) {
     return c.json(result.response, 402);
@@ -479,7 +609,7 @@ app.post("/api/resource", async (c) => {
 });
 ```
 
-### Next.js API Route
+### Next.js App Router
 
 ```typescript
 import { X402Server } from "@wtflabs/x402-server";
@@ -488,24 +618,21 @@ import { NextRequest } from "next/server";
 import { createPublicClient, http } from "viem";
 import { bscTestnet } from "viem/chains";
 
-// Create client
 const client = createPublicClient({
   chain: bscTestnet,
   transport: http(),
 });
 
-// Create facilitator
 const facilitator = new Facilitator({
   recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
 });
 
-// Create server
 const server = new X402Server({ client, facilitator });
 
 export async function POST(req: NextRequest) {
   const requirements = await server.createRequirements({
     asset: "0xUSDC",
-    maxAmountRequired: "1000",
+    maxAmountRequired: "1000000",
   });
   
   const result = await server.process(
@@ -521,110 +648,452 @@ export async function POST(req: NextRequest) {
 }
 ```
 
-## Performance
+## 🎯 中间件详细文档
 
-| Operation | First Call | Cached Call |
-|-----------|-----------|-------------|
-| `createRequirements(autoDetect: true)` | 2-5s | <1ms |
-| `createRequirements(autoDetect: false)` | <1ms | <1ms |
-| `process()` | 2-5s + network | <1ms + network |
+### Express 中间件
 
-**Tips:**
-- Use `initialize()` on startup to pre-warm cache
-- Set `autoDetect: false` for maximum speed (requires manual `paymentType`)
-- Cache persists for the lifetime of the server instance
+#### 基础用法
 
-## Error Handling
+```typescript
+import { createExpressMiddleware } from "@wtflabs/x402-server";
+
+const middleware = createExpressMiddleware({
+  server,
+  getToken: (req) => req.body.token || "0xUSDC",
+  getAmount: (req) => calculatePrice(req.body),
+});
+
+app.post("/api", middleware, (req, res) => {
+  const { payer, txHash } = req.x402!;
+  res.json({ data: "resource", payer, txHash });
+});
+```
+
+#### 高级配置
 
 ```typescript
-const result = await server.process(paymentHeader, requirements);
+const middleware = createExpressMiddleware({
+  server,
+  
+  // 获取 token 地址
+  getToken: (req) => req.query.token as string || "0xUSDC",
+  
+  // 获取金额
+  getAmount: (req) => {
+    const { complexity } = req.body;
+    return calculateDynamicPrice(complexity);
+  },
+  
+  // 可选：额外配置
+  getConfig: (req) => ({
+    description: `API call for user ${req.user?.id}`,
+    resource: req.url,
+  }),
+  
+  // 可选：自定义错误处理
+  onError: (error, req, res) => {
+    console.error("Payment error:", error);
+    res.status(500).json({ error: error.message });
+  },
+  
+  // 可选：自定义 402 响应
+  on402: (req, res, response402) => {
+    console.log("Payment required for:", req.url);
+    res.status(402).json(response402);
+  },
+  
+  // 可选：支付成功回调
+  onPaymentSuccess: async (req, payer, txHash) => {
+    await logPayment(payer, txHash);
+    console.log(`Payment received from ${payer}`);
+  },
+});
+```
 
-if (!result.success) {
-  // 402 response with error details
-  console.log(result.response.error);
-  return res.status(402).json(result.response);
+#### 类型定义
+
+```typescript
+import type { 
+  ExpressRequest, 
+  ExpressResponse, 
+  ExpressNextFunction,
+  ExpressMiddleware 
+} from "@wtflabs/x402-server";
+
+// ExpressRequest 接口
+interface ExpressRequest {
+  headers: Record<string, string | string[] | undefined>;
+  body?: unknown;
+  params?: Record<string, string>;
+  query?: Record<string, string | string[] | undefined>;
+  x402?: {
+    payer: string;
+    txHash: string;
+  };
+}
+
+// ExpressResponse 接口
+interface ExpressResponse {
+  status(code: number): this;
+  json(body: unknown): this;
 }
 
-// Success!
-console.log(result.data.payer);
-console.log(result.data.txHash);
+// 中间件类型
+type ExpressMiddleware = (
+  req: ExpressRequest,
+  res: ExpressResponse,
+  next: ExpressNextFunction
+) => void | Promise<void>;
 ```
 
-## TypeScript Support
+### Hono 中间件
 
-Full TypeScript support with comprehensive type definitions:
+#### 基础用法
+
+```typescript
+import { createHonoMiddleware } from "@wtflabs/x402-server";
+
+const middleware = createHonoMiddleware({
+  server,
+  getToken: (c) => c.req.query("token") || "0xUSDC",
+  getAmount: async (c) => {
+    const body = await c.req.json();
+    return calculatePrice(body.complexity);
+  },
+});
+
+app.post("/api", middleware, (c) => {
+  const x402 = c.get("x402") as { payer: string; txHash: string };
+  return c.json({ data: "resource", payer: x402.payer });
+});
+```
+
+#### 高级配置
+
+```typescript
+const middleware = createHonoMiddleware({
+  server,
+  
+  // 获取 token 地址
+  getToken: (c) => c.req.query("token") || "0xUSDC",
+  
+  // 获取金额
+  getAmount: async (c) => {
+    const body = await c.req.json<{ complexity: number }>();
+    return calculateDynamicPrice(body.complexity);
+  },
+  
+  // 可选：额外配置
+  getConfig: async (c) => {
+    const body = await c.req.json();
+    return {
+      description: `API call with complexity ${body.complexity}`,
+    };
+  },
+  
+  // 可选：自定义错误处理
+  onError: (error, c) => {
+    console.error("Payment error:", error);
+    return c.json({ error: error.message }, 500);
+  },
+  
+  // 可选：自定义 402 响应
+  on402: (c, response402) => {
+    console.log("Payment required");
+    return c.json(response402, 402);
+  },
+  
+  // 可选：支付成功回调
+  onPaymentSuccess: async (c, payer, txHash) => {
+    await logPayment(payer, txHash);
+    console.log(`Payment received from ${payer}`);
+  },
+});
+```
+
+#### 类型定义
+
+```typescript
+import type { 
+  HonoContext, 
+  HonoRequest, 
+  HonoNext,
+  HonoMiddlewareHandler 
+} from "@wtflabs/x402-server";
+
+// HonoRequest 接口
+interface HonoRequest {
+  header(name: string): string | undefined;
+  json<T = unknown>(): Promise<T>;
+  query(name: string): string | undefined;
+}
+
+// HonoContext 接口
+interface HonoContext {
+  req: HonoRequest;
+  json(body: unknown, status?: number): Response;
+  set(key: string, value: unknown): void;
+  get(key: string): unknown;
+}
+
+// 中间件类型
+type HonoMiddlewareHandler = (
+  c: HonoContext, 
+  next: HonoNext
+) => Promise<Response | void>;
+```
+
+## 🎨 TypeScript 类型
+
+### 完整类型导出
 
 ```typescript
 import type {
+  // 配置
   X402ServerConfig,
   CreateRequirementsConfig,
+  
+  // 数据结构
   PaymentRequirements,
-  ProcessResult,
+  PaymentPayload,
+  Response402,
+  ParsedPayment,
+  
+  // 结果类型
   InitResult,
+  ProcessResult,
+  ParseResult,
+  VerifyResult,
+  SettleResult,
+  
+  // 中间件类型
+  ExpressRequest,
+  ExpressResponse,
+  ExpressNextFunction,
+  ExpressMiddleware,
+  ExpressMiddlewareOptions,
+  
+  HonoContext,
+  HonoRequest,
+  HonoNext,
+  HonoMiddlewareHandler,
+  HonoMiddlewareOptions,
+  
+  // Facilitator 类型
+  WaitUntil,
 } from "@wtflabs/x402-server";
 ```
 
-## Middlewares
+### Zod Schema 导出
 
-### Express Middleware
+所有类型都有对应的 Zod schema，用于运行时验证：
 
 ```typescript
-import { createExpressMiddleware } from "@wtflabs/x402-server";
+import {
+  CreateRequirementsConfigSchema,
+  PaymentRequirementsSchema,
+  PaymentPayloadSchema,
+  Response402Schema,
+  InitResultSchema,
+  ProcessResultSchema,
+  ParseResultSchema,
+  VerifyResultSchema,
+  SettleResultSchema,
+  ParsedPaymentSchema,
+} from "@wtflabs/x402-server";
 
-const middleware = createExpressMiddleware({
-  server,
-  getToken: (req) => req.body.token,
-  getAmount: (req) => calculatePrice(req.body),
-  onPaymentSuccess: async (req, payer, txHash) => {
-    console.log(`Payment from ${payer}: ${txHash}`);
-  },
-});
+// 使用 schema 验证
+const validated = CreateRequirementsConfigSchema.parse(config);
+```
 
-app.post("/api", middleware, (req, res) => {
-  const { payer, txHash } = req.x402!;
-  res.json({ data: "resource", payer, txHash });
+## ⚡ 性能优化
+
+### 性能指标
+
+| 操作 | 首次调用 | 缓存调用 |
+|------|---------|---------|
+| `createRequirements(autoDetect: true)` | 2-5s | <1ms |
+| `createRequirements(autoDetect: false)` | <1ms | <1ms |
+| `process()` | 2-5s + 网络 | <1ms + 网络 |
+
+### 优化技巧
+
+#### 1. 预热缓存
+
+```typescript
+// 服务启动时预热
+await server.initialize([
+  "0xUSDC",
+  "0xDAI",
+  "0xUSDT",
+]);
+```
+
+#### 2. 快速模式
+
+```typescript
+// 跳过自动检测以获得最大性能
+const requirements = await server.createRequirements({
+  asset: "0xUSDC",
+  maxAmountRequired: "1000000",
+  paymentType: "permit",
+  autoDetect: false, // <1ms
 });
 ```
 
-### Hono Middleware
+#### 3. 复用 Requirements
 
 ```typescript
-import { createHonoMiddleware } from "@wtflabs/x402-server";
+// 对于固定金额的 API，可以复用 requirements
+const cachedRequirements = await server.createRequirements({
+  asset: "0xUSDC",
+  maxAmountRequired: "1000000",
+});
 
-const middleware = createHonoMiddleware({
-  server,
-  getToken: async (c) => (await c.req.json()).token,
-  getAmount: async (c) => calculatePrice(await c.req.json()),
-  onPaymentSuccess: async (c, payer, txHash) => {
-    console.log(`Payment from ${payer}: ${txHash}`);
-  },
+// 在多个请求中复用
+app.post("/api", async (req, res) => {
+  const result = await server.process(
+    req.headers["x-payment"] as string,
+    cachedRequirements
+  );
+  // ...
 });
+```
 
-app.post("/api", middleware, (c) => {
-  const x402 = c.get("x402")!;
-  return c.json({ data: "resource", payer: x402.payer });
+#### 4. 后台初始化
+
+```typescript
+// 不阻塞服务启动
+server.initialize([tokenAddress]).then(result => {
+  if (result.success) {
+    console.log("✅ Cache warmed up");
+  }
 });
+
+// 立即开始服务
+app.listen(3000);
+```
+
+## ❌ 错误处理
+
+### ProcessResult 类型
+
+```typescript
+type ProcessResult = 
+  | {
+      success: true;
+      status: 200;
+      data: {
+        payer: string;
+        txHash: string;
+      };
+    }
+  | {
+      success: false;
+      status: 402;
+      response: Response402;
+    };
 ```
 
-**See [MIDDLEWARES.md](./MIDDLEWARES.md) for detailed guide.**
+### 错误处理示例
 
-## Documentation
+```typescript
+const result = await server.process(paymentHeader, requirements);
+
+if (!result.success) {
+  // 402 响应，包含错误详情
+  console.log("Error:", result.response.error);
+  console.log("Accepts:", result.response.accepts);
+  return res.status(402).json(result.response);
+}
+
+// 成功
+console.log("Payer:", result.data.payer);
+console.log("TxHash:", result.data.txHash);
+```
 
-- **[README.md](./README.md)** - This file
-- **[QUICK-START.md](./QUICK-START.md)** - 5-minute quick start guide
-- **[USAGE.md](./USAGE.md)** - Detailed usage documentation
-- **[MIDDLEWARES.md](./MIDDLEWARES.md)** - Express and Hono middleware guide
-- **[ZOD-VALIDATION.md](./ZOD-VALIDATION.md)** - Zod validation explained
-- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Architecture and design
-- **[examples/](./examples/)** - Complete examples
+### 常见错误
 
-## License
+| 错误 | 原因 | 解决方案 |
+|------|------|---------|
+| `missing_payment_header` | 未提供 X-Payment header | 客户端需要发送支付头 |
+| `invalid_payment_header` | 支付头格式错误 | 检查 Base64 编码和 JSON 格式 |
+| `Verification failed` | 签名验证失败 | 检查签名和参数匹配 |
+| `Settlement failed` | 链上交易失败 | 检查余额、授权和网络状态 |
+
+### Try-Catch 处理
+
+```typescript
+try {
+  const result = await server.process(paymentHeader, requirements);
+  
+  if (!result.success) {
+    return res.status(402).json(result.response);
+  }
+  
+  res.json({ data: "success" });
+} catch (error) {
+  console.error("Unexpected error:", error);
+  res.status(500).json({ 
+    error: "Internal server error",
+    message: error instanceof Error ? error.message : "Unknown error"
+  });
+}
+```
+
+## 🔍 调试
+
+### 启用日志
+
+```typescript
+// Facilitator 支持自定义 logger
+const facilitator = new Facilitator({
+  recipientAddress: "0x...",
+  logger: console, // 或自定义 logger
+});
+```
+
+### 缓存统计
+
+```typescript
+const stats = server.getCacheStats();
+console.log("Cache size:", stats.size);
+console.log("Cached tokens:", stats.keys);
+```
+
+### 清除缓存
+
+```typescript
+// 清除特定 token
+await server.clearCache("0xUSDC");
+
+// 清除所有缓存
+await server.clearCache();
+```
+
+## 📖 相关资源
+
+### 相关包
+
+- [`@wtflabs/x402`](../x402) - 核心协议类型和工具
+- [`@wtflabs/x402-detector`](../x402-detector) - Token 检测库
+- [`@wtflabs/x402-facilitator`](../x402-facilitator) - 支付处理库
+- [`@wtflabs/x402-fetch`](../x402-fetch) - 客户端 SDK
+
+### 文档
+
+- [x402 协议规范](../../specs/x402-specification.md)
+- [Exact Scheme 文档](../../specs/schemes/exact/)
+- [HTTP Transport](../../specs/transports/http.md)
+
+## 📄 许可证
 
 Apache-2.0
 
-## Related Packages
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+---
 
-- `@wtflabs/x402-detector` - Token detection (used internally)
-- `@wtflabs/x402-facilitator` - Payment processing (used internally)
-- `@wtflabs/x402-fetch` - Client SDK
-- `@wtflabs/x402` - Core protocol types
+**Made with ❤️ by WTFLabs**