Skip to main content

​
Automatic Attribution on Base

Once your app is registered on base.dev, the Base App will auto-append your Builder Code to transactions its users make in your app (e.g. via your mini app, or the Base App’s browser). This powers your onchain analytics in base.dev and qualifies you for potential future rewards.

​
Integrating Outside the Base App

If users also access your app on the web or through other clients, you’ll need to integrate the dataSuffix parameter to capture that activity. When you register on base.dev, you will receive a Builder Code—a random string (e.g., bc_b7k3p9da) that you’ll use to generate your attribution suffix. The recommended approach is to configure dataSuffix at the client level, which appends your Builder Code to all transactions.
You can find your code anytime under Settings → Builder Code.

​
Quick Setup with Wagmi

1

Install Dependencies

Install the required packages. Requires viem version 2.45.0 or higher.
npm i ox wagmi viem
2

Configure Your Wagmi Client

Add the dataSuffix option to your Wagmi config. This automatically appends your Builder Code to all transactions.
config.ts
import { createConfig, http } from "wagmi";
import { base } from "wagmi/chains";
import { Attribution } from "ox/erc8021";

// Get your Builder Code from base.dev > Settings > Builder Codes
const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"],
});

export const config = createConfig({
  chains: [base],
  transports: {
    [base.id]: http(),
  },
  dataSuffix: DATA_SUFFIX,
});
3

Use Wagmi Hooks as Usual

With the config in place, all transactions automatically include your Builder Code—no changes to your hooks or components. This works with both useSendTransaction and useSendCalls.
App.tsx
import { useSendTransaction } from "wagmi";
import { parseEther } from "viem";

function SendButton() {
  const { sendTransaction } = useSendTransaction();

  return (
    <button
      onClick={() =>
        sendTransaction({
          to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
          value: parseEther("0.01"),
        })
      }
    >
      Send ETH
    </button>
  );
}

​
Quick Setup with Viem

1

Install Dependencies

Install the required packages. Requires viem version 2.45.0 or higher.
npm i ox viem
2

Configure Your Wallet Client

Add the dataSuffix option when creating your wallet client. See the viem wallet client docs for more configuration options.
client.ts
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { Attribution } from "ox/erc8021";

// Get your Builder Code from base.dev > Settings > Builder Codes
const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"],
});

export const walletClient = createWalletClient({
  chain: base,
  transport: http(),
  dataSuffix: DATA_SUFFIX,
});
3

Send Transactions as Usual

All transactions sent through this client automatically include your Builder Code.
import { parseEther } from "viem";
import { walletClient } from "./client";

const hash = await walletClient.sendTransaction({
  to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
  value: parseEther("0.01"),
});

​
Using Privy

Privy provides a dataSuffix plugin that automatically appends your Builder Code to all transactions—including both EOA transactions and ERC-4337 smart wallet user operations. See the Privy Builder Codes integration guide for setup instructions.

​
Legacy: Per-Transaction Approach

If you need to append the suffix on a per-transaction basis rather than at the client level, you can pass dataSuffix directly to the transaction.
App.tsx
import { useSendTransaction } from "wagmi";
import { parseEther } from "viem";
import { Attribution } from "ox/erc8021";

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"],
});

function App() {
  const { sendTransaction } = useSendTransaction();

  return (
    <button
      onClick={() =>
        sendTransaction({
          to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
          value: parseEther("0.01"),
          dataSuffix: DATA_SUFFIX,
        })
      }
    >
      Send ETH
    </button>
  );
}

​
Schema 2: CBOR Attribution

​
Encoding a Schema 2 Suffix

Pass appCode, walletCode, or both to Attribution.toDataSuffix. The ox library detects Schema 2 automatically when either field is present.
1

Install Dependencies

Install the required packages. Requires the version of ox that includes ERC-8021 Schema 2 support.
npm i ox wagmi viem
2

Generate Your Attribution Suffix

Call Attribution.toDataSuffix with your app code and add it to your Wagmi config or Viem wallet client.
config.ts
import { createConfig, http } from "wagmi";
import { base } from "wagmi/chains";
import { Attribution } from "ox/erc8021";

// Get your Builder Code from base.dev > Settings > Builder Codes
const DATA_SUFFIX = Attribution.toDataSuffix({
  appCode: "YOUR-APP-CODE",
});

export const config = createConfig({
  chains: [base],
  transports: { [base.id]: http() },
  dataSuffix: DATA_SUFFIX,
});
3

Extend with Wallet Code, Registries, or Metadata (Optional)

If you also need to attribute the wallet provider, point entities to custom registries, or attach campaign metadata, pass the additional fields to Attribution.toDataSuffix.
config.ts
import { Attribution } from "ox/erc8021";

const DATA_SUFFIX = Attribution.toDataSuffix({
 appCode:    "YOUR-APP-CODE",    // optional: use if you're an app
 walletCode: "YOUR-WALLET-CODE", // optional: use if you're a wallet
  registries: {
    app: {
      chainId: 8453,
      address: "0xYourAppRegistryAddress",
    },
    wallet: {
      chainId: 8453,
      address: "0xYourWalletRegistryAddress",
    },
  },
  metadata: {
    utm_campaign: "winter-promo",
    source: "webapp",
  },
});
At least one of appCode or walletCode must be present. chainId in registries is a plain number (e.g., 8453), consistent with Schema 1.

​
Decoding a Schema 2 Suffix

Attribution.fromData handles all three schemas. Check attribution.id === 2 to type-narrow to Schema 2 fields: 
import { Attribution } from "ox/erc8021";

const attribution = Attribution.fromData(hexSuffix);

if (attribution && attribution.id === 2) {
  console.log(attribution.appCode);    // string | undefined
  console.log(attribution.walletCode); // string | undefined
  console.log(attribution.registries); // { app?, wallet? } | undefined
  console.log(attribution.metadata);   // Record<string, unknown> | undefined
}
Use the Builder Code Validation tool to verify that your Schema 2 suffix decodes correctly before shipping.

​
Verify Attribution

To confirm your Builder Code is being appended correctly: 1. Check base.dev
  • Visit base.dev
  • Select Onchain from the transaction type dropdown
  • Under the Total Transactions section, attribution counts increment when transactions with your code are processed
2. Use a Block Explorer (Basescan, Etherscan, etc.)
  • Find your transaction hash
  • View the input data field
  • Verify the last 16 bytes are the 8021 repeating
  • Decode the suffix to confirm your Builder Code is present
3. Open Source Tools
  • Use the Builder Code Validation tool
  • Select transaction type
  • Enter the transaction or UserOperation hash
  • Click the Check Attribution button