x402x-server

概述

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

核心特性

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

安装与依赖

npm i x402x-server x402x-facilitator viem

可选（按需）：

# Express
npm i express

# Hono
npm i hono

快速开始

最小用法（手动处理）

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 中间件（推荐）

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 中间件

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 检测

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

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

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) 配置与工具

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 参考（精简）

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
记录链上交易哈希，建立对账与重试机制
统一日志与指标，便于观测与调优

Packages

概述

核心特性

安装与依赖

快速开始

最小用法（手动处理）

Express 中间件（推荐）

Hono 中间件

核心能力

1) 自动 Token 检测

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

3) 配置与工具

工具

API 参考（精简）

性能与优化

最佳实践

相关资源

Packages

Documentation Index

​概述

​核心特性

​安装与依赖

​快速开始

​最小用法（手动处理）

​Express 中间件（推荐）

​Hono 中间件

​核心能力

​1) 自动 Token 检测

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

​3) 配置与工具

​工具

​API 参考（精简）

​性能与优化

​最佳实践

​相关资源

概述

核心特性

安装与依赖

快速开始

最小用法（手动处理）

Express 中间件（推荐）

Hono 中间件

核心能力

1) 自动 Token 检测

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

3) 配置与工具

工具

API 参考（精简）

性能与优化

最佳实践

相关资源