From 77fd0311636f80f4b6ba9b2c7aacb18c9726e205 Mon Sep 17 00:00:00 2001 From: Akhil Date: Tue, 6 Oct 2026 15:23:27 +0530 Subject: [PATCH 1/7] docs(builder-codes): add user analytics guide for app developers Adds a Track User Analytics section to the Builder Codes for App Developers page with a copy-paste prompt builders can give their coding agent to set up product analytics. --- .../builder-codes/for-app-developers.mdx | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/specifications/builder-codes/for-app-developers.mdx b/docs/specifications/builder-codes/for-app-developers.mdx index 3ac3cabe8..3f25e7d0d 100644 --- a/docs/specifications/builder-codes/for-app-developers.mdx +++ b/docs/specifications/builder-codes/for-app-developers.mdx @@ -239,3 +239,60 @@ To confirm your Builder Code is being appended correctly: - Select transaction type - Enter the transaction or UserOperation hash - Click the **Check Attribution** button + +## Track User Analytics + +To understand who your users are and how they behave, such as active users, retention and conversion funnels, add product analytics to your app. Because your app is a standard web app with a wallet, any analytics tool works. + +The fastest way is to give your coding agent (Cursor, Claude Code, Codex, or similar) the prompt below. + +| Metric | Source | +|---|---| +| Daily, weekly and monthly active users | Page views and wallet connects | +| D1, D7 and D30 retention | Returning wallets | +| Funnels (open, connect, first action) | Custom events | +| Onchain transactions attributed to your app | Your Builder Code | + + + + Run the prompt from the root of your app's repository. It uses PostHog's free tier, but you can swap in Plausible, Mixpanel or Amplitude and the prompt works the same way. + + ```text Analytics prompt for your coding agent wrap + Add product analytics to this web app using PostHog (free tier). + + 1. Install posthog-js and initialize it once, client-side only, at app startup. + Read the project key and host from public env vars using this framework's + convention (e.g. NEXT_PUBLIC_POSTHOG_KEY in Next.js, VITE_POSTHOG_KEY in Vite). + Add them to .env.example and never commit real values. Skip init if the key + is missing. + 2. Turn on autocapture and set capture_pageview: "history_change" so client-side + route changes count as page views. + 3. When a wallet connects (wagmi useAccount), call + posthog.identify(address.toLowerCase()). When it disconnects, call + posthog.reset(). + 4. Capture these events: + - app_opened { referrer, utm_source, utm_medium, utm_campaign } + - wallet_connected { connector, chain_id } + - tx_submitted { action, tx_hash } + - tx_confirmed { action, tx_hash } after the receipt confirms with status success + - tx_failed { action, error_message } when rejected, errored or reverted + Name "action" after what this app does (e.g. mint, swap, deposit). + 5. Wallet address is the only user identifier. Never capture emails, names, + government IDs or payment details. + 6. Summarize every file you changed and how to verify events in PostHog's live + events view. + ``` + + + The prompt assumes your app uses Wagmi to connect wallets. If you use a different library, tell your agent which hook or event fires when a wallet connects. + + + + + In your analytics tool, set up: + + 1. **Growth:** daily, weekly and monthly active users, plus new vs. returning wallets. + 2. **Retention:** D1, D7 and D30 cohorts by the week a wallet was first seen. + 3. **Funnel:** `app_opened` → `wallet_connected` → `tx_confirmed`, split by `utm_source`. + + From a473be79b4d550358182246a7dc693527c6465d0 Mon Sep 17 00:00:00 2001 From: Akhil Date: Tue, 6 Oct 2026 21:02:45 +0530 Subject: [PATCH 2/7] docs(builder-codes): make user analytics section tool-agnostic Addresses review feedback: removes the agent prompt, analytics tool names and Wagmi references; replaces them with steps describing what to measure and which onchain signals to use. --- .../builder-codes/for-app-developers.mdx | 68 ++++++++----------- 1 file changed, 27 insertions(+), 41 deletions(-) diff --git a/docs/specifications/builder-codes/for-app-developers.mdx b/docs/specifications/builder-codes/for-app-developers.mdx index 3f25e7d0d..ebe8c6194 100644 --- a/docs/specifications/builder-codes/for-app-developers.mdx +++ b/docs/specifications/builder-codes/for-app-developers.mdx @@ -242,57 +242,43 @@ To confirm your Builder Code is being appended correctly: ## Track User Analytics -To understand who your users are and how they behave, such as active users, retention and conversion funnels, add product analytics to your app. Because your app is a standard web app with a wallet, any analytics tool works. +To understand how people use your app, such as active users, retention and conversion, track user activity in your app alongside your onchain data. This section covers what to measure and where each signal comes from. Which analytics stack you use and how you set it up is up to you. -The fastest way is to give your coding agent (Cursor, Claude Code, Codex, or similar) the prompt below. - -| Metric | Source | +| Metric | Data source | |---|---| -| Daily, weekly and monthly active users | Page views and wallet connects | -| D1, D7 and D30 retention | Returning wallets | -| Funnels (open, connect, first action) | Custom events | -| Onchain transactions attributed to your app | Your Builder Code | +| Daily, weekly and monthly active users | Wallet connections and app sessions | +| D1, D7 and D30 retention | Returning wallet addresses | +| Conversion funnel (open, connect, first successful transaction) | App sessions, wallet connections and onchain transactions | +| Onchain activity attributed to your app | Transactions that carry your Builder Code | - - Run the prompt from the root of your app's repository. It uses PostHog's free tier, but you can swap in Plausible, Mixpanel or Amplitude and the prompt works the same way. - - ```text Analytics prompt for your coding agent wrap - Add product analytics to this web app using PostHog (free tier). - - 1. Install posthog-js and initialize it once, client-side only, at app startup. - Read the project key and host from public env vars using this framework's - convention (e.g. NEXT_PUBLIC_POSTHOG_KEY in Next.js, VITE_POSTHOG_KEY in Vite). - Add them to .env.example and never commit real values. Skip init if the key - is missing. - 2. Turn on autocapture and set capture_pageview: "history_change" so client-side - route changes count as page views. - 3. When a wallet connects (wagmi useAccount), call - posthog.identify(address.toLowerCase()). When it disconnects, call - posthog.reset(). - 4. Capture these events: - - app_opened { referrer, utm_source, utm_medium, utm_campaign } - - wallet_connected { connector, chain_id } - - tx_submitted { action, tx_hash } - - tx_confirmed { action, tx_hash } after the receipt confirms with status success - - tx_failed { action, error_message } when rejected, errored or reverted - Name "action" after what this app does (e.g. mint, swap, deposit). - 5. Wallet address is the only user identifier. Never capture emails, names, - government IDs or payment details. - 6. Summarize every file you changed and how to verify events in PostHog's live - events view. - ``` + + Use the connected wallet address, lowercased, as the user identifier, and clear it when the wallet disconnects. This lets you join in-app activity with onchain activity for the same user. + + Wallet address should be the only identifier you collect. Do not record emails, names, government IDs or payment details. + + + + Record when a user: + + 1. Opens the app, along with the referrer or campaign source + 2. Connects a wallet + 3. Submits a transaction, along with what the transaction does in your app (for example, mint, swap or deposit) + + + + Onchain data is the source of truth for transaction outcomes. For each transaction, look at: - - The prompt assumes your app uses Wagmi to connect wallets. If you use a different library, tell your agent which hook or event fires when a wallet connects. - + - **Builder Code:** whether the calldata carries your Builder Code suffix (see [Verify Attribution](#verify-attribution)) + - **Sender:** the wallet address that sent it, which matches the user identifier from step 1 + - **Status:** whether the transaction receipt shows success or a revert - In your analytics tool, set up: + With these signals in place, set up: 1. **Growth:** daily, weekly and monthly active users, plus new vs. returning wallets. 2. **Retention:** D1, D7 and D30 cohorts by the week a wallet was first seen. - 3. **Funnel:** `app_opened` → `wallet_connected` → `tx_confirmed`, split by `utm_source`. + 3. **Funnel:** open → connect → first successful transaction, split by referrer or campaign source. From acfcbbd35cd6a92ebce0569c106336e1aee6a763 Mon Sep 17 00:00:00 2001 From: Youssef El Allali Date: Tue, 6 Oct 2026 18:35:13 +0100 Subject: [PATCH 3/7] docs(builder-codes): drop deprecated base.dev attribution check Base Dashboard 2.0 no longer has the Onchain transaction-type view, so the Check base.dev step sent developers to a screen that no longer exists. Matches the overview page (#2024) and supersedes #2066. Co-authored-by: Toshi --- .../builder-codes/for-agent-developers.mdx | 10 ++-------- .../builder-codes/for-app-developers.mdx | 10 ++-------- 2 files changed, 4 insertions(+), 16 deletions(-) diff --git a/docs/specifications/builder-codes/for-agent-developers.mdx b/docs/specifications/builder-codes/for-agent-developers.mdx index 44feec93b..64d000b08 100644 --- a/docs/specifications/builder-codes/for-agent-developers.mdx +++ b/docs/specifications/builder-codes/for-agent-developers.mdx @@ -67,20 +67,14 @@ The skill handles wallet validation, calls the registration API, writes the retu To confirm your Builder Code is being appended correctly: -**1. Check base.dev** - -- Visit [base.dev](https://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.)** +**1. 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** +**2. Open source tools** - Use the [Builder Code Validation](https://builder-code-checker.vercel.app/) tool - Select transaction type diff --git a/docs/specifications/builder-codes/for-app-developers.mdx b/docs/specifications/builder-codes/for-app-developers.mdx index ebe8c6194..eb10fb1dc 100644 --- a/docs/specifications/builder-codes/for-app-developers.mdx +++ b/docs/specifications/builder-codes/for-app-developers.mdx @@ -220,20 +220,14 @@ See the [Privy Builder Codes integration guide](https://docs.privy.io/recipes/ev To confirm your Builder Code is being appended correctly: -**1. Check base.dev** - -- Visit [base.dev](https://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.)** +**1. 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** +**2. Open Source Tools** - Use the [Builder Code Validation](https://builder-code-checker.vercel.app/) tool - Select transaction type From cd4c48705abcca96537ecbf91ae7ee81aa25fcbf Mon Sep 17 00:00:00 2001 From: Youssef El Allali Date: Tue, 6 Oct 2026 18:40:55 +0100 Subject: [PATCH 4/7] docs(builder-codes): show where each analytics signal comes from Replaces the generic Track User Analytics steps with the concrete data sources behind each journey stage: - read the user identifier from the EIP-1193 provider (eth_requestAccounts, accountsChanged, chainChanged) and explain smart account addresses - list the in-app signal for open, connect, submit and success, including the wallet_sendCalls bundle ID and wallet_getCallsStatus resolution and EIP-1193 error code 4001 - explain where the user, Builder Code and success live for EOA transactions vs ERC-4337 UserOperations, the ERC-8021 suffix byte layout, and a Viem + ox function that returns one row per user action - define the active user, retention and funnel calculations Drops the guidance on which identifiers to collect; the section is about finding the right data, not prescribing a data policy. Co-authored-by: Toshi --- .../builder-codes/for-app-developers.mdx | 146 +++++++++++++++--- 1 file changed, 122 insertions(+), 24 deletions(-) diff --git a/docs/specifications/builder-codes/for-app-developers.mdx b/docs/specifications/builder-codes/for-app-developers.mdx index eb10fb1dc..17b9fd2d0 100644 --- a/docs/specifications/builder-codes/for-app-developers.mdx +++ b/docs/specifications/builder-codes/for-app-developers.mdx @@ -236,43 +236,141 @@ To confirm your Builder Code is being appended correctly: ## Track User Analytics -To understand how people use your app, such as active users, retention and conversion, track user activity in your app alongside your onchain data. This section covers what to measure and where each signal comes from. Which analytics stack you use and how you set it up is up to you. +Builder Codes tell you which onchain transactions came from your app. To measure active users, retention and conversion, join that onchain data with the signals your app already sees when someone opens it, connects a wallet and sends a transaction. This section shows where each signal comes from and how to read it. Where you store the data and which analytics stack you use is up to you. -| Metric | Data source | -|---|---| -| Daily, weekly and monthly active users | Wallet connections and app sessions | -| D1, D7 and D30 retention | Returning wallet addresses | -| Conversion funnel (open, connect, first successful transaction) | App sessions, wallet connections and onchain transactions | -| Onchain activity attributed to your app | Transactions that carry your Builder Code | +| Metric | Signal | Where to read it | +|---|---|---| +| Daily, weekly and monthly active users | Distinct wallet addresses that connected, or that sent a successful attributed transaction, in the period | `eth_requestAccounts` result; transaction sender and status | +| D1, D7 and D30 retention | The date each address was first seen, and whether it came back in a later period | Block timestamp of the address's first successful attributed transaction | +| Conversion funnel | Open, connect, submit, success, joined on wallet address and transaction hash | Page load, `eth_requestAccounts`, the hash or call bundle ID returned on submit, and the receipt | +| Onchain activity attributed to your app | Transactions whose ERC-8021 suffix contains your Builder Code | `input` of the transaction, or `callData` of each UserOperation | - Use the connected wallet address, lowercased, as the user identifier, and clear it when the wallet disconnects. This lets you join in-app activity with onchain activity for the same user. + The connected wallet address is the key that joins in-app activity to onchain activity. Read it from the wallet's [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) provider, which every wallet library exposes, and normalize it to lowercase so the same address always matches. - Wallet address should be the only identifier you collect. Do not record emails, names, government IDs or payment details. + ```typescript identify-wallet.ts lines wrap + // `provider` is the connected wallet's EIP-1193 provider + const [address] = await provider.request({ method: "eth_requestAccounts" }); + const chainId = await provider.request({ method: "eth_chainId" }); // "0x2105" on Base, "0x14a34" on Base Sepolia + + const userId = address.toLowerCase(); + + // The user switched accounts (new identity) or disconnected (empty array) + provider.on("accountsChanged", (accounts: string[]) => {}); + // The user switched networks; activity on other chains will not carry your Base attribution + provider.on("chainChanged", (chainId: string) => {}); + ``` + + For smart accounts (such as Base Account), this is the smart contract account address. Onchain, it appears as the `sender` of each UserOperation, not as the `from` of the outer transaction (see step 3). - - Record when a user: + + Each stage of the funnel has a signal your app can read directly. Store each one with the wallet address and a timestamp. + + | Stage | Where the data comes from | + |---|---| + | Open | The page load. Acquisition source comes from URL query parameters (for example, `utm_source` or `ref`) and `document.referrer`. Read them on the first load, before client-side navigation drops them. | + | Connect | A resolved `eth_requestAccounts` call. A rejected request returns EIP-1193 error code `4001` (user rejected). | + | Submit | The value returned when the user signs. `eth_sendTransaction` returns the transaction hash. `wallet_sendCalls` ([EIP-5792](https://eips.ethereum.org/EIPS/eip-5792)) returns a call bundle ID that you resolve to transaction hashes with `wallet_getCallsStatus`. Error code `4001` means the user rejected the signature. | + | Success | The transaction receipt onchain (step 3). | + + Record the transaction hash and the action it performs in your app (for example, mint, swap or deposit) at submit time. The hash is what links an in-app action to its onchain outcome. - 1. Opens the app, along with the referrer or campaign source - 2. Connects a wallet - 3. Submits a transaction, along with what the transaction does in your app (for example, mint, swap or deposit) + ```typescript resolve-call-bundle.ts lines wrap + const { id } = await provider.request({ + method: "wallet_sendCalls", + params: [{ version: "2.0.0", chainId: "0x2105", from: address, atomicRequired: true, calls, capabilities }], + }); + + // Poll until the bundle settles. 100 = pending, 200 = confirmed, 4xx/5xx/600 = failed or partial + const { status, receipts } = await provider.request({ + method: "wallet_getCallsStatus", + params: [id], + }); + + const transactionHashes = receipts?.map((receipt) => receipt.transactionHash) ?? []; + ``` - - Onchain data is the source of truth for transaction outcomes. For each transaction, look at: + + Onchain data is the source of truth for whether a transaction happened, who sent it and whether it carried your Builder Code. Where each field lives depends on the account type: + + | Field | EOA transaction | ERC-4337 UserOperation (smart account) | + |---|---|---| + | User | `from` of the transaction | `sender` of the UserOperation. The transaction `from` is the bundler. | + | Builder Code | Suffix at the end of the transaction `input` | Suffix at the end of the UserOperation `callData`, inside the EntryPoint `handleOps` call | + | Success | Receipt `status` | `success` field of the EntryPoint's `UserOperationEvent` log. The outer receipt can succeed while an individual UserOperation reverts. | + | Time | Block timestamp | Block timestamp | + + The ERC-8021 suffix sits at the end of the calldata and reads backwards: the 16-byte marker `0x80218021802180218021802180218021`, then a 1-byte schema ID, then a 1-byte length, then the comma-separated codes as ASCII. For example, `bc_b7k3p9da` produces the suffix `0x62635f62376b33703964610b0080218021802180218021802180218021`. Match on the decoded codes rather than the raw bytes, because a wallet can add its own code next to yours. + + The function below takes a transaction hash recorded in step 2 and returns one row per user action, for both account types. It uses Viem and `ox`, which are already used on this page; any RPC client works the same way. + + ```typescript get-attributed-activity.ts lines expandable wrap + import { createPublicClient, decodeFunctionData, http, isAddressEqual, parseEventLogs, type Hash } from "viem"; + import { base } from "viem/chains"; + import { entryPoint06Abi, entryPoint06Address, entryPoint07Abi, entryPoint07Address } from "viem/account-abstraction"; + import { Attribution } from "ox/erc8021"; + + const client = createPublicClient({ chain: base, transport: http() }); + + const BUILDER_CODE = "YOUR-BUILDER-CODE"; + + export async function getAttributedActivity(hash: Hash) { + const [tx, receipt] = await Promise.all([ + client.getTransaction({ hash }), + client.getTransactionReceipt({ hash }), + ]); + + const block = await client.getBlock({ blockNumber: receipt.blockNumber }); + const common = { + transactionHash: hash, + blockNumber: receipt.blockNumber, + timestamp: Number(block.timestamp), + }; + + // ERC-4337: the outer transaction is sent by a bundler to the EntryPoint. + // The user is each UserOperation's sender, and the suffix sits in its callData. + const entryPoint = + tx.to && isAddressEqual(tx.to, entryPoint07Address) ? { abi: entryPoint07Abi } : + tx.to && isAddressEqual(tx.to, entryPoint06Address) ? { abi: entryPoint06Abi } : + undefined; + + if (entryPoint) { + const { args } = decodeFunctionData({ abi: entryPoint.abi, data: tx.input }); + const ops = (args?.[0] ?? []) as readonly { sender: `0x${string}`; callData: `0x${string}` }[]; + const events = parseEventLogs({ abi: entryPoint.abi, eventName: "UserOperationEvent", logs: receipt.logs }); + + return ops.map((op) => { + const event = events.find((e) => isAddressEqual(e.args.sender, op.sender)); + return { + ...common, + sender: op.sender.toLowerCase(), + success: event?.args.success ?? false, + attributed: Attribution.fromData(op.callData)?.codes?.includes(BUILDER_CODE) ?? false, + }; + }); + } + + // EOA transaction: the user is tx.from and the suffix is at the end of tx.input. + return [{ + ...common, + sender: tx.from.toLowerCase(), + success: receipt.status === "success", + attributed: Attribution.fromData(tx.input)?.codes?.includes(BUILDER_CODE) ?? false, + }]; + } + ``` - - **Builder Code:** whether the calldata carries your Builder Code suffix (see [Verify Attribution](#verify-attribution)) - - **Sender:** the wallet address that sent it, which matches the user identifier from step 1 - - **Status:** whether the transaction receipt shows success or a revert + To backfill history, or to catch transactions sent outside your app's UI, scan Base blocks (or your contracts' logs with `eth_getLogs`) for calldata that ends with the ERC-8021 marker, and decode each match the same way. - - With these signals in place, set up: + + Join the in-app signals from step 2 with the onchain rows from step 3 on the lowercased wallet address, and on the transaction hash for the submit and success stages. Then: - 1. **Growth:** daily, weekly and monthly active users, plus new vs. returning wallets. - 2. **Retention:** D1, D7 and D30 cohorts by the week a wallet was first seen. - 3. **Funnel:** open → connect → first successful transaction, split by referrer or campaign source. + 1. **Active users:** count distinct addresses per UTC day, week or month. Report connected users and transacting users (at least one row with `success` and `attributed` both true) separately, since the gap between them is your activation rate. + 2. **Retention:** assign each address to a cohort by the week of its first successful attributed transaction, then measure the share of each cohort that transacts again 1, 7 and 30 days later. + 3. **Funnel:** count addresses that reach each stage (open → connect → submit → success), split by acquisition source. Drop-offs between submit and success split into rejected signatures (error code `4001`), reverted transactions (`success` is false) and transactions without your Builder Code (`attributed` is false), which usually means a client is not configured with `dataSuffix`. From 025534b059fb3b430f7bd18b2ee211589dd3ccd8 Mon Sep 17 00:00:00 2001 From: Youssef El Allali Date: Tue, 6 Oct 2026 18:42:19 +0100 Subject: [PATCH 5/7] docs(builder-codes): update Dashboard references for Dashboard 2.0 Base Dashboard 2.0 replaced the transaction and user counts with spot trading volume, borrow TVL and lending TVL derived from Builder Code activity, renamed apps to projects, and moved the code to Settings > Project Settings > Builder Code. - point the Builder Code location and code comments to the new path - document the Encoded String format (the ready-made dataSuffix) - replace the analytics benefit claims on the overview, app and agent pages with what the Dashboard shows today, linking to Track User Analytics for users, retention and conversion Co-authored-by: Toshi --- .../builder-codes/for-agent-developers.mdx | 4 ++-- .../builder-codes/for-app-developers.mdx | 10 +++++----- docs/specifications/builder-codes/overview.mdx | 4 ++-- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/specifications/builder-codes/for-agent-developers.mdx b/docs/specifications/builder-codes/for-agent-developers.mdx index 64d000b08..eb33cd203 100644 --- a/docs/specifications/builder-codes/for-agent-developers.mdx +++ b/docs/specifications/builder-codes/for-agent-developers.mdx @@ -1,7 +1,7 @@ --- title: "Builder Codes for Agent Developers" sidebarTitle: "For Agent Developers" -description: "Attribute your AI agent's onchain transactions to your identity on Base and unlock analytics and leaderboard features." +description: "Attribute your AI agent's onchain transactions to your identity on Base and make them measurable onchain." --- AI agents operate autonomously and send transactions without a user manually triggering each one. Builder Codes give you a way to attribute all of that activity back to your agent's identity on Base. @@ -9,7 +9,7 @@ AI agents operate autonomously and send transactions without a user manually tri ## Why agents need Builder Codes - **Attribution** — Every transaction your agent sends is tied to your identity in the Base registry. Without it, your agent's onchain activity is anonymous. -- **Analytics** — Track your agent's transaction volume, user reach, and onchain conversion in [base.dev](https://base.dev). +- **Analytics** — Every attributed transaction carries your code onchain, so you can measure your agent's transaction volume and reach from chain data. See [Track User Analytics](/specifications/builder-codes/for-app-developers#track-user-analytics) for where each signal lives. - **Visibility** — Agents with Builder Codes can appear in discovery surfaces like Base's App Leaderboard and ecosystem spotlights. ## How it works diff --git a/docs/specifications/builder-codes/for-app-developers.mdx b/docs/specifications/builder-codes/for-app-developers.mdx index 17b9fd2d0..a80d4df58 100644 --- a/docs/specifications/builder-codes/for-app-developers.mdx +++ b/docs/specifications/builder-codes/for-app-developers.mdx @@ -6,16 +6,16 @@ description: "Integrate Builder Codes into your app using Wagmi or Viem to attri ## Automatic Attribution on Base -Once your app is registered on [base.dev](http://base.dev/), the Base App will auto-append your Builder Code to transactions its users make in your app (e.g. via your app, or the Base App's browser). This powers your onchain analytics in [base.dev](http://base.dev/) and qualifies you for potential future rewards. +Once your project is registered on [Base Dashboard](https://base.dev/), the Base App will auto-append your Builder Code to transactions its users make in your app (e.g. via your app, or the Base App's browser). This attributes that activity to your project 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](https://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. +When you register a project on [Base Dashboard](https://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**. + You can find your code anytime under **Settings** → **Project Settings** → **Builder Code**. Switch the format to **Encoded String** to copy the full ERC-8021 suffix, the same hex value `Attribution.toDataSuffix` returns. ## Quick Setup with Wagmi @@ -37,7 +37,7 @@ When you register on [base.dev](https://base.dev/), you will receive a **Builder import { base } from "wagmi/chains"; import { Attribution } from "ox/erc8021"; - // Get your Builder Code from base.dev > Settings > Builder Codes + // Get your Builder Code from Base Dashboard > Settings > Project Settings > Builder Code const DATA_SUFFIX = Attribution.toDataSuffix({ codes: ["YOUR-BUILDER-CODE"], }); @@ -98,7 +98,7 @@ When you register on [base.dev](https://base.dev/), you will receive a **Builder import { base } from "viem/chains"; import { Attribution } from "ox/erc8021"; - // Get your Builder Code from base.dev > Settings > Builder Codes + // Get your Builder Code from Base Dashboard > Settings > Project Settings > Builder Code const DATA_SUFFIX = Attribution.toDataSuffix({ codes: ["YOUR-BUILDER-CODE"], }); diff --git a/docs/specifications/builder-codes/overview.mdx b/docs/specifications/builder-codes/overview.mdx index 95ac1de6f..e4cfe60d5 100644 --- a/docs/specifications/builder-codes/overview.mdx +++ b/docs/specifications/builder-codes/overview.mdx @@ -9,7 +9,7 @@ Base Builder Codes are an ERC-721 NFT collection where unique codes (e.g. "abc12 Each code has associated metadata. Onchain metadata primarily includes a "payout address" where each code declares where potential rewards should be sent to. Offchain metadata includes more details about the app including its name and site. - Get your Builder Code by registering on [base.dev](https://base.dev/). You can find your code under **Settings** → **Builder Code**. + Get your Builder Code by registering a project on [Base Dashboard](https://base.dev/). You can find your code under **Settings** → **Project Settings** → **Builder Code**. ## Integration Guides @@ -29,7 +29,7 @@ Each code has associated metadata. Onchain metadata primarily includes a "payout ## Benefits - **Rewards:** If your app drives transactions, Builder Codes let Base automatically attribute that usage back to you, unlocking rewards as the program expands. -- **Analytics:** Reliably track onchain usage, user acquisition, and conversion metrics in Base.dev. +- **Analytics:** Base Dashboard shows spot trading volume, borrow TVL and lending TVL derived from your Builder Code activity. To measure users, retention and conversion yourself, see [Track User Analytics](/specifications/builder-codes/for-app-developers#track-user-analytics). - **Visibility:** Apps with Builder Codes can show up in discovery surfaces like App Leaderboards, Base App store, and ecosystem spotlights. ## FAQ From b83fb74e8f82b5653fd794bdf0de75fe9743af74 Mon Sep 17 00:00:00 2001 From: Youssef El Allali Date: Tue, 6 Oct 2026 18:47:39 +0100 Subject: [PATCH 6/7] docs: link to dashboard.base.org instead of base.dev base.dev now 302-redirects to dashboard.base.org. Points the Builder Codes links and the two data-driven-growth redirects straight at the canonical host. blog.base.dev, verify.base.dev and api.base.dev are separate services and are unchanged. Co-authored-by: Toshi --- docs/docs.json | 4 ++-- docs/specifications/builder-codes/for-app-developers.mdx | 4 ++-- docs/specifications/builder-codes/overview.mdx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 069f3a33b..dd6535b25 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1762,11 +1762,11 @@ }, { "source": "/mini-apps/growth/data-driven-growth", - "destination": "https://base.dev" + "destination": "https://dashboard.base.org" }, { "source": "/mini-apps/technical-guides/data-driven-growth", - "destination": "https://base.dev" + "destination": "https://dashboard.base.org" }, { "source": "/mini-apps/features/links", diff --git a/docs/specifications/builder-codes/for-app-developers.mdx b/docs/specifications/builder-codes/for-app-developers.mdx index a80d4df58..69dfe0aab 100644 --- a/docs/specifications/builder-codes/for-app-developers.mdx +++ b/docs/specifications/builder-codes/for-app-developers.mdx @@ -6,13 +6,13 @@ description: "Integrate Builder Codes into your app using Wagmi or Viem to attri ## Automatic Attribution on Base -Once your project is registered on [Base Dashboard](https://base.dev/), the Base App will auto-append your Builder Code to transactions its users make in your app (e.g. via your app, or the Base App's browser). This attributes that activity to your project and qualifies you for potential future rewards. +Once your project is registered on [Base Dashboard](https://dashboard.base.org/), the Base App will auto-append your Builder Code to transactions its users make in your app (e.g. via your app, or the Base App's browser). This attributes that activity to your project 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 a project on [Base Dashboard](https://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. +When you register a project on [Base Dashboard](https://dashboard.base.org/), 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** → **Project Settings** → **Builder Code**. Switch the format to **Encoded String** to copy the full ERC-8021 suffix, the same hex value `Attribution.toDataSuffix` returns. diff --git a/docs/specifications/builder-codes/overview.mdx b/docs/specifications/builder-codes/overview.mdx index e4cfe60d5..52df5de40 100644 --- a/docs/specifications/builder-codes/overview.mdx +++ b/docs/specifications/builder-codes/overview.mdx @@ -9,7 +9,7 @@ Base Builder Codes are an ERC-721 NFT collection where unique codes (e.g. "abc12 Each code has associated metadata. Onchain metadata primarily includes a "payout address" where each code declares where potential rewards should be sent to. Offchain metadata includes more details about the app including its name and site. - Get your Builder Code by registering a project on [Base Dashboard](https://base.dev/). You can find your code under **Settings** → **Project Settings** → **Builder Code**. + Get your Builder Code by registering a project on [Base Dashboard](https://dashboard.base.org/). You can find your code under **Settings** → **Project Settings** → **Builder Code**. ## Integration Guides From 9e70cc503c34ab93f7395dd2ca70fc94c62474b7 Mon Sep 17 00:00:00 2001 From: Youssef El Allali Date: Tue, 6 Oct 2026 18:48:55 +0100 Subject: [PATCH 7/7] docs(builder-codes): drop Base Account example from smart account note Co-authored-by: Toshi --- docs/specifications/builder-codes/for-app-developers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specifications/builder-codes/for-app-developers.mdx b/docs/specifications/builder-codes/for-app-developers.mdx index 69dfe0aab..42f6ec3db 100644 --- a/docs/specifications/builder-codes/for-app-developers.mdx +++ b/docs/specifications/builder-codes/for-app-developers.mdx @@ -262,7 +262,7 @@ Builder Codes tell you which onchain transactions came from your app. To measure provider.on("chainChanged", (chainId: string) => {}); ``` - For smart accounts (such as Base Account), this is the smart contract account address. Onchain, it appears as the `sender` of each UserOperation, not as the `from` of the outer transaction (see step 3). + For smart accounts, this is the smart contract account address. Onchain, it appears as the `sender` of each UserOperation, not as the `from` of the outer transaction (see step 3).