​

x402 Builder Codes Setup

First, ask the user: Are you a buyer/client (you make payment requests) or a seller (you serve paid endpoints)? Then follow the corresponding path below.

---

​

Path A: Buyer / Client

Integrate a Base Builder Code into your x402 client so every payment you drive on Base is attributed to your app onchain.

​

Steps

1. Check for a Base Builder Code Ask the user if they already have a Base Builder Code. If not, direct them to:

   Go to https://dashboard.base.org and log in. Register your app name, add and verify your domain, then go to Settings → Builder Codes to get your code.

   The code looks like bc_b7k3p9da and must match ^[a-z0-9_]{1,32}$ (lowercase letters, digits, underscores, 1–32 characters).
2. Install dependencies
   npm install @x402/fetch @x402/extensions @x402/evm
   
3. Register the BuilderCodeClientExtension In the file where you create your x402 client, import and register BuilderCodeClientExtension. Replace "your_builder_code" with the user’s actual Base Builder Code.
   import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
   import { ExactEvmScheme } from "@x402/evm/exact/client";
   import { BuilderCodeClientExtension } from "@x402/extensions/builder-code";
   
   const client = new x402Client();
   client.register("eip155:*", new ExactEvmScheme(signer));
   client.registerExtension(
     new BuilderCodeClientExtension("your_builder_code"),
   );
   
   const fetchWithPayment = wrapFetchWithPayment(fetch, client);
   
   // All x402 payments made through fetchWithPayment will carry the Builder Code
   const response = await fetchWithPayment("https://example.com/paid-endpoint");
   
4. Verify attribution After an x402 payment settles on Base, confirm your Builder Code was recorded. Get the settlement transaction hash and run:
   import { createPublicClient, http } from "viem";
   import { base } from "viem/chains";
   import { parseBuilderCodeSuffixFromCalldata } from "@x402/extensions/builder-code";
   
   const publicClient = createPublicClient({ chain: base, transport: http() });
   const tx = await publicClient.getTransaction({ hash: "0xYourTxHash" });
   
   const attribution = parseBuilderCodeSuffixFromCalldata(tx.input);
   console.log(attribution);
   // { a: "seller_app_code_if_integrated", w: "cdp_facil", s: "your_builder_code" }
   // `s` appears if you completed setup above; `w` appears if using CDP Facilitator;
   // `a` is only present if the seller also integrated Builder Codes.
   
   Assert: attribution?.s === "your_builder_code". Alternatively, paste the transaction hash into https://buildercode-checker.vercel.app/ to inspect attribution without writing any code.

---

​

Path B: Seller / Resource Server

Declare a Base Builder Code on your x402 resource server so every payment your endpoint receives on Base is attributed to your app onchain.

​

Steps

1. Check for a Base Builder Code Ask the user if they already have a Base Builder Code. If not, direct them to:

   Go to https://dashboard.base.org and log in. Register your app name, add and verify your domain, then go to Settings → Builder Codes to get your code.

   The code looks like bc_b7k3p9da and must match ^[a-z0-9_]{1,32}$ (lowercase letters, digits, underscores, 1–32 characters).
2. Install dependencies
   npm install @x402/extensions
   
3. Declare the BuilderCodeExtension on your routes Add declareBuilderCodeExtension to the extensions field of each route you want attributed. Replace "your_builder_code" with the user’s actual Base Builder Code.
   import { paymentMiddleware, x402ResourceServer } from "@x402/express";
   import { ExactEvmScheme } from "@x402/evm/exact/server";
   import {
     BUILDER_CODE,
     declareBuilderCodeExtension,
   } from "@x402/extensions/builder-code";
   
   app.use(
     paymentMiddleware(
       {
         "GET /weather": {
           accepts: [
             {
               scheme: "exact",
               price: "$0.001",
               network: "eip155:8453",
               payTo: "0xYourAddress",
             },
           ],
           description: "Weather data",
           mimeType: "application/json",
           extensions: {
             [BUILDER_CODE]: declareBuilderCodeExtension("your_builder_code"),
           },
         },
       },
       new x402ResourceServer(facilitatorClient).register(
         "eip155:8453",
         new ExactEvmScheme(),
       ),
     ),
   );
   
   For Go, import github.com/x402-foundation/x402/go/v2/extensions/buildercode and call buildercode.DeclareBuilderCodeExtension("your_builder_code") in the route’s Extensions map.
4. Verify attribution After a payment settles, paste the transaction hash into https://buildercode-checker.vercel.app/ or parse the calldata programmatically. Assert: the a field in the parsed attribution matches your declared builder code.

---

​

Notes

• Dashboard: Attribution data and app metrics are visible at https://dashboard.base.org.
• Docs: Full details at https://docs.cdp.coinbase.com/x402/core-concepts/builder-codes.