[SDK] Add x402 payment protocol utilities

.changeset/sad-hairs-smash.md

@@ -0,0 +1,5 @@
+---
+"thirdweb": minor
+---
+
+x402 utilities

apps/playground-web/package.json

@@ -48,6 +48,7 @@
     "thirdweb": "workspace:*",
     "use-debounce": "^10.0.5",
     "use-stick-to-bottom": "^1.1.1",
+    "x402-next": "^0.6.1",
     "zod": "3.25.75"
   },
   "devDependencies": {

apps/playground-web/src/app/api/paywall/route.ts

@@ -0,0 +1,10 @@
+import { NextResponse } from "next/server";
+// Allow streaming responses up to 5 minutes
+export const maxDuration = 300;
+
+export async function GET(_req: Request) {
+  return NextResponse.json({
+    success: true,
+    message: "Congratulations! You have accessed the protected route.",
+  });
+}

apps/playground-web/src/app/navLinks.ts

@@ -206,6 +206,10 @@ const payments: ShadcnSidebarLink = {
       href: "/payments/transactions",
       label: "Onchain Transaction",
     },
+    {
+      href: "/payments/x402",
+      label: "x402",
+    },
   ],
 };
 

apps/playground-web/src/app/payments/x402/components/x402-client-preview.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import { CodeClient } from "@workspace/ui/components/code/code.client";
+import { CodeIcon, LockIcon } from "lucide-react";
+import { baseSepolia } from "thirdweb/chains";
+import {
+  ConnectButton,
+  getDefaultToken,
+  useActiveAccount,
+  useActiveWallet,
+} from "thirdweb/react";
+import { wrapFetchWithPayment } from "thirdweb/x402";
+import { Button } from "@/components/ui/button";
+import { Card } from "@/components/ui/card";
+import { THIRDWEB_CLIENT } from "../../../../lib/client";
+
+const chain = baseSepolia;
+const token = getDefaultToken(chain, "USDC");
+
+export function X402ClientPreview() {
+  const activeWallet = useActiveWallet();
+  const activeAccount = useActiveAccount();
+  const paidApiCall = useMutation({
+    mutationFn: async () => {
+      if (!activeWallet) {
+        throw new Error("No active wallet");
+      }
+      const fetchWithPay = wrapFetchWithPayment(
+        fetch,
+        THIRDWEB_CLIENT,
+        activeWallet,
+      );
+      const response = await fetchWithPay("/api/paywall");
+      return response.json();
+    },
+  });
+
+  const handlePayClick = async () => {
+    paidApiCall.mutate();
+  };
+
+  return (
+    <div className="flex flex-col gap-4 w-full p-4 md:p-12 max-w-lg mx-auto">
+      <ConnectButton
+        client={THIRDWEB_CLIENT}
+        chain={chain}
+        detailsButton={{
+          displayBalanceToken: {
+            [chain.id]: token!.address,
+          },
+        }}
+        supportedTokens={{
+          [chain.id]: [token!],
+        }}
+      />
+      <Card className="p-6">
+        <div className="flex items-center gap-3 mb-4">
+          <LockIcon className="w-5 h-5 text-muted-foreground" />
+          <span className="text-lg font-medium">Paid API Call</span>
+          <span className="text-xl font-bold text-red-600">$0.01</span>
+        </div>
+
+        <Button
+          onClick={handlePayClick}
+          className="w-full mb-4"
+          size="lg"
+          disabled={paidApiCall.isPending || !activeAccount}
+        >
+          Pay Now
+        </Button>
+        <p className="text-sm text-muted-foreground">
+          {" "}
+          <a
+            className="underline"
+            href={"https://faucet.circle.com/"}
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Click here to get USDC on {chain.name}
+          </a>
+        </p>
+      </Card>
+      <Card className="p-6">
+        <div className="flex items-center gap-3 mb-2">
+          <CodeIcon className="w-5 h-5 text-muted-foreground" />
+          <span className="text-lg font-medium">API Call Response</span>
+        </div>
+        {paidApiCall.isPending && <div className="text-center">Loading...</div>}
+        {paidApiCall.isError && (
+          <div className="text-center">Error: {paidApiCall.error.message}</div>
+        )}
+        {paidApiCall.data && (
+          <CodeClient
+            code={JSON.stringify(paidApiCall.data, null, 2)}
+            lang="json"
+          />
+        )}
+      </Card>
+    </div>
+  );
+}

apps/playground-web/src/app/payments/x402/page.tsx

