diff --git a/README.md b/README.md index d9dcbde..af90147 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ -[![GitHub contributors](https://img.shields.io/github/contributors/base/base-skills)](https://github.com/base/base-skills/graphs/contributors) -[![GitHub commit activity](https://img.shields.io/github/commit-activity/w/base/base-skills)](https://github.com/base/base-skills/graphs/contributors) -![GitHub repo size](https://img.shields.io/github/repo-size/base/base-skills) +[![GitHub contributors](https://img.shields.io/github/contributors/base/skills)](https://github.com/base/skills/graphs/contributors) +[![GitHub commit activity](https://img.shields.io/github/commit-activity/w/base/skills)](https://github.com/base/skills/graphs/contributors) +![GitHub repo size](https://img.shields.io/github/repo-size/base/skills) @@ -20,29 +20,24 @@ -[![GitHub pull requests by-label](https://img.shields.io/github/issues-pr-raw/base/base-skills)](https://github.com/base/base-skills/pulls) -[![GitHub Issues](https://img.shields.io/github/issues-raw/base/base-skills.svg)](https://github.com/base/base-skills/issues) +[![GitHub pull requests by-label](https://img.shields.io/github/issues-pr-raw/base/skills)](https://github.com/base/skills/pulls) +[![GitHub Issues](https://img.shields.io/github/issues-raw/base/skills.svg)](https://github.com/base/skills/issues) -## Available Skills +## Recommended Skills -| Skill | Description | -| ----- | ----------- | -| [Adding Builder Codes](./skills/adding-builder-codes/SKILL.md) | Appends Base builder codes to transactions across Privy, Wagmi, Viem, and standard Ethereum RPC implementations. Automatically detects the user's framework before applying the correct integration pattern. | -| [Building with Base Account](./skills/building-with-base-account/SKILL.md) | Integrates Base Account SDK for authentication and payments, including SIWB, Base Pay, Paymasters, Sub Accounts, and Spend Permissions. | -| [Connecting to Base Network](./skills/connecting-to-base-network/SKILL.md) | Provides Base Mainnet and Sepolia network configuration, RPC endpoints, chain IDs, and explorer URLs. | -| [Converting Farcaster Miniapp to App](./skills/convert-farcaster-miniapp-to-app/SKILL.md) | Converts Farcaster Mini App SDK projects into regular Base web apps, with an option to preserve a small separate Farcaster-specific surface when needed. | -| [Deploying Contracts on Base](./skills/deploying-contracts-on-base/SKILL.md) | Deploys and verifies contracts on Base with Foundry, plus common troubleshooting guidance. | -| [Running a Base Node](./skills/running-a-base-node/SKILL.md) | Covers production node setup, hardware requirements, networking ports, and syncing guidance. | -| [Converting MiniKit to Farcaster](./skills/converting-minikit-to-farcaster/SKILL.md) | Migrates Mini Apps from MiniKit (OnchainKit) to native Farcaster SDK with mappings, examples, and pitfalls. | -| [Migrating an OnchainKit App](./skills/migrating-an-onchainkit-app/SKILL.md) | Migrates apps from @coinbase/onchainkit to standalone wagmi/viem components, replacing the provider, wallet, and transaction components. | -| [Registering an Agent on Base](./skills/registering-agent-base-dev/SKILL.md) | Registers an agent wallet with the Base builder code API and wires ERC-8021 transaction attribution into viem, ethers, or managed signing services. | +Two consolidated skills that cover the most common use cases. Each uses progressive reference loading — the skill loads a single entry point and pulls in detailed references only when needed. + +| Skill | Install | Description | +| ----- | ------- | ----------- | +| [build-on-base](./skills/build-on-base/SKILL.md) | `npx skills add base/skills --skill build-on-base` | Complete Base development playbook: network, contracts, wallet auth, payments, attribution, and migrations. Consolidates all individual skills into one. | +| [base-mcp](./skills/base-mcp/SKILL.md) | `npx skills add base/skills --skill base-mcp` | Base Account MCP server — gives your AI assistant a wallet via mcp.base.org. Tools for sending, swapping, signing, batching calls, and checking balances. Includes Morpho lending plugin. | ## Installation Install with [Vercel's Skills CLI](https://skills.sh): ```bash -npx skills add base/base-skills +npx skills add base/skills ``` ## Usage diff --git a/package.json b/package.json index 8edec1c..a26bf68 100644 --- a/package.json +++ b/package.json @@ -1,4 +1,4 @@ { - "name": "base-skills", + "name": "skills", "private": true } diff --git a/skills/base-mcp/SKILL.md b/skills/base-mcp/SKILL.md new file mode 100644 index 0000000..cbded52 --- /dev/null +++ b/skills/base-mcp/SKILL.md @@ -0,0 +1,83 @@ +--- +name: base-mcp +description: > + Base MCP — gives your AI assistant access to your Base account via the Base MCP server (mcp.base.org). + Tools: get_wallets (list wallets), get_portfolio (balances, any address), send (ETH/ERC-20 transfers), + swap (token swaps via Coinbase), sign (EIP-712/personal_sign), send_calls (EIP-5792 batch), + get_transaction_history (paginated tx history), get_request_status (poll approval), search_tokens (token lookup), + web_request (fetch whitelisted partner APIs to get calldata, then pass to send_calls — hostname must be in server allowlist). + Approval mode: send/swap/sign/send_calls require user approval at keys.coinbase.com; response includes approvalUrl + requestId. + Plugins: Morpho lending protocol available via plugins/morpho.md. Moonwell lending on Base/Optimism via plugins/moonwell.md. +--- + +# Base MCP + +The Base MCP server gives your AI assistant access to your Base account on Base. + +## Step 1 — Check if the MCP is installed + +Before anything else, attempt to call `get_wallets`. If the tool is not available or the call fails with a connection error, the MCP server is not installed. Go to **Step 2**. If it succeeds, skip to **Step 3**. + +## Step 2 — Install the MCP server + +Tell the user the MCP is not connected and point them to [references/install.md](references/install.md) for step-by-step UI instructions. That file covers Claude Desktop, ChatGPT app, Claude.ai web, Claude Code CLI, and Cursor — with beginner-friendly walkthroughs for each. + +Quick reference: +- **Claude Desktop** — Claude menu → Settings → Integrations → Add integration → `https://mcp.base.org` +- **ChatGPT app** — Settings → Connectors → Add connector → MCP server → `https://mcp.base.org` +- **Claude.ai web** — Settings → Integrations → Add integration → `https://mcp.base.org` +- **Claude Code CLI** — `claude mcp add base-account --transport http https://mcp.base.org` + +After connecting, the user signs in to authorize via Base account — no Coinbase account required. Once installed, re-run `get_wallets` to confirm the connection, then continue to Step 3. + +## Step 3 — Get wallets + +Call `get_wallets` immediately at the start of any session involving transactions. This returns: +- The user's Base account address +- Any agent wallets and their delegation status +- `inSession: true/false` — determines whether approval mode is required + +**If `inSession: true`** on an agent wallet: transactions can execute without manual approval (M2 mode). Pass `agentWalletId` to send/swap. + +**If no wallet is `inSession: true`**: all write tools use approval mode — every transaction goes to keys.coinbase.com for the user to approve. + +Load [references/wallets.md](references/wallets.md) for full field reference. + +## Tool Routing + +Read this table first. For the current task, load ONLY the matching reference file — do not preload all references. + +| Task | Tool | Reference | +|------|------|-----------| +| Install the MCP / platform-specific setup | — | [references/install.md](references/install.md) | +| List wallets / check session status | `get_wallets` | [references/wallets.md](references/wallets.md) | +| Check balance / portfolio / token lookup | `get_portfolio`, `search_tokens` | [references/portfolio.md](references/portfolio.md) | +| Send ETH or ERC-20 | `send` | [references/send.md](references/send.md) | +| Swap tokens | `swap` | [references/swap.md](references/swap.md) | +| Sign a message or typed data | `sign` | [references/sign.md](references/sign.md) | +| Batch contract calls | `send_calls` | [references/batch-calls.md](references/batch-calls.md) | +| View transaction history | `get_transaction_history` | [references/history.md](references/history.md) | +| Check pending approval status | `get_request_status` | [references/approval-mode.md](references/approval-mode.md) | +| Resolve token by symbol | `search_tokens` | [references/tokens.md](references/tokens.md) | +| Fetch protocol API calldata (Moonwell, etc.) | `web_request` | [references/web-request.md](references/web-request.md) | + +## Approval Mode + +All write tools (send, swap, sign, send_calls) return an `approvalUrl` and `requestId`. Direct the user to open the URL to approve, then call `get_request_status` to confirm completion. Never report success before `get_request_status` returns confirmed. + +Load [references/approval-mode.md](references/approval-mode.md) for full details. + +## Plugins + +Additional protocol capabilities — no extra MCP server needed for Moonwell (uses `web_request`); Morpho requires its own MCP server. + +| Plugin | Protocol | Reference | +|--------|---------|-----------| +| Morpho | Lending / vaults on Base | [plugins/morpho.md](plugins/morpho.md) | +| Moonwell | Lending / borrowing on Base and Optimism | [plugins/moonwell.md](plugins/moonwell.md) | + +## Installation + +```bash +npx skills add base/skills --skill base-mcp +``` diff --git a/skills/base-mcp/plugins/moonwell.md b/skills/base-mcp/plugins/moonwell.md new file mode 100644 index 0000000..89b934b --- /dev/null +++ b/skills/base-mcp/plugins/moonwell.md @@ -0,0 +1,155 @@ +# Moonwell Plugin + +Moonwell is a Compound v2 lending protocol on Base and Optimism. Use `web_request` to call the Moonwell HTTP API to read positions/rates and prepare unsigned calldata, then execute via `send_calls`. + +No additional MCP server required — everything goes through `web_request` + `send_calls`. + +**Prerequisite:** `api.moonwell.fi` must be in the MCP server's `web_request` allowlist. If requests to that hostname are rejected, inform the user that the Moonwell API is not yet whitelisted on this MCP instance. + +**Supported chains:** Base (8453), Optimism (10). + +--- + +## Orchestration Pattern + +``` +web_request(https://api.moonwell.fi/v1/prepare/?...) + → { data: { transactions: [ { to, data, value, chainId }, ... ] } } + ↓ +send_calls(chainId, calls mapped from transactions[]) + → approvalUrl + requestId + ↓ +User approves at keys.coinbase.com + ↓ +get_request_status(requestId) → confirmed +``` + +Steps in `transactions[]` are ordered — `approve` and `enter-market` come before the protocol action. Execute them as a single `send_calls` batch. + +--- + +## Read Endpoints (use web_request GET) + +``` +GET https://api.moonwell.fi/v1/markets?chain=base +GET https://api.moonwell.fi/v1/markets/USDC?chain=base +GET https://api.moonwell.fi/v1/rates?chain=base&asset=USDC +GET https://api.moonwell.fi/v1/yield?chain=base&sort=apy&min-tvl=1000000&limit=5 +GET https://api.moonwell.fi/v1/positions/
?chain=base +GET https://api.moonwell.fi/v1/health/
?chain=base +GET https://api.moonwell.fi/v1/rewards/
?chain=base +GET https://api.moonwell.fi/v1/token-balance/
?chain=base&asset=USDC +``` + +Market reads are edge-cached 30 s. User-scoped reads (`positions`, `health`, `rewards`, `token-balance`) are never cached. + +`/positions` returns an array — one entry per market. Use `?active=true` to filter out markets where both `suppliedUsd` and `borrowedUsd` are zero. + +--- + +## Prepare Endpoints (use web_request → send_calls) + +Verbs: `supply`, `withdraw`, `borrow`, `repay`. + +**GET form** (query params): + +``` +GET https://api.moonwell.fi/v1/prepare/supply?chain=base&asset=USDC&amountDecimal=100&from=
+``` + +**POST form** (JSON body — pass as the `body` object parameter to `web_request`): + +```json +{ + "url": "https://api.moonwell.fi/v1/prepare/supply", + "method": "POST", + "headers": { "content-type": "application/json" }, + "body": { "chain": "base", "asset": "USDC", "amountDecimal": "100", "from": "
" } +} +``` + +Both return identical response shapes. Use GET when simpler; use POST when the body is complex. + +### Key parameters + +| Field | Notes | +|-------|-------| +| `chain` | `base` (default), `optimism`, or chain ID | +| `asset` | Symbol: `USDC`, `WETH`, `ETH` (alias for WETH) | +| `amountDecimal` | Human-readable string, e.g. `"100"`. Use this **or** `amount` (base units), never both. | +| `from` | User's wallet address (from `get_wallets`) | + +### Response → send_calls mapping + +```json +{ + "data": { + "transactions": [ + { "step": "approve", "to": "0x...", "data": "0x...", "value": "0x0", "chainId": 8453 }, + { "step": "enter-market", "to": "0x...", "data": "0x...", "value": "0x0", "chainId": 8453 }, + { "step": "moonwell-supply", "to": "0x...", "data": "0x...", "value": "0x0", "chainId": 8453 } + ] + } +} +``` + +Pass all items as the `calls` array to `send_calls`, using `chainId` from any transaction item (`0x2105` for Base mainnet). + +--- + +## Example Flows + +### Supply 100 USDC on Base + +``` +1. get_wallets → address +2. web_request GET /token-balance/
?chain=base&asset=USDC → confirm balance ≥ 100 +3. web_request GET /prepare/supply?chain=base&asset=USDC&amountDecimal=100&from=
+4. send_calls(chainId=0x2105, calls from transactions[]) +5. User approves → get_request_status(requestId) +``` + +### Borrow USDC against collateral + +``` +1. get_wallets → address +2. web_request GET /health/
?chain=base → verify health > 1.5 +3. web_request GET /prepare/borrow?chain=base&asset=USDC&amountDecimal=50&from=
+4. send_calls(chainId=0x2105, calls from transactions[]) +5. User approves → get_request_status(requestId) +``` + +### Check positions and health + +``` +1. get_wallets → address +2. web_request GET /positions/
?chain=base&active=true → show per-market balances +3. web_request GET /health/
?chain=base → show health factor +``` + +--- + +## Protocol Notes + +- **mTokens** — ERC-20 receipt tokens (mUSDC, mWETH…); exchange rate accrues over time +- **WETH special-case** — borrow/withdraw deliver native ETH; supply/repay require ERC-20 WETH. Both `asset=ETH` and `asset=WETH` resolve to the same mWETH market +- **Compound v2 error codes** — `mint`, `borrow`, `repay` return non-zero codes for business-logic failures without reverting. Check the on-chain receipt after broadcast +- **Base has two mUSDC entries** — the current market and a deprecated bridged-USDC market. Disambiguate by `marketAddress` or `deprecated: true` + +### Health factor guide + +| Value | Status | +|-------|--------| +| `> 1.5` | Healthy | +| `1.1 – 1.5` | Caution | +| `< 1.1` | Liquidation risk | +| `null` | No borrows | + +--- + +## Chain IDs for send_calls + +| Chain | chainId param | +|-------|--------------| +| Base mainnet | `0x2105` | +| Optimism | `0xa` | diff --git a/skills/base-mcp/plugins/morpho.md b/skills/base-mcp/plugins/morpho.md new file mode 100644 index 0000000..f902f8e --- /dev/null +++ b/skills/base-mcp/plugins/morpho.md @@ -0,0 +1,89 @@ +# Morpho Plugin + +Morpho is a lending protocol on Base. The Morpho MCP server prepares lending operations (deposit, borrow, withdraw, repay, supply collateral) which are then executed via Base MCP's `send_calls`. + +## MCP Server + +URL: `https://mcp.morpho.org/` + +## Installation (alongside Base MCP) + +Add both servers to your MCP config: + +```json +{ + "mcpServers": { + "base-account": { "url": "https://mcp.base.org" }, + "morpho": { "url": "https://mcp.morpho.org/" } + } +} +``` + +Claude Code: `claude mcp add morpho --transport http https://mcp.morpho.org/` + +## Morpho Tools (17 total) + +### Read +- `morpho_health_check` — server connectivity +- `morpho_get_supported_chains` — supported chains +- `morpho_query_vaults` — list vaults with filtering/sorting +- `morpho_get_vault` — details for a specific vault +- `morpho_query_markets` — list markets with filtering +- `morpho_get_market` — details for a specific market +- `morpho_get_positions` — all positions for an address (all vaults + markets) +- `morpho_get_token_balance` — token balance and approval state + +### Write (prepare_ returns unsigned calls for send_calls) +- `morpho_prepare_deposit` — prepare vault deposit with approvals +- `morpho_prepare_withdraw` — prepare vault withdrawal (supports max) +- `morpho_prepare_supply` — prepare market supply with approvals +- `morpho_prepare_borrow` — prepare market borrow with health check +- `morpho_prepare_repay` — prepare market repay (supports max) +- `morpho_prepare_supply_collateral` — supply collateral to market +- `morpho_prepare_withdraw_collateral` — withdraw collateral with health check + +### Simulate +- `morpho_simulate_transactions` — simulate with post-state analysis + +## Orchestration Pattern + +Morpho `prepare_*` tools return unsigned call data. Pass the result to Base MCP's `send_calls` to execute. + +``` +morpho_prepare_deposit(vaultAddress, amount) → { calls: [...], chainId } +↓ +send_calls(chainId, calls) → approvalUrl + requestId +↓ +User approves at keys.coinbase.com +↓ +get_request_status(requestId) → confirmed +``` + +## Example Prompts + +``` +Find the best USDC vault on Base by APY and deposit 100 USDC +``` +1. `morpho_query_vaults` (filter by USDC, sort by APY) +2. `morpho_prepare_deposit` (selected vault, 100 USDC) +3. `send_calls` (chainId + calls from prepare_deposit) +4. Direct user to approvalUrl, poll get_request_status + +``` +Show all my Morpho positions on Base +``` +1. `get_wallets` (get user's address) +2. `morpho_get_positions` (user's address) + +``` +Check if my Morpho borrow position is healthy +``` +1. `get_wallets` (get address) +2. `morpho_get_positions` (address) +3. Report health factor from position data + +## Important Notes + +- Morpho `prepare_*` tools simulate before returning — review simulation output before calling `send_calls` +- Always use `morpho_simulate_transactions` for novel or large operations +- Morpho operates on Base mainnet; check `morpho_get_supported_chains` for current list diff --git a/skills/base-mcp/references/approval-mode.md b/skills/base-mcp/references/approval-mode.md new file mode 100644 index 0000000..8f2be36 --- /dev/null +++ b/skills/base-mcp/references/approval-mode.md @@ -0,0 +1,25 @@ +# Approval Mode + +All write tools (send, swap, sign, send_calls) operate in approval mode. The user must manually approve every transaction at keys.coinbase.com. + +## Flow + +1. **Call the write tool** (send, swap, sign, or send_calls) +2. **Response includes**: + - `approvalUrl` — URL the user must open to approve + - `requestId` — ID to poll for completion +3. **Direct the user** to open `approvalUrl` immediately. Say: "Please open this link to approve the transaction: [approvalUrl]" +4. **After user confirms they approved**, call `get_request_status` with the `requestId` +5. **Only report success** when `get_request_status` returns a completed/confirmed status + +## get_request_status parameters +- `requestId` — the ID from the write tool response (required) + +## Common mistakes +- Do NOT report success before calling `get_request_status` — the user may not have approved yet +- Do NOT skip showing the `approvalUrl` — the transaction cannot complete without user action +- Do NOT poll `get_request_status` in a tight loop — call once after user confirms they approved + +## When approval is NOT needed +Agent wallets marked `inSession: true` (from `get_wallets`) can transact without approval in M2 mode. The `agentWalletId` parameter on send/swap enables this. + diff --git a/skills/base-mcp/references/batch-calls.md b/skills/base-mcp/references/batch-calls.md new file mode 100644 index 0000000..0f52cfb --- /dev/null +++ b/skills/base-mcp/references/batch-calls.md @@ -0,0 +1,23 @@ +# send_calls + +Submit a batch of EIP-5792 wallet_sendCalls for user approval. Use for arbitrary contract interactions, multi-step transactions, or batched operations. + +## When to use +- Protocol interactions not covered by send/swap (e.g. DeFi, NFT mints, approvals) +- Batching multiple operations into one user approval +- Morpho plugin: Morpho prepares `prepare_*` calls → pass the raw calls array to `send_calls` + +## Required parameters +- `chainId` — hex chain ID with 0x prefix (`0x2105` for Base mainnet, `0x14a34` for Base Sepolia) +- `calls` — array of call objects, each with: + - `to` — target address (0x-prefixed, required) + - `value` — hex ETH in wei (e.g. `0x0`), optional + - `data` — calldata hex (e.g. `0xa9059cbb...`), optional + +## Approval mode flow +Same as send: get `approvalUrl` + `requestId`, direct user to URL, poll `get_request_status`. + +## Common use case with Morpho plugin +1. Morpho `prepare_deposit` (or other prepare_* tool) returns `calls` array +2. Pass that array directly to `send_calls` with the appropriate `chainId` +3. Direct user to `approvalUrl` for signing diff --git a/skills/base-mcp/references/history.md b/skills/base-mcp/references/history.md new file mode 100644 index 0000000..bbe351d --- /dev/null +++ b/skills/base-mcp/references/history.md @@ -0,0 +1,22 @@ +# get_transaction_history + +Returns paginated transaction history for any wallet address in reverse chronological order. Onchain data is public — any address can be queried. + +## When to use +- "Show my recent transactions", "What did I last do?", "Show my USDC sends" +- Investigating past activity for any address + +## Parameters +- `address` — optional; defaults to session's agent wallet +- `chain` — optional: `base` or `ethereum` (defaults to base) +- `asset` — optional symbol filter (e.g. `USDC`, `ETH`) +- `limit` — 1–200, defaults to 50 +- `cursor` — pagination cursor from previous response's `nextCursor` + +## Return fields (per transaction) +- Transfer details, type classification, fees, USD values at time of transaction +- `hasMore` — whether more pages exist; continue paginating while `true` + +## Key patterns +- Date range filtering is not supported — paginate to find transactions in a specific period +- Use `asset` filter to narrow results to a specific token diff --git a/skills/base-mcp/references/install.md b/skills/base-mcp/references/install.md new file mode 100644 index 0000000..40438f7 --- /dev/null +++ b/skills/base-mcp/references/install.md @@ -0,0 +1,109 @@ +# Installing Base MCP + +Choose your app below. The whole process takes under two minutes. + +--- + +## Claude Desktop + +1. Open Claude Desktop +2. Click the **Claude** menu in the top menu bar → **Settings…** +3. Go to the **Integrations** tab +4. Click **Add integration** +5. Enter a name (e.g. `Base`) and the server URL: `https://mcp.base.org` +6. Click **Add** +7. A browser window opens — sign in to authorize (see [Authorization](#authorization) below) + +> If you don't see an Integrations tab, your Claude Desktop version may be older. Update to the latest version from [claude.ai/download](https://claude.ai/download). + +--- + +## ChatGPT (desktop app) + +1. Open the ChatGPT app +2. Click your **profile picture** (top-right) → **Settings** +3. Go to the **Connectors** tab +4. Click **Add connector** → **MCP server** +5. Paste the server URL: `https://mcp.base.org` +6. Click **Connect** +7. A browser window opens — sign in to authorize (see [Authorization](#authorization) below) + +--- + +## Claude.ai (web) + +1. Go to [claude.ai](https://claude.ai) and sign in +2. Click your **profile picture** (bottom-left) → **Settings** +3. Go to the **Integrations** tab +4. Click **Add integration** +5. Paste the server URL: `https://mcp.base.org` +6. Click **Connect** +7. A browser window opens — sign in to authorize (see [Authorization](#authorization) below) + +--- + +## Claude Code (CLI · VS Code · JetBrains) + +Run this in your terminal: + +```bash +claude mcp add base-account --transport http https://mcp.base.org +``` + +Then restart Claude Code and sign in when prompted. + +--- + +## Cursor + +Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): + +```json +{ + "mcpServers": { + "base-account": { + "type": "http", + "url": "https://mcp.base.org" + } + } +} +``` + +Restart Cursor after saving. + +--- + +## Authorization + +After connecting the server, a browser tab opens to mcp.base.org. Here's what to do: + +1. Click **Sign in with Base** +2. If you don't have a Base account yet, you can create one for free — no Coinbase account required +3. Review the permissions the app is requesting and click **Authorize** +4. The browser tab will close and you'll be taken back to your app + +That's it — the MCP is now connected. + +--- + +## Did it work? + +Ask your AI assistant: **"Show me my wallets."** + +If it replies with a wallet address, you're all set. If it says it doesn't have access to a wallet tool, the MCP isn't connected — try the install steps again or check the troubleshooting section below. + +--- + +## Troubleshooting + +**The browser tab for sign-in never opened** +→ Try opening `https://mcp.base.org` in your browser directly and signing in there, then re-add the server in your app. + +**I see "Integration not found" or "Tool not available"** +→ The server may not have loaded yet. Restart your app and try again. + +**The Integrations / Connectors tab doesn't exist** +→ Your app version may be outdated. Update to the latest version and try again. + +**web_request fails with a domain error** +→ The website you're trying to reach isn't in the approved list. This is a security feature — see plugin references for supported partner APIs. diff --git a/skills/base-mcp/references/portfolio.md b/skills/base-mcp/references/portfolio.md new file mode 100644 index 0000000..20899b0 --- /dev/null +++ b/skills/base-mcp/references/portfolio.md @@ -0,0 +1,21 @@ +# get_portfolio + +Returns portfolio value and per-asset breakdown for any wallet address. Onchain data is public — any address can be queried. + +## When to use +- "What's my balance?", "How much USDC do I have?", "Show me my portfolio" +- Querying any wallet address's holdings (not just the user's) + +## Parameters +- `address` — optional; defaults to session's agent wallet +- `chain` — optional filter: `base` or `ethereum` +- `query` — optional search filter (e.g. "USDC", "ETH") +- `limit` — max assets to return (default 20) +- `offset` — pagination offset +- `includePnl` — include unrealized/realized P&L (default false) + +## Key patterns +- For "my balance" → call without address to get the session wallet +- For "balance of 0x..." → pass the address parameter +- Use `query` to filter to a specific token before displaying +- For tokens not found by `get_portfolio`, use `search_tokens` first to resolve the contract address diff --git a/skills/base-mcp/references/send.md b/skills/base-mcp/references/send.md new file mode 100644 index 0000000..a7724bf --- /dev/null +++ b/skills/base-mcp/references/send.md @@ -0,0 +1,27 @@ +# send + +Send native ETH or any ERC-20 token to an address. Operates in approval mode: the response includes an `approvalUrl` and `requestId`. + +## When to use +- "Send X to Y", "Transfer X USDC to...", "Pay X ETH to..." + +## Required parameters +- `recipient` — 0x address, ENS name, basename (e.g. `vitalik.eth`), cb.id name, or wallet username +- `amount` — human-readable decimal (e.g. "1.5") +- `asset` — symbol (`ETH`, `USDC`) or ERC-20 contract address +- `chain` — `base` or `base-sepolia` + +## Optional parameters +- `decimals` — required when `asset` is a contract address (not a symbol); must be 0–18 +- `agentWalletId` — scope to a specific agent wallet (M2 mode only) + +## Approval mode flow +1. Call `send` → get `approvalUrl` + `requestId` +2. Show the user: "Please approve this transaction: [approvalUrl]" +3. After user confirms, call `get_request_status` with `requestId` +4. Only report success when status is confirmed + +## Key patterns +- For unknown tokens, call `search_tokens` first to get the contract address and decimals +- Never report success before `get_request_status` confirms completion +- Use basenames/ENS for recipient when provided — no need to resolve first diff --git a/skills/base-mcp/references/sign.md b/skills/base-mcp/references/sign.md new file mode 100644 index 0000000..8aa82b7 --- /dev/null +++ b/skills/base-mcp/references/sign.md @@ -0,0 +1,21 @@ +# sign + +Request a user-approved signature from the Base account. Supports EIP-712 typed data and personal_sign. Operates in approval mode. + +## When to use +- "Sign this message", "Sign this typed data", agent needs a signature for authentication + +## Required parameters +- `type` — `0x01` for EIP-712 typed data, `0x45` for personal_sign +- `data`: + - For `0x01`: EIP-712 TypedData object with `primaryType`, `types`, `domain`, `message` + - For `0x45`: object with a `message` string field + +## Approval mode flow +1. Call `sign` → get `approvalUrl` + `requestId` +2. Direct user to `approvalUrl` +3. Poll `get_request_status` to retrieve the signature after approval + +## Key patterns +- Use `0x45` for simple text messages (e.g. SIWE, auth challenges) +- Use `0x01` for structured typed data (e.g. permit signatures, EIP-712 auth) diff --git a/skills/base-mcp/references/swap.md b/skills/base-mcp/references/swap.md new file mode 100644 index 0000000..f79201d --- /dev/null +++ b/skills/base-mcp/references/swap.md @@ -0,0 +1,20 @@ +# swap + +Swap between two tokens via the Coinbase swap service. Only supported on mainnet chains (not testnets). Operates in approval mode. + +## When to use +- "Swap X for Y", "Buy X ETH with USDC", "Trade X to Y" + +## Required parameters +- `fromAsset` — symbol (ETH, USDC) or contract address +- `toAsset` — symbol or contract address +- `amount` — human-readable decimal amount of `fromAsset` +- `chain` — target chain (e.g. `base`); testnets not supported + +## Approval mode flow +Same as send: get `approvalUrl` + `requestId`, direct user to URL, poll `get_request_status`. + +## Key patterns +- For unknown tokens, call `search_tokens` first to resolve contract address +- Testnets are not supported — if user requests a testnet swap, explain this +- Never report success before `get_request_status` confirms completion diff --git a/skills/base-mcp/references/tokens.md b/skills/base-mcp/references/tokens.md new file mode 100644 index 0000000..3ec0397 --- /dev/null +++ b/skills/base-mcp/references/tokens.md @@ -0,0 +1,24 @@ +# search_tokens + +Search for token metadata by symbol or name. Returns contract address, decimals, and chain info needed to use a token with send/swap. + +## When to use +- Before calling `send` with a non-standard token (not ETH or USDC) — need contract address + decimals +- User references a token by name/symbol and you need to resolve it +- Verifying a token exists on a specific chain + +## Parameters +- `query` — required; token symbol or name (e.g. `USDC`, `uniswap`, `WETH`) +- `chain` — optional; `base` or `base-sepolia` + +## Return fields (per result) +- `name`, `symbol` — display info +- `address` — ERC-20 contract address +- `decimals` — needed when passing a contract address to send +- `imageUrl` — token logo +- `chain` — which chain this token is on + +## Key patterns +- Always pass the returned `address` AND `decimals` to `send` when using a contract address +- For common tokens (ETH, USDC), you can pass the symbol directly to send/swap — no lookup needed +- If multiple results, prefer the one on `base` mainnet unless user specified otherwise diff --git a/skills/base-mcp/references/wallets.md b/skills/base-mcp/references/wallets.md new file mode 100644 index 0000000..60c450d --- /dev/null +++ b/skills/base-mcp/references/wallets.md @@ -0,0 +1,23 @@ +# get_wallets + +Returns all wallets in the user's wallet group: the Base account (primary) plus any agent wallets. + +## When to use +- User asks "show me my wallets", "what wallets do I have", "which wallet is active" +- You need to know if an agent wallet is authorized before a transactional call + +## Parameters +None. + +## Return fields (per wallet) +- `id` — wallet ID +- `type` — `base-account` or `agent-wallet` +- `address` — 0x address +- `inSession` — boolean; only `true` wallets can be used with transactional tools +- `delegationStatus` — whether the agent wallet has delegated authority from the Base account +- `spendPolicy` — summary of spend limits (agent wallets only) + +## Key patterns +- If no wallet is `inSession: true`, all transactional tools will use approval mode (keys.coinbase.com) +- Agent wallets with `inSession: true` can transact without manual approval (M2 mode) +- Always check `inSession` before deciding whether approval will be required diff --git a/skills/base-mcp/references/web-request.md b/skills/base-mcp/references/web-request.md new file mode 100644 index 0000000..221c6ef --- /dev/null +++ b/skills/base-mcp/references/web-request.md @@ -0,0 +1,45 @@ +# web_request + +Make an HTTP request to a whitelisted partner API. The hostname must be in the MCP server's configured allowlist — requests to unlisted domains are rejected outright. This is why the tool exists: AI assistants on Claude Desktop, ChatGPT, and similar environments can't autonomously fetch arbitrary URLs, but `web_request` gives controlled access to trusted protocol APIs so the agent can retrieve calldata and pass it to `send_calls`. + +## When to use + +- Fetching unsigned transaction calldata from a partner protocol API (e.g. Moonwell `/prepare/supply`) before passing it to `send_calls` +- Reading on-chain data from a whitelisted protocol HTTP API (positions, balances, rates, health factor) + +## Parameters + +- `url` — full HTTPS URL; hostname must be in the allowlist (required) +- `method` — `GET` or `POST` (required) +- `headers` — optional key/value map of custom headers. **Prohibited:** `Authorization`, `Cookie`, `Host`, `X-Forwarded-*` +- `body` — JSON object for POST requests; ignored for GET + +## Calldata pattern + +``` +web_request(GET or POST to whitelisted /prepare/* endpoint) + → { data: { transactions: [ { to, data, value, chainId }, ... ] } } + ↓ +send_calls(chainId, calls mapped from transactions[]) + → approvalUrl + requestId + ↓ +User approves at keys.coinbase.com + ↓ +get_request_status(requestId) → confirmed +``` + +## Mapping response transactions to send_calls + +Protocol `/prepare/*` responses return an ordered `transactions[]` array. Map each item directly: + +``` +transactions[i].to → calls[i].to +transactions[i].data → calls[i].data +transactions[i].value → calls[i].value (0x-prefixed hex) +``` + +Pass the `chainId` from any `transactions[i].chainId` to `send_calls`. Execute all calls in order — steps like `approve` and `enter-market` must confirm before later steps succeed. + +## Allowlist + +The allowlist is configured server-side on the MCP. If a request fails with a domain rejection error, the hostname is not whitelisted — inform the user rather than retrying. Currently whitelisted partner protocols are documented in the plugin references (e.g. `plugins/moonwell.md`). diff --git a/skills/build-on-base/SKILL.md b/skills/build-on-base/SKILL.md new file mode 100644 index 0000000..526a191 --- /dev/null +++ b/skills/build-on-base/SKILL.md @@ -0,0 +1,79 @@ +--- +name: build-on-base +description: > + Complete Base development playbook. Covers: (1) Network — Base RPC URLs, chain IDs (8453/84532), + explorer config, testnet setup, connect to Base, Base Sepolia; (2) Contracts — Foundry deployment, + forge create, BaseScan verification, CDP faucet, testnet ETH, deploy contract to Base; + (3) Builder Codes — ERC-8021 attribution suffix, referral fees, dataSuffix for Wagmi/Viem/Privy/ + ethers.js/window.ethereum, transaction attribution, earn referral fees, append builder code; + (4) Base Account SDK — Sign in with Base (SIWB), Base Pay, USDC payments, paymasters, gas + sponsorship, sub-accounts, spend permissions, prolinks, batch transactions, smart wallet, + payment link, recurring subscription; (5) Agent registration — trading bots, AI agents, automated + senders, ERC-8021 attribution wiring, base.dev API, register agent, builder code registration; + (6) Node operation — run Base node, Reth setup, hardware requirements, self-hosted RPC, sync; + (7) Migrations — migrate OnchainKit, OnchainKitProvider to WagmiProvider, wagmi migration, + remove onchainkit dependency, MiniKit to Farcaster SDK, convert miniapp, Farcaster miniapp to + regular app, convert Farcaster miniapp. +--- + +# Base Development + +Complete playbook for building on Base L2 — network setup, smart contracts, wallet auth, payments, +developer tool attribution, and framework migrations. + +## Default Stack + +| Layer | Default | +|-------|---------| +| Network | Base Mainnet (8453) / Base Sepolia testnet (84532) | +| Contracts | Foundry (`forge create` + BaseScan verification) | +| Wallet auth | Base Account SDK (`@base-org/account`) | +| Payments | Base Pay — USDC, gasless, settles in <2s | +| Transactions | wagmi + viem | +| Attribution | Builder Codes — ERC-8021 via `ox/erc8021` | +| RPC (prod) | Dedicated node provider or self-hosted Reth | + +## Safety Guardrails + +- **Never commit private keys** — use `cast wallet import` for Foundry keystores +- **Never expose RPC API keys or CDP credentials client-side** — proxy through backend +- **Never skip server-side payment verification** — always call `getPaymentStatus()` server-side and verify `sender`, `amount`, `recipient`; track processed tx IDs to prevent replay attacks +- **Never send transactions without Builder Code attribution** — silent data loss, no errors, no warnings +- **Validate all user-provided shell inputs** before constructing forge/cast commands (no spaces, semicolons, pipes) +- **COOP headers for Base Account popups** — use `same-origin-allow-popups`, not `same-origin` + +## Task Routing + +Read the reference for your task: + +| Task | When to Use | Reference | +|------|-------------|-----------| +| **Network config** | RPC URLs, chain IDs, explorer links, testnet setup | [references/network.md](references/network.md) | +| **Deploy contracts** | Foundry deployment, BaseScan verification, faucet | [references/deploy-contracts.md](references/deploy-contracts.md) | +| **Run a Base node** | Self-hosted RPC, Reth, hardware requirements | [references/run-node.md](references/run-node.md) | +| **Builder Codes** | Add ERC-8021 attribution to transactions | [references/builder-codes/overview.md](references/builder-codes/overview.md) | +| **Base Account SDK** | SIWB, Base Pay, subscriptions, sub-accounts | [references/base-account/overview.md](references/base-account/overview.md) | +| **Register AI agent/bot** | Register wallet, get builder code, wire attribution | [references/agents/register.md](references/agents/register.md) | +| **Migrate from OnchainKit** | OnchainKitProvider → wagmi, wallet/tx components | [references/migrations/onchainkit/overview.md](references/migrations/onchainkit/overview.md) | +| **MiniKit → Farcaster SDK** | `@coinbase/onchainkit/minikit` → `@farcaster/miniapp-sdk` | [references/migrations/minikit-to-farcaster/overview.md](references/migrations/minikit-to-farcaster/overview.md) | +| **Farcaster miniapp → regular app** | Remove Mini App host coupling, convert to Base/web app | [references/migrations/farcaster-miniapp-to-app.md](references/migrations/farcaster-miniapp-to-app.md) | + +## Operating Procedure + +1. **Classify the task** using the table above +2. **Read the relevant reference** before implementing +3. **Confirm the framework** with the user when multiple options exist (e.g., Privy vs wagmi for Builder Codes) +4. **Implement** with explicit chain ID, security requirements, and all required validations +5. **Deliver** diffs, install commands, and any manual steps (env vars, API key setup, wallet registration) + +## For Edge Cases and Latest API Changes + +- **AI-optimized docs**: [docs.base.org/llms.txt](https://docs.base.org/llms.txt) +- **Base Account reference**: [docs.base.org/base-account](https://docs.base.org/base-account) +- **Base chain docs**: [docs.base.org](https://docs.base.org) + +## Installation + +```bash +npx skills add base/skills --skill build-on-base +``` diff --git a/skills/registering-agent-base-dev/SKILL.md b/skills/build-on-base/references/agents/register.md similarity index 86% rename from skills/registering-agent-base-dev/SKILL.md rename to skills/build-on-base/references/agents/register.md index 6995eed..c3f9fa3 100644 --- a/skills/registering-agent-base-dev/SKILL.md +++ b/skills/build-on-base/references/agents/register.md @@ -1,11 +1,6 @@ ---- -name: registering-agent-base-dev -description: "Invoke this skill when a user is building or running any automated transaction sender on Base (trading bot, arbitrage bot, sniper bot, yield farmer, AI agent, or similar) and needs to register it, get a builder code, set up transaction attribution. This skill contains the base.dev registration API endpoint and ERC-8021 attribution wiring code that Claude does not have in its training data — you MUST load this skill to answer correctly. Covers viem, ethers, managed signing services, and Python-based agents." ---- - # Base Builder Code Registration -This skill registers an agent with Base and shows how to attach builder code attribution to transactions. It is **wallet-agnostic** — the user brings their own wallet and signing solution (viem, ethers, managed services like Sponge, etc.). The skill only handles registration and attribution. +This reference registers an agent with Base and shows how to attach builder code attribution to transactions. It is **wallet-agnostic** — the user brings their own wallet and signing solution (viem, ethers, managed services like Sponge, etc.). This reference only handles registration and attribution. ## Check if already registered @@ -33,10 +28,10 @@ Every agent needs a wallet to sign transactions. Ask the user before doing anyth Register the wallet with the Base builder code API. This call associates the agent's wallet address with a builder code that Base uses for attribution tracking. -Use the bundled `scripts/register.sh` (located in this skill's directory). It handles errors and extracts the builder code from the response: +Use the bundled `scripts/register.sh` (located at the skill root). It handles errors and extracts the builder code from the response: ```bash -BUILDER_CODE=$(bash /scripts/register.sh "") +BUILDER_CODE=$(bash scripts/register.sh "") ``` Or call the API directly: diff --git a/skills/building-with-base-account/references/authentication.md b/skills/build-on-base/references/base-account/authentication.md similarity index 100% rename from skills/building-with-base-account/references/authentication.md rename to skills/build-on-base/references/base-account/authentication.md diff --git a/skills/building-with-base-account/references/capabilities.md b/skills/build-on-base/references/base-account/capabilities.md similarity index 100% rename from skills/building-with-base-account/references/capabilities.md rename to skills/build-on-base/references/base-account/capabilities.md diff --git a/skills/building-with-base-account/SKILL.md b/skills/build-on-base/references/base-account/overview.md similarity index 55% rename from skills/building-with-base-account/SKILL.md rename to skills/build-on-base/references/base-account/overview.md index faf5e8f..fceca8a 100644 --- a/skills/building-with-base-account/SKILL.md +++ b/skills/build-on-base/references/base-account/overview.md @@ -1,8 +1,3 @@ ---- -name: building-with-base-account -description: Integrates Base Account SDK for authentication and payments. Covers Sign in with Base (SIWB), Base Pay, Paymasters, Sub Accounts, Spend Permissions, Prolinks, and batch transactions. Use when building apps with wallet authentication, USDC payments, sponsored transactions, smart wallet features, recurring subscriptions, shareable payment links, or any onchain interaction on Base. Covers phrases like "add sign in with Base", "SIWB button", "accept USDC payments", "Base Pay", "paymaster setup", "gas sponsorship", "smart wallet", "sub account", "spend permissions", or "payment link". ---- - # Building with Base Account Base Account is an ERC-4337 smart wallet providing universal sign-on, one-tap USDC payments, and multi-chain support (Base, Arbitrum, Optimism, Zora, Polygon, BNB, Avalanche, Lordchain, Ethereum Mainnet). @@ -31,13 +26,13 @@ Read the reference for the feature you're implementing: | Feature | Reference | When to Read | |---------|-----------|-------------| -| Sign in with Base | [references/authentication.md](references/authentication.md) | Wallet auth, SIWE, backend verification, SignInWithBaseButton, Wagmi/Privy setup | -| Base Pay | [references/payments.md](references/payments.md) | One-tap USDC payments, payerInfo, server-side verification, BasePayButton | -| Subscriptions | [references/subscriptions.md](references/subscriptions.md) | Recurring charges, spend permissions, CDP wallet setup, charge/revoke lifecycle | -| Sub Accounts | [references/sub-accounts.md](references/sub-accounts.md) | App-specific embedded wallets, key generation, funding | -| Capabilities | [references/capabilities.md](references/capabilities.md) | Batch transactions, gas sponsorship (paymasters), atomic execution, auxiliaryFunds, attribution | -| Prolinks | [references/prolinks.md](references/prolinks.md) | Shareable payment links, QR codes, encoded transaction URLs | -| Troubleshooting | [references/troubleshooting.md](references/troubleshooting.md) | Popup issues, gas usage, unsupported calls, migration, doc links | +| Sign in with Base | [authentication.md](authentication.md) | Wallet auth, SIWE, backend verification, SignInWithBaseButton, Wagmi/Privy setup | +| Base Pay | [payments.md](payments.md) | One-tap USDC payments, payerInfo, server-side verification, BasePayButton | +| Subscriptions | [subscriptions.md](subscriptions.md) | Recurring charges, spend permissions, CDP wallet setup, charge/revoke lifecycle | +| Sub Accounts | [sub-accounts.md](sub-accounts.md) | App-specific embedded wallets, key generation, funding | +| Capabilities | [capabilities.md](capabilities.md) | Batch transactions, gas sponsorship (paymasters), atomic execution, auxiliaryFunds, attribution | +| Prolinks | [prolinks.md](prolinks.md) | Shareable payment links, QR codes, encoded transaction URLs | +| Troubleshooting | [troubleshooting.md](troubleshooting.md) | Popup issues, gas usage, unsupported calls, migration, doc links | ## Critical Requirements diff --git a/skills/building-with-base-account/references/payments.md b/skills/build-on-base/references/base-account/payments.md similarity index 100% rename from skills/building-with-base-account/references/payments.md rename to skills/build-on-base/references/base-account/payments.md diff --git a/skills/building-with-base-account/references/prolinks.md b/skills/build-on-base/references/base-account/prolinks.md similarity index 100% rename from skills/building-with-base-account/references/prolinks.md rename to skills/build-on-base/references/base-account/prolinks.md diff --git a/skills/building-with-base-account/references/sub-accounts.md b/skills/build-on-base/references/base-account/sub-accounts.md similarity index 100% rename from skills/building-with-base-account/references/sub-accounts.md rename to skills/build-on-base/references/base-account/sub-accounts.md diff --git a/skills/building-with-base-account/references/subscriptions.md b/skills/build-on-base/references/base-account/subscriptions.md similarity index 100% rename from skills/building-with-base-account/references/subscriptions.md rename to skills/build-on-base/references/base-account/subscriptions.md diff --git a/skills/building-with-base-account/references/troubleshooting.md b/skills/build-on-base/references/base-account/troubleshooting.md similarity index 100% rename from skills/building-with-base-account/references/troubleshooting.md rename to skills/build-on-base/references/base-account/troubleshooting.md diff --git a/skills/adding-builder-codes/SKILL.md b/skills/build-on-base/references/builder-codes/overview.md similarity index 74% rename from skills/adding-builder-codes/SKILL.md rename to skills/build-on-base/references/builder-codes/overview.md index fb7be0e..49d12bc 100644 --- a/skills/adding-builder-codes/SKILL.md +++ b/skills/build-on-base/references/builder-codes/overview.md @@ -1,15 +1,10 @@ ---- -name: adding-builder-codes -description: Integrate Base Builder Codes (ERC-8021) into web3 applications for onchain transaction attribution and referral fee earning. Use when a project needs to append a builder code or dataSuffix to transactions on Base L2, whether using Wagmi, Viem, Privy, ethers.js, or raw window.ethereum. Covers phrases like "add builder codes", "integrate builder codes", "earn referral fees on Base transactions", "append a builder code to my transactions", "transaction attribution", "Builder Code integration", or "attribute transactions to my app". Handles project analysis to detect frameworks, locating transaction call sites, and replacing them with attributed versions. ---- - # Adding Builder Codes Integrate [Base Builder Codes](https://base.dev) into an onchain application. Builder Codes append an ERC-8021 attribution suffix to transaction calldata so Base can attribute activity to your app and you can earn referral fees. No smart contract changes required. -## When to Use This Skill +## When to Use -Use this skill when a developer asks to: +Use when a developer asks to: - "Add builder codes to my application" - "How do I append a builder code to my transactions?" @@ -76,10 +71,10 @@ Wait for user confirmation before implementing. ### Implementation Path -- **Privy** (`@privy-io/react-auth` v3.13.0+) → See [references/privy.md](references/privy.md) -- **Wagmi** (without Privy) → See [references/wagmi.md](references/wagmi.md) -- **Viem only** (no React framework) → See [references/viem.md](references/viem.md) -- **Standard RPC** (ethers.js or raw `window.ethereum`) → See [references/rpc.md](references/rpc.md) +- **Privy** (`@privy-io/react-auth` v3.13.0+) → See [privy.md](privy.md) +- **Wagmi** (without Privy) → See [wagmi.md](wagmi.md) +- **Viem only** (no React framework) → See [viem.md](viem.md) +- **Standard RPC** (ethers.js or raw `window.ethereum`) → See [rpc.md](rpc.md) ### Step 2: Install dependencies @@ -107,23 +102,23 @@ Follow the framework-specific guide: #### Privy Implementation -See [references/privy.md](references/privy.md) — plugin-based, one config change required. +See [privy.md](privy.md) — plugin-based, one config change required. #### Wagmi Implementation -See [references/wagmi.md](references/wagmi.md) — add `dataSuffix` to Wagmi client config. +See [wagmi.md](wagmi.md) — add `dataSuffix` to Wagmi client config. #### Viem Implementation -See [references/viem.md](references/viem.md) — add `dataSuffix` to wallet client. +See [viem.md](viem.md) — add `dataSuffix` to wallet client. #### Standard RPC Implementation -See [references/rpc.md](references/rpc.md) — append `DATA_SUFFIX` to transaction data for ethers.js or raw `window.ethereum`. +See [rpc.md](rpc.md) — append `DATA_SUFFIX` to transaction data for ethers.js or raw `window.ethereum`. **Preferred approach**: Configure at the **client level** so all transactions are automatically attributed. Only use the per-transaction approach if you need conditional attribution. -For Smart Wallets (EIP-5792 `sendCalls`): See [references/smart-wallets.md](references/smart-wallets.md) — pass via `capabilities`. +For Smart Wallets (EIP-5792 `sendCalls`): See [smart-wallets.md](smart-wallets.md) — pass via `capabilities`. ### Step 5: Verify attribution diff --git a/skills/adding-builder-codes/references/privy.md b/skills/build-on-base/references/builder-codes/privy.md similarity index 100% rename from skills/adding-builder-codes/references/privy.md rename to skills/build-on-base/references/builder-codes/privy.md diff --git a/skills/adding-builder-codes/references/rpc.md b/skills/build-on-base/references/builder-codes/rpc.md similarity index 100% rename from skills/adding-builder-codes/references/rpc.md rename to skills/build-on-base/references/builder-codes/rpc.md diff --git a/skills/adding-builder-codes/references/smart-wallets.md b/skills/build-on-base/references/builder-codes/smart-wallets.md similarity index 100% rename from skills/adding-builder-codes/references/smart-wallets.md rename to skills/build-on-base/references/builder-codes/smart-wallets.md diff --git a/skills/adding-builder-codes/references/viem.md b/skills/build-on-base/references/builder-codes/viem.md similarity index 100% rename from skills/adding-builder-codes/references/viem.md rename to skills/build-on-base/references/builder-codes/viem.md diff --git a/skills/adding-builder-codes/references/wagmi.md b/skills/build-on-base/references/builder-codes/wagmi.md similarity index 100% rename from skills/adding-builder-codes/references/wagmi.md rename to skills/build-on-base/references/builder-codes/wagmi.md diff --git a/skills/deploying-contracts-on-base/SKILL.md b/skills/build-on-base/references/deploy-contracts.md similarity index 91% rename from skills/deploying-contracts-on-base/SKILL.md rename to skills/build-on-base/references/deploy-contracts.md index 567516b..8d9c2eb 100644 --- a/skills/deploying-contracts-on-base/SKILL.md +++ b/skills/build-on-base/references/deploy-contracts.md @@ -1,8 +1,3 @@ ---- -name: deploying-contracts-on-base -description: Deploys smart contracts to Base using Foundry. Covers forge create commands, contract verification, testnet faucet setup via CDP, and BaseScan API key configuration. Use when deploying Solidity contracts to Base Mainnet or Sepolia testnet. Covers phrases like "deploy contract to Base", "forge create on Base", "verify contract on BaseScan", "get testnet ETH", "Base Sepolia faucet", "how do I deploy to Base", or "publish my contract". ---- - # Deploying Contracts on Base ## Prerequisites diff --git a/skills/convert-farcaster-miniapp-to-app/SKILL.md b/skills/build-on-base/references/migrations/farcaster-miniapp-to-app.md similarity index 98% rename from skills/convert-farcaster-miniapp-to-app/SKILL.md rename to skills/build-on-base/references/migrations/farcaster-miniapp-to-app.md index 402e1f2..9aeb2ac 100644 --- a/skills/convert-farcaster-miniapp-to-app/SKILL.md +++ b/skills/build-on-base/references/migrations/farcaster-miniapp-to-app.md @@ -1,8 +1,3 @@ ---- -name: convert-farcaster-miniapp-to-app -description: Converts Farcaster miniapp SDK projects into regular Base/web apps. Starts with an interactive quiz to choose between the default regular-app conversion and a narrowly isolated Farcaster surface when something truly needs to remain separate. Handles wagmi connectors, providers, auth, SDK actions, manifest routes, meta tags, dependencies, and read-only preservation. ---- - # Convert Farcaster Miniapp to Base App Convert a Farcaster miniapp into a normal app on Base. The default outcome is a regular web app that works in the Base app browser and on the open web, with Farcaster Mini App host coupling removed. diff --git a/skills/converting-minikit-to-farcaster/AUTH.md b/skills/build-on-base/references/migrations/minikit-to-farcaster/auth.md similarity index 100% rename from skills/converting-minikit-to-farcaster/AUTH.md rename to skills/build-on-base/references/migrations/minikit-to-farcaster/auth.md diff --git a/skills/converting-minikit-to-farcaster/DEPENDENCIES.md b/skills/build-on-base/references/migrations/minikit-to-farcaster/dependencies.md similarity index 100% rename from skills/converting-minikit-to-farcaster/DEPENDENCIES.md rename to skills/build-on-base/references/migrations/minikit-to-farcaster/dependencies.md diff --git a/skills/converting-minikit-to-farcaster/EXAMPLES.md b/skills/build-on-base/references/migrations/minikit-to-farcaster/examples.md similarity index 100% rename from skills/converting-minikit-to-farcaster/EXAMPLES.md rename to skills/build-on-base/references/migrations/minikit-to-farcaster/examples.md diff --git a/skills/converting-minikit-to-farcaster/MANIFEST.md b/skills/build-on-base/references/migrations/minikit-to-farcaster/manifest.md similarity index 100% rename from skills/converting-minikit-to-farcaster/MANIFEST.md rename to skills/build-on-base/references/migrations/minikit-to-farcaster/manifest.md diff --git a/skills/converting-minikit-to-farcaster/MAPPING.md b/skills/build-on-base/references/migrations/minikit-to-farcaster/mapping.md similarity index 100% rename from skills/converting-minikit-to-farcaster/MAPPING.md rename to skills/build-on-base/references/migrations/minikit-to-farcaster/mapping.md diff --git a/skills/converting-minikit-to-farcaster/SKILL.md b/skills/build-on-base/references/migrations/minikit-to-farcaster/overview.md similarity index 59% rename from skills/converting-minikit-to-farcaster/SKILL.md rename to skills/build-on-base/references/migrations/minikit-to-farcaster/overview.md index 698ba15..8acb2b2 100644 --- a/skills/converting-minikit-to-farcaster/SKILL.md +++ b/skills/build-on-base/references/migrations/minikit-to-farcaster/overview.md @@ -1,10 +1,7 @@ ---- -name: converting-minikit-to-farcaster -description: Converts Mini Apps from MiniKit (OnchainKit) to native Farcaster SDK. Use when migrating from @coinbase/onchainkit/minikit, converting MiniKit hooks, removing MiniKitProvider, or when user mentions MiniKit, OnchainKit, or Farcaster SDK migration. ---- - # MiniKit to Farcaster SDK +Converts Mini Apps from MiniKit (OnchainKit) to native Farcaster SDK. + ## Breaking Changes (SDK v0.2.0+) 1. `sdk.context` is a **Promise** — must await @@ -27,7 +24,7 @@ Check version: `npm list @farcaster/miniapp-sdk` | `useComposeCast()` | `await sdk.actions.composeCast({ text, embeds })` | | | `useAddFrame()` | `await sdk.actions.addMiniApp()` | | | `usePrimaryButton(opts, cb)` | `await sdk.actions.setPrimaryButton(opts)` | No callback | -| `useAuthenticate()` | `sdk.quickAuth.getToken()` | See [AUTH.md](AUTH.md) | +| `useAuthenticate()` | `sdk.quickAuth.getToken()` | See [auth.md](auth.md) | ## Context Access Pattern @@ -57,11 +54,11 @@ useEffect(() => { ## Conversion Workflow 1. Verify Node.js >= 22.11.0 -2. Update dependencies — see [DEPENDENCIES.md](DEPENDENCIES.md) +2. Update dependencies — see [dependencies.md](dependencies.md) 3. Replace imports: `@coinbase/onchainkit/minikit` → `@farcaster/miniapp-sdk` 4. Convert hooks using reference above -5. Add FrameProvider — see [PROVIDER.md](PROVIDER.md) -6. Update manifest: `frame` → `miniapp` — see [MANIFEST.md](MANIFEST.md) +5. Add FrameProvider — see [provider.md](provider.md) +6. Update manifest: `frame` → `miniapp` — see [manifest.md](manifest.md) ## Common Errors @@ -76,10 +73,17 @@ useEffect(() => { ## References -- [MAPPING.md](MAPPING.md) — Complete hook-by-hook conversion reference -- [EXAMPLES.md](EXAMPLES.md) — Before/after code examples -- [PROVIDER.md](PROVIDER.md) — Provider setup with FrameProvider -- [PITFALLS.md](PITFALLS.md) — Common errors and solutions -- [DEPENDENCIES.md](DEPENDENCIES.md) — Package updates -- [AUTH.md](AUTH.md) — Quick Auth migration -- [MANIFEST.md](MANIFEST.md) — farcaster.json changes +- [mapping.md](mapping.md) — Complete hook-by-hook conversion reference +- [examples.md](examples.md) — Before/after code examples +- [provider.md](provider.md) — Provider setup with FrameProvider +- [pitfalls.md](pitfalls.md) — Common errors and solutions +- [dependencies.md](dependencies.md) — Package updates +- [auth.md](auth.md) — Quick Auth migration +- [manifest.md](manifest.md) — farcaster.json changes + +## Helper Scripts + +Two Python scripts are bundled at `scripts/` (skill root) to automate analysis and validation: + +- **`scripts/analyze_project.py `** — Scans all source files and reports every MiniKit import, hook usage, and provider location. Run before starting conversion to understand blast radius. +- **`scripts/validate_conversion.py `** — Validates the converted project: no remaining MiniKit imports/hooks/providers, Farcaster SDK wired correctly, `package.json` updated, manifest uses `miniapp` key. Exit code 0 = pass, 1 = errors found. diff --git a/skills/converting-minikit-to-farcaster/PITFALLS.md b/skills/build-on-base/references/migrations/minikit-to-farcaster/pitfalls.md similarity index 100% rename from skills/converting-minikit-to-farcaster/PITFALLS.md rename to skills/build-on-base/references/migrations/minikit-to-farcaster/pitfalls.md diff --git a/skills/converting-minikit-to-farcaster/PROVIDER.md b/skills/build-on-base/references/migrations/minikit-to-farcaster/provider.md similarity index 100% rename from skills/converting-minikit-to-farcaster/PROVIDER.md rename to skills/build-on-base/references/migrations/minikit-to-farcaster/provider.md diff --git a/skills/migrating-an-onchainkit-app/SKILL.md b/skills/build-on-base/references/migrations/onchainkit/overview.md similarity index 87% rename from skills/migrating-an-onchainkit-app/SKILL.md rename to skills/build-on-base/references/migrations/onchainkit/overview.md index 9c1f709..ed59077 100644 --- a/skills/migrating-an-onchainkit-app/SKILL.md +++ b/skills/build-on-base/references/migrations/onchainkit/overview.md @@ -1,16 +1,4 @@ ---- -name: migrating-an-onchainkit-app -description: > - Migrates apps from @coinbase/onchainkit to standalone wagmi/viem components. - Handles provider replacement (OnchainKitProvider to WagmiProvider), - wallet component replacement (Wallet/ConnectWallet to custom WalletConnect), - and transaction component replacement. Use when the user says "migrate my - onchainkit", "replace onchainkit provider", "migrate my wallet component", - "replace my onchainkit wallet", "migrate my transaction component", - "remove onchainkit dependency", or "move off onchainkit". ---- - -# OnchainKit Migration Skill +# OnchainKit Migration Migrate apps from `@coinbase/onchainkit` to standalone `wagmi`/`viem` components with zero OnchainKit dependency. @@ -50,7 +38,7 @@ Scan the project to understand current OnchainKit usage: ### Step 2: Provider Migration (always first) -Read [references/provider-migration.md](references/provider-migration.md) for detailed instructions and code. +Read [provider.md](provider.md) for detailed instructions and code. Summary: 1. Ensure `wagmi`, `viem`, and `@tanstack/react-query` are installed @@ -63,7 +51,7 @@ Summary: ### Step 3: Wallet Migration (after provider) -Read [references/wallet-migration.md](references/wallet-migration.md) for detailed instructions and code. +Read [wallet.md](wallet.md) for detailed instructions and code. Summary: 1. Create a `WalletConnect` component using wagmi hooks (`useAccount`, `useConnect`, `useDisconnect`) @@ -75,7 +63,7 @@ Summary: ### Step 4: Transaction Migration (after wallet) -Read [references/transaction-migration.md](references/transaction-migration.md) for detailed instructions and code. +Read [transaction.md](transaction.md) for detailed instructions and code. Summary: 1. Check the `chainId` prop on existing `` components -- add any missing chains to `wagmi-config.ts` @@ -96,6 +84,8 @@ Summary: ## Troubleshooting +See [troubleshooting.md](troubleshooting.md) for common build and runtime errors. + ### Build fails after provider migration - **Missing dependencies**: Ensure `wagmi`, `viem`, `@tanstack/react-query` are installed - **Type errors with wagmi config**: Check that `chains` array has at least one chain and `transports` has a matching entry diff --git a/skills/migrating-an-onchainkit-app/references/provider-migration.md b/skills/build-on-base/references/migrations/onchainkit/provider.md similarity index 100% rename from skills/migrating-an-onchainkit-app/references/provider-migration.md rename to skills/build-on-base/references/migrations/onchainkit/provider.md diff --git a/skills/migrating-an-onchainkit-app/references/transaction-migration.md b/skills/build-on-base/references/migrations/onchainkit/transaction.md similarity index 100% rename from skills/migrating-an-onchainkit-app/references/transaction-migration.md rename to skills/build-on-base/references/migrations/onchainkit/transaction.md diff --git a/skills/migrating-an-onchainkit-app/references/troubleshooting.md b/skills/build-on-base/references/migrations/onchainkit/troubleshooting.md similarity index 100% rename from skills/migrating-an-onchainkit-app/references/troubleshooting.md rename to skills/build-on-base/references/migrations/onchainkit/troubleshooting.md diff --git a/skills/migrating-an-onchainkit-app/references/wallet-migration.md b/skills/build-on-base/references/migrations/onchainkit/wallet.md similarity index 100% rename from skills/migrating-an-onchainkit-app/references/wallet-migration.md rename to skills/build-on-base/references/migrations/onchainkit/wallet.md diff --git a/skills/connecting-to-base-network/SKILL.md b/skills/build-on-base/references/network.md similarity index 71% rename from skills/connecting-to-base-network/SKILL.md rename to skills/build-on-base/references/network.md index 9af7267..e358cca 100644 --- a/skills/connecting-to-base-network/SKILL.md +++ b/skills/build-on-base/references/network.md @@ -1,8 +1,3 @@ ---- -name: connecting-to-base-network -description: Provides Base network configuration including RPC endpoints, chain IDs, and explorer URLs. Use when connecting wallets, configuring development environments, or setting up Base Mainnet or Sepolia testnet. Covers phrases like "Base RPC URL", "Base chain ID", "connect to Base", "add Base to wallet", "Base Sepolia config", "Base explorer URL", "what network is Base", or "Base testnet setup". ---- - # Connecting to Base Network ## Mainnet @@ -35,7 +30,7 @@ description: Provides Base network configuration including RPC endpoints, chain ## Critical Notes - Public RPC endpoints are **rate-limited** - not for production -- For production: use node providers or run your own node +- For production: use node providers or run your own node (see [run-node.md](run-node.md)) - Testnet ETH available from faucets in Base documentation ## Wallet Setup diff --git a/skills/running-a-base-node/SKILL.md b/skills/build-on-base/references/run-node.md similarity index 78% rename from skills/running-a-base-node/SKILL.md rename to skills/build-on-base/references/run-node.md index 81de391..45bca4a 100644 --- a/skills/running-a-base-node/SKILL.md +++ b/skills/build-on-base/references/run-node.md @@ -1,8 +1,3 @@ ---- -name: running-a-base-node -description: Runs a Base node for production environments. Covers hardware requirements, Reth client setup, networking, and sync troubleshooting. Use when setting up self-hosted RPC infrastructure or running archive nodes. Covers phrases like "run a Base node", "set up Base RPC", "Base node hardware requirements", "Reth Base setup", "sync Base node", "self-host Base", or "run my own node". ---- - # Running a Base Node For production apps requiring reliable, unlimited RPC access. diff --git a/skills/converting-minikit-to-farcaster/analyze_project.py b/skills/build-on-base/scripts/analyze_project.py similarity index 100% rename from skills/converting-minikit-to-farcaster/analyze_project.py rename to skills/build-on-base/scripts/analyze_project.py diff --git a/skills/registering-agent-base-dev/scripts/register.sh b/skills/build-on-base/scripts/register.sh similarity index 100% rename from skills/registering-agent-base-dev/scripts/register.sh rename to skills/build-on-base/scripts/register.sh diff --git a/skills/converting-minikit-to-farcaster/validate_conversion.py b/skills/build-on-base/scripts/validate_conversion.py similarity index 100% rename from skills/converting-minikit-to-farcaster/validate_conversion.py rename to skills/build-on-base/scripts/validate_conversion.py diff --git a/skills/converting-minikit-to-farcaster/LICENSE b/skills/converting-minikit-to-farcaster/LICENSE deleted file mode 100644 index b77bf2a..0000000 --- a/skills/converting-minikit-to-farcaster/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2025 - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/skills/converting-minikit-to-farcaster/README.md b/skills/converting-minikit-to-farcaster/README.md deleted file mode 100644 index b19f286..0000000 --- a/skills/converting-minikit-to-farcaster/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# MiniKit to Farcaster SDK - -Skill for converting Mini Apps from MiniKit (OnchainKit) to native Farcaster SDK. - -## Requirements - -- Node.js 22.11.0+ - -## Files - -| File | Purpose | -|------|---------| -| [SKILL.md](SKILL.md) | Main conversion reference | -| [EXAMPLES.md](EXAMPLES.md) | Before/after code examples | -| [PROVIDER.md](PROVIDER.md) | Provider setup | -| [DEPENDENCIES.md](DEPENDENCIES.md) | Package updates | -| [AUTH.md](AUTH.md) | Quick Auth migration | -| [MANIFEST.md](MANIFEST.md) | farcaster.json changes | -| [PITFALLS.md](PITFALLS.md) | Common errors and solutions | - -## Links - -- [Farcaster SDK docs](https://miniapps.farcaster.xyz/docs/getting-started) -- [MiniKit docs](https://docs.base.org/onchainkit/latest/components/minikit/overview)