Payments

Facilitator

The facilitator is a service that handles verifying and submitting x402 payments. It uses your own server wallet and leverages EIP-7702 to submit transactions gaslessly.

The thirdweb facilitator is compatible with any x402 backend and middleware libraries like x402-hono, x402-next, and more.

How It Works

Verification - Validates payment signatures and requirements
Settlement - Submits the payment transaction on-chain
Gasless - Uses EIP-7702 for gasless transactions
Your Wallet - Uses your own server wallet for receiving payments

You can view all transactions processed by your facilitator in your project dashboard.

Chain and token support

Our facilitator supports payments on any EVM chain, as long as the payment token supports either:

ERC-2612 permit (most ERC20 tokens)
ERC-3009 sign with authorization (USDC on all chains)

Creating a Facilitator

Create a facilitator instance to use with settlePayment() or external middleware:


import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
 
const client = createThirdwebClient({
  secretKey: "your-secret-key",
});
 
const thirdwebFacilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});

Configuration Options


const thirdwebFacilitator = facilitator({
  // Required: Your thirdweb client with secret key
  client: client,
 
  // Required: Your server wallet address that will execute transactions
  // get it from your project dashboard
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
 
  // Optional: Wait behavior for settlements
  // - "simulated": Only simulate the transaction (fastest)
  // - "submitted": Wait until transaction is submitted
  // - "confirmed": Wait for full on-chain confirmation (slowest, default)
  waitUntil: "confirmed",
});

Usage with settlePayment()

Use the facilitator with the settlePayment() function:


import { settlePayment, facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
import { arbitrumSepolia } from "thirdweb/chains";
 
const client = createThirdwebClient({
  secretKey: process.env.THIRDWEB_SECRET_KEY,
});
 
const thirdwebFacilitator = facilitator({
  client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});
 
export async function GET(request: Request) {
  const paymentData = request.headers.get("x-payment");
 
  const result = await settlePayment({
    resourceUrl: "https://api.example.com/premium-content",
    method: "GET",
    paymentData,
    payTo: "0x1234567890123456789012345678901234567890",
    network: arbitrumSepolia,
    price: "$0.10",
    facilitator: thirdwebFacilitator, // Pass the facilitator here
  });
 
  if (result.status === 200) {
    return Response.json({ data: "premium content" });
  } else {
    return Response.json(result.responseBody, {
      status: result.status,
      headers: result.responseHeaders,
    });
  }
}

Usage with other x402 middleware libraries

Use the facilitator with third-party x402 middleware libraries:


import { Hono } from "hono";
import { paymentMiddleware } from "x402-hono";
import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
 
const client = createThirdwebClient({
  secretKey: "your-secret-key",
});
 
const thirdwebFacilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});
 
const app = new Hono();
 
// Add the facilitator to the x402 middleware
app.use(
  paymentMiddleware(
    "0xYourWalletAddress",
    {
      "/api/paywall": {
        price: "$0.01",
        network: "base-sepolia",
        config: {
          description: "Access to paid content",
        },
      },
    },
    thirdwebFacilitator, // Pass the facilitator to the middleware
  ),
);
 
app.get("/api/paywall", (c) => {
  return c.json({ message: "This is premium content!" });
});
 
export default app;

Getting Supported Payment Methods

Query which payment methods are supported by the facilitator:


// Get all supported payment methods
const allSupported = await thirdwebFacilitator.supported();
 
// Filter by chain
const baseSupported = await thirdwebFacilitator.supported({
  chainId: 8453, // Base
});
 
// Filter by chain and token
const usdcOnBase = await thirdwebFacilitator.supported({
  chainId: 8453,
  tokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
});