/build-on-base

Adding Builder Codes

Integrate Base Builder Codes into an onchain application. Builder Codes append an ERC-8021 attribution suffix to transaction calldata so Base can attribute activity to your app and you can earn referral fees. No smart contract changes required.

When to Use

Use when a developer asks to:

• "Add builder codes to my application"
• "How do I append a builder code to my transactions?"
• "I want to earn referral fees on Base transactions"
• "Integrate builder codes"
• Set up transaction attribution on Base

Prerequisites

• A Builder Code from base.dev > Settings > Builder Codes
• The ox library for generating ERC-8021 suffixes: npm install ox

Integration Workflow

Copy this checklist and track progress:

Builder Codes Integration:
- [ ] Step 1: Detect framework (Required First Step)
- [ ] Step 2: Install dependencies
- [ ] Step 3: Generate the dataSuffix constant
- [ ] Step 4: Apply attribution (framework-specific)
- [ ] Step 5: Verify attribution is working

Framework Detection (Required First Step)

Before implementing, determine the framework in use.

1. Read package.json and scan source files

# Check for framework dependencies
grep -E "wagmi|@privy-io/react-auth|viem|ethers" package.json

# Check for smart wallet / account abstraction usage
grep -rn "useSendCalls\|sendCalls\|ERC-4337\|useSmartWallets" src/

# Check for EOA transaction patterns
grep -rn "useSendTransaction\|sendTransaction\|writeContract\|useWriteContract" src/

# Check Privy version if present
grep "@privy-io/react-auth" package.json

2. Classify into one framework

Priority order if multiple are detected: Privy > Wagmi > Viem > Standard RPC

3. Confirm with user

Before proceeding, confirm the detected framework:

"I detected you are using [Framework]. I'll implement builder codes using the [Framework] approach — does that sound right?"

Wait for user confirmation before implementing.

Implementation Path

• Privy (@privy-io/react-auth v3.13.0+) → See privy.md
• Wagmi (without Privy) → See wagmi.md
• Viem only (no React framework) → See viem.md
• Standard RPC (ethers.js or raw window.ethereum) → See rpc.md

Step 2: Install dependencies

npm install ox

Requires viem >= 2.45.0 for Wagmi/Viem paths. Privy requires @privy-io/react-auth >= 3.13.0.

Step 3: Generate the dataSuffix constant

Create a shared constant (e.g., src/lib/attribution.ts or src/constants/builderCode.ts):

import { Attribution } from "ox/erc8021";

export const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"], // Replace with your code from base.dev
});

Step 4: Apply attribution

Follow the framework-specific guide:

Privy Implementation

See privy.md — plugin-based, one config change required.

Wagmi Implementation

See wagmi.md — add dataSuffix to Wagmi client config.

Viem Implementation

See viem.md — add dataSuffix to wallet client.

Standard RPC Implementation

See rpc.md — append DATA_SUFFIX to transaction data for ethers.js or raw window.ethereum.

Preferred approach: Configure at the client level so all transactions are automatically attributed. Only use the per-transaction approach if you need conditional attribution.

For Smart Wallets (EIP-5792 sendCalls): See smart-wallets.md — pass via capabilities.

Step 5: Verify attribution

1. base.dev: Check Onchain > Total Transactions for attribution counts
2. Block explorer: Find tx hash, view input data, confirm last 16 bytes are 8021 repeating
3. Validation tool: Use builder-code-checker.vercel.app

Key Facts

• Builder Codes are ERC-721 NFTs minted on Base
• The suffix is appended to calldata; smart contracts ignore it (no upgrades needed)
• Gas cost is negligible: 16 gas per non-zero byte
• Analytics on base.dev currently support Smart Account (AA) transactions; EOA support is coming (attribution data is preserved)
• The dataSuffix plugin in Privy appends to all chains, not just Base. If chain-specific behavior is needed, contact Privy
• Privy's dataSuffix plugin is NOT yet supported with @privy-io/wagmi adapter

Finding Transaction Call Sites

When retrofitting an existing project, search for these patterns:

# React hooks (Wagmi)
grep -rn "useSendTransaction\|useSendCalls\|useWriteContract\|useContractWrite" src/

# Viem client calls
grep -rn "sendTransaction\|writeContract\|sendRawTransaction" src/

# Privy embedded wallet calls
grep -rn "sendTransaction\|signTransaction" src/

# ethers.js
grep -rn "signer\.sendTransaction\|contract\.connect" src/

# Raw window.ethereum
grep -rn "window\.ethereum\|eth_sendTransaction" src/

For client-level integration (Wagmi/Viem/Privy), you typically only need to modify the config file — individual transaction call sites remain unchanged.