Skip to main content

​
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://base.dev 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://base.dev 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