@@ -0,0 +1,127 @@
+import { CodeServer } from "@workspace/ui/components/code/code.server";
+import { CircleDollarSignIcon, Code2Icon } from "lucide-react";
+import { CodeExample, TabName } from "@/components/code/code-example";
+import ThirdwebProvider from "@/components/thirdweb-provider";
+import { PageLayout } from "../../../components/blocks/APIHeader";
+import { createMetadata } from "../../../lib/metadata";
+import { X402ClientPreview } from "./components/x402-client-preview";
+
+const title = "x402 Payments";
+const description =
+  "Use the x402 payment protocol to pay for API calls using any web3 wallet.";
+const ogDescription =
+  "Use the x402 payment protocol to pay for API calls using any web3 wallet.";
+
+export const metadata = createMetadata({
+  title,
+  description: ogDescription,
+  image: {
+    icon: "payments",
+    title,
+  },
+});
+
+export default function Page() {
+  return (
+    <ThirdwebProvider>
+      <PageLayout
+        icon={CircleDollarSignIcon}
+        title={title}
+        description={description}
+        docsLink="https://portal.thirdweb.com/payments/x402?utm_source=playground"
+      >
+        <X402Example />
+        <div className="h-8" />
+        <ServerCodeExample />
+      </PageLayout>
+    </ThirdwebProvider>
+  );
+}
+
+function ServerCodeExample() {
+  return (
+    <>
+      <div className="mb-4">
+        <h2 className="font-semibold text-xl tracking-tight">
+          Next.js Server Code Example
+        </h2>
+        <p className="max-w-4xl text-muted-foreground text-balance text-sm md:text-base">
+          Use any x402 middleware + the thirdweb facilitator to settle
+          transactions with our server wallet.
+        </p>
+      </div>
+      <div className="overflow-hidden rounded-lg border bg-card">
+        <div className="flex grow flex-col border-b md:border-r md:border-b-0">
+          <TabName icon={Code2Icon} name="Server Code" />
+          <CodeServer
+            className="h-full rounded-none border-none"
+            code={`// src/middleware.ts
+
+import { facilitator } from "thirdweb/x402";
+import { createThirdwebClient } from "thirdweb";
+import { paymentMiddleware } from "x402-next";
+
+const client = createThirdwebClient({ secretKey: "your-secret-key" });
+
+export const middleware = paymentMiddleware(
+  "0xYourWalletAddress",
+  {
+    "/api/paid-endpoint": {
+      price: "$0.01",
+      network: "base-sepolia",
+      config: {
+        description: "Access to paid content",
+      },
+    },
+  },
+  facilitator({
+    client,
+    serverWalletAddress: "0xYourServerWalletAddress",
+  }),
+);
+
+// Configure which paths the middleware should run on
+export const config = {
+  matcher: ["/api/paid-endpoint"],
+};
+
+      `}
+            lang="tsx"
+          />
+        </div>
+      </div>
+    </>
+  );
+}
+
+function X402Example() {
+  return (
+    <CodeExample
+      header={{
+        title: "Client Code Example",
+        description:
+          "Wrap your fetch requests with the `wrapFetchWithPayment` function to enable x402 payments.",
+      }}
+      code={`import { createThirdwebClient } from "thirdweb";
+import { wrapFetchWithPayment } from "thirdweb/x402";
+import { useActiveWallet } from "thirdweb/react";
+
+const client = createThirdwebClient({ clientId: "your-client-id" });
+
+export default function Page() {
+  const wallet = useActiveWallet();
+
+  const onClick = async () => {
+    const fetchWithPay = wrapFetchWithPayment(fetch, client, wallet);
+    const response = await fetchWithPay('/api/paid-endpoint');
+  }
+
+  return (
+        <Button onClick={onClick}>Pay Now</Button>
+  );
+}`}
+      lang="tsx"
+      preview={<X402ClientPreview />}
+    />
+  );
+}

apps/playground-web/src/middleware.ts

@@ -0,0 +1,36 @@
+import { createThirdwebClient } from "thirdweb";
+import { facilitator } from "thirdweb/x402";
+import { paymentMiddleware } from "x402-next";
+
+const client = createThirdwebClient({
+  secretKey: process.env.THIRDWEB_SECRET_KEY as string,
+});
+
+const BACKEND_WALLET_ADDRESS = process.env.ENGINE_BACKEND_WALLET as string;
+const ENGINE_VAULT_ACCESS_TOKEN = process.env
+  .ENGINE_VAULT_ACCESS_TOKEN as string;
+const API_URL = `https://${process.env.NEXT_PUBLIC_API_URL || "api.thirdweb.com"}`;
+
+export const middleware = paymentMiddleware(
+  "0xdd99b75f095d0c4d5112aCe938e4e6ed962fb024",
+  {
+    "/api/paywall": {
+      price: "$0.01",
+      network: "base-sepolia",
+      config: {
+        description: "Access to paid content",
+      },
+    },
+  },
+  facilitator({
+    baseUrl: `${API_URL}/v1/payments/x402`,
+    client,
+    serverWalletAddress: BACKEND_WALLET_ADDRESS,
+    vaultAccessToken: ENGINE_VAULT_ACCESS_TOKEN,
+  }),
+);
+
+// Configure which paths the middleware should run on
+export const config = {
+  matcher: ["/api/paywall"],
+};

apps/portal/src/app/payments/sidebar.tsx

@@ -61,6 +61,10 @@ export const sidebar: SideBar = {
           href: `${paymentsSlug}/custom-data`,
           name: "Custom Data",
         },
+        {
+          href: `${paymentsSlug}/x402`,
+          name: "x402",
+        },
       ],
       name: "Guides",
     },