Base-8004 Registration

intent

register your ai agent onchain with erc-8004 on base mainnet to get a permanent, verifiable identity. you get an erc-721 nft token, a public reputation score, and verifiable metadata that any platform or service can read. use this skill when you want your agent to have a persistent identity across multiple platforms, accumulate reputation, and advertise your capabilities to other agents and services.

inputs

environment variables:

• AGENT_PRIVATE_KEY (string, hex format 0x...) - your wallet private key. required to sign transactions. store in .env, never commit to version control.
• ERC8004_AGENT_ID (string, optional) - your agent's token ID after initial registration. needed for updates via setAgentURI.

wallet requirements:

• ethereum-compatible wallet with erc-20 support (viem handles this).
• minimum 0.0005 ETH on base mainnet to cover gas (~$0.02 usd).
• no existing erc-8004 registration for your wallet address (one per address per registration).

external dependencies:

• viem ^2.0.0 (typescript ethereum library).
• base mainnet rpc endpoint (viem uses public default; you can specify custom via http(process.env.RPC_URL)).
• basescan (read-only, for verification).

contract addresses (base mainnet):

• identity registry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
• reputation registry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

metadata for registration:

• agent name (string, <255 chars).
• agent description (string, <1000 chars).
• agent avatar url (string, optional, recommend 256x256px or larger).
• services array (list of objects with name, endpoint, version).

procedure

step 1: install viem and set up wallet infrastructure

install viem to interact with base mainnet.

npm install viem

inputs: none.

outputs: viem library available in your project.

step 2: generate or import a private key

generate a new private key or import an existing one.

import { generatePrivateKey } from "viem/accounts";

const privateKey = generatePrivateKey();
console.log("Private key:", privateKey);

if you already have a wallet, use its private key instead.

inputs: none (or existing private key).

outputs: privateKey in hex format (0x...).

critical: save this immediately. if lost, you lose the wallet and onchain identity forever.

step 3: derive your wallet address from the private key

convert the private key to an account object and extract the address.

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(privateKey);
console.log("Address:", account.address);

inputs: privateKey.

outputs: account object with address field. store the address for verification.

step 4: store the private key securely in environment

add the private key to a .env file and ensure git ignores it.

AGENT_PRIVATE_KEY=0x...your_private_key_here...

add to .gitignore:

echo ".env" >> .gitignore

inputs: private key from step 2.

outputs: .env file with AGENT_PRIVATE_KEY set, .gitignore updated.

security rules:

• never log, commit, or send the private key in api calls.
• never overwrite without backup.
• never share with anyone.

step 5: create wallet and public clients for base mainnet

instantiate viem clients for signing and reading.

