From ef731a98af1233dfdd924bb03a51607c222cc6d2 Mon Sep 17 00:00:00 2001
From: Joaquim Verges <joaquim.verges@gmail.com>
Date: Wed, 5 Nov 2025 10:53:37 +1300
Subject: [PATCH] [X402] Add support for extra metadata in payment requests

---
 .changeset/four-ghosts-tickle.md          | 5 +++++
 packages/thirdweb/src/x402/common.ts      | 2 ++
 packages/thirdweb/src/x402/facilitator.ts | 1 +
 packages/thirdweb/src/x402/types.ts       | 2 ++
 4 files changed, 10 insertions(+)
 create mode 100644 .changeset/four-ghosts-tickle.md

diff --git a/.changeset/four-ghosts-tickle.md b/.changeset/four-ghosts-tickle.md
new file mode 100644
index 00000000000..3ff6e87b8b2
--- /dev/null
+++ b/.changeset/four-ghosts-tickle.md
@@ -0,0 +1,5 @@
+---
+"thirdweb": patch
+---
+
+Add support for extraMetadata in x402 payment requirements
diff --git a/packages/thirdweb/src/x402/common.ts b/packages/thirdweb/src/x402/common.ts
index 5b6a9a271da..f438409dad1 100644
--- a/packages/thirdweb/src/x402/common.ts
+++ b/packages/thirdweb/src/x402/common.ts
@@ -44,6 +44,7 @@ export async function decodePaymentRequest(
     routeConfig = {},
     method,
     paymentData,
+    extraMetadata,
   } = args;
   const { errorMessages } = routeConfig;
 
@@ -54,6 +55,7 @@ export async function decodePaymentRequest(
     price,
     routeConfig,
     payTo,
+    extraMetadata,
   });
 
   // Check for payment header, if none, return the payment requirements
diff --git a/packages/thirdweb/src/x402/facilitator.ts b/packages/thirdweb/src/x402/facilitator.ts
index 3ad103ea02f..31ad4c27faa 100644
--- a/packages/thirdweb/src/x402/facilitator.ts
+++ b/packages/thirdweb/src/x402/facilitator.ts
@@ -281,6 +281,7 @@ export function facilitator(
           routeConfig: args.routeConfig,
           serverWalletAddress: facilitator.address,
           recipientAddress: args.payTo,
+          extraMetadata: args.extraMetadata,
         }),
       });
       if (res.status !== 402) {
diff --git a/packages/thirdweb/src/x402/types.ts b/packages/thirdweb/src/x402/types.ts
index db235c1c5e4..1b67fdf3a42 100644
--- a/packages/thirdweb/src/x402/types.ts
+++ b/packages/thirdweb/src/x402/types.ts
@@ -35,6 +35,8 @@ export type PaymentArgs = {
   routeConfig?: PaymentMiddlewareConfig;
   /** Optional recipient address to receive the payment if different from your facilitator address */
   payTo?: string;
+  /** Optional extra data to be included in the payment request */
+  extraMetadata?: Record<string, unknown>;
 };
 
 export type SettlePaymentArgs = PaymentArgs & {