x402x-facilitator/dist/index.d.ts

X402 Payment Facilitator for handling payment settlements

/**
 * Facilitator 等待策略
 */
type WaitUntil = "simulated" | "submitted" | "confirmed";
/**
 * Facilitator 配置选项
 */
interface FacilitatorConfig {
    /**
     * 商家地址 (收款地址，支持 EIP 7702)
     */
    recipientAddress: string;
    /**
     * 等待策略
     * - "simulated": 仅模拟交易 (最快)
     * - "submitted": 等待交易提交
     * - "confirmed": 等待链上确认 (最安全，默认)
     */
    waitUntil?: WaitUntil;
    /**
     * Facilitator API 基础 URL (可选)
     */
    baseUrl?: string;
    /**
     * API 密钥 (可选)
     */
    apiKey?: string;
}
/**
 * 支付负载
 */
interface PaymentPayload {
    x402Version: number;
    scheme: string;
    network: string;
    payload: any;
}
/**
 * 支付要求
 */
interface PaymentRequirements {
    scheme: string;
    network: string;
    maxAmountRequired: string;
    resource: string;
    description: string;
    mimeType: string;
    payTo: string;
    maxTimeoutSeconds: number;
    asset: string;
    extra?: Record<string, any>;
}
/**
 * 验证响应
 */
interface VerifyResponse {
    success: boolean;
    payer?: string;
    error?: string;
    errorMessage?: string;
}
/**
 * 结算响应
 */
interface SettleResponse {
    success: boolean;
    transaction?: string;
    network?: string;
    error?: string;
    errorMessage?: string;
    receipt?: any;
}
/**
 * 支持的支付类型响应
 */
interface SupportedResponse {
    kinds: Array<{
        x402Version: number;
        scheme: string;
        network: string;
        extra?: Record<string, any>;
    }>;
}

/**
 * Facilitator 类
 * 用于处理支付验证和结算
 *
 * @example
 * ```typescript
 * const facilitator = new Facilitator({
 *   recipientAddress: "0x1234...",
 *   waitUntil: "confirmed", // 可选
 * });
 *
 * // 验证支付
 * const verifyResult = await facilitator.verify(
 *   paymentPayload,
 *   paymentRequirements
 * );
 *
 * // 结算支付
 * const settleResult = await facilitator.settle(
 *   paymentPayload,
 *   paymentRequirements
 * );
 *
 * // 获取支持的支付类型
 * const supported = await facilitator.supported();
 * ```
 */
declare class Facilitator {
    private config;
    private authHeaders;
    constructor(config: FacilitatorConfig);
    /**
     * 获取 recipient 地址
     */
    get recipientAddress(): string;
    /**
     * 获取等待策略
     */
    get waitUntil(): WaitUntil;
    /**
     * 验证支付
     * @param payload 支付负载
     * @param requirements 支付要求
     * @returns 验证结果
     */
    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
    /**
     * 结算支付
     * @param payload 支付负载
     * @param requirements 支付要求
     * @param waitUntil 可选的等待策略，覆盖配置中的默认值
     * @returns 结算结果
     */
    settle(payload: PaymentPayload, requirements: PaymentRequirements, waitUntil?: WaitUntil): Promise<SettleResponse>;
    /**
     * 获取支持的支付类型
     * @param filters 可选的过滤条件
     * @returns 支持的支付类型列表
     */
    supported(filters?: {
        chainId?: number;
        tokenAddress?: string;
    }): Promise<SupportedResponse>;
    /**
     * 获取完整配置
     */
    getConfig(): Required<FacilitatorConfig>;
}

export { Facilitator, type FacilitatorConfig, type PaymentPayload, type PaymentRequirements, type SettleResponse, type SupportedResponse, type VerifyResponse, type WaitUntil };