base · youssefea · May 14, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
diff --git a/docs/ai-agents/setup/agent-builder-codes.mdx → .../ai-agents/guides/agent-builder-codes.mdx b/docs/ai-agents/setup/agent-builder-codes.mdx → .../ai-agents/guides/agent-builder-codes.mdx
@@ -2,7 +2,6 @@
 title: "Builder Codes for Agents"
 description: "Register your agent on Base.dev and append a Builder Code to every transaction to measure onchain activity."
 keywords: ["builder code", "Base.dev", "ERC-8021", "attribution", "onchain activity", "agent attribution", "dataSuffix", "builder codes", "Base builder codes", "agent onchain"]
-tag: "NEW"
 ---
 
 [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.

diff --git a/docs/ai-agents/guides/batch-calls.mdx b/docs/ai-agents/guides/batch-calls.mdx
@@ -0,0 +1,66 @@
+---
+title: "Execute Contract Calls"
+description: "Batch multiple contract interactions into a single user approval using send_calls and Base MCP"
+keywords: ["send_calls MCP", "batch contract calls AI", "EIP-5792 AI", "DeFi AI agent", "Moonwell AI Base", "batch transaction AI"]
+---
+
+import { AcceptingPaymentsDemo } from "/snippets/AcceptingPaymentsDemo.jsx"
+
+<AcceptingPaymentsDemo />
+
+## What it does
+
+`send_calls` submits a batch of EIP-5792 contract calls to your Base Account in a single approval. Use it for DeFi interactions, multi-step operations, and NFT mints that go beyond simple send or swap.
+
+The most common use case: [protocol plugins](/ai-agents/plugins/native-plugins) like Moonwell prepare a `calls` array (including token approvals and deposits), and you pass it directly to `send_calls` — everything executes atomically in one approval. Moonwell works entirely via `web_request`, with no additional MCP server required.
+
+## What you can ask
+
+With the [Moonwell plugin](/ai-agents/plugins/native-plugins):
+
+```text
+Find the best USDC market on Base and supply 100 USDC
+```
+
+```text
+Borrow 500 USDC against my collateral on Moonwell
+```
+
+```text
+Repay all my Moonwell debt
+```
+
+## How it works
+
+<Steps>
+  <Step title="A plugin prepares the calls">
+    Protocol plugins like Moonwell return a `calls` array and `chainId` from their prepare endpoints. The calls include any required token approvals and the protocol interaction itself.
+  </Step>
+  <Step title="Your assistant calls send_calls()">
+    Passes the `calls` array and hex `chainId` to Base MCP.
+  </Step>
+  <Step title="You review and approve">
+    Open the `keys.coinbase.com` link to review all calls in the batch before signing.
+  </Step>
+  <Step title="Calls execute onchain">
+    All calls in the batch execute atomically — if one fails, none go through.
+  </Step>
+</Steps>
+
+## Parameters
+
+| Parameter | Required | What it does |
+|-----------|----------|-------------|
+| `chainId` | Yes | Hex chain ID: `0x2105` for Base mainnet, `0x14a34` for Base Sepolia |
+| `calls` | Yes | Array of `{ to, value?, data? }` objects |
+
+## Related guides
+
+<CardGroup cols={2}>
+  <Card title="Native plugins" icon="puzzle-piece" href="/ai-agents/plugins/native-plugins">
+    Morpho, Moonwell, Uniswap, and Avantis — full orchestration patterns in the skill repo.
+  </Card>
+  <Card title="Sign messages" icon="pen-nib" href="/ai-agents/guides/sign-messages">
+    Sign individual messages and typed data.
+  </Card>
+</CardGroup>
diff --git a/docs/ai-agents/guides/check-balance.mdx b/docs/ai-agents/guides/check-balance.mdx
@@ -0,0 +1,52 @@
+---
+title: "Check Balance & Portfolio"
+description: "View your token balances, portfolio value, and wallet details using Base MCP"
+keywords: ["check balance AI", "get_portfolio MCP", "get_wallets MCP", "Base wallet balance AI assistant"]
+---
+
+import { DataFetchingDemo } from "/snippets/DataFetchingDemo.jsx"
+
+<DataFetchingDemo />
+
+## What you can ask
+
+```text
+Show me my wallets
+```
+
+```text
+What is my USDC balance?
+```
+
+```text
+Show my full portfolio
+```
+
+```text
+What tokens do I have in my wallet?
+```
+
+## How it works
+
+**`get_wallets`** — lists all wallets in your wallet group (your Base Account plus any agent wallets).
+
+**`get_portfolio`** — returns portfolio value and per-asset breakdown for your connected wallet.
+
+| Parameter | What it does |
+|-----------|-------------|
+| `chain` | Filter by chain: `base` or `ethereum` |
+| `query` | Filter by token name or symbol (e.g. "USDC") |
+| `includePnl` | Include unrealized/realized P&L per asset |
+
+**`search_tokens`** — resolve a token symbol or name to its contract address and decimals. Useful before sending less common tokens.
+
+## Related guides
+
+<CardGroup cols={2}>
+  <Card title="Send tokens" icon="paper-plane" href="/ai-agents/guides/send-tokens">
+    Send ETH or any ERC-20 from your Base Account.
+  </Card>
+  <Card title="View transaction history" icon="clock-rotate-left" href="/ai-agents/guides/view-history">
+    See past sends, swaps, and receives.
+  </Card>
+</CardGroup>
diff --git a/docs/ai-agents/guides/index.mdx b/docs/ai-agents/guides/index.mdx
@@ -0,0 +1,26 @@
+---
+title: "Guides"
+description: "Step-by-step guides for common things to do with Base MCP"
+keywords: ["Base MCP guides", "send tokens AI", "swap tokens AI", "check balance AI", "sign messages AI"]
+---
+
+<CardGroup cols={2}>
+  <Card title="Check balance & portfolio" icon="wallet" href="/ai-agents/guides/check-balance">
+    View your token balances, portfolio value, and wallet details.
+  </Card>
+  <Card title="Send tokens" icon="paper-plane" href="/ai-agents/guides/send-tokens">
+    Send ETH or any ERC-20 to an address, ENS name, or basename.
+  </Card>
+  <Card title="Swap tokens" icon="arrows-rotate" href="/ai-agents/guides/swap-tokens">
+    Swap between any two tokens via the Coinbase swap service.
+  </Card>
+  <Card title="View transaction history" icon="clock-rotate-left" href="/ai-agents/guides/view-history">
+    Browse past transactions and filter by asset or date range.
+  </Card>
+  <Card title="Sign messages" icon="pen-nib" href="/ai-agents/guides/sign-messages">
+    Sign EIP-712 typed data and plain messages for authentication.
+  </Card>
+  <Card title="Execute contract calls" icon="code" href="/ai-agents/guides/batch-calls">
+    Batch multiple contract interactions into a single user approval.
+  </Card>
+</CardGroup>
diff --git a/docs/ai-agents/guides/send-tokens.mdx b/docs/ai-agents/guides/send-tokens.mdx
@@ -0,0 +1,73 @@
+---
+title: "Send Tokens"
+description: "Send ETH or any ERC-20 token to an address, ENS name, basename, or cb.id using Base MCP"
+keywords: ["send tokens AI", "send USDC AI assistant", "send ETH AI", "Base MCP send", "ENS basename send AI"]
+---
+
+import { TradeExecutionDemo } from "/snippets/TradeExecutionDemo.jsx"
+
+<TradeExecutionDemo />
+
+## What you can ask
+
+```text
+Send 10 USDC to alice.base.eth
+```
+
+```text
+Transfer 0.01 ETH to 0x1234...abcd
+```
+
+```text
+Pay bob.eth 5 USDC
+```
+
+```text
+Send 50 DEGEN to vitalik.eth
+```
+
+## How it works
+
+The `send` tool constructs a transaction from your Base Account and requires your approval at `keys.coinbase.com`. Nothing is sent until you confirm.
+
+| Parameter | Required | What it does |
+|-----------|----------|-------------|
+| `recipient` | Yes | Address, ENS name, basename (e.g. `alice.base.eth`), cb.id name, or username |
+| `amount` | Yes | Human-readable decimal (e.g. `"10.5"`) |
+| `asset` | Yes | Token symbol (`ETH`, `USDC`) or ERC-20 contract address |
+| `chain` | Yes | Network to send on (e.g. `base`, `arbitrum`, `optimism`, `ethereum`) |
+| `decimals` | When using contract address | Required when `asset` is a contract address |
+
+<Tip>
+For common tokens like ETH and USDC, just use the symbol — no contract address needed. For less common tokens, your assistant will call `search_tokens` first to resolve the address and decimals automatically.
+</Tip>
+
+## Approval flow
+
+Every send requires a manual approval:
+
+<Steps>
+  <Step title="Your assistant calls send()">
+    The transaction is constructed but not yet broadcast.
+  </Step>
+  <Step title="You receive an approval link">
+    Open the `keys.coinbase.com` link to review the recipient, amount, and fee.
+  </Step>
+  <Step title="You approve">
+    Confirm the transaction in the approval UI. Nothing is sent without your explicit confirmation.
+  </Step>
+  <Step title="Transaction confirms">
+    Your assistant polls `get_request_status` and reports success once the transaction is confirmed onchain.
+  </Step>
+</Steps>
+
+## Related guides
+
+<CardGroup cols={2}>
+  <Card title="Swap tokens" icon="arrows-rotate" href="/ai-agents/guides/swap-tokens">
+    Exchange one token for another.
+  </Card>
+  <Card title="Check balance" icon="wallet" href="/ai-agents/guides/check-balance">
+    Verify your balance before sending.
+  </Card>
+</CardGroup>
diff --git a/docs/ai-agents/guides/sign-messages.mdx b/docs/ai-agents/guides/sign-messages.mdx
@@ -0,0 +1,60 @@
+---
+title: "Sign Messages"
+description: "Sign EIP-712 typed data and plain messages with your Base Account using Base MCP"
+keywords: ["sign message AI", "EIP-712 sign AI", "personal_sign AI", "Base MCP sign", "sign typed data AI assistant"]
+---
+
+import { SignMessagesDemo } from "/snippets/SignMessagesDemo.jsx"
+
+<SignMessagesDemo />
+
+## What it does
+
+The `sign` tool requests a cryptographic signature from your Base Account. Like all write tools, it requires your approval at `keys.coinbase.com`.
+
+Two signature types are supported:
+
+| Type | Standard | Use case |
+|------|----------|---------|
+| `0x45` | personal_sign (EIP-191) | Simple text messages, SIWE auth challenges |
+| `0x01` | EIP-712 typed data | Structured data, permit signatures, protocol auth |
+
+## What you can ask
+
+```text
+Sign this message: "I agree to the terms of service"
+```
+
+```text
+Sign in to this app using my Base Account
+```
+
+Signing is usually invoked by protocols or integrations, not directly prompted by users. Your assistant will handle the signing flow when a service requests it.
+
+## How it works
+
+<Steps>
+  <Step title="Your assistant calls sign()">
+    Passes the message type and payload to Base MCP.
+  </Step>
+  <Step title="You receive an approval link">
+    Open `keys.coinbase.com` to review what you're signing — the message content is shown in full.
+  </Step>
+  <Step title="You approve">
+    Confirm the signature in the approval UI.
+  </Step>
+  <Step title="Signature returned">
+    Your assistant polls `get_request_status` to retrieve the completed signature, then passes it to the requesting service.
+  </Step>
+</Steps>
+
+## Related guides
+
+<CardGroup cols={2}>
+  <Card title="Execute contract calls" icon="code" href="/ai-agents/guides/batch-calls">
+    Batch multiple contract interactions into one approval.
+  </Card>
+  <Card title="Native plugins" icon="puzzle-piece" href="/ai-agents/plugins/native-plugins">
+    Morpho, Moonwell, Uniswap, and Avantis — signing in the flow with DeFi protocols.
+  </Card>
+</CardGroup>
diff --git a/docs/ai-agents/guides/swap-tokens.mdx b/docs/ai-agents/guides/swap-tokens.mdx
@@ -0,0 +1,57 @@
+---
+title: "Swap Tokens"
+description: "Swap between any two tokens on Base via the Coinbase swap service using Base MCP"
+keywords: ["swap tokens AI", "token swap AI assistant", "USDC ETH swap AI", "Base MCP swap", "DeFi swap AI"]
+---
+
+import { TradingQuickstartDemo } from "/snippets/TradingQuickstartDemo.jsx"
+
+<TradingQuickstartDemo />
+
+## What you can ask
+
+```text
+Swap 100 USDC for ETH on Base
+```
+
+```text
+Buy $50 of ETH with USDC
+```
+
+```text
+Trade 0.01 ETH for USDC
+```
+
+```text
+Convert all my USDC to ETH
+```
+
+## How it works
+
+The `swap` tool routes through the Coinbase swap service and requires your approval at `keys.coinbase.com`. Swaps are only supported on mainnet — not on testnets.
+
+| Parameter | Required | What it does |
+|-----------|----------|-------------|
+| `fromAsset` | Yes | Token to swap from — symbol (`USDC`) or contract address |
+| `toAsset` | Yes | Token to swap to — symbol (`ETH`) or contract address |
+| `amount` | Yes | Amount of `fromAsset` to swap (human-readable decimal) |
+| `chain` | Yes | `base` — testnets are not supported |
+
+<Note>
+Testnet swaps are not supported. If you need to test, use `send` on `base-sepolia` instead.
+</Note>
+
+## Approval flow
+
+Same as sending — every swap requires approval at `keys.coinbase.com`. Your assistant will give you a link to review the swap details (input amount, expected output, price impact) before anything is signed.
+
+## Related guides
+
+<CardGroup cols={2}>
+  <Card title="Send tokens" icon="paper-plane" href="/ai-agents/guides/send-tokens">
+    Send tokens directly to another address.
+  </Card>
+  <Card title="Check balance" icon="wallet" href="/ai-agents/guides/check-balance">
+    Verify balances before swapping.
+  </Card>
+</CardGroup>