> ## 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

> 验证（verify）、结算（settle）与支持查询（supported）

## 概述

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

### 核心特性

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

## 安装

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

## 快速上手

```ts theme={null}
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

```ts theme={null}
type VerifyResponse = { success: boolean; payer?: string; error?: string };
type SettleResponse = { success: boolean; transactionHash?: string; error?: string };
```

### 等待策略（WaitUntil）

```ts theme={null}
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 参考（精简）

```ts theme={null}
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>;
}
```

## 使用示例

### 基础支付流程

```ts theme={null}
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);
```

### 仅验证模式

```ts theme={null}
const result = await f.verify(payload, requirements);
if (result.success) {
  // 仅验证用户意图，无需上链
  await grantAccess(result.payer!);
}
```

### 动态等待策略

```ts theme={null}
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`