TypeScript SDK

x402.facilitator

Creates a facilitator for the x402 payment protocol. You can use this with verifyPayment or with any x402 middleware to enable settling transactions with your thirdweb server wallet.

Example


import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
 
const client = createThirdwebClient({
  secretKey: "your-secret-key",
});
const thirdwebX402Facilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});
 
// add the facilitator to any x402 payment middleware
const middleware = paymentMiddleware(
  "0x1234567890123456789012345678901234567890",
  {
    "/api/paywall": {
      price: "$0.01",
      network: "base-sepolia",
      config: {
        description: "Access to paid content",
      },
    },
  },
  thirdwebX402Facilitator,
);


function facilitator(config: ThirdwebX402FacilitatorConfig): {
  createAuthHeaders: () => Promise<{
    list: { "x-secret-key": string };
    settle: {
      "x-secret-key": string;
      "x-settlement-wallet-address": string;
      "x-vault-access-token"?: string;
    };
    supported: { "x-secret-key": string };
    verify: { "x-secret-key": string };
  }>;
  url: `${string}://${string}`;
  settle: (
    payload: {
      network: string;
      payload:
        | {
            authorization: {
              from: string;
              nonce: string;
              to: string;
              validAfter: string;
              validBefore: string;
              value: string;
            };
            signature: string;
          }
        | { transaction: string };
      scheme: "exact";
      x402Version: number;
    },
    paymentRequirements: {
      asset: string;
      description: string;
      extra?: Record<string, any>;
      maxAmountRequired: string;
      maxTimeoutSeconds: number;
      mimeType: string;
      network: string;
      outputSchema?: Record<string, any>;
      payTo: string;
      resource: string;
      scheme: "exact";
    },
  ) => Promise<{
    errorReason?:
      | "insufficient_funds"
      | "invalid_exact_evm_payload_authorization_valid_after"
      | "invalid_exact_evm_payload_authorization_valid_before"
      | "invalid_exact_evm_payload_authorization_value"
      | "invalid_exact_evm_payload_signature"
      | "invalid_exact_evm_payload_recipient_mismatch"
      | "invalid_exact_svm_payload_transaction"
      | "invalid_exact_svm_payload_transaction_amount_mismatch"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_payee"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_asset"
      | "invalid_exact_svm_payload_transaction_instructions"
      | "invalid_exact_svm_payload_transaction_instructions_length"
      | "invalid_exact_svm_payload_transaction_instructions_compute_limit_instruction"
      | "invalid_exact_svm_payload_transaction_instructions_compute_price_instruction"
      | "invalid_exact_svm_payload_transaction_instructions_compute_price_instruction_too_high"
      | "invalid_exact_svm_payload_transaction_instruction_not_spl_token_transfer_checked"
      | "invalid_exact_svm_payload_transaction_instruction_not_token_2022_transfer_checked"
      | "invalid_exact_svm_payload_transaction_not_a_transfer_instruction"
      | "invalid_exact_svm_payload_transaction_cannot_derive_receiver_ata"
      | "invalid_exact_svm_payload_transaction_receiver_ata_not_found"
      | "invalid_exact_svm_payload_transaction_sender_ata_not_found"
      | "invalid_exact_svm_payload_transaction_simulation_failed"
      | "invalid_exact_svm_payload_transaction_transfer_to_incorrect_ata"
      | "invalid_network"
      | "invalid_payload"
      | "invalid_payment_requirements"
      | "invalid_scheme"
      | "invalid_payment"
      | "payment_expired"
      | "unsupported_scheme"
      | "invalid_x402_version"
      | "invalid_transaction_state"
      | "settle_exact_svm_block_height_exceeded"
      | "settle_exact_svm_transaction_confirmation_timed_out"
      | "unexpected_settle_error"
      | "unexpected_verify_error";
    network: string;
    payer?: string;
    success: boolean;
    transaction: string;
  }>;
  supported: () => Promise<{
    kinds: Array<{
      extra?: Record<string, any>;
      network:
        | "base"
        | "base-sepolia"
        | "avalanche-fuji"
        | "avalanche"
        | "iotex"
        | "solana-devnet"
        | "solana"
        | "sei"
        | "sei-testnet";
      scheme: "exact";
      x402Version: number;
    }>;
  }>;
  verify: (
    payload: {
      network: string;
      payload:
        | {
            authorization: {
              from: string;
              nonce: string;
              to: string;
              validAfter: string;
              validBefore: string;
              value: string;
            };
            signature: string;
          }
        | { transaction: string };
      scheme: "exact";
      x402Version: number;
    },
    paymentRequirements: {
      asset: string;
      description: string;
      extra?: Record<string, any>;
      maxAmountRequired: string;
      maxTimeoutSeconds: number;
      mimeType: string;
      network: string;
      outputSchema?: Record<string, any>;
      payTo: string;
      resource: string;
      scheme: "exact";
    },
  ) => Promise<{
    invalidReason?:
      | "insufficient_funds"
      | "invalid_exact_evm_payload_authorization_valid_after"
      | "invalid_exact_evm_payload_authorization_valid_before"
      | "invalid_exact_evm_payload_authorization_value"
      | "invalid_exact_evm_payload_signature"
      | "invalid_exact_evm_payload_recipient_mismatch"
      | "invalid_exact_svm_payload_transaction"
      | "invalid_exact_svm_payload_transaction_amount_mismatch"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_payee"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_asset"
      | "invalid_exact_svm_payload_transaction_instructions"
      | "invalid_exact_svm_payload_transaction_instructions_length"
      | "invalid_exact_svm_payload_transaction_instructions_compute_limit_instruction"
      | "invalid_exact_svm_payload_transaction_instructions_compute_price_instruction"
      | "invalid_exact_svm_payload_transaction_instructions_compute_price_instruction_too_high"
      | "invalid_exact_svm_payload_transaction_instruction_not_spl_token_transfer_checked"
      | "invalid_exact_svm_payload_transaction_instruction_not_token_2022_transfer_checked"
      | "invalid_exact_svm_payload_transaction_not_a_transfer_instruction"
      | "invalid_exact_svm_payload_transaction_cannot_derive_receiver_ata"
      | "invalid_exact_svm_payload_transaction_receiver_ata_not_found"
      | "invalid_exact_svm_payload_transaction_sender_ata_not_found"
      | "invalid_exact_svm_payload_transaction_simulation_failed"
      | "invalid_exact_svm_payload_transaction_transfer_to_incorrect_ata"
      | "invalid_network"
      | "invalid_payload"
      | "invalid_payment_requirements"
      | "invalid_scheme"
      | "invalid_payment"
      | "payment_expired"
      | "unsupported_scheme"
      | "invalid_x402_version"
      | "invalid_transaction_state"
      | "settle_exact_svm_block_height_exceeded"
      | "settle_exact_svm_transaction_confirmation_timed_out"
      | "unexpected_settle_error"
      | "unexpected_verify_error";
    isValid: boolean;
    payer?: string;
  }>;
};

