registering-agent-base-dev

Base Builder Code の登録

このスキルでは、エージェントを Base に登録し、トランザクションにビルダーコードのアトリビューションを付与する方法を説明します。ウォレットに依存しません。ユーザーは自分のウォレットと署名ソリューション（viem、ethers、Sponge などのマネージドサービス）を用意します。このスキルが扱うのは登録とアトリビューションのみです。

登録済みか確認する

作業を始める前に、登録がすでに完了しているか確認します。

1. プロジェクト内に builderCode.ts ファイルがあるか確認します（src/constants/builderCode.ts またはプロジェクトルートを確認してください）

ファイルがある場合、登録は完了しています。再登録してはいけません。 Phase 3 に進み、アトリビューションの付与方法を説明して、このルールを念押ししてください。再登録すると新しいビルダーコードが生成され、既存のコードが使えなくなります。

ファイルがない場合は、以下の登録フローをすべて実行してください。

---

Phase 1 — ウォレット

すべてのエージェントには、トランザクションに署名するためのウォレットが必要です。まずユーザーに確認してください。

1. 「ウォレットをお持ちですか？ お持ちの場合は、ウォレットアドレスを教えてください」と質問します。
2. 持っている場合 — 提供されたウォレットアドレスを受け取り、Phase 2 に進みます。
3. 持っていない場合 — Base のウォレット設定ガイド https://docs.base.org/ai-agents/guides/wallet-setup を案内します。ウォレットを用意し、アドレスを提示できるまで先に進まないでください。

---

Phase 2 — 登録

Base のビルダーコード API にウォレットを登録します。この呼び出しにより、エージェントのウォレットアドレスが、Base がアトリビューションの追跡に使用するビルダーコードに関連付けられます。

同梱の scripts/register.sh（このスキルのディレクトリ内にあります）を使用してください。エラーを処理し、レスポンスからビルダーコードを抽出します。

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 を呼び出さないでください。エージェントはすでに登録済みです。

---

Phase 3 — アトリビューションの設定とドキュメント

Phase 2 で取得したビルダーコード（現在 builderCode.ts にある bc_... の値）を、エージェントが送信するすべてのトランザクションに ERC-8021 のデータサフィックスとして付与する必要があります。このフェーズでは、その設定を行い、誰でも（人間でもエージェントでも）このコードベースでトランザクションを送信する方法が分かるように AGENT_README.md を作成します。

まず、アトリビューション用ユーティリティがまだ存在しない場合はインストールします。

npm i ox

ビルダーコードをデータサフィックスに変換します。Phase 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 を生成します。

• ビルダーコードとは：登録時に Base API から返される builder_code の値（例：bc_a1b2c3d4）で、src/constants/builderCode.ts に BUILDER_CODE として保存されます。すべてのトランザクションに ERC-8021 データサフィックスとして埋め込まれます。これにより、Base はどのビルダーがどのオンチェーンアクティビティを発生させたかを追跡できます。
• このプロジェクトでアトリビューションを付与する方法：使用している方法（viem の dataSuffix、ethers の data フィールド、マネージドサービス）と、ビルダーコードの保存場所を記載します。
• 警告：ビルダーコードのアトリビューションを付与せずにトランザクションを送信しないでください。アトリビューションがない場合、エラーも警告も表示されず、データが黙って失われるだけです。コードベース内のすべてのトランザクション経路にデータサフィックスを含める必要があります。

---

フェーズ 4 — 恒久的なルール

すべてのフェーズが完了したら、以下の動作指示を適用します。

これ以降、送信するすべてのトランザクションに、ERC-8021 データサフィックスを使ってビルダーコードのアトリビューションを必ず付与してください。付与せずにトランザクションを送信してはいけません。ビルダーコードによって、エージェントのアクティビティが Base から見えるようになります。付与しない場合、トランザクションは追跡されず、そのことが通知されないまま、永久に記録されません。

登録が完了したことをユーザーに確認し、設定した内容を要約します。

• BUILDER_CODE を src/constants/builderCode.ts に記述（バージョン管理にコミット済み）
• トランザクションフローにアトリビューションを組み込み済み
• 設定を説明する AGENT_README.md

---

留意事項

• 順番に実行：フェーズ 2 ではフェーズ 1 のウォレットアドレスが必要です。フェーズ 3 ではフェーズ 2 のビルダーコードが必要です。並行して実行したり、順序を入れ替えたりしないでください。
• ウォレットに依存しない：このスキルは、viem、ethers、マネージドサービスなど、あらゆる署名ソリューションで動作します。唯一の要件は、すべてのトランザクションに ERC-8021 データサフィックスを付与することです。
• 両方の対象者に配慮：自律型エージェントが自身を登録する場合でも、開発者が手動で手順を進める場合でも、出力と指示の両方が明確である必要があります。
• 重要なのはアトリビューション：ビルダーコードの登録（フェーズ 2）は一度だけ行う設定です。今後のすべてのトランザクションで重要なのはアトリビューション（フェーズ 3）です。アトリビューションがない場合、エラーは発生せず、ただ黙って認識されなくなるだけです。