x402 SDK API Reference

`new X402FacilitatorClient(options)`

Option	Required	Description
`apiKey`	✅	Your XentFi WAAS API key.
`orgId`	✅	Your XentFi WAAS organization ID.

The facilitator URL (https://api.xentfi.com/v1/x402) and relayer wallet are fixed on the backend — they are not configurable in the client. Every request sends apiKey/orgId as the apikey/orgid headers.

Methods

`getSupported()`

getSupported(): Promise<SupportedResponse>

Lists all (chain, asset) pairs and schemes this facilitator supports. No authentication required — safe to call before you have apiKey/orgId configured, e.g. to build a merchant’s accepts list dynamically.

`verify(paymentPayload, paymentRequirements)`

verify(
  paymentPayload: PaymentPayload,
  paymentRequirements: PaymentRequirement
): Promise<VerifyResult>

Verifies a payment payload against a requirement — checks the EIP-712 signature, amount, recipient, and validity window. Returns { isValid: true } on success; throws on failure (see Error Handling).

`settle(paymentPayload, paymentRequirements)`

settle(
  paymentPayload: PaymentPayload,
  paymentRequirements: PaymentRequirement
): Promise<SettleResult>

Settles a payment by submitting the TransferWithAuthorization on-chain via your organization’s WAAS relayer wallet, which pays gas. Returns { success: true, txHash, network } on success; throws on failure.

Types

`PaymentRequirement`

What a resource server demands to be paid, expressed to the client in the 402 challenge.

interface PaymentRequirement {
  scheme: "eip3009";
  network: string;
  blockchainId: string;
  assetId: string;
  maxAmountRequired: string; // decimal string, in the token's own units
  payTo: Address;
  resource: string;
  description?: string;
  maxTimeoutSeconds: number;
}

`X402Challenge`

The full 402 response body.

interface X402Challenge {
  x402Version: 1;
  accepts: PaymentRequirement[];
}

`PaymentPayload` / `Eip3009SchemePayload`

What the payer sends back (base64-encoded) as the X-PAYMENT header. Currently the only supported scheme is eip3009; PaymentPayload is an alias for Eip3009SchemePayload.

interface Eip3009SchemePayload {
  scheme: "eip3009";
  from: Address;
  to: Address;
  value: string;        // token base units, decimal string
  validAfter: string;   // unix seconds
  validBefore: string;  // unix seconds
  nonce: Hex;
  signature: Hex;
}

`VerifyResult` / `SettleResult`

type VerifyResult = { isValid: true };
type SettleResult = { success: true; txHash: Hex; network: string };

Both are the success shape only — failures throw instead of returning a falsy result (see Error Handling).

`SupportedResponse`

interface SupportedResponse {
  protocolVersion: string;
  facilitatorAddress: string;
  supportedConfigurations: SupportedConfiguration[];
}

interface SupportedConfiguration {
  network: { id: string; name: string; type: string };
  gasSponsorship: { enabled: boolean; maxSponsorshipValueUsd?: string };
  tokens: Array<{
    id: string;
    name: string;
    symbol: string;
    address: string;
    decimals: number;
    version: string;
    supportedSchemes: Array<{
      type: string;
      methods: string[];
      contractAddress?: string;
    }>;
  }>;
}

`Eip3009TokenDomain`

Needed if you use the signing helpers — see EIP-3009 Signing Reference for full detail.

interface Eip3009TokenDomain {
  chainId: number;
  tokenAddress: Address;
  tokenName: string;
  tokenVersion: string;
  tokenDecimals: number;
}

All exports

import {
  X402FacilitatorClient,
  X402FacilitatorError,
  X402FacilitatorNetworkError,
  X402FacilitatorConfigError,
  signEip3009Authorization,
  buildEip3009Domain,
  TRANSFER_WITH_AUTHORIZATION_TYPES,
} from "@xentfi/x402-facilitator";

import type {
  X402FacilitatorClientOptions,
  SignExactAuthorizationParams,
  RetryOptions,
  X402Scheme,
  PaymentRequirement,
  X402Challenge,
  Eip3009SchemePayload,
  PaymentPayload,
  VerifyResult,
  SettleResult,
  SupportedResponse,
  SupportedConfiguration,
  Eip3009TokenDomain,
} from "@xentfi/x402-facilitator";

Next steps

Resource Server Guide

See verify/settle used end-to-end.

Error Handling

Error classes and HTTP status mapping.

Getting Started

Guides

Reference

`new X402FacilitatorClient(options)`

Methods

`getSupported()`

`verify(paymentPayload, paymentRequirements)`

`settle(paymentPayload, paymentRequirements)`

Types

`PaymentRequirement`

`X402Challenge`

`PaymentPayload` / `Eip3009SchemePayload`

`VerifyResult` / `SettleResult`

`SupportedResponse`

`Eip3009TokenDomain`

All exports

Next steps

Resource Server Guide

Error Handling

​new X402FacilitatorClient(options)

​Methods

​getSupported()

​verify(paymentPayload, paymentRequirements)

​settle(paymentPayload, paymentRequirements)

​Types

​PaymentRequirement

​X402Challenge

​PaymentPayload / Eip3009SchemePayload

​VerifyResult / SettleResult

​SupportedResponse

​Eip3009TokenDomain

​All exports

​Next steps

Resource Server Guide

Error Handling

`new X402FacilitatorClient(options)`

Methods

`getSupported()`

`verify(paymentPayload, paymentRequirements)`

`settle(paymentPayload, paymentRequirements)`

Types

`PaymentRequirement`

`X402Challenge`

`PaymentPayload` / `Eip3009SchemePayload`

`VerifyResult` / `SettleResult`

`SupportedResponse`

`Eip3009TokenDomain`

All exports

Next steps