Parameters

The configuration for the facilitator

Type


let config: {
  baseUrl?: string;
  client: ThirdwebClient;
  serverWalletAddress: string;
  vaultAccessToken?: string;
};

Returns


let returnType: {
  createAuthHeaders: () => Promise<{
    list: { "x-secret-key": string };
    settle: {
      "x-secret-key": string;
      "x-settlement-wallet-address": string;
      "x-vault-access-token"?: string;
    };
    supported: { "x-secret-key": string };
    verify: { "x-secret-key": string };
  }>;
  url: `${string}://${string}`;
  settle: (
    payload: {
      network: string;
      payload:
        | {
            authorization: {
              from: string;
              nonce: string;
              to: string;
              validAfter: string;
              validBefore: string;
              value: string;
            };
            signature: string;
          }
        | { transaction: string };
      scheme: "exact";
      x402Version: number;
    },
    paymentRequirements: {
      asset: string;
      description: string;
      extra?: Record<string, any>;
      maxAmountRequired: string;
      maxTimeoutSeconds: number;
      mimeType: string;
      network: string;
      outputSchema?: Record<string, any>;
      payTo: string;
      resource: string;
      scheme: "exact";
    },
  ) => Promise<{
    errorReason?:
      | "insufficient_funds"
      | "invalid_exact_evm_payload_authorization_valid_after"
      | "invalid_exact_evm_payload_authorization_valid_before"
      | "invalid_exact_evm_payload_authorization_value"
      | "invalid_exact_evm_payload_signature"
      | "invalid_exact_evm_payload_recipient_mismatch"
      | "invalid_exact_svm_payload_transaction"
      | "invalid_exact_svm_payload_transaction_amount_mismatch"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_payee"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_asset"
      | "invalid_exact_svm_payload_transaction_instructions"
      | "invalid_exact_svm_payload_transaction_instructions_length"
      | "invalid_exact_svm_payload_transaction_instructions_compute_limit_instruction"
      | "invalid_exact_svm_payload_transaction_instructions_compute_price_instruction"
      | "invalid_exact_svm_payload_transaction_instructions_compute_price_instruction_too_high"
      | "invalid_exact_svm_payload_transaction_instruction_not_spl_token_transfer_checked"
      | "invalid_exact_svm_payload_transaction_instruction_not_token_2022_transfer_checked"
      | "invalid_exact_svm_payload_transaction_not_a_transfer_instruction"
      | "invalid_exact_svm_payload_transaction_cannot_derive_receiver_ata"
      | "invalid_exact_svm_payload_transaction_receiver_ata_not_found"
      | "invalid_exact_svm_payload_transaction_sender_ata_not_found"
      | "invalid_exact_svm_payload_transaction_simulation_failed"
      | "invalid_exact_svm_payload_transaction_transfer_to_incorrect_ata"
      | "invalid_network"
      | "invalid_payload"
      | "invalid_payment_requirements"
      | "invalid_scheme"
      | "invalid_payment"
      | "payment_expired"
      | "unsupported_scheme"
      | "invalid_x402_version"
      | "invalid_transaction_state"
      | "settle_exact_svm_block_height_exceeded"
      | "settle_exact_svm_transaction_confirmation_timed_out"
      | "unexpected_settle_error"
      | "unexpected_verify_error";
    network: string;
    payer?: string;
    success: boolean;
    transaction: string;
  }>;
  supported: () => Promise<{
    kinds: Array<{
      extra?: Record<string, any>;
      network:
        | "base"
        | "base-sepolia"
        | "avalanche-fuji"
        | "avalanche"
        | "iotex"
        | "solana-devnet"
        | "solana"
        | "sei"
        | "sei-testnet";
      scheme: "exact";
      x402Version: number;
    }>;
  }>;
  verify: (
    payload: {
      network: string;
      payload:
        | {
            authorization: {
              from: string;
              nonce: string;
              to: string;
              validAfter: string;
              validBefore: string;
              value: string;
            };
            signature: string;
          }
        | { transaction: string };
      scheme: "exact";
      x402Version: number;
    },
    paymentRequirements: {
      asset: string;
      description: string;
      extra?: Record<string, any>;
      maxAmountRequired: string;
      maxTimeoutSeconds: number;
      mimeType: string;
      network: string;
      outputSchema?: Record<string, any>;
      payTo: string;
      resource: string;
      scheme: "exact";
    },
  ) => Promise<{
    invalidReason?:
      | "insufficient_funds"
      | "invalid_exact_evm_payload_authorization_valid_after"
      | "invalid_exact_evm_payload_authorization_valid_before"
      | "invalid_exact_evm_payload_authorization_value"
      | "invalid_exact_evm_payload_signature"
      | "invalid_exact_evm_payload_recipient_mismatch"
      | "invalid_exact_svm_payload_transaction"
      | "invalid_exact_svm_payload_transaction_amount_mismatch"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_payee"
      | "invalid_exact_svm_payload_transaction_create_ata_instruction_incorrect_asset"
      | "invalid_exact_svm_payload_transaction_instructions"
      | "invalid_exact_svm_payload_transaction_instructions_length"
      | "invalid_exact_svm_payload_transaction_instructions_compute_limit_instruction"
      | "invalid_exact_svm_payload_transaction_instructions_compute_price_instruction"
      | "invalid_exact_svm_payload_transaction_instructions_compute_price_instruction_too_high"
      | "invalid_exact_svm_payload_transaction_instruction_not_spl_token_transfer_checked"
      | "invalid_exact_svm_payload_transaction_instruction_not_token_2022_transfer_checked"
      | "invalid_exact_svm_payload_transaction_not_a_transfer_instruction"
      | "invalid_exact_svm_payload_transaction_cannot_derive_receiver_ata"
      | "invalid_exact_svm_payload_transaction_receiver_ata_not_found"
      | "invalid_exact_svm_payload_transaction_sender_ata_not_found"
      | "invalid_exact_svm_payload_transaction_simulation_failed"
      | "invalid_exact_svm_payload_transaction_transfer_to_incorrect_ata"
      | "invalid_network"
      | "invalid_payload"
      | "invalid_payment_requirements"
      | "invalid_scheme"
      | "invalid_payment"
      | "payment_expired"
      | "unsupported_scheme"
      | "invalid_x402_version"
      | "invalid_transaction_state"
      | "settle_exact_svm_block_height_exceeded"
      | "settle_exact_svm_transaction_confirmation_timed_out"
      | "unexpected_settle_error"
      | "unexpected_verify_error";
    isValid: boolean;
    payer?: string;
  }>;
};

a x402 compatible FacilitatorConfig