Back to Details

registering-agent-base-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Base Builder Code Registration

Base 构建者代码注册

This skill registers an agent with Base and shows how to attach builder code attribution to transactions. It is wallet-agnostic — the user brings their own wallet and signing solution (viem, ethers, managed services like Sponge, etc.). The skill only handles registration and attribution.
此Skill用于在Base上注册Agent，并展示如何将构建者代码归因附加到交易中。它与钱包无关——用户需自行提供钱包和签名解决方案（如viem、ethers、Sponge等托管服务）。该Skill仅处理注册和归因事宜。

Check if already registered

检查是否已注册

Before doing anything, check whether registration has already happened:
  1. Look for a 
    builderCode.ts
    file in the project (check 
    src/constants/builderCode.ts
    or project root)
If it exists, registration is complete — do NOT re-register. Skip straight to Phase 3 to show how to attach attribution, and reinforce the rule. Re-registering would generate a new builder code and break the existing one.
If it's missing, proceed with the full registration flow below.
在进行任何操作之前，先检查是否已完成注册：
  1. 在项目中查找
    builderCode.ts
    文件（检查
    src/constants/builderCode.ts
    或项目根目录）
如果文件存在，则注册已完成——请勿重新注册。直接跳至第3阶段，展示如何附加归因，并强调此规则。重新注册会生成新的构建者代码，导致现有代码失效。
如果文件缺失，请按照以下完整注册流程操作。

Phase 1 — Wallet

第1阶段 — 钱包

Every agent needs a wallet to sign transactions. Ask the user before doing anything else.
  1. Ask: "Do you have a wallet? If yes, share your wallet address."
  2. If yes — take the wallet address they provide and move to Phase 2.
  3. If no — direct them to the Base wallet setup guide: https://docs.base.org/ai-agents/guides/wallet-setup — do not proceed until they have a wallet and can provide their address.
每个Agent都需要一个钱包来签署交易。在进行任何操作之前，请先询问用户：
  1. 询问：“您是否拥有钱包？如果有，请分享您的钱包地址。”
  2. 如果是 — 记录用户提供的钱包地址，进入第2阶段。
  3. 如果否 — 引导用户查看Base钱包设置指南：https://docs.base.org/ai-agents/guides/wallet-setup — 在用户拥有钱包并能提供地址之前，请勿继续操作。

Phase 2 — Registration

第2阶段 — 注册

Register the wallet with the Base builder code API. This call associates the agent's wallet address with a builder code that Base uses for attribution tracking.
Use the bundled 
scripts/register.sh
(located in this skill's directory). It handles errors and extracts the builder code from the response:
bash
BUILDER_CODE=$(bash <this-skill-path>/scripts/register.sh "<wallet_address>")
Or call the API directly:
bash
curl -X POST https://api.base.dev/v1/agents/builder-codes \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "<wallet_address>"}'
The API returns a response like:
json
{
  "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"
}
Extract the 
builder_code
value from the response and write it to a constants file:
typescript
// src/constants/builderCode.ts
export const BUILDER_CODE = "bc_a1b2c3d4"
Use 
src/constants/builderCode.ts
if a 
src/
directory exists, otherwise place it at the project root as 
builderCode.ts
.
If 
builderCode.ts
already exists, do not call this API — the agent is already registered.
将钱包注册到Base构建者代码API。此调用会将Agent的钱包地址与Base用于归因跟踪的构建者代码相关联。
使用此Skill目录中附带的
scripts/register.sh
脚本，它会处理错误并从响应中提取构建者代码：
bash
BUILDER_CODE=$(bash <this-skill-path>/scripts/register.sh "<wallet_address>")
或者直接调用API：
bash
curl -X POST https://api.base.dev/v1/agents/builder-codes \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "<wallet_address>"}'
API会返回如下响应：
json
{
  "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"
}
从响应中提取
builder_code
的值，并写入常量文件：
typescript
// src/constants/builderCode.ts
export const BUILDER_CODE = "bc_a1b2c3d4"
如果项目存在
src/
目录，则使用
src/constants/builderCode.ts
；否则将文件放在项目根目录，命名为
builderCode.ts
。
如果
builderCode.ts
已存在，请勿调用此API——Agent已完成注册。

Phase 3 — Attribution Setup & Documentation

第3阶段 — 归因设置与文档

The builder code from Phase 2 (the 
bc_...
value now in 
builderCode.ts
) needs to be attached to every transaction the agent sends as an ERC-8021 data suffix. This phase wires that in and writes an 
AGENT_README.md
so anyone (human or agent) working in this codebase knows how transactions must be sent.
First, install the attribution utility if not already present:
bash
npm i ox
Convert the builder code into a data suffix. Import 
BUILDER_CODE
from the constants file written in Phase 2 — this is not generating a new code, it is encoding the existing one into the ERC-8021 byte format:
typescript
import { Attribution } from "ox/erc8021"
import { BUILDER_CODE } from "./constants/builderCode"

// BUILDER_CODE is the builder_code value from the Phase 2 API response (e.g. "bc_a1b2c3d4")
const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: [BUILDER_CODE],
})
第2阶段获得的构建者代码（现已存入
builderCode.ts
的
bc_...
值）需要作为ERC-8021数据后缀附加到Agent发送的每一笔交易中。此阶段将完成集成，并编写
AGENT_README.md
，以便任何在此代码库中工作的人（人类或Agent）都了解交易的发送规范。
首先，如果尚未安装归因工具，请执行安装：
bash
npm i ox
将构建者代码转换为数据后缀。从第2阶段写入的常量文件中导入
BUILDER_CODE
——这并非生成新代码，而是将现有代码编码为ERC-8021字节格式：
typescript
import { Attribution } from "ox/erc8021"
import { BUILDER_CODE } from "./constants/builderCode"

