Skip to content

Commit f50aafe

Browse files
roethkesoheimam
roethke
and
soheimam
authored
add builder codes overview page, fix agent builder codes guide and update sidebar (#1256)
* added keywords to metadata * changed side bar added tag * updated skill to write builder code in readme * updated skill to write builder code in readme * removed * removed * changed name * removed next * removed next * removed response * removed response * updated llm txt * updated llm txt * updated callout * updated agents file * add agent builder code overview page, fix guide, update sidebar * fix typo * add api reference, skill, cross-link overview/guide, add verification steps * update guide title * fix redirects, update title, remove outdated sidebar links * update links, replace product card, reorder tabs --------- Co-authored-by: sohey <soheimam@gmail.com>
1 parent 6485213 commit f50aafe

File tree

5 files changed

+154
-53
lines changed

5 files changed

+154
-53
lines changed

‎docs/ai-agents/setup/agent-builder-codes.mdx‎

Lines changed: 25 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ keywords: ["builder code", "Base.dev", "ERC-8021", "attribution", "onchain activ
55
tag: "NEW"
66
---
77

8-
Base.dev is the canonical registry for agents on Base. A Builder Code ties every transaction your agent sends to your identity in that registry, giving you verifiable onchain attribution and access to analytics and leaderboard features.
8+
[Base.dev](https://base.dev) is the canonical registry for agents on Base. A Builder Code ties every transaction your agent sends to your identity in that registry, giving you verifiable onchain attribution and access to analytics and leaderboard features.
99

1010
## What you get
1111

@@ -19,28 +19,29 @@ Base.dev is the canonical registry for agents on Base. A Builder Code ties every
1919

2020
## Get your Builder Code
2121

22-
One call. No auth.
22+
A single, unauthenticated API call:
2323

2424
```bash Terminal
2525
curl -X POST https://api.base.dev/v1/agents/builder-codes \
2626
-H "Content-Type: application/json" \
2727
-d '{
28-
"wallet_address": "0x<your-wallet-address>"
28+
"walletAddress": "<your-wallet-address>"
2929
}'
3030
```
3131

3232
Response:
3333

34-
```json Title Response
34+
```json Response
3535
{
36-
"builder_code": "bc_a1b2c3d4",
37-
"wallet_address": "0x...",
36+
"builderCode": "bc_a1b2c3d4",
37+
"walletAddress": "0x...",
3838
}
3939
```
4040

41-
<Warning>
41+
<Info>
4242
Already registered? Calling this endpoint again with the same wallet address returns your existing builder code.
43-
</Warning>
43+
</Info>
44+
4445
---
4546

4647
## Get a Builder Code using the Base skill
@@ -53,17 +54,17 @@ npx skills add base/skills
5354

5455
Then ask your agent: **"Register my agent for a builder code on Base.dev."**
5556

56-
The skill runs four phases:
57+
The skill runs three phases:
5758

5859
<Steps>
5960
<Step title="Wallet">
60-
Asks for your agent's wallet address. If you don't have one, it sends you to the [wallet setup guide](/ai-agents/guides/wallet-setup) before continuing.
61+
Asks for your agent's wallet address. If you don't have one, it sends you to the [wallet setup guide](/ai-agents/setup/wallet-setup) before continuing.
6162
</Step>
6263
<Step title="Registration and attribution">
6364
Calls `POST /v1/agents/builder-codes` with your wallet address, 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). It also writes an `AGENT_README.md` documenting the setup.
6465
</Step>
6566
<Step title="Permanent rule">
66-
Confirms the setup and instructs you that every future transaction must include the ERC-8021 suffix. Missing it causes silent, permanent attribution loss — no error, no warning.
67+
Confirms the setup and instructs you that every future transaction must include the ERC-8021 suffix. Missing it causes silent, permanent attribution loss.
6768
</Step>
6869
</Steps>
6970

@@ -73,27 +74,26 @@ The skill runs four phases:
7374

7475
If you're using an AI agent, point it to this page:
7576

76-
```text Title Prompt
77-
Get a Builder Code for my agent on Base.dev using the documentation at [URL of this page].
77+
```text Prompt
78+
Get a Builder Code for my agent on Base.dev using the documentation at https://docs.base.org/ai-agents/setup/agent-builder-codes.
7879
7980
My agent's wallet address: [0x...]
8081
81-
Run this curl command, replacing the wallet address with mine:
82+
Run this curl command, replacing the wallet address with my agent's:
8283
curl -X POST https://api.base.dev/v1/agents/builder-codes \
8384
-H "Content-Type: application/json" \
84-
-d '{"wallet_address": "[0x...]"}'
85+
-d '{"walletAddress": "0x..."}'
8586
86-
Return the builder_code from the response, then show me how to append it to my transactions using ERC-8021.
87+
Return the `builderCode` from the response, then show me how to append it to my transactions using ERC-8021.
8788
```
88-
---
8989

90+
---
9091

9192
## What happens next
9293

93-
Once you receive your Builder Code, it becomes active right away Base will begin tracking any transactions that include it.
94-
95-
## API reference
94+
Once you receive your Builder Code, it becomes active right away and Base will begin tracking any transactions that include it.
9695

96+
## API Reference
9797
### Get builder code
9898

9999
```
@@ -104,8 +104,10 @@ No authentication required.
104104

105105
| Field | Type | Required | Description |
106106
|---|---|---|---|
107-
| `wallet_address` | string | Yes | Your agent's EVM wallet address (`0x...`) |
108-
109-
Returns the builder code for the given wallet. The same wallet address always returns the same code — safe to call multiple times.
107+
| `walletAddress` | string | Yes | Your agent's EVM wallet address (`0x...`) |
110108

109+
Returns the builder code for the given wallet. The same wallet address always returns the same code and is safe to call multiple times.
111110

111+
## Further reading
112+
- [Builder Codes Overview](/base-chain/builder-codes/builder-codes) - What Builder Codes are, how ERC-8021 attribution works, and FAQs on gas, identity, and wallet support
113+
- [Builder Codes for Agent Developers](/base-chain/builder-codes/agent-developers) - API reference, skill reference, and overview

‎docs/base-chain/builder-codes/agent-developers.mdx‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: "Builder Codes for Agent Developers"
3+
sidebarTitle: "For Agent Developers"
4+
description: "Attribute your AI agent's onchain transactions to your identity on Base and unlock analytics and leaderboard features."
5+
---
6+
7+
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.
8+
9+
## Why agents need Builder Codes
10+
11+
- **Attribution** — Every transaction your agent sends is tied to your identity in the Base registry. Without it, your agent's onchain activity is anonymous.
12+
- **Analytics** — Track your agent's transaction volume, user reach, and onchain conversion in [base.dev](https://base.dev).
13+
- **Visibility** — Agents with Builder Codes can appear in discovery surfaces like Base's App Leaderboard and ecosystem spotlights.
14+
15+
## How it works
16+
17+
A Builder Code is a unique identifier (e.g. `bc_a1b2c3d4`) that gets appended to your agent's transaction calldata as an [ERC-8021](https://eip.tools/eip/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).
18+
19+
## API reference
20+
21+
### Register your agent
22+
23+
```
24+
POST /v1/agents/builder-codes
25+
```
26+
27+
No authentication required.
28+
29+
| Field | Type | Required | Description |
30+
|---|---|---|---|
31+
| `walletAddress` | string | Yes | Your agent's EVM wallet address (`0x...`) |
32+
33+
Returns the builder code for the given wallet. The same wallet address always returns the same code.
34+
35+
```bash Terminal
36+
curl -X POST https://api.base.dev/v1/agents/builder-codes \
37+
-H "Content-Type: application/json" \
38+
-d '{
39+
"walletAddress": "<your-wallet-address>"
40+
}'
41+
```
42+
43+
```json Response
44+
{
45+
"builderCode": "bc_a1b2c3d4",
46+
"walletAddress": "0x..."
47+
}
48+
```
49+
50+
<Info>
51+
Already registered? Calling this endpoint again with the same wallet address returns your existing builder code. Safe to call on every deploy.
52+
</Info>
53+
54+
## Using the Base skill
55+
56+
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:
57+
58+
```bash Terminal
59+
npx skills add base/skills
60+
```
61+
62+
Then ask your agent: **"Register my agent for a builder code on Base.dev."**
63+
64+
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).
65+
66+
Read more in the [Builder Codes for Agents guide](/ai-agents/setup/agent-builder-codes).
67+
68+
## Verify attribution
69+
70+
To confirm your Builder Code is being appended correctly:
71+
72+
**1. Check base.dev**
73+
74+
- Visit [base.dev](https://base.dev)
75+
- Select **Onchain** from the transaction type dropdown
76+
- Under the Total Transactions section, attribution counts increment when transactions with your code are processed
77+
78+
**2. Use a block explorer (Basescan, Etherscan, etc.)**
79+
80+
- Find your transaction hash
81+
- View the input data field
82+
- Verify the last 16 bytes are the `8021` repeating
83+
- Decode the suffix to confirm your Builder Code is present
84+
85+
**3. Open source tools**
86+
87+
- Use the [Builder Code Validation](https://builder-code-checker.vercel.app/) tool
88+
- Select transaction type
89+
- Enter the transaction or UserOperation hash
90+
- Click the **Check Attribution** button
91+
92+
## Next steps
93+
94+
<CardGroup cols={2}>
95+
<Card title="Full registration guide" icon="robot" href="/ai-agents/setup/agent-builder-codes">
96+
Step-by-step walkthrough for manual registration, prompt-driven setup, and wiring ERC-8021 into your transaction client
97+
</Card>
98+
</CardGroup>

‎docs/base-chain/builder-codes/builder-codes.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Base Builder Codes"
3-
description: "Attribute onchain activity to your app or wallet with Builder Codes."
3+
description: "Attribute onchain activity to your app, wallet or agent with Builder Codes."
44
---
55

66
## What Are Builder Codes
@@ -22,8 +22,8 @@ Each code has associated metadata. Onchain metadata primarily includes a "payout
2222
<Card title="For Wallet Developers" icon="wallet" href="/base-chain/builder-codes/wallet-developers">
2323
Implement the dataSuffix capability
2424
</Card>
25-
<Card title="For Bridge Developers" icon="bridge" href="/base-chain/builder-codes/bridge-developers">
26-
Integrate with the Base-Solana bridge
25+
<Card title="For Agent Developers" icon="robot" href="/base-chain/builder-codes/agent-developers">
26+
Attribute your AI agent's transactions via the API
2727
</Card>
2828
</CardGroup>
2929

‎docs/docs.json‎

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,8 @@
154154
"pages": [
155155
"base-chain/builder-codes/builder-codes",
156156
"base-chain/builder-codes/app-developers",
157-
"base-chain/builder-codes/wallet-developers"
157+
"base-chain/builder-codes/wallet-developers",
158+
"base-chain/builder-codes/agent-developers"
158159
]
159160
},
160161
{
@@ -496,24 +497,6 @@
496497
]
497498
}
498499
},
499-
{
500-
"tab": "Mini Apps",
501-
"groups": [
502-
{
503-
"group": "Quickstart",
504-
"pages": [
505-
"mini-apps/quickstart/migrate-to-standard-web-app",
506-
"get-started/build-app"
507-
]
508-
},
509-
{
510-
"group": "Growth",
511-
"pages": [
512-
"mini-apps/growth/rewards"
513-
]
514-
}
515-
]
516-
},
517500
{
518501
"tab": "AI Agents",
519502
"groups": [
@@ -583,6 +566,24 @@
583566
}
584567
]
585568
},
569+
{
570+
"tab": "Mini Apps",
571+
"groups": [
572+
{
573+
"group": "Quickstart",
574+
"pages": [
575+
"mini-apps/quickstart/migrate-to-standard-web-app",
576+
"get-started/build-app"
577+
]
578+
},
579+
{
580+
"group": "Growth",
581+
"pages": [
582+
"mini-apps/growth/rewards"
583+
]
584+
}
585+
]
586+
},
586587
{
587588
"tab": "OnchainKit",
588589
"groups": [
@@ -800,7 +801,7 @@
800801
"destination": "/get-started/build-app"
801802
},
802803
{
803-
"source": "ai-agents/guides/agent-builder-codes",
804+
"source": "/ai-agents/guides/agent-builder-codes",
804805
"destination": "/ai-agents/setup/agent-builder-codes"
805806
},
806807
{
@@ -2845,7 +2846,7 @@
28452846
},
28462847
{
28472848
"source": "/ai-agents/core-concepts/payments-and-transactions",
2848-
"destination": "/ai-agents/payments/x402-protocol"
2849+
"destination": "/ai-agents/payments/pay-for-services-with-x402"
28492850
},
28502851
{
28512852
"source": "/ai-agents/core-concepts/identity-verification-auth",
@@ -2869,7 +2870,7 @@
28692870
},
28702871
{
28712872
"source": "/ai-agents/quickstart/agentkit",
2872-
"destination": "/ai-agents/frameworks/agentkit"
2873+
"destination": "/ai-agents/skills/index"
28732874
},
28742875
{
28752876
"source": "/ai-agents/guides/agent-app",

‎docs/get-started/base.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ mode: "wide"
1313
</div>
1414
<div className="use-cases-links">
1515
### Agents
16-
[Build an AI Agent](/ai-agents/index)
17-
[Give Your Agent a Wallet](/ai-agents/core-concepts/wallets)
18-
[Register Your Agent](/ai-agents/core-concepts/identity-verification-auth)
16+
[Build an AI Agent](/ai-agents)
17+
[Get Started with Agentic Payments (x402)](/ai-agents/quickstart/payments)
18+
[Get Started with Agentic Trading](/ai-agents/quickstart/trading)
1919
</div>
2020
<div className="use-cases-links">
2121
### Tokens
@@ -34,8 +34,8 @@ mode: "wide"
3434
<Card title="Base Account" icon="wallet" href="/base-account/overview/what-is-base-account">
3535
Authentication, payments, Basenames
3636
</Card>
37-
<Card title="Mini Apps" icon="grid-2" href="/mini-apps/introduction/overview">
38-
Build in-app social experiences
37+
<Card title="AI Agents" icon="robot" href="/ai-agents">
38+
Build and deploy autonomous onchain agents
3939
</Card>
4040
<Card title="Solana Bridge" icon="bridge" href="/base-chain/quickstart/base-solana-bridge">
4141
Cross-chain asset transfers

0 commit comments

Comments
 (0)