Skip to main content
AI agents operate autonomously and send transactions without a user manually triggering each one. Builder Codes give you a way to attribute all of that activity back to your agent’s identity on Base.

​
Why agents need Builder Codes

  • Attribution — Every transaction your agent sends is tied to your identity in the Base registry. Without it, your agent’s onchain activity is anonymous.
  • Analytics — Track your agent’s transaction volume, user reach, and onchain conversion in base.dev.
  • Visibility — Agents with Builder Codes can appear in discovery surfaces like Base’s App Leaderboard and ecosystem spotlights.

​
How it works

A Builder Code is a unique identifier (e.g. bc_a1b2c3d4) that gets appended to your agent’s transaction calldata as an ERC-8021 suffix. Smart contracts ignore the suffix; it is extracted by offchain indexers after the fact. The gas overhead is minimal (16 gas per non-zero byte).

​
API reference

​
Register your agent

POST /v1/agents/builder-codes
No authentication required.
FieldTypeRequiredDescription
walletAddressstringYesYour agent’s EVM wallet address (0x...)
Returns the builder code for the given wallet. The same wallet address always returns the same code.
Terminal
curl -X POST https://api.base.dev/v1/agents/builder-codes \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "<your-wallet-address>"
  }'
Response
{
  "builderCode": "bc_a1b2c3d4",
  "walletAddress": "0x..."
}
Already registered? Calling this endpoint again with the same wallet address returns your existing builder code. Safe to call on every deploy.

​
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:
Terminal
npx skills add base/skills
Then ask your agent: “Register my agent for a builder code on Base.dev.” The skill handles wallet validation, calls the registration API, 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). Read more in the Builder Codes for Agents guide.

​
Verify attribution

To confirm your Builder Code is being appended correctly: 1. Check base.dev
  • Visit base.dev
  • Select Onchain from the transaction type dropdown
  • Under the Total Transactions section, attribution counts increment when transactions with your code are processed
2. Use a block explorer (Basescan, Etherscan, etc.)
  • Find your transaction hash
  • View the input data field
  • Verify the last 16 bytes are the 8021 repeating
  • Decode the suffix to confirm your Builder Code is present
3. Open source tools
  • Use the Builder Code Validation tool
  • Select transaction type
  • Enter the transaction or UserOperation hash
  • Click the Check Attribution button

​
Next steps

Full registration guide

Step-by-step walkthrough for manual registration, prompt-driven setup, and wiring ERC-8021 into your transaction client