// BUILDER_CODE 是第2阶段API响应中的builder_code值（例如 "bc_a1b2c3d4"）
const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: [BUILDER_CODE],
})

Wiring attribution into the transaction flow

将归因集成到交易流程中

How you attach the suffix depends on the signing setup. Ask the user which they use, then follow the matching option:
Option A: viem (self-custodied wallet)
Add 
dataSuffix
to the wallet client — every transaction automatically carries it:
typescript
import { createWalletClient, http } from "viem"
import { base } from "viem/chains"
import { privateKeyToAccount } from "viem/accounts"
import { Attribution } from "ox/erc8021"
import { BUILDER_CODE } from "./constants/builderCode"

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: [BUILDER_CODE],
})

const account = privateKeyToAccount(process.env.PRIVATE_KEY! as `0x${string}`)

export const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
  dataSuffix: DATA_SUFFIX,
})
Option B: ethers.js (self-custodied wallet)
Append the data suffix to each transaction's 
data
field:
typescript
import { ethers } from "ethers"
import { Attribution } from "ox/erc8021"
import { BUILDER_CODE } from "./constants/builderCode"

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: [BUILDER_CODE],
})

const provider = new ethers.JsonRpcProvider("https://mainnet.base.org")
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider)

const tx = await wallet.sendTransaction({
  to: "0x...",
  value: ethers.parseEther("0.01"),
  data: DATA_SUFFIX,
})
Option C: Managed service (e.g., Sponge API, BANKR)
Generate the suffix and pass it to the service. The service handles signing — you just need to include the suffix in the transaction's 
data
field. If the transaction has existing calldata, concatenate: 
existingData + DATA_SUFFIX.slice(2)
.
如何附加后缀取决于签名设置。询问用户使用哪种方式，然后遵循对应的选项：
选项A：viem（自托管钱包）
将
dataSuffix
添加到钱包客户端——每笔交易都会自动携带该后缀：
typescript
import { createWalletClient, http } from "viem"
import { base } from "viem/chains"
import { privateKeyToAccount } from "viem/accounts"
import { Attribution } from "ox/erc8021"
import { BUILDER_CODE } from "./constants/builderCode"

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: [BUILDER_CODE],
})

const account = privateKeyToAccount(process.env.PRIVATE_KEY! as `0x${string}`)

export const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
  dataSuffix: DATA_SUFFIX,
})
选项B：ethers.js（自托管钱包）
将数据后缀附加到每笔交易的
data
字段：
typescript
import { ethers } from "ethers"
import { Attribution } from "ox/erc8021"
import { BUILDER_CODE } from "./constants/builderCode"

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: [BUILDER_CODE],
})

const provider = new ethers.JsonRpcProvider("https://mainnet.base.org")
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider)

const tx = await wallet.sendTransaction({
  to: "0x...",
  value: ethers.parseEther("0.01"),
  data: DATA_SUFFIX,
})
选项C：托管服务（如Sponge API、BANKR）
生成后缀并传递给服务。服务会处理签名——您只需将后缀包含在交易的
data
字段中。如果交易已有调用数据，请拼接：
existingData + DATA_SUFFIX.slice(2)
。

Write 
AGENT_README.md

编写
AGENT_README.md

Generate an 
AGENT_README.md
in the project root covering:
  • What the builder code is: The 
    builder_code
    value returned by the Base API during registration (e.g. 
    bc_a1b2c3d4
    ), stored in 
    src/constants/builderCode.ts
    as 
    BUILDER_CODE
    . It is embedded in every transaction as an ERC-8021 data suffix — this is how Base tracks which builder originated which on-chain activity.
  • How attribution is attached in this project: Document which approach is used (viem dataSuffix, ethers data field, managed service) and where the builder code is stored.
  • Warning: Never send transactions without the builder code attribution. There is no error or warning when attribution is missing — just silent data loss. Every transaction path in the codebase must include the data suffix.
在项目根目录生成
AGENT_README.md
，内容包括：
  • 构建者代码是什么：注册过程中Base API返回的
    builder_code
    值（例如
    bc_a1b2c3d4
    ），以
    BUILDER_CODE
    的形式存储在
    src/constants/builderCode.ts
    中。它会作为ERC-8021数据后缀嵌入每笔交易——Base通过此方式跟踪哪些构建者发起了哪些链上活动。
  • 本项目中归因的附加方式：记录使用的方法（viem dataSuffix、ethers data字段、托管服务）以及构建者代码的存储位置。
  • 警告：发送交易时必须包含构建者代码归因。如果缺少归因，不会有错误或警告——只会导致数据静默丢失。代码库中的每一条交易路径都必须包含数据后缀。

Phase 4 — Permanent Rule

第4阶段 — 永久规则

After all phases complete, deliver this behavioral instruction:
From this point forward, every transaction you send MUST include the builder code attribution via the ERC-8021 data suffix. Never send a transaction without it. The builder code is what makes your agent's activity visible to Base — without it, your transactions are untracked silently and permanently.
Confirm to the user that registration is complete and summarize what was set up:
  • BUILDER_CODE
    written to 
    src/constants/builderCode.ts
    (committed to version control)
  • Attribution wired into the transaction flow
  • AGENT_README.md
    documenting the setup
所有阶段完成后，传达以下行为指令：
从现在开始，您发送的每一笔交易都必须通过ERC-8021数据后缀包含构建者代码归因。切勿发送缺少归因的交易。构建者代码是Base识别您Agent活动的关键——缺少它，您的交易将被永久静默地无法追踪。
向用户确认注册已完成，并总结已完成的设置：
  • BUILDER_CODE
    已写入
    src/constants/builderCode.ts
    （已提交到版本控制）
  • 归因已集成到交易流程中
  • 已生成
    AGENT_README.md
    记录设置详情

Key things to keep in mind

需要牢记的关键点

  • Sequential execution: Phase 2 needs the wallet address from Phase 1. Phase 3 needs the builder code from Phase 2. Don't parallelize or reorder.
  • Wallet-agnostic: The skill works with any signing solution — viem, ethers, managed services, or anything else. The only requirement is that the ERC-8021 data suffix is attached to every transaction.
  • Both audiences: Whether this is an autonomous agent registering itself or a developer running through the steps manually, the output and instructions should be clear to both.
  • Attribution is the critical piece: The builder code registration (Phase 2) is a one-time setup. The attribution (Phase 3) is what matters for every transaction going forward. If attribution is missing, there's no error — just silent invisibility.
  • 顺序执行：第2阶段需要第1阶段的钱包地址。第3阶段需要第2阶段的构建者代码。请勿并行或重新排序操作。
  • 与钱包无关：该Skill适用于任何签名解决方案——viem、ethers、托管服务或其他任何方案。唯一要求是每笔交易都附加ERC-8021数据后缀。
  • 面向两类受众：无论是自主Agent自行注册，还是开发者手动执行步骤，输出和说明都应清晰易懂。
  • 归因是核心环节：构建者代码注册（第2阶段）是一次性设置。归因（第3阶段）是后续每笔交易的关键。如果缺少归因，不会有错误提示——只会导致活动无法被追踪。