跳转到主要内容

​
概述

x402x-facilitator 是 x402x 支付协议的“支付处理器”，负责验证支付签名（verify）与链上结算（settle），并提供查询支持能力（supported）。它连接你的服务与区块链，实现安全、可观测的收款流程。

​
核心特性

  • ✅ Verify：校验签名、金额与身份，快速且不上链
  • 🔗 Settle：执行链上交易，返回交易哈希（由 Facilitator 代付 gas）
  • 📊 Supported：查询链/Token 支持的支付类型
  • 🧱 EIP-7702：支持商家地址使用 Code Delegation
  • ⏱️ 灵活等待策略：simulated | submitted | confirmed

​
安装

npm i x402x-facilitator

​
快速上手

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