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

> Verification (verify), settlement (settle), and capability query (supported)

## Overview

`x402x-facilitator` is the “payment processor” for the x402x payment protocol. It verifies payment signatures (verify), performs on-chain settlement (settle), and provides capability queries (supported). It connects your service to the blockchain for a secure and observable payment flow.

### Key features

* Verify: validate signature, amount, and identity — fast and off-chain
* Settle: submit on-chain transaction and return tx hash (gas sponsored by the Facilitator)
* Supported: query payment types supported by chains/tokens
* EIP-7702: support code delegation for merchant addresses
* Flexible waiting strategy: `simulated` | `submitted` | `confirmed`

## Install

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

## Quick start

```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);         // returns transaction hash
const supported = await f.supported();         // { kinds, networks, ... }
```

## Core concepts

### Verify vs Settle

* Verify: off-chain, `<100ms`; validates signature/amount/authorization (recommended before settlement)
* Settle: on-chain; returns `transactionHash`; gas is paid by a relayer

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

### Waiting strategy (WaitUntil)

```ts theme={null}
type WaitUntil = "simulated" | "submitted" | "confirmed";
// - simulated: only simulate (fastest)
// - submitted: wait until submitted to mempool (fast)
// - confirmed: wait for on-chain confirmation (safest; default in prod)
```

### Recipient / Relayer

* `recipientAddress`: merchant address (supports EIP-7702)
* `relayer`: relayer address (optional, default built-in)

## Configuration highlights

* `recipientAddress`: merchant address (EIP-7702)
* `waitUntil`: "simulated" | "submitted" | "confirmed"

## Scenario tips

* Perform `verify` before `settle` for a more robust flow
* Log settlement failures for reconciliation and compensation

## API reference (condensed)

```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>;
}
```

## Usage examples

### Basic payment flow

```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); // third param can override waitUntil
if (!settleResult.success) throw new Error(settleResult.error);

console.log("payer:", verifyResult.payer, "tx:", settleResult.transactionHash);
```

### Verify-only mode

```ts theme={null}
const result = await f.verify(payload, requirements);
if (result.success) {
  // Validate user intent only; no on-chain transaction
  await grantAccess(result.payer!);
}
```

### Dynamic waiting strategy

```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);
```

## Best practices

* Use `confirmed` by default in production; consider `submitted` for small amounts
* Classify and log errors; support reconciliation and retries
* Use environment variables to manage `recipientAddress`, API keys, etc.

## Resources

* Source: `https://github.com/WTFLabs-WTF/x402x/tree/main/typescript/packages/x402x-facilitator`
* Issues: `https://github.com/WTFLabs-WTF/x402x/issues`