From d4b646969718c694a6ae1b146d7ea590ad8c7de4 Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 15:19:27 +0100 Subject: [PATCH 01/11] added keywords to metadata --- docs/ai-agents/guides/builder-codes.mdx | 178 ++++++++++++++++++++++++ docs/docs.json | 1 + 2 files changed, 179 insertions(+) create mode 100644 docs/ai-agents/guides/builder-codes.mdx diff --git a/docs/ai-agents/guides/builder-codes.mdx b/docs/ai-agents/guides/builder-codes.mdx new file mode 100644 index 000000000..4fc37a7ca --- /dev/null +++ b/docs/ai-agents/guides/builder-codes.mdx @@ -0,0 +1,178 @@ +--- +title: "Get a Builder Code for Your Agent" +description: "Register your agent on Base.dev and append a Builder Code to every transaction to measure onchain activity." +keywords: ["builder code", "Base.dev", "ERC-8021", "attribution", "onchain activity", "agent attribution", "dataSuffix", "builder codes", "Base builder codes", "agent onchain"] +--- + +Base.dev is the canonical registry for agents on Base. A Builder Code ties every transaction your agent sends to your identity in that registry, giving you verifiable onchain attribution and access to analytics and leaderboard features. + +## What you get + +- **Builder Code** — a unique identifier (e.g. `bc_a1b2c3d4`) that you append to your onchain transactions. Base uses this to measure your agent's activity on Base Chain. + +## Prerequisites + +- An EVM wallet address that your agent operates from + +That's it. No authentication, no wallet signing, no account creation. + +--- + +## Get your Builder Code + +One call. No auth. + +```bash Terminal +curl -X POST https://api.base.dev/v1/agents/builder-codes \ + -H "Content-Type: application/json" \ + -d '{ + "wallet_address": "0x" + }' +``` + +Response: + +```json Title Response +{ + "builder_code": "bc_a1b2c3d4", + "wallet_address": "0x...", + "usage_instructions": "Append this builder code to your onchain transactions using the ERC-8021 standard. See: https://docs.base.org/base-chain/quickstart/builder-codes" +} +``` + +**Idempotent** — calling it again with the same wallet address returns the same builder code. + +--- + +## Get a Builder Code with a prompt + +If you're using an AI agent, point it to this page: + +```text Title Prompt +Get a Builder Code for my agent on Base.dev using the documentation at [URL of this page]. + +My agent's wallet address: [0x...] + +Follow the instructions to: +1. Call POST /v1/agents/builder-codes with my wallet address +2. Return the builder code +3. Show me how to append the builder code to my transactions using ERC-8021 +``` + +--- + +## Append your Builder Code to transactions + +Once you have a Builder Code, append it to every onchain transaction so Base can measure your agent's activity. This uses the [ERC-8021 standard](/base-chain/quickstart/builder-codes). + + + +```typescript viem lines expandable +import { createWalletClient, http } from "viem"; +import { base } from "viem/chains"; +import { privateKeyToAccount } from "viem/accounts"; +import { Attribution } from "ox/erc8021"; + +const DATA_SUFFIX = Attribution.toDataSuffix({ + codes: ["bc_a1b2c3d4"], +}); + +const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); + +export const walletClient = createWalletClient({ + account, + chain: base, + transport: http(), + dataSuffix: DATA_SUFFIX, +}); + +// All transactions sent through this client automatically include your Builder Code +const hash = await walletClient.sendTransaction({ + to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", + value: parseEther("0.1"), +}); +``` + +```javascript ethers.js lines expandable +import { Attribution } from 'ox/erc8021'; +import { ethers } from 'ethers'; + +const builderCode = 'bc_a1b2c3d4'; +const suffix = Attribution.toDataSuffix({ codes: [builderCode] }); + +const provider = new ethers.JsonRpcProvider('https://mainnet.base.org'); +const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider); + +const tx = { + to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', + value: ethers.parseEther('0.1'), + data: suffix, // or append to existing calldata +}; + +const txResponse = await wallet.sendTransaction(tx); +``` + +```python web3.py lines expandable +from web3 import Web3 +from eth_account import Account +from ox.erc8021 import Attribution + +builder_code = 'bc_a1b2c3d4' +suffix = Attribution.to_data_suffix(codes=[builder_code]) + +w3 = Web3(Web3.HTTPProvider('https://mainnet.base.org')) +account = Account.from_key(os.environ['PRIVATE_KEY']) + +tx = { + 'from': account.address, + 'to': '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', + 'value': Web3.to_wei(0.1, 'ether'), + 'data': suffix, # or append to existing calldata + 'nonce': w3.eth.get_transaction_count(account.address), + 'gas': 21000, + 'gasPrice': w3.eth.gas_price, + 'chainId': 8453, +} + +signed = account.sign_transaction(tx) +tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction) +``` + + + +--- + +## What happens next + +Your Builder Code starts working immediately — Base will measure any transaction that includes it. + +To unlock additional features, you can optionally register your agent later: + +| Feature | Requires registration? | +|---|---| +| Onchain activity measurement | No — works as soon as you append the builder code | +| Public leaderboard | Yes — requires wallet verification via registration | +| Verified coin badge | Yes — requires registration + coin verification | +| Dashboard analytics | Yes — requires registration + claiming | + +**Register later:** When you're ready, authenticate via SIWE and call `POST /v1/agents/register` to verify your wallet, add metadata, and become leaderboard-eligible. See [full registration docs](./register-and-sign-in-your-agent). + +--- + +## API reference + +### Get builder code + +``` +POST /v1/agents/builder-codes +``` + +No authentication required. + +| Field | Type | Required | Description | +|---|---|---|---| +| `wallet_address` | string | Yes | Your agent's EVM wallet address (`0x...`) | + +Returns the builder code for the given wallet. Idempotent — the same wallet always returns the same code. + + diff --git a/docs/docs.json b/docs/docs.json index 73cedf9ad..15ec50eb3 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -534,6 +534,7 @@ { "group": "Guides", "pages": [ + "ai-agents/guides/builder-codes", "ai-agents/guides/wallet-setup", "ai-agents/guides/x402-payments", "ai-agents/guides/register-and-sign-in-your-agent", From e358c01e6e9062fdf1597b62979dbb8fa775c794 Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 17:30:02 +0100 Subject: [PATCH 02/11] changed side bar added tag --- docs/ai-agents/guides/builder-codes.mdx | 83 +------------------------ docs/docs.json | 2 +- 2 files changed, 2 insertions(+), 83 deletions(-) diff --git a/docs/ai-agents/guides/builder-codes.mdx b/docs/ai-agents/guides/builder-codes.mdx index 4fc37a7ca..ba1a97894 100644 --- a/docs/ai-agents/guides/builder-codes.mdx +++ b/docs/ai-agents/guides/builder-codes.mdx @@ -2,6 +2,7 @@ title: "Get a Builder Code for Your Agent" description: "Register your agent on Base.dev and append a Builder Code to every transaction to measure onchain activity." keywords: ["builder code", "Base.dev", "ERC-8021", "attribution", "onchain activity", "agent attribution", "dataSuffix", "builder codes", "Base builder codes", "agent onchain"] +tag: "NEW" --- Base.dev is the canonical registry for agents on Base. A Builder Code ties every transaction your agent sends to your identity in that registry, giving you verifiable onchain attribution and access to analytics and leaderboard features. @@ -58,88 +59,6 @@ Follow the instructions to: 2. Return the builder code 3. Show me how to append the builder code to my transactions using ERC-8021 ``` - ---- - -## Append your Builder Code to transactions - -Once you have a Builder Code, append it to every onchain transaction so Base can measure your agent's activity. This uses the [ERC-8021 standard](/base-chain/quickstart/builder-codes). - - - -```typescript viem lines expandable -import { createWalletClient, http } from "viem"; -import { base } from "viem/chains"; -import { privateKeyToAccount } from "viem/accounts"; -import { Attribution } from "ox/erc8021"; - -const DATA_SUFFIX = Attribution.toDataSuffix({ - codes: ["bc_a1b2c3d4"], -}); - -const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); - -export const walletClient = createWalletClient({ - account, - chain: base, - transport: http(), - dataSuffix: DATA_SUFFIX, -}); - -// All transactions sent through this client automatically include your Builder Code -const hash = await walletClient.sendTransaction({ - to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", - value: parseEther("0.1"), -}); -``` - -```javascript ethers.js lines expandable -import { Attribution } from 'ox/erc8021'; -import { ethers } from 'ethers'; - -const builderCode = 'bc_a1b2c3d4'; -const suffix = Attribution.toDataSuffix({ codes: [builderCode] }); - -const provider = new ethers.JsonRpcProvider('https://mainnet.base.org'); -const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider); - -const tx = { - to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', - value: ethers.parseEther('0.1'), - data: suffix, // or append to existing calldata -}; - -const txResponse = await wallet.sendTransaction(tx); -``` - -```python web3.py lines expandable -from web3 import Web3 -from eth_account import Account -from ox.erc8021 import Attribution - -builder_code = 'bc_a1b2c3d4' -suffix = Attribution.to_data_suffix(codes=[builder_code]) - -w3 = Web3(Web3.HTTPProvider('https://mainnet.base.org')) -account = Account.from_key(os.environ['PRIVATE_KEY']) - -tx = { - 'from': account.address, - 'to': '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', - 'value': Web3.to_wei(0.1, 'ether'), - 'data': suffix, # or append to existing calldata - 'nonce': w3.eth.get_transaction_count(account.address), - 'gas': 21000, - 'gasPrice': w3.eth.gas_price, - 'chainId': 8453, -} - -signed = account.sign_transaction(tx) -tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction) -``` - - - --- ## What happens next diff --git a/docs/docs.json b/docs/docs.json index 15ec50eb3..d2c1064f8 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -534,8 +534,8 @@ { "group": "Guides", "pages": [ - "ai-agents/guides/builder-codes", "ai-agents/guides/wallet-setup", + "ai-agents/guides/builder-codes", "ai-agents/guides/x402-payments", "ai-agents/guides/register-and-sign-in-your-agent", "ai-agents/guides/agent-app", From 73ce367f3b896c9b5261a84dc100f90a657f2672 Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 21:42:05 +0100 Subject: [PATCH 03/11] updated skill to write builder code in readme --- docs/ai-agents/guides/builder-codes.mdx | 31 +++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/ai-agents/guides/builder-codes.mdx b/docs/ai-agents/guides/builder-codes.mdx index ba1a97894..039401add 100644 --- a/docs/ai-agents/guides/builder-codes.mdx +++ b/docs/ai-agents/guides/builder-codes.mdx @@ -61,6 +61,35 @@ Follow the instructions to: ``` --- +## Get a Builder Code using the Base skill + +If you're using an AI coding tool (Claude Code, Cursor, Codex), install the Base skills package and let the skill handle registration end-to-end: + +```bash Terminal +npx skills add base/skills +``` + +Then ask your agent: **"Register my agent for a builder code on Base.dev."** + +The skill runs four phases: + + + + Looks for an existing `builderCode.ts` in your project. If found, registration is already done and the skill exits early. + + + Asks for your agent's wallet address. If you don't have one, it sends you to the [wallet setup guide](/ai-agents/guides/wallet-setup) before continuing. + + + Calls `POST /v1/agents/builder-codes` with your wallet address, writes the returned code to `src/constants/builderCode.ts`, installs `ox`, and wires the ERC-8021 `dataSuffix` into your transaction client (viem, ethers.js, or managed service). It also writes an `AGENT_README.md` documenting the setup. + + + Confirms the setup and instructs you that every future transaction must include the ERC-8021 suffix. Missing it causes silent, permanent attribution loss — no error, no warning. + + + +--- + ## What happens next Your Builder Code starts working immediately — Base will measure any transaction that includes it. @@ -74,8 +103,6 @@ To unlock additional features, you can optionally register your agent later: | Verified coin badge | Yes — requires registration + coin verification | | Dashboard analytics | Yes — requires registration + claiming | -**Register later:** When you're ready, authenticate via SIWE and call `POST /v1/agents/register` to verify your wallet, add metadata, and become leaderboard-eligible. See [full registration docs](./register-and-sign-in-your-agent). - --- ## API reference From 89c8e032164f4eba8981db1dab5e4dea0cddbe6c Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 21:45:17 +0100 Subject: [PATCH 04/11] updated skill to write builder code in readme --- docs/ai-agents/guides/builder-codes.mdx | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/ai-agents/guides/builder-codes.mdx b/docs/ai-agents/guides/builder-codes.mdx index 039401add..8b5d497e8 100644 --- a/docs/ai-agents/guides/builder-codes.mdx +++ b/docs/ai-agents/guides/builder-codes.mdx @@ -41,7 +41,7 @@ Response: } ``` -**Idempotent** — calling it again with the same wallet address returns the same builder code. +**Already registered?** Calling this endpoint again with the same wallet address returns your existing builder code — safe to call multiple times. --- @@ -74,9 +74,6 @@ Then ask your agent: **"Register my agent for a builder code on Base.dev."** The skill runs four phases: - - Looks for an existing `builderCode.ts` in your project. If found, registration is already done and the skill exits early. - Asks for your agent's wallet address. If you don't have one, it sends you to the [wallet setup guide](/ai-agents/guides/wallet-setup) before continuing. @@ -119,6 +116,6 @@ No authentication required. |---|---|---|---| | `wallet_address` | string | Yes | Your agent's EVM wallet address (`0x...`) | -Returns the builder code for the given wallet. Idempotent — the same wallet always returns the same code. +Returns the builder code for the given wallet. The same wallet address always returns the same code — safe to call multiple times. From ccf997970af0df6243cea543997caaa12de123d7 Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 21:53:26 +0100 Subject: [PATCH 05/11] removed --- docs/ai-agents/guides/builder-codes.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/ai-agents/guides/builder-codes.mdx b/docs/ai-agents/guides/builder-codes.mdx index 8b5d497e8..1f1963869 100644 --- a/docs/ai-agents/guides/builder-codes.mdx +++ b/docs/ai-agents/guides/builder-codes.mdx @@ -15,8 +15,6 @@ Base.dev is the canonical registry for agents on Base. A Builder Code ties every - An EVM wallet address that your agent operates from -That's it. No authentication, no wallet signing, no account creation. - --- ## Get your Builder Code From cdfca983c926e891eaed263602eeb61ff39a299e Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 21:54:55 +0100 Subject: [PATCH 06/11] removed --- docs/ai-agents/guides/builder-codes.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/ai-agents/guides/builder-codes.mdx b/docs/ai-agents/guides/builder-codes.mdx index 1f1963869..e70f640e4 100644 --- a/docs/ai-agents/guides/builder-codes.mdx +++ b/docs/ai-agents/guides/builder-codes.mdx @@ -39,8 +39,9 @@ Response: } ``` -**Already registered?** Calling this endpoint again with the same wallet address returns your existing builder code — safe to call multiple times. - + +Already registered? Calling this endpoint again with the same wallet address returns your existing builder code. + --- ## Get a Builder Code with a prompt From 2f89e7f49a246c4c13bab56226f7a069f212dc09 Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 22:02:14 +0100 Subject: [PATCH 07/11] changed name --- .../{builder-codes.mdx => agent-builder-codes.mdx} | 10 ++++++---- docs/docs.json | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) rename docs/ai-agents/guides/{builder-codes.mdx => agent-builder-codes.mdx} (92%) diff --git a/docs/ai-agents/guides/builder-codes.mdx b/docs/ai-agents/guides/agent-builder-codes.mdx similarity index 92% rename from docs/ai-agents/guides/builder-codes.mdx rename to docs/ai-agents/guides/agent-builder-codes.mdx index e70f640e4..4b178c433 100644 --- a/docs/ai-agents/guides/builder-codes.mdx +++ b/docs/ai-agents/guides/agent-builder-codes.mdx @@ -53,10 +53,12 @@ Get a Builder Code for my agent on Base.dev using the documentation at [URL of t My agent's wallet address: [0x...] -Follow the instructions to: -1. Call POST /v1/agents/builder-codes with my wallet address -2. Return the builder code -3. Show me how to append the builder code to my transactions using ERC-8021 +Run this curl command, replacing the wallet address with mine: +curl -X POST https://api.base.dev/v1/agents/builder-codes \ + -H "Content-Type: application/json" \ + -d '{"wallet_address": "[0x...]"}' + +Return the builder_code from the response, then show me how to append it to my transactions using ERC-8021. ``` --- diff --git a/docs/docs.json b/docs/docs.json index d2c1064f8..5c72e77c6 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -535,7 +535,7 @@ "group": "Guides", "pages": [ "ai-agents/guides/wallet-setup", - "ai-agents/guides/builder-codes", + "ai-agents/guides/agent-builder-codes", "ai-agents/guides/x402-payments", "ai-agents/guides/register-and-sign-in-your-agent", "ai-agents/guides/agent-app", From 934fa5a2be606958f8adb9d987e94ff36c73eaab Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 22:04:35 +0100 Subject: [PATCH 08/11] removed next --- docs/ai-agents/guides/agent-builder-codes.mdx | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/ai-agents/guides/agent-builder-codes.mdx b/docs/ai-agents/guides/agent-builder-codes.mdx index 4b178c433..a3846441d 100644 --- a/docs/ai-agents/guides/agent-builder-codes.mdx +++ b/docs/ai-agents/guides/agent-builder-codes.mdx @@ -92,16 +92,6 @@ The skill runs four phases: Your Builder Code starts working immediately — Base will measure any transaction that includes it. -To unlock additional features, you can optionally register your agent later: - -| Feature | Requires registration? | -|---|---| -| Onchain activity measurement | No — works as soon as you append the builder code | -| Public leaderboard | Yes — requires wallet verification via registration | -| Verified coin badge | Yes — requires registration + coin verification | -| Dashboard analytics | Yes — requires registration + claiming | - ---- ## API reference From 96b31a5dc4f3b06352d98741340060a3f5e3d05b Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 22:05:41 +0100 Subject: [PATCH 09/11] removed next --- docs/ai-agents/guides/agent-builder-codes.mdx | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/ai-agents/guides/agent-builder-codes.mdx b/docs/ai-agents/guides/agent-builder-codes.mdx index a3846441d..a48ac4392 100644 --- a/docs/ai-agents/guides/agent-builder-codes.mdx +++ b/docs/ai-agents/guides/agent-builder-codes.mdx @@ -44,24 +44,6 @@ Already registered? Calling this endpoint again with the same wallet address ret --- -## Get a Builder Code with a prompt - -If you're using an AI agent, point it to this page: - -```text Title Prompt -Get a Builder Code for my agent on Base.dev using the documentation at [URL of this page]. - -My agent's wallet address: [0x...] - -Run this curl command, replacing the wallet address with mine: -curl -X POST https://api.base.dev/v1/agents/builder-codes \ - -H "Content-Type: application/json" \ - -d '{"wallet_address": "[0x...]"}' - -Return the builder_code from the response, then show me how to append it to my transactions using ERC-8021. -``` ---- - ## Get a Builder Code using the Base skill If you're using an AI coding tool (Claude Code, Cursor, Codex), install the Base skills package and let the skill handle registration end-to-end: @@ -88,11 +70,29 @@ The skill runs four phases: --- +## Get a Builder Code with a prompt + +If you're using an AI agent, point it to this page: + +```text Title Prompt +Get a Builder Code for my agent on Base.dev using the documentation at [URL of this page]. + +My agent's wallet address: [0x...] + +Run this curl command, replacing the wallet address with mine: +curl -X POST https://api.base.dev/v1/agents/builder-codes \ + -H "Content-Type: application/json" \ + -d '{"wallet_address": "[0x...]"}' + +Return the builder_code from the response, then show me how to append it to my transactions using ERC-8021. +``` +--- + + ## What happens next Your Builder Code starts working immediately — Base will measure any transaction that includes it. - ## API reference ### Get builder code From b92a94f690e7853d557bc5c7dfc102b5115589c9 Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 25 Mar 2026 22:25:46 +0100 Subject: [PATCH 10/11] removed response --- docs/ai-agents/guides/agent-builder-codes.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/ai-agents/guides/agent-builder-codes.mdx b/docs/ai-agents/guides/agent-builder-codes.mdx index a48ac4392..3e5d72970 100644 --- a/docs/ai-agents/guides/agent-builder-codes.mdx +++ b/docs/ai-agents/guides/agent-builder-codes.mdx @@ -35,7 +35,6 @@ Response: { "builder_code": "bc_a1b2c3d4", "wallet_address": "0x...", - "usage_instructions": "Append this builder code to your onchain transactions using the ERC-8021 standard. See: https://docs.base.org/base-chain/quickstart/builder-codes" } ``` From 882181dec3b8d3ee901b23e9fc98d684378bb44e Mon Sep 17 00:00:00 2001 From: sohey Date: Thu, 26 Mar 2026 12:17:59 +0100 Subject: [PATCH 11/11] removed response --- docs/ai-agents/guides/agent-builder-codes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ai-agents/guides/agent-builder-codes.mdx b/docs/ai-agents/guides/agent-builder-codes.mdx index 3e5d72970..9c7b7bcce 100644 --- a/docs/ai-agents/guides/agent-builder-codes.mdx +++ b/docs/ai-agents/guides/agent-builder-codes.mdx @@ -90,7 +90,7 @@ Return the builder_code from the response, then show me how to append it to my t ## What happens next -Your Builder Code starts working immediately — Base will measure any transaction that includes it. +Once you receive your Builder Code, it becomes active right away—Base will begin tracking any transactions that include it. To view your analytics, prompt your agent to perform a transaction (like a token swap), and then visit [Base.dev](https://base.dev) to see your updated transaction count. ## API reference