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-facilitator 是 x402x 支付协议的“支付处理器”，负责验证支付签名（verify）与链上结算（settle），并提供查询支持能力（supported）。它连接你的服务与区块链，实现安全、可观测的收款流程。
核心特性
- ✅ Verify：校验签名、金额与身份，快速且不上链
- 🔗 Settle：执行链上交易，返回交易哈希（由 Facilitator 代付 gas）
- 📊 Supported：查询链/Token 支持的支付类型
- 🧱 EIP-7702：支持商家地址使用 Code Delegation
- ⏱️ 灵活等待策略：
simulated | submitted | confirmed
快速上手
import { Facilitator } from "x402x-facilitator";
const f = new Facilitator({ recipientAddress: "0xSeller", waitUntil: "confirmed" });
await f.verify(payload, requirements);
await f.settle(payload, requirements); // 返回交易哈希
const supported = await f.supported(); // { kinds, networks, ... }
核心概念
Verify vs Settle
- Verify（验证）：不上链，
<100ms，校验签名/金额/授权（推荐在结算前进行）
- Settle（结算）：上链，返回
transactionHash，由中继器代付 gas
type VerifyResponse = { success: boolean; payer?: string; error?: string };
type SettleResponse = { success: boolean; transactionHash?: string; error?: string };
等待策略（WaitUntil）
type WaitUntil = "simulated" | "submitted" | "confirmed";
// - simulated：仅模拟（最快）
// - submitted：等待提交到 mempool（快）
// - confirmed：等待链上确认（最稳，生产默认）
Recipient / Relayer
recipientAddress：商家地址（支持 EIP-7702）relayer：中继器地址（可选，默认内置）
配置要点
recipientAddress：商家地址（EIP-7702）waitUntil: “simulated” | “submitted” | “confirmed”
场景建议
- 先
verify 再 settle，链路更稳健
- 记录结算失败以便补偿与对账
API 参考（精简）
class Facilitator {
constructor(config: {
recipientAddress: string;
relayer?: string;
waitUntil?: "simulated" | "submitted" | "confirmed";
baseUrl?: string;
apiKey?: string;
});
verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<{
success: boolean; payer?: string; error?: string;
}>;
settle(
payload: PaymentPayload,
requirements: PaymentRequirements,
waitUntil?: "simulated" | "submitted" | "confirmed"
): Promise<{ success: boolean; transactionHash?: string; error?: string }>;
supported(filters?: { chainId?: number; tokenAddress?: string }): Promise<{ kinds: string[] }>;
getConfig(): Required<FacilitatorConfig>;
}
使用示例
基础支付流程
const verifyResult = await f.verify(payload, requirements);
if (!verifyResult.success) throw new Error(verifyResult.error);
const settleResult = await f.settle(payload, requirements); // 可传第三参覆盖 waitUntil
if (!settleResult.success) throw new Error(settleResult.error);
console.log("payer:", verifyResult.payer, "tx:", settleResult.transactionHash);
仅验证模式
const result = await f.verify(payload, requirements);
if (result.success) {
// 仅验证用户意图，无需上链
await grantAccess(result.payer!);
}
动态等待策略
const getWait = (amount: string) => BigInt(amount) > BigInt("10000000") ? "confirmed" : "submitted";
const waitUntil = getWait(requirements.maxAmountRequired);
const settled = await f.settle(payload, requirements, waitUntil);
最佳实践
- 生产默认使用
confirmed，小额可选 submitted
- 识别/分类错误，记录失败以支持对账与重试
- 使用环境变量管理
recipientAddress/API Key 等敏感信息
相关资源
- 源代码：
https://github.com/WTFLabs-WTF/x402x/tree/main/typescript/packages/x402x-facilitator
- 问题反馈：
https://github.com/WTFLabs-WTF/x402x/issues
