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

# x402x-server

> 创建支付要求、解析/验证/结算与框架中间件

## 概述

`x402x-server` 是服务端 SDK，整合 Token 检测、支付验证和结算，一站式完成 x402x 协议从“创建支付要求 → 解析/验证/结算 → 返回资源”的完整链路。

### 核心特性

* ✅ 简洁 API：两参起步，自动处理复杂性
* 🔍 自动 Token 检测：基于 `x402x-detector`，内置缓存
* 💰 完整支付流程：`parse → verify → settle` 一体化
* ⚡ 动态创建支付要求：固定价/动态价均支持
* 🚀 性能优化：缓存预热、快速模式、非阻塞初始化
* 🔌 框架中间件：Express / Hono 开箱即用
* ✅ 类型安全：100% TypeScript + Zod 运行时校验

## 安装与依赖

```bash theme={null}
npm i x402x-server x402x-facilitator viem
```

可选（按需）：

```bash theme={null}
# Express
npm i express

# Hono
npm i hono
```

## 快速开始

### 最小用法（手动处理）

```ts theme={null}
import { X402Server } from "x402x-server";
import { Facilitator } from "x402x-facilitator";
import { createPublicClient, http } from "viem";
import { bscTestnet } from "viem/chains";

const client = createPublicClient({ chain: bscTestnet, transport: http() });
const f = new Facilitator({ recipientAddress: "0xSeller", waitUntil: "confirmed" });
const server = new X402Server({ client, facilitator: f });

// 1) 创建支付要求（自动/手动指定 paymentType 均可）
const reqs = await server.createRequirements({
  asset: "0xToken",
  maxAmountRequired: "1000000",
  description: "Premium API",
});

// 2) 处理支付（parse → verify → settle）
const result = await server.process(req.headers["x-payment"] as string, reqs);

// 3) 根据结果返回
if (!result.success) {
  return res.status(result.status).json(result.response);
}
return res.json({ data: "ok", payer: result.data.payer, txHash: result.data.txHash });
```

### Express 中间件（推荐）

```ts theme={null}
import express from "express";
import { createExpressMiddleware, X402Server } from "x402x-server";
import { Facilitator } from "x402x-facilitator";
import { createPublicClient, http } from "viem";
import { bscTestnet } from "viem/chains";

const app = express();
const client = createPublicClient({ chain: bscTestnet, transport: http() });
const facilitator = new Facilitator({ recipientAddress: "0xSeller", waitUntil: "confirmed" });
const server = new X402Server({ client, facilitator });

const payment = createExpressMiddleware({
  server,
  getToken: () => "0xUSDC",
  getAmount: () => "1000000", // 1 USDC (6 decimals)
  // 可选：getConfig/onError/on402/onPaymentSuccess
});

app.post("/premium", payment, (req, res) => {
  const { payer, txHash } = req.x402!;
  res.json({ success: true, payer, txHash, data: "Premium content" });
});

app.listen(3000);
```

### Hono 中间件

```ts theme={null}
import { Hono } from "hono";
import { createHonoMiddleware } from "x402x-server";

const app = new Hono();
const middleware = createHonoMiddleware({
  server,
  getToken: (c) => c.req.query("token") || "0xUSDC",
  getAmount: async (c) => {
    const body = await c.req.json<{ complexity: number }>();
    return (body.complexity * 100000).toString();
  },
});
app.post("/api", middleware, (c) => {
  const x402 = c.get("x402") as { payer: string; txHash: string };
  return c.json({ data: "resource", payer: x402.payer, txHash: x402.txHash });
});
```

## 核心能力

### 1) 自动 Token 检测

```ts theme={null}
const requirements = await server.createRequirements({
  asset: "0xUSDC",
  maxAmountRequired: "1000000",
  // 默认 autoDetect: true，将通过 detector 自动选择 paymentType
});
// 可能选择：eip3009 / permit / permit2（优先级：eip3009 > permit > permit2）
```

### 2) 一体化处理：parse → verify → settle

```ts theme={null}
const result = await server.process(paymentHeader, requirements);
// 成功：{ success: true, status: 200, data: { payer, txHash } }
// 失败（客户端问题）：{ success: false, status: 402, errorStage: "parse" | "verify", response }
// 失败（服务端结算）：{ success: false, status: 500, errorStage: "settle", response, error }
```

### 3) 配置与工具

```ts theme={null}
const server = new X402Server({ client, facilitator, network: "bsc-testnet" });
await server.initialize(["0xUSDC"]);          // 预热（非阻塞）
server.getCacheStats();                        // { size, keys }
await server.clearCache();                     // 清理缓存
server.get402Response(requirements, "reason"); // 生成标准 402 响应
```

## 工具

* `initialize(tokens)`：预热 Token 检测缓存（`<1ms` 命中）
* `get402Response(reqs, message?)`：生成标准 402 响应体
* `getCacheStats/clearCache`：查看/清理缓存

## API 参考（精简）

```ts theme={null}
class X402Server {
  constructor(config: { client: PublicClient; facilitator: Facilitator; network?: string });
  initialize(tokens: string[]): Promise<{ success: boolean; detected?: number; total?: number; error?: string }>;
  createRequirements(config: {
    asset: string;
    maxAmountRequired: string;
    network?: string;
    scheme?: "exact";
    outputSchema?: Record<string, unknown>;
    paymentType?: "permit" | "eip3009" | "permit2" | "auto";
    resource?: string;
    description?: string;
    mimeType?: string;
    maxTimeoutSeconds?: number;
    extra?: Record<string, unknown>;
    autoDetect?: boolean;
  }): Promise<PaymentRequirements>;
  process(paymentHeader: string | undefined, requirements: PaymentRequirements): Promise<
    | { success: true; status: 200; data: { payer: string; txHash: string } }
    | { success: false; status: 402; errorStage: "parse" | "verify"; response: Response402 }
    | { success: false; status: 500; errorStage: "settle"; response: Response402; error: string }
  >;
  parse(paymentHeader: string | undefined, requirements: PaymentRequirements): ParseResult;
  verify(parsed: ParsedPayment): Promise<VerifyResult>;
  settle(parsed: ParsedPayment): Promise<SettleResult>;
  get402Response(requirements: PaymentRequirements, error?: string): Response402;
  clearCache(tokenAddress?: string): Promise<void>;
  getCacheStats(): { size: number; keys: string[] };
}
```

## 性能与优化

* 预热缓存：服务启动时 `initialize([tokens])`
* 快速模式：`createRequirements({ paymentType: "permit", autoDetect: false })`（`<1ms`）
* 复用要求：固定价接口复用同一 `requirements`
* 后台初始化：不阻塞启动，初始化完成后打印日志

性能参考：

| 操作                                      | 首次调用      | 缓存调用        |
| --------------------------------------- | --------- | ----------- |
| `createRequirements(autoDetect: true)`  | 2-5s      | `<1ms`      |
| `createRequirements(autoDetect: false)` | `<1ms`    | `<1ms`      |
| `process()`                             | 2-5s + 网络 | `<1ms` + 网络 |

## 最佳实践

* 使用环境变量配置 `recipientAddress`、RPC 等
* 区分错误阶段：`parse/verify` 返回 402，`settle` 返回 500
* 记录链上交易哈希，建立对账与重试机制
* 统一日志与指标，便于观测与调优

## 相关资源

* 源代码：`https://github.com/WTFLabs-WTF/x402x/tree/main/typescript/packages/x402x-server`
* 问题反馈：`https://github.com/WTFLabs-WTF/x402x/issues`