Payments

Facilitator API

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.

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",
});