import { createWalletClient, createPublicClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const publicClient = createPublicClient({ chain: base, transport: http() });
const walletClient = createWalletClient({ account, chain: base, transport: http() });

inputs: AGENT_PRIVATE_KEY env var.

outputs: account, publicClient, walletClient ready to use.

step 6: check wallet balance on base

query your eth balance and verify it's at least 0.0005 eth (enough for registration gas).

const balance = await publicClient.getBalance({ address: account.address });
const balanceEth = Number(balance) / 1e18;
console.log("Balance:", balanceEth, "ETH");

if (balance < 500000000000000n) {
  console.error("insufficient balance. need at least 0.0005 ETH.");
  process.exit(1);
}

inputs: publicClient, account.address.

outputs: balance in wei (bigint), converted to eth for readability. script exits if balance too low.

step 7: create your agent registration metadata

build a json object with your agent's name, description, services, and avatar.

const registration = {
  type: "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  name: "Your Agent Name",
  description: "What your agent does",
  image: "https://example.com/your-agent-avatar.png",
  active: true,
  x402Support: false,
  services: [
    { name: "A2A", endpoint: "https://your-agent.example.com/a2a", version: "0.3.0" },
    { name: "MCP", endpoint: "https://your-agent.example.com/mcp", version: "0.1.0" },
  ],
};

inputs: agent metadata (name, description, services).

outputs: registration object (typescript object, not yet encoded).

notes:

• services array declares your capabilities onchain. common types: A2A (agent-to-agent), MCP (model context protocol).
• image can be empty string "" initially; update later via setAgentURI.
• active and x402Support are protocol flags; set as shown.

step 8: encode metadata as base64 data uri

convert the registration json to a data uri for onchain storage.

const uri =
  "data:application/json;base64," + Buffer.from(JSON.stringify(registration)).toString("base64");
console.log("Agent URI:", uri);

inputs: registration object.

outputs: uri string (data uri with base64-encoded json).

step 9: estimate gas for registration transaction

call estimateGas to predict the cost before submitting.

import { encodeFunctionData } from "viem";

const IDENTITY_REGISTRY = "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";

const registerAbi = [
  {
    inputs: [{ name: "agentURI", type: "string" }],
    name: "register",
    outputs: [{ name: "agentId", type: "uint256" }],
    stateMutability: "nonpayable",
    type: "function",
  },
] as const;

const gas = await publicClient.estimateGas({
  account: account.address,
  to: IDENTITY_REGISTRY,
  data: encodeFunctionData({
    abi: registerAbi,
    functionName: "register",
    args: [uri],
  }),
});

console.log("Estimated gas:", gas.toString());

inputs: publicClient, account.address, IDENTITY_REGISTRY, registerAbi, uri.

outputs: gas as bigint (gas units). typically 100k-200k units.

step 10: submit registration transaction

send the register transaction to the identity registry.

const hash = await walletClient.writeContract({
  address: IDENTITY_REGISTRY,
  abi: registerAbi,
  functionName: "register",
  args: [uri],
});

console.log("Transaction hash:", hash);

inputs: walletClient, IDENTITY_REGISTRY, registerAbi, uri.

outputs: hash string (0x-prefixed transaction hash).

step 11: wait for transaction confirmation

poll until the transaction is mined and confirmed.

const receipt = await publicClient.waitForTransactionReceipt({ hash });

if (receipt.status !== "success") {
  console.error("registration failed. check basescan for details:", hash);
  process.exit(1);
}

console.log("Registration confirmed on block", receipt.blockNumber);

inputs: publicClient, hash.

outputs: receipt object with status, blockNumber, logs.

step 12: extract your agent token id from the transfer event

parse the erc-721 transfer event to retrieve your token id.

const transferTopic = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
const transferLog = receipt.logs.find(
  (log) =>
    log.topics[0] === transferTopic && log.address.toLowerCase() === IDENTITY_REGISTRY.toLowerCase()
);

const erc8004AgentId = transferLog?.topics[3]
  ? BigInt(transferLog.topics[3]).toString()
  : undefined;

if (!erc8004AgentId) {
  console.error("failed to parse agent id from event logs.");
  process.exit(1);
}

console.log("Your ERC-8004 Agent ID:", erc8004AgentId);

inputs: receipt.logs, IDENTITY_REGISTRY address.

outputs: erc8004AgentId string (decimal token id).

step 13: save your agent id to environment

store your token id for future updates.

ERC8004_AGENT_ID=42

add to .env file.

inputs: erc8004AgentId from step 12.

outputs: .env updated with ERC8004_AGENT_ID.

step 14: verify registration on basescan

confirm your agent is registered and visible onchain.

open your browser to:

https://basescan.org/nft/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432/{your_agent_id}

inputs: your agent id.

outputs: basescan page showing your nft token, owner, and metadata uri.

step 15 (optional): update your registration metadata

if you need to change your agent name, description, services, or avatar, call setAgentURI on the identity registry.

const setAgentUriAbi = [
  {
    inputs: [
      { name: "agentId", type: "uint256" },
      { name: "agentURI", type: "string" },
    ],
    name: "setAgentURI",
    outputs: [],
    stateMutability: "nonpayable",
    type: "function",
  },
] as const;

const updatedRegistration = {
  type: "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  name: "Your Agent Name",
  description: "Updated description",
  image: "https://example.com/your-agent-avatar.png",
  active: true,
  x402Support: false,
  services: [
    { name: "A2A", endpoint: "https://your-agent.example.com/a2a", version: "0.3.0" },
    { name: "MCP", endpoint: "https://your-agent.example.com/mcp", version: "0.1.0" },
  ],
};

const newUri =
  "data:application/json;base64," +
  Buffer.from(JSON.stringify(updatedRegistration)).toString("base64");

const hash = await walletClient.writeContract({
  address: IDENTITY_REGISTRY,
  abi: setAgentUriAbi,
  functionName: "setAgentURI",
  args: [BigInt(process.env.ERC8004_AGENT_ID!), newUri],
});

console.log("URI updated, TX:", hash);

inputs: walletClient, IDENTITY_REGISTRY, setAgentUriAbi, ERC8004_AGENT_ID, updated registration object.

outputs: hash (transaction hash). only callable by the token owner (your wallet).

decision points

if you already have a base wallet with eth: skip steps 2-6 and go directly to step 7. provide your existing private key at step 5.

if you have no eth on base: stop at step 6. fund your wallet via coinbase (direct withdrawal to base), relay bridge (relay.link/bridge), or transfer from another base wallet. wait for confirmation before continuing.

if your balance check fails (< 0.0005 eth): acquire more eth on base. registration costs ~$0.02 usd in gas; $1 provides ample buffer.

if the transaction reverts at step 10: check basescan for revert reason. common causes: invalid uri format, registry contract paused, or wallet already registered. verify your uri is valid base64 json.

if you cannot parse the token id at step 12: the transfer event may not exist in the logs. check basescan tx receipt for errors. if registration succeeded but event is missing, call ownerOf(wallet_address) on the identity registry contract to find your token id (requires reading contract state).

if you want to update metadata after registration: you must own the token. use step 15 (setAgentURI). only the token owner can update. non-owners will receive a tx revert.

if you need to query your metadata onchain later: use the read-only examples in the resources section (no gas, no signing required).

output contract

success state:

• transaction receipt shows status: "success" on base mainnet.
• token id extracted from erc-721 transfer event (bigint, stored as string).
• ERC8004_AGENT_ID saved in .env.
• basescan nft page displays your agent token, owner address, and metadata uri.
• basescan shows your agent's name, description, image, and services list.

file locations:

• .env file contains AGENT_PRIVATE_KEY and ERC8004_AGENT_ID.
• .gitignore includes .env entry.

data format:

• private key: hex string 0x followed by 64 hex chars (256 bits).
• agent id: decimal integer (as string or bigint).
• metadata uri: data uri with data:application/json;base64, prefix.
• registration json: erc-8004 spec v1, with name, description, image, active, x402Support, services array.

outcome signal

you know it worked when:

• console logs show a valid transaction hash (0x-prefixed hex string).
• publicClient.waitForTransactionReceipt returns a receipt with status: "success".
• console logs print your agent id (a positive integer).
• basescan shows your nft token at the identity registry address with your wallet as owner.
• basescan displays your agent's metadata (name, description, image, services) decoded from the onchain uri.
• querying tokenURI(your_agent_id) returns your data uri.
• you can transfer or manage your token on basescan like any other nft.

if something went wrong:

• console shows an error message with a transaction hash. look up the tx on basescan and check the revert reason.
• balance check exits the script. acquire more eth and retry.
• private key is lost. you cannot recover it or the wallet. generate a new one and start over.

resources

• erc-8004 protocol - protocol spec and documentation.
• base - base l2 chain homepage.
• basescan - base block explorer and contract viewer.
• viem docs - typescript ethereum library.
• relay bridge - cross-chain bridge to base.

onchain queries (read-only examples)

check token ownership or read metadata without gas cost.

import { createPublicClient, http } from "viem";
import { base } from "viem/chains";

const client = createPublicClient({ chain: base, transport: http() });

// check who owns a token
const owner = await client.readContract({
  address: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
  abi: [
    {
      inputs: [{ name: "agentId", type: "uint256" }],
      name: "ownerOf",
      outputs: [{ name: "", type: "address" }],
      stateMutability: "view",
      type: "function",
    },
  ],
  functionName: "ownerOf",
  args: [42n],
});

// read agent metadata uri
const uri = await client.readContract({
  address: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
  abi: [
    {
      inputs: [{ name: "tokenId", type: "uint256" }],
      name: "tokenURI",