x402 support

Joaquim Verges

We're excited to announce the release of x402 payment support in the thirdweb SDK, enabling developers to monetize their backend and agent services with seamless, automatic crypto payments.

The x402 protocol is an emerging standard that extends existing 402 HTTP error with automatic crypto payments. When an API requires payment, it responds with a 402 Payment Required status code along with payment instructions. The client can then automatically fulfill the payment and retry the request—all without user intervention beyond the initial wallet approval.
Think of it as "pay-per-call" for APIs, where each request can be individually priced and paid for using cryptocurrency.

We've added two new functions to make x402 integration effortless:

Automatically handle paid API calls with a simple wrapper around the native fetch API:

import { wrapFetchWithPayment } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
import { createWallet } from "thirdweb/wallets";
 
const client = createThirdwebClient({ clientId: "your-client-id" });
const wallet = createWallet("io.metamask");
await wallet.connect({ client });
 
const fetchWithPay = wrapFetchWithPayment(fetch, client, wallet);
 
// This call will automatically handle payment if required
const response = await fetchWithPay(
  "https://api.example.com/premium-data",
);
const data = await response.json();

How it works:
1. Makes the initial API request
2. If a 402 response is received, parses payment requirements
3. Verifies the payment amount is within your specified limits
4. Signs the payment authorization with your wallet
5. Retries the request with the payment header
6. Returns the successful response

Integrate x402 payments into your middleware stack with minimal configuration. Works with all the existing x402 middleware libraries already out there. Here's an example with x402-next

import { createThirdwebClient } from "thirdweb";
import { facilitator } from "thirdweb/x402";
import { paymentMiddleware } from "x402-next";
 
const client = createThirdwebClient({
  secretKey: process.env.THIRDWEB_SECRET_KEY,
});
 
export const middleware = paymentMiddleware(
  "0xYourRecipientWallet",
  {
    "/api/premium-endpoint": {
      price: "$0.01",
      network: "base-sepolia",
      config: {
        description: "Access to premium AI features",
      },
    },
    "/api/data-analysis": {
      price: "$0.05",
      network: "base-sepolia",
      config: {
        description: "Advanced data processing",
      },
    },
  },
  facilitator({
    client,
    serverWalletAddress: "0xYourServerWallet",
  }),
);
 
export const config = {
  matcher: ["/api/premium-endpoint", "/api/data-analysis"],
};

Try the Live Demo
Experience x402 payments in action at our interactive playground.

Read the Documentation
Get detailed implementation guides in our x402 documentation.

Stay tuned for more x402 utilities and expanded functionality in the next few weeks!

Happy building! 🛠️