registering-agent-base-dev

Base Builder Code 注册

此技能用于在 Base 上注册 Agent，并介绍如何将 Builder Code 归属信息附加到交易中。此技能与钱包无关——用户可以使用自己的钱包和签名方案（viem、ethers、Sponge 等托管服务）。此技能仅处理注册和归属信息。

检查是否已注册

开始任何操作前，请检查是否已经完成注册：

1. 在项目中查找 builderCode.ts 文件（检查 src/constants/builderCode.ts 或项目根目录）

如果文件存在，表示已完成注册——请勿重新注册。 直接跳到第 3 阶段，介绍如何附加归属信息，并再次强调这一规则。重新注册会生成新的 Builder Code，导致现有代码失效。

如果文件不存在，请继续下面的完整注册流程。

---

第 1 阶段 — 钱包

每个 Agent 都需要一个钱包来签署交易。开始任何其他操作前，请先询问用户。

1. 询问：“你有钱包吗？如果有，请提供钱包地址。”
2. 如果有——使用用户提供的钱包地址，进入第 2 阶段。
3. 如果没有——引导用户查看 Base 钱包设置指南：https://docs.base.org/ai-agents/guides/wallet-setup — 在用户拥有钱包并能提供地址之前，请勿继续。

---

第 2 阶段 — 注册

使用 Base Builder Code API 注册钱包。此调用会将 Agent 的钱包地址与 Base 用于归属追踪的 Builder Code 关联起来。

使用随附的 scripts/register.sh（位于此技能目录中）。该脚本会处理错误并从响应中提取 Builder Code：

BUILDER_CODE=$(bash <this-skill-path>/scripts/register.sh "<wallet_address>")

也可以直接调用 API：

curl -X POST https://api.base.dev/v1/agents/builder-codes \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "<wallet_address>"}'

API 会返回类似以下内容的响应：

{
  "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 值，并将其写入常量文件：

// src/constants/builderCode.ts
export const BUILDER_CODE = "bc_a1b2c3d4"

如果存在 src/ 目录，请使用 src/constants/builderCode.ts；否则，将文件放在项目根目录下，命名为 builderCode.ts。

如果 builderCode.ts 已存在，请勿调用此 API——该 Agent 已完成注册。

---

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

第 2 阶段生成的 Builder Code（现在位于 builderCode.ts 中的 bc_... 值）需要作为 ERC-8021 数据后缀附加到该 Agent 发送的每笔交易中。本阶段会完成接入，并编写 AGENT_README.md，让任何（人类或 Agent）在此代码库中工作的人都了解交易必须如何发送。

首先，如果尚未安装，请安装归属工具：

npm i ox

将 Builder Code 转换为数据后缀。从第 2 阶段写入的常量文件中导入 BUILDER_CODE——此操作不会生成新的代码，而是将现有代码编码为 ERC-8021 字节格式：

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],
})

将归属信息接入交易流程

附加后缀的方式取决于签名设置。询问用户使用哪种方案，然后按照对应选项操作：

选项 A：viem（自托管钱包）

将 dataSuffix 添加到钱包客户端——每笔交易都会自动携带该后缀：

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 字段：

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 字段中。如果交易已有 calldata，请进行拼接：existingData + DATA_SUFFIX.slice(2)。

编写 AGENT_README.md

在项目根目录生成 AGENT_README.md，涵盖以下内容：

• Builder code 是什么：注册期间由 Base API 返回的 builder_code 值（例如 bc_a1b2c3d4），存储在 src/constants/builderCode.ts 中，变量名为 BUILDER_CODE。它会作为 ERC-8021 数据后缀嵌入每笔交易中，这是 Base 追踪哪个 Builder 发起了哪些链上活动的方式。
• 本项目如何附加归因信息：记录使用了哪种方式（viem dataSuffix、ethers data 字段或托管服务），以及 builder code 存储的位置。
• 警告：绝不要发送未附加 builder code 归因信息的交易。缺少归因信息时不会报错或警告，只会导致数据悄然丢失。代码库中的每条交易路径都必须包含该数据后缀。

---

阶段 4 — 永久规则

所有阶段完成后，给出以下行为指令：

从现在起，你发送的每笔交易都必须通过 ERC-8021 数据后缀附加 builder code 归因信息。绝不要发送未附加归因信息的交易。builder code 能让 Base 看到你的 Agent 活动；如果没有它，你的交易就会在毫无提示的情况下永久无法被追踪。

向用户确认注册已完成，并总结已完成的设置：

• 已将 BUILDER_CODE 写入 src/constants/builderCode.ts（已提交到版本控制）
• 已将归因信息接入交易流程
• 已创建 AGENT_README.md，记录相关设置

---

需要牢记的要点

• 按顺序执行：阶段 2 需要阶段 1 中获取的钱包地址。阶段 3 需要阶段 2 中获取的 builder code。不要并行执行或调整顺序。
• 不依赖特定钱包：此技能适用于任何签名方案，包括 viem、ethers、托管服务等。唯一要求是每笔交易都附加 ERC-8021 数据后缀。
• 面向两类受众：无论是自主注册的 Agent，还是手动逐步操作的开发者，输出和说明都应清晰易懂。
• 归因信息至关重要：builder code 注册（阶段 2）只需设置一次。归因信息（阶段 3）才是之后每笔交易都需要的内容。如果缺少归因信息，不会报错，只会悄然无法被追踪。