From 9c43927aaf63917665221ea2abbd47ed7ed11ddf Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 24 Mar 2026 16:06:36 +0000 Subject: [PATCH 1/3] update ia for agents --- docs/agents.md | 46 ++++ .../{quickstart => frameworks}/agentkit.mdx | 44 ++-- docs/ai-agents/frameworks/eliza.mdx | 2 +- docs/ai-agents/frameworks/langchain.mdx | 4 +- docs/ai-agents/frameworks/vercel-ai-sdk.mdx | 4 +- docs/ai-agents/guides/agent-app.mdx | 76 ------ docs/ai-agents/guides/wallet-setup.mdx | 145 ----------- docs/ai-agents/guides/x402-payments.mdx | 235 ------------------ docs/ai-agents/index.mdx | 59 ++--- .../introduction/choosing-a-framework.mdx | 53 ---- .../ai-agents/payments/accepting-payments.mdx | 140 +++++++++++ docs/ai-agents/payments/x402-protocol.mdx | 133 ++++++++++ docs/ai-agents/quickstart/openclaw-claude.mdx | 125 ---------- docs/ai-agents/quickstart/payments.mdx | 127 ++++++++++ docs/ai-agents/quickstart/trading.mdx | 99 ++++++++ docs/ai-agents/reference/contracts.mdx | 4 +- .../agent-registration.mdx} | 83 +++---- docs/ai-agents/setup/wallet-setup.mdx | 103 ++++++++ docs/ai-agents/trading/data-fetching.mdx | 119 +++++++++ .../trade-execution.mdx} | 66 +++-- docs/docs.json | 83 +++++-- 21 files changed, 963 insertions(+), 787 deletions(-) create mode 100644 docs/agents.md rename docs/ai-agents/{quickstart => frameworks}/agentkit.mdx (66%) delete mode 100644 docs/ai-agents/guides/agent-app.mdx delete mode 100644 docs/ai-agents/guides/wallet-setup.mdx delete mode 100644 docs/ai-agents/guides/x402-payments.mdx delete mode 100644 docs/ai-agents/introduction/choosing-a-framework.mdx create mode 100644 docs/ai-agents/payments/accepting-payments.mdx create mode 100644 docs/ai-agents/payments/x402-protocol.mdx delete mode 100644 docs/ai-agents/quickstart/openclaw-claude.mdx create mode 100644 docs/ai-agents/quickstart/payments.mdx create mode 100644 docs/ai-agents/quickstart/trading.mdx rename docs/ai-agents/{guides/register-and-sign-in-your-agent.mdx => setup/agent-registration.mdx} (52%) create mode 100644 docs/ai-agents/setup/wallet-setup.mdx create mode 100644 docs/ai-agents/trading/data-fetching.mdx rename docs/ai-agents/{guides/trading.mdx => trading/trade-execution.mdx} (79%) diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 000000000..766beab7d --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,46 @@ +# Base Docs Index +IMPORTANT: Prefer retrieval-led reasoning. Read relevant docs before generating code. +Base is an Ethereum L2 by Coinbase. Docs for: Base Chain, Smart Wallet, OnchainKit, MiniKit. +[Docs]|root:./docs +|ai-agents:index +|ai-agents/frameworks:agentkit,eliza,langchain,vercel-ai-sdk +|ai-agents/payments:accepting-payments,x402-protocol +|ai-agents/quickstart:payments,trading +|ai-agents/reference:contracts +|ai-agents/setup:agent-registration,wallet-setup +|ai-agents/trading:data-fetching,trade-execution +|base-account/basenames:basename-transfer,basenames-faq,basenames-wagmi-tutorial +|base-account/contribute:contribute-to-base-account-docs,security-and-bug-bounty +|base-account/framework-integrations:cdp,rainbowkit,reown,thirdweb +|base-account/framework-integrations/privy:authentication,setup,spend-permissions,sub-accounts,wallet-actions +|base-account/framework-integrations/wagmi:base-pay,basenames,batch-transactions,other-use-cases,setup,sign-in-with-base,sub-accounts +|base-account/guides:accept-payments,accept-recurring-payments,authenticate-users,migration-guide,sign-and-verify-typed-data,verify-social-accounts +|base-account/guides/tips:inspect-txn-simulation,popup-tips +|base-account/improve-ux:batch-transactions,spend-permissions,sub-accounts +|base-account/improve-ux/sponsor-gas:erc20-paymasters,paymasters +|base-account/more:base-gasless-campaign,telemetry +|base-account/more/troubleshooting/usage-details:gas-usage,popups,simulations,unsupported-calls,wallet-library-support +|base-account/overview:what-is-base-account +|base-account/quickstart:ai-tools-available-for-devs,mobile-integration,web-react,web +|base-account/reference/base-pay:charge,getOrCreateSubscriptionOwnerWallet,getPaymentStatus,getStatus,pay,prepareCharge,prepareRevoke,revoke,subscribe,subscriptions-overview +|base-account/reference/core:createBaseAccount,generateKeyPair,getCryptoKeyAccount,getKeypair,getProvider,sdk-utilities +|base-account/reference/core/capabilities:atomic,auxiliaryFunds,dataSuffix,datacallback,flowControl,gasLimitOverride,overview,paymasterService,signInWithEthereum +|base-account/reference/core/provider-rpc-methods:coinbase_fetchPermission,coinbase_fetchPermissions,eth_accounts,eth_blockNumber,eth_chainId,eth_coinbase,eth_estimateGas,eth_feeHistory,eth_gasPrice,eth_getBalance,eth_getBlockByHash,eth_getBlockByNumber,eth_getBlockTransactionCountByHash,eth_getBlockTransactionCountByNumber,eth_getCode,eth_getLogs,eth_getProof,eth_getStorageAt,eth_getTransactionByBlockHashAndIndex,eth_getTransactionByBlockNumberAndIndex,eth_getTransactionByHash,eth_getTransactionCount,eth_getTransactionReceipt,eth_getUncleCountByBlockHash,eth_getUncleCountByBlockNumber,eth_requestAccounts,eth_sendRawTransaction,eth_sendTransaction,eth_signTypedData_v4,personal_sign,request-overview,sdk-overview,standard-rpc-methods,wallet_addEthereumChain,wallet_addSubAccount,wallet_connect,wallet_getCallsStatus,wallet_getCapabilities,wallet_getSubAccounts,wallet_sendCalls,wallet_switchEthereumChain,wallet_watchAsset,web3_clientVersion +|base-account/reference/onchain-contracts:basenames,smart-wallet,spend-permissions +|base-account/reference/prolink-utilities:createProlinkUrl,decodeProlink,encodeProlink +|base-account/reference/spend-permission-utilities:fetchPermission,fetchPermissions,getPermissionStatus,prepareRevokeCallData,prepareSpendCallData,requestRevoke,requestSpendPermission +|base-account/reference/ui-elements:base-pay-button,brand-guidelines,sign-in-with-base-button +|base-chain/builder-codes:app-developers,builder-codes,wallet-developers +|base-chain/flashblocks:api-reference,app-integration,architecture,faq,overview,run-a-flashblocks-node +|base-chain/network-information:base-contracts,block-building,bridges,configuration-changelog,diffs-ethereum-base,ecosystem-contracts,network-faucets,network-fees,transaction-finality,troubleshooting-transactions +|base-chain/node-operators:node-providers,performance-tuning,run-a-base-node,snapshots,troubleshooting +|base-chain/quickstart:base-solana-bridge,connecting-to-base,deploy-on-base,why-base +|base-chain/reference:json-rpc-api +|base-chain/security:avoid-malicious-flags,bug-bounty,report-vulnerability,security-council +|get-started:base-mentorship-program,base-services-hub,base,block-explorers,build-app,concepts,country-leads-and-ambassadors,data-indexers,deploy-smart-contracts,docs-llms,docs-mcp,get-funded,launch-token,learning-resources,mistakes,prompt-library,resources-for-ai-agents +|mini-apps/growth:rewards +|mini-apps/quality-and-publishing:overview,quality-bar,submission-guidelines +|mini-apps/quickstart:build-checklist,building-for-the-base-app,create-new-miniapp,migrate-existing-apps,migrate-to-standard-web-app,template +|mini-apps/technical-guides:accept-payments,building-chat-agents,neynar-notifications,sharing-and-social-graph,sign-manifest +|onchainkit:migrate-from-onchainkit +|root:cookie-policy,privacy-policy,terms-of-service,tone_of_voice diff --git a/docs/ai-agents/quickstart/agentkit.mdx b/docs/ai-agents/frameworks/agentkit.mdx similarity index 66% rename from docs/ai-agents/quickstart/agentkit.mdx rename to docs/ai-agents/frameworks/agentkit.mdx index a7ef99de1..bbeaaf8fc 100644 --- a/docs/ai-agents/quickstart/agentkit.mdx +++ b/docs/ai-agents/frameworks/agentkit.mdx @@ -1,10 +1,12 @@ --- title: "AgentKit" -description: "Set up AgentKit, configure a CDP wallet, and send your first onchain transaction" -keywords: ["AgentKit quickstart", "CDP AgentKit", "onchain agent Base", "AgentKit install", "AI agent TypeScript Python"] +description: "Coinbase's developer toolkit for building AI agents with full wallet control in TypeScript or Python" +keywords: ["AgentKit", "CDP AgentKit", "onchain agent Base", "AI agent TypeScript Python", "AgentKit install", "Coinbase AgentKit"] --- -AgentKit is Coinbase's developer toolkit for building AI agents that can interact with onchain services. This guide gets you from zero to a running agent that can check balances and send transactions on Base Sepolia. +AgentKit is Coinbase's developer toolkit for building AI agents that interact with onchain services. You write the agent logic, define its tools, and deploy on your own infrastructure — full control over every aspect of the agent's behavior. + +**When to use AgentKit:** You need full control over your agent's logic, tool definitions, and deployment pipeline in TypeScript or Python. For a skills-based harness with less boilerplate, see [OpenClaw](/ai-agents/quickstart/payments). **What you'll need:** - Node 18+ (TypeScript) or Python 3.10+ (Python) @@ -107,7 +109,7 @@ AgentKit creates and manages a wallet through the CDP API. On first run, the sca -Fund your wallet on Base Sepolia using the [Base faucet](https://docs.base.org/tools/network-faucets), then re-run the balance check to confirm receipt. +Fund your wallet on Base Sepolia using the [Base faucet](https://docs.base.org/base-chain/network-information/network-faucets), then re-run the balance check to confirm receipt. ## Send a transaction @@ -139,8 +141,6 @@ Fund your wallet on Base Sepolia using the [Base faucet](https://docs.base.org/t ## Run the agent -Start the interactive chatbot that the scaffold provides: - ```bash Terminal @@ -154,22 +154,30 @@ Start the interactive chatbot that the scaffold provides: -## Next steps +## Available actions - - - Learn about CDP Agentic Wallet options and production configuration. - +AgentKit's action set covers common onchain operations. Key actions include: - - Let your agent pay for API access per-request using stablecoins. - +| Action | Description | +|--------|-------------| +| `get_balance` | Check wallet balance for any token | +| `transfer` | Send tokens to another address | +| `trade` | Swap tokens via the CDP API | +| `deploy_token` | Deploy an ERC-20 token | +| `deploy_nft` | Deploy an ERC-721 collection | +| `get_wallet_details` | Retrieve wallet address and network | +| `request_faucet_funds` | Get testnet tokens | + +For the full action list, see the [AgentKit documentation](https://docs.cdp.coinbase.com/agentkit/docs/welcome). - - Combine AgentKit with LangChain for more complex agent workflows. +## Framework integrations + + + + Combine AgentKit with LangChain for complex agent workflows and tool chaining. - - Register and verify your agent's identity onchain. + + Build streaming AI agents with AgentKit tools and the Vercel AI SDK. diff --git a/docs/ai-agents/frameworks/eliza.mdx b/docs/ai-agents/frameworks/eliza.mdx index 344bff52a..2a073365a 100644 --- a/docs/ai-agents/frameworks/eliza.mdx +++ b/docs/ai-agents/frameworks/eliza.mdx @@ -122,7 +122,7 @@ The scaffold comes with AgentKit's full action set pre-registered: ## Next steps - + Build an agent with AgentKit directly, without Eliza. diff --git a/docs/ai-agents/frameworks/langchain.mdx b/docs/ai-agents/frameworks/langchain.mdx index f1cab6ed9..066c7ec0b 100644 --- a/docs/ai-agents/frameworks/langchain.mdx +++ b/docs/ai-agents/frameworks/langchain.mdx @@ -202,11 +202,11 @@ Replit templates store wallet data in `wallet_data.txt`. This file contains your ## Next steps - + Configure a production-ready CDP wallet for your LangChain agent. - + Add per-request stablecoin payments to your agent. diff --git a/docs/ai-agents/frameworks/vercel-ai-sdk.mdx b/docs/ai-agents/frameworks/vercel-ai-sdk.mdx index f2c7a714c..1e78393c1 100644 --- a/docs/ai-agents/frameworks/vercel-ai-sdk.mdx +++ b/docs/ai-agents/frameworks/vercel-ai-sdk.mdx @@ -119,11 +119,11 @@ See [all supported providers](https://sdk.vercel.ai/docs/foundations/providers-a ## Next steps - + Configure a production-ready CDP wallet for your agent. - + Add per-request stablecoin payments to your agent. diff --git a/docs/ai-agents/guides/agent-app.mdx b/docs/ai-agents/guides/agent-app.mdx deleted file mode 100644 index 4ad7d3bde..000000000 --- a/docs/ai-agents/guides/agent-app.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Optimize your App for Agents" -description: "Build services designed for agents and make your app discoverable through SKILL.md and the ERC-8004 registry" -keywords: ["agent app", "base agent app", "AI agent discovery", "build for AI agents", "SKILL.md", "ERC-8004"] ---- - -import { GithubRepoCard } from "/snippets/GithubRepoCard.mdx"; - -An agent app is a service built with AI agents as the primary user. Instead of rendering a visual UI for humans to click through, an agent app exposes structured endpoints that agents can discover, understand, and call programmatically. - - - - -The Agent App Framework is experimental. APIs and conventions may change as the standard evolves. - - -## How agents discover your app - -Agents find your service through a `SKILL.md` file hosted at a well-known URL path: `/.well-known/SKILL.md`. If you've worked with web development, this pattern may be familiar: - -- Apple uses `/.well-known/apple-app-site-association` for universal links -- SSL certificate authorities use `/.well-known/acme-challenge/` to verify domain ownership -- OAuth uses `/.well-known/openid-configuration` for discovery - -The `/.well-known/` convention is a standard way to host metadata at a predictable location. For agent apps, your `SKILL.md` file lives there so any agent can find it by checking `yourdomain.com/.well-known/SKILL.md`. - -### What goes in a SKILL.md - -Your `SKILL.md` file describes what your app does, what endpoints are available, and how to use them: - -```markdown SKILL.md template -# Your App Name - -## Description -What your app does, in plain language. - -## Endpoints - -### POST /api/action-name -- **Description:** What this endpoint does -- **Inputs:** What parameters it expects -- **Output:** What it returns -- **Payment:** Whether it requires x402 payment and the cost - -## Authentication -How agents should authenticate (e.g., SIWA, API key, x402). -``` - -When an agent reads your `SKILL.md`, it understands what your service offers and how to interact with it — no human in the loop required. - -## Designing for agent users - -Agents aren't humans. They don't browse, guess, or interpret visual cues. When building an agent app, follow these guidelines: - -- **Document side effects**: if an endpoint transfers funds, modifies state, or triggers external actions, say so explicitly in your `SKILL.md` -- **Return structured JSON**: agents parse JSON, not HTML. Every endpoint should return well-structured JSON responses with consistent field names -- **Support x402 for paid access**: if your service costs money, implement the [x402 protocol](/ai-agents/guides/x402-payments) so agents can pay per request without pre-registration -- **Use clear error responses**: return descriptive error messages with appropriate HTTP status codes so agents can handle failures gracefully - -## Making your app discoverable - -Host your `SKILL.md` at `/.well-known/SKILL.md` and register your app in the [ERC-8004 registry](/ai-agents/guides/identity-siwa). The same registry used for agent identity is used for app discovery. Once registered, agents can query the registry, find your service, and read your `SKILL.md` to understand how to interact with it. - - - -## Continue exploring - - - Return to the AI agents overview for a summary of all components. - diff --git a/docs/ai-agents/guides/wallet-setup.mdx b/docs/ai-agents/guides/wallet-setup.mdx deleted file mode 100644 index 7afc754ad..000000000 --- a/docs/ai-agents/guides/wallet-setup.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: "Setup a Wallet for your Agent" -description: "Give your AI agent a dedicated wallet on Base to hold funds, send payments, sign messages, and interact with onchain protocols securely." -keywords: ["AI agent wallet", "crypto agent wallet", "Base wallet", "CDP agentic wallet", "onchain AI agent", "OpenClaw wallet"] ---- - -An onchain wallet gives your agent the ability to hold funds, authorize transactions, and sign messages. Without one, your agent can read data but can't pay for services, receive payments, or prove its identity. - - - -## Why your agent needs a dedicated wallet - -An AI agent *could* generate its own wallet by creating a random private key through prompting, but this is unsafe: - -- The private key appears in the agent's conversation context, where it can be logged, cached, or leaked through middleware -- Any system with access to the agent's prompt history could extract the key -- If the key is compromised, all funds in the wallet are permanently lost - -Dedicated wallet services solve this by managing keys in secure infrastructure that is separated from your agent's runtime. Your agent can request transactions without ever seeing the private key. - -## Wallet setup - - - - - **Claude Code, Codex, and OpenCode users** — the wallet skills below work with any skills-enabled AI coding tool, not just OpenClaw. Run the same `npx skills add` command from within your coding tool to get the same onchain wallet capabilities. - - - OpenClaw supports multiple wallet providers. Choose one: - - - - Coinbase's standalone wallet for AI agents. Authentication is via email OTP — no API keys required. Private keys stay in Coinbase's infrastructure. - - Install the pre-built wallet skills: - - ```bash Terminal - npx skills add coinbase/agentic-wallet-skills - ``` - - Then ask your agent to authenticate and start transacting: - - ```text - Sign in to my wallet with your@email.com - Send 10 USDC to vitalik.eth - Buy $5 of ETH - ``` - - Skills include: `authenticate-wallet`, `fund`, `send-usdc`, `trade`, `pay-for-service`, and more. Operates on Base. - - [CDP Agentic Wallet docs →](https://docs.cdp.coinbase.com/agentic-wallet/welcome) - - - - Every Bankr agent gets a cross-chain wallet on Base, Ethereum, Solana, Polygon, and Unichain. Gas is sponsored on supported chains. - - Install the Bankr skill from your agent chat: - - ```text - install the bankr skill from https://github.com/BankrBot/skills - ``` - - Create a dedicated account at [bankr.bot](https://bankr.bot) and generate an API key at [bankr.bot/api](https://bankr.bot/api). Don't use your personal account — keep your agent's wallet separate. - - [Bankr docs →](https://docs.bankr.bot) - - - - A multi-chain agent wallet with built-in x402 payments, token swaps, and cross-chain bridges (Base, Ethereum, Solana). - - Register your agent to get a wallet immediately: - - ```bash Terminal - curl -X POST https://api.wallet.paysponge.com/api/agents/register \ - -H "Sponge-Version: 0.2.1" \ - -H "Content-Type: application/json" \ - -d '{"name": "my-agent", "agentFirst": true}' - ``` - - Store the returned `apiKey`: - - ```bash Terminal - export SPONGE_API_KEY=sponge_live_... - ``` - - [Sponge Wallet docs →](https://wallet.paysponge.com/skill.md) - - - - - - AgentKit uses Coinbase's CDP Agentic Wallet — API-based wallet management with enterprise-grade key security. - - ```typescript TypeScript - import { AgentKit } from "@coinbase/agentkit"; - - const agentkit = await AgentKit.from({ - cdpApiKeyName: process.env.CDP_API_KEY_NAME!, - cdpApiKeyPrivateKey: process.env.CDP_API_KEY_PRIVATE_KEY!, - networkId: "base-mainnet", - }); - - const wallet = agentkit.wallet; - console.log("Agent wallet address:", wallet.getDefaultAddress()); - ``` - - ```python Python - from coinbase_agentkit import AgentKit, AgentKitConfig - - agentkit = AgentKit(AgentKitConfig( - cdp_api_key_name=os.environ["CDP_API_KEY_NAME"], - cdp_api_key_private_key=os.environ["CDP_API_KEY_PRIVATE_KEY"], - network_id="base-mainnet", - )) - - wallet = agentkit.wallet - print("Agent wallet address:", wallet.default_address) - ``` - - Your agent requests transactions via the CDP API. Coinbase handles signing and broadcasting. Keys are managed in Coinbase's secure enclave — your agent never touches them directly. - - [CDP Agentic Wallet docs →](https://docs.cdp.coinbase.com/agentic-wallet/quickstart) - - - -## What your agent can do with a wallet - -Once your agent has a wallet, it can: - -- **Hold stablecoins**: receive and store USDC or other tokens -- **Send and receive payments**: transfer funds to other wallets, pay for API access, or receive payments for services -- **Sign messages**: cryptographically prove that a message or request came from your agent (used for identity verification) -- **Interact with protocols**: call smart contracts to swap tokens, provide liquidity, or use other onchain services - -## Next step - - - Learn how your agent pays for services and executes onchain actions. - diff --git a/docs/ai-agents/guides/x402-payments.mdx b/docs/ai-agents/guides/x402-payments.mdx deleted file mode 100644 index a7e43d497..000000000 --- a/docs/ai-agents/guides/x402-payments.mdx +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: "Make and Accept Payments (x402)" -description: "Let your agent pay for API access with stablecoins and accept payments from other agents using the x402 protocol" -keywords: ["x402 protocol", "autonomous agent payments", "machine payments protocol", "programmatic payments", "AI agent payments", "agentic payments", "agent stablecoin payments", "x402 Base", "HTTP 402 payment required", "agentic commerce"] ---- - -x402 is a payment protocol built on HTTP status code `402 Payment Required` — a code that has been in the HTTP spec since the 1990s but was never widely adopted. x402 finally puts it to use, enabling agents to pay for API access with stablecoins and receive payments from other agents, with no subscriptions or API keys required. - - - -## Paying with x402 (your agent as client) - -### How x402 works - - - - Your agent sends a standard HTTP request to an API endpoint, just like any other API call. - - - - Instead of returning data, the server responds with a `402` status code and includes payment requirements in the `PAYMENT-REQUIRED` header: how much it costs, which token, and on which network. - - - - Your agent's wallet constructs a signed payment payload and resubmits the request with a `PAYMENT-SIGNATURE` header. No human approval needed. - - - - The server verifies the payment via a facilitator, settles onchain, and returns the requested data. The entire flow takes seconds. - - - -Any agent with a funded wallet can pay for any x402-enabled API — no pre-existing relationship or account required. - -[Learn more about x402 →](https://docs.cdp.coinbase.com/x402/docs/client-server-model) - -### Making x402 requests - - - - - **Claude Code, Codex, and OpenCode users** — the payment skills shown here are compatible with any skills-enabled AI coding tool. Install them with the same `npx skills add` command and your coding tool handles x402 payments automatically. - - - #### CDP Agentic Wallet - - With the CDP Agentic Wallet skills installed, your agent handles x402 payments automatically. First make sure skills are installed: - - ```bash Terminal - npx skills add coinbase/agentic-wallet-skills - ``` - - Then ask your agent to discover and call a paid service: - - ```text - Find APIs for sentiment analysis - Call that weather API and get the forecast for New York - ``` - - The `search-for-service` and `pay-for-service` skills handle discovery, payment, and retries without any additional configuration. - - [CDP Agentic Wallet skills →](https://docs.cdp.coinbase.com/agentic-wallet/skills) - - #### Sponge Wallet - - Sponge Wallet has a built-in x402 proxy that discovers services and handles payment automatically. Follow this three-step flow: - - **Step 1 — Discover a service:** - - ```bash Terminal - curl "https://api.wallet.paysponge.com/api/discover?query=weather+forecast" \ - -H "Authorization: Bearer $SPONGE_API_KEY" \ - -H "Sponge-Version: 0.2.1" - ``` - - **Step 2 — Get service details** (required — do not skip): - - ```bash Terminal - curl "https://api.wallet.paysponge.com/api/discover/{serviceId}" \ - -H "Authorization: Bearer $SPONGE_API_KEY" \ - -H "Sponge-Version: 0.2.1" - ``` - - This returns the `baseUrl`, endpoint paths, parameters, and pricing. - - **Step 3 — Call the service** (payment is automatic): - - ```bash Terminal - curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \ - -H "Authorization: Bearer $SPONGE_API_KEY" \ - -H "Sponge-Version: 0.2.1" \ - -H "Content-Type: application/json" \ - -d '{ - "url": "https://{baseUrl}/{endpointPath}", - "method": "POST", - "body": { "query": "New York" }, - "preferred_chain": "base" - }' - ``` - - Sponge detects the `402`, pays in USDC from your wallet, and returns the API response. - - [Sponge Wallet Skills →](https://wallet.paysponge.com/skill.md) - - - - Install the `x402-axios` package to add automatic payment handling to any Axios client: - - ```bash Terminal - npm install x402-axios axios - ``` - - ```typescript TypeScript - import { withPaymentInterceptor } from "x402-axios"; - import axios from "axios"; - - // walletClient must be a viem-compatible WalletClient - const client = withPaymentInterceptor(axios.create(), walletClient); - - // If the endpoint returns 402, the interceptor pays automatically and retries - const response = await client.get("https://api.example.com/paid-endpoint"); - console.log(response.data); - ``` - - The interceptor handles the full flow: detecting the `402`, parsing payment requirements, signing the payment payload, and retrying the request. - - For wiring a viem `WalletClient` to your AgentKit setup, see the [x402 client docs →](https://docs.cdp.coinbase.com/x402/docs/client-server-model) - - - -## Accepting payments (your agent as server) - -You can also build agent services that charge other agents for access using x402. When a client calls your endpoint without paying, you return `402` with payment requirements. Once the client pays, the CDP facilitator verifies the payment and your server delivers the response. - -### Setting up an x402 endpoint - - - - - **Claude Code, Codex, and OpenCode users** — the skills for monetizing a service work the same way in any skills-enabled AI coding tool. Install them with `npx skills add coinbase/agentic-wallet-skills` and ask your coding tool to set up a paid endpoint. - - - #### CDP Agentic Wallet - - With the CDP Agentic Wallet skills installed, your agent can expose a paid API endpoint using the `monetize-service` skill: - - ```bash Terminal - npx skills add coinbase/agentic-wallet-skills - ``` - - Then ask your agent: - - ```text - Set up a paid endpoint for my market data at $0.01 per request - ``` - - The `monetize-service` skill configures the x402 gating and deploys the endpoint. - - [CDP Agentic Wallet skills →](https://docs.cdp.coinbase.com/agentic-wallet/skills) - - #### Sponge Wallet - - Create a reusable x402 payment link that other agents can pay before accessing your service: - - ```bash Terminal - curl -X POST "https://api.wallet.paysponge.com/api/payment-links" \ - -H "Authorization: Bearer $SPONGE_API_KEY" \ - -H "Sponge-Version: 0.2.1" \ - -H "Content-Type: application/json" \ - -d '{ - "amount": "0.01", - "description": "Access to my market data API" - }' - ``` - - Share the returned payment link URL with clients. Check payment status: - - ```bash Terminal - curl "https://api.wallet.paysponge.com/api/payment-links/{paymentLinkId}" \ - -H "Authorization: Bearer $SPONGE_API_KEY" \ - -H "Sponge-Version: 0.2.1" - ``` - - [Sponge Wallet Skills →](https://wallet.paysponge.com/skill.md) - - - - Use the `x402-express` package to add payment gating to any Express endpoint: - - ```bash Terminal - npm install x402-express express - ``` - - ```typescript TypeScript - import express from "express"; - import { paymentMiddleware } from "x402-express"; - - const app = express(); - - app.use( - paymentMiddleware( - "0xYourAgentWalletAddress", - { - "/api/data": { - price: "$0.01", - network: "base-sepolia", - }, - } - ) - ); - - app.get("/api/data", (req, res) => { - res.json({ data: "premium content" }); - }); - - app.listen(3000); - ``` - - The middleware returns `402` to unpaid callers. The CDP facilitator handles verification and onchain settlement. Supported on Base, Polygon, and Solana. - - [x402 seller quickstart →](https://docs.cdp.coinbase.com/x402/docs/client-server-model) - - - -## Next step - - - Register your agent and verify its identity using Sign In With Agent. - diff --git a/docs/ai-agents/index.mdx b/docs/ai-agents/index.mdx index cd51c14d2..354fe254f 100644 --- a/docs/ai-agents/index.mdx +++ b/docs/ai-agents/index.mdx @@ -1,60 +1,39 @@ --- title: "AI Agents on Base" -description: "Build AI agents that can hold funds, make payments, verify identity, and interact with services on Base" -keywords: ["AI agents Base", "x402 protocol", "onchain agents", "Base L2", "Build with AI", "Base MCP server", "AgentKit", "OpenClaw"] +description: "Build AI agents that trade, earn, and transact autonomously on Base" +keywords: ["AI agents Base", "x402 protocol", "onchain agents", "Base L2", "Build with AI", "OpenClaw", "trading agent", "payment agent"] --- -Base gives your AI agent the tools to operate as an independent economic actor: a wallet to hold and spend funds, identity standards so other agents and services can trust it, a payment protocol for pay-per-request APIs, and a discovery layer so agents can find each other. - -## What you can build - -- **A trading agent** that monitors market conditions and executes token swaps automatically using a funded wallet -- **A payment agent** that pays for premium API data on behalf of your application using the x402 pay-per-request protocol -- **A discoverable service** that other agents can find, verify, and pay to use — no human integration required -- **A multi-channel assistant** that manages a wallet, answers questions, and executes onchain actions across Discord, Telegram, or web +Base gives your AI agent the tools to operate as an independent economic actor: a wallet to hold and spend funds, identity standards so other agents and services can trust it, and payment protocols for services and commerce. ## Choose your path - - An open-source assistant you install and run locally. Add onchain skills through plugins. Best for self-hosted agents with a CLI-first workflow. + + Build an agent that pays for API access with stablecoins and charges other agents for your services. Get running in under 10 minutes. - - Coinbase's developer toolkit for building custom agents in TypeScript or Python. Full control over logic, integrations, and deployment. + + Build an agent that fetches live market data and executes token swaps automatically on Base. -Not sure which to pick? See the [framework comparison guide](/ai-agents/introduction/choosing-a-framework). - - -**Using Claude Code, Codex, or OpenCode?** All skills and wallet tools built for OpenClaw are also compatible with AI coding tools. Install any skill package with `npx skills add` from within your coding tool and the onchain capabilities work the same way — no separate setup required. - - -## How the pieces fit together - -1. **Choose a framework** — pick between OpenClaw (self-hosted, skills-based) or AgentKit (SDK, full control) -2. **Add a wallet** — give your agent the ability to hold stablecoins, send payments, and sign transactions -3. **Use x402 payments** — let your agent pay for services per-request using stablecoins, no subscriptions or API keys -4. **Establish identity** — register your agent in a public directory so other agents and services can discover and verify it -5. **Build or connect to agent apps** — create services designed for agents, or connect your agent to existing ones +## The stack -## Guides - - - - Give your agent a dedicated wallet to hold funds and authorize transactions. - - - - Pay for API access with stablecoins and accept payments from other agents. + + + An open-source AI assistant you install and run locally. Add onchain skills through plugins. Compatible with Claude Code, Codex, and OpenCode. - - Register and verify your agent's identity using Sign In With Agent. + + Dedicated agent wallets with gas sponsorship, cross-chain support, and native x402 payment handling. No raw private key management. - - Build services with agents as the primary user and make them discoverable. + + Pay for API access per-request using USDC — no subscriptions or API keys. Accept payments from other agents with a single skill. + + +Before using either quickstart, complete the [wallet setup](/ai-agents/setup/wallet-setup) and optionally [register your agent](/ai-agents/setup/agent-registration) for discoverability and identity verification. + diff --git a/docs/ai-agents/introduction/choosing-a-framework.mdx b/docs/ai-agents/introduction/choosing-a-framework.mdx deleted file mode 100644 index c6dd951d3..000000000 --- a/docs/ai-agents/introduction/choosing-a-framework.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Choosing a Framework" -description: "Compare OpenClaw and AgentKit to find the right foundation for your AI agent on Base" -keywords: ["AI agent frameworks Base", "OpenClaw vs AgentKit", "onchain AI agent", "build AI agent Base", "AgentKit Base", "OpenClaw Base"] ---- - -Your first decision when building an AI agent on Base is choosing a framework. This determines how you write your agent's logic, where it runs, and how much infrastructure you manage yourself. - -## Comparing your options - -| | OpenClaw | AgentKit | -|---|---|---| -| **What it is** | An open-source AI assistant that runs locally or on a server, extended with skill plugins — skills also work in Claude Code, Codex, and OpenCode | A developer toolkit for building custom agents with full control over behavior and integrations | -| **Language** | TypeScript (plugins); any LLM via config | TypeScript / Python | -| **Hosting** | Self-hosted (local or VPS) | Self-hosted | -| **Skill system** | Plugin-based skills installed via CLI — compatible with Claude Code, Codex, and OpenCode | Tool definitions you write in code | -| **Best for** | Multi-channel assistants with pre-built skills and a CLI-first workflow; also great for adding onchain skills to an AI coding tool | Production agents where you need full control over logic, integrations, and deployment | - -## OpenClaw - -OpenClaw is an open-source AI assistant you install and run locally. It connects to multiple messaging platforms out of the box (Discord, Telegram, web) and comes with a plugin system for adding skills — pre-built actions your agent can perform onchain. You configure it through a `config.json` file and extend it by installing skill packages. - -Use OpenClaw when you want to run a conversational agent across multiple channels and extend it with community-built or custom plugins. - - -**Claude Code, Codex, and OpenCode are compatible** — All skills and wallet tools built for OpenClaw work with AI coding tools too. Install any skill package with `npx skills add` inside Claude Code, Codex, or OpenCode and the onchain capabilities are available immediately. You can use whichever tool fits your workflow. - - -[Get started with OpenClaw →](/ai-agents/quickstart/openclaw) - -## AgentKit - -AgentKit is Coinbase's developer toolkit for building agents that can interact with onchain services. You write the agent logic, define its tools, and deploy it on your own infrastructure. This is the most flexible option: you control every aspect of the agent's behavior, from how it processes prompts to which services it calls. - -Use AgentKit when you're building a production agent and want full control over its architecture in TypeScript or Python. - -[Get started with AgentKit →](/ai-agents/quickstart/agentkit) - - -**How to choose:** Use **OpenClaw** if you want a multi-channel chatbot with a plugin-based skill system and minimal boilerplate. Use **AgentKit** if you need full control over your agent's logic, tool definitions, and deployment pipeline. - - -## Next steps - - - - Install OpenClaw and send your first onchain transaction in minutes. - - - - Set up AgentKit and build your first agent with a CDP wallet. - - diff --git a/docs/ai-agents/payments/accepting-payments.mdx b/docs/ai-agents/payments/accepting-payments.mdx new file mode 100644 index 000000000..1b6a18a25 --- /dev/null +++ b/docs/ai-agents/payments/accepting-payments.mdx @@ -0,0 +1,140 @@ +--- +title: "Accepting Payments" +description: "Gate your agent's endpoints with x402 to charge other agents per request" +keywords: ["x402 server", "accept agent payments", "monetize API agent", "x402-express", "monetize-service skill", "OpenClaw x402 server"] +--- + +You can build agent services that charge other agents for access using x402. When a client calls your endpoint without paying, you return `402` with payment requirements. Once the client pays, the facilitator verifies the payment and your server delivers the response. + +## Option 1 — OpenClaw monetize-service skill (simplest) + +With the CDP Agentic Wallet skills installed, expose a paid endpoint with a single prompt: + +```bash Terminal +npx skills add coinbase/agentic-wallet-skills +``` + +Then ask your agent: + +```text +Set up a paid endpoint for my market data at $0.01 per request +``` + +The `monetize-service` skill configures the x402 gating and deploys the endpoint. No server code required. + +[CDP Agentic Wallet skills →](https://docs.cdp.coinbase.com/agentic-wallet/skills) + +## Option 2 — Sponge Wallet payment links + +Create a reusable x402 payment link that other agents pay before accessing your service: + +```bash Terminal +curl -X POST "https://api.wallet.paysponge.com/api/payment-links" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" \ + -H "Content-Type: application/json" \ + -d '{ + "amount": "0.01", + "description": "Access to my market data API" + }' +``` + +Share the returned payment link URL with clients. Check payment status: + +```bash Terminal +curl "https://api.wallet.paysponge.com/api/payment-links/{paymentLinkId}" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" +``` + +[Sponge Wallet docs →](https://wallet.paysponge.com/skill.md) + +## Option 3 — Custom server with x402-express + +Use the `x402-express` package to add payment gating to any Express endpoint: + +```bash Terminal +npm install x402-express express +``` + +```typescript TypeScript +import express from "express"; +import { paymentMiddleware } from "x402-express"; + +const app = express(); + +app.use( + paymentMiddleware( + "0xYourAgentWalletAddress", + { + "/api/data": { + price: "$0.01", + network: "base-sepolia", + }, + } + ) +); + +app.get("/api/data", (req, res) => { + res.json({ data: "premium content" }); +}); + +app.listen(3000); +``` + +The middleware returns `402` to unpaid callers. The CDP facilitator handles verification and onchain settlement. + +[x402 seller quickstart →](https://docs.cdp.coinbase.com/x402/docs/client-server-model) + +## Configuring facilitators + +A facilitator is the off-chain service that verifies payment payloads and settles payments onchain. Two options: + +| Facilitator | When to use | +|-------------|-------------| +| **CDP facilitator** (default) | Production — requires CDP API key, supports Base and Solana | +| **Public testnet facilitator** | Development — no API key, Base Sepolia only | + +The public testnet facilitator endpoint is `https://www.x402.org/facilitator`. Switch to the CDP facilitator for mainnet. See [contract addresses](/ai-agents/reference/contracts) for full endpoint details. + +## Pricing and payment terms + +- Set prices in USD (e.g., `"$0.01"`) — the middleware converts to the appropriate token amount +- Payments settle in USDC on Base by default +- There is no minimum payment — even fractions of a cent are supported +- Your wallet receives payment directly — no platform fee from the protocol + +## Make your endpoint discoverable + +Host a `SKILL.md` file at `/.well-known/SKILL.md` describing your endpoint's inputs, outputs, pricing, and authentication requirements. Agents discover your service by checking this path. + +```markdown SKILL.md template +# Your Agent Service + +## Description +What your service does, in plain language. + +## Endpoints + +### GET /api/data +- **Description:** Returns premium market data +- **Payment:** $0.01 per request via x402 (Base, USDC) +- **Output:** JSON with current prices and volume + +## Authentication +x402 payment required. No API key needed. +``` + +Register your service in the ERC-8004 registry so agents can discover it by category — see [agent registration](/ai-agents/setup/agent-registration). + +## Related + + + + How x402 works from the client side. + + + + Facilitator endpoints and protocol addresses. + + diff --git a/docs/ai-agents/payments/x402-protocol.mdx b/docs/ai-agents/payments/x402-protocol.mdx new file mode 100644 index 000000000..c5d6169f5 --- /dev/null +++ b/docs/ai-agents/payments/x402-protocol.mdx @@ -0,0 +1,133 @@ +--- +title: "x402 Protocol" +description: "How x402 works, how your agent makes payments, and which networks and tokens are supported" +keywords: ["x402 protocol", "autonomous agent payments", "machine payments protocol", "programmatic payments", "AI agent payments", "agentic payments", "HTTP 402 payment required", "x402 Base"] +--- + +x402 is a payment protocol built on HTTP status code `402 Payment Required` — a code in the HTTP spec since the 1990s, finally put to use. It lets agents pay for API access with stablecoins per-request, with no subscriptions or API keys required. + + + +## Payment flow + + + + Your agent sends a standard HTTP request to an API endpoint, just like any other API call. + + + + Instead of returning data, the server responds with a `402` status code and includes payment requirements in the `PAYMENT-REQUIRED` header: how much it costs, which token, and on which network. + + + + Your agent's wallet constructs a signed payment payload and resubmits the request with a `PAYMENT-SIGNATURE` header. No human approval needed. + + + + The server verifies the payment via a facilitator, settles onchain, and returns the requested data. The entire flow takes seconds. + + + +Any agent with a funded wallet can pay for any x402-enabled API — no pre-existing relationship or account required. + +[Learn more about x402 →](https://docs.cdp.coinbase.com/x402/docs/client-server-model) + +## Making x402 requests + +### CDP Agentic Wallet + +With the CDP Agentic Wallet skills installed, your agent handles x402 payments automatically: + +```bash Terminal +npx skills add coinbase/agentic-wallet-skills +``` + +Then ask your agent to discover and call a paid service: + +```text +Find APIs for sentiment analysis +Call that weather API and get the forecast for New York +``` + +The `search-for-service` and `pay-for-service` skills handle discovery, payment, and retries. + +[CDP Agentic Wallet skills →](https://docs.cdp.coinbase.com/agentic-wallet/skills) + +### Sponge Wallet + +Sponge Wallet has a built-in x402 proxy that discovers services and handles payment automatically: + +**Step 1 — Discover a service:** + +```bash Terminal +curl "https://api.wallet.paysponge.com/api/discover?query=weather+forecast" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" +``` + +**Step 2 — Get service details** (required — do not skip): + +```bash Terminal +curl "https://api.wallet.paysponge.com/api/discover/{serviceId}" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" +``` + +This returns the `baseUrl`, endpoint paths, parameters, and pricing. + +**Step 3 — Call the service** (payment is automatic): + +```bash Terminal +curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" \ + -H "Content-Type: application/json" \ + -d '{ + "url": "https://{baseUrl}/{endpointPath}", + "method": "POST", + "body": { "query": "New York" }, + "preferred_chain": "base" + }' +``` + +Sponge detects the `402`, pays in USDC from your wallet, and returns the API response. + +[Sponge Wallet docs →](https://wallet.paysponge.com/skill.md) + +## Supported networks and tokens + +| Network | Token | Notes | +|---------|-------|-------| +| Base | USDC | Default — lowest fees | +| Base Sepolia | USDC | Testnet | +| Solana | USDC | Via CDP facilitator | +| Polygon | USDC | Via CDP facilitator | + +## Error handling and retries + +| Status | Meaning | What to do | +|--------|---------|------------| +| `402` | Payment required | Parse `PAYMENT-REQUIRED` header and pay | +| `402` with `X-Payment-Error` | Payment rejected | Check wallet balance and token approval | +| `408` | Payment timeout | Retry with same or higher payment | +| `429` | Rate limit | Back off and retry after the indicated delay | + +The CDP Agentic Wallet `pay-for-service` skill and Sponge Wallet's x402 proxy handle retries automatically. If you're building a custom client, parse the `PAYMENT-REQUIRED` header, construct the signed payload, and retry with the `PAYMENT-SIGNATURE` header. + +## Related + + + + Gate your own endpoints and charge other agents per request. + + + + Facilitator endpoints and protocol addresses. + + diff --git a/docs/ai-agents/quickstart/openclaw-claude.mdx b/docs/ai-agents/quickstart/openclaw-claude.mdx deleted file mode 100644 index f88c3232a..000000000 --- a/docs/ai-agents/quickstart/openclaw-claude.mdx +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "OpenClaw & Similar Tools" -description: "Install OpenClaw or use with Claude Code, Codex, or OpenCode — connect a wallet and send your first onchain transaction on Base" -keywords: ["OpenClaw quickstart", "Claude Code onchain", "AI agent local setup", "onchain agent Base", "OpenClaw install", "self-hosted AI agent", "Codex onchain agent", "OpenCode Base agent"] ---- - -OpenClaw is an open-source AI assistant you run locally or on a server. This guide gets you from zero to a running agent that can check balances and send transactions on Base Sepolia. - - -**Also works with Claude Code, Codex, and OpenCode** — The wallet skills and onchain tools in this guide are compatible with any skills-enabled AI coding tool. If you use Claude Code, Codex, or OpenCode, run the same `npx skills add` commands and the capabilities work identically. You don't need OpenClaw to use the skills shown here. - - -**What you'll need:** -- Node 22.16+ (Node 24 recommended) -- A funded Base Sepolia wallet (get testnet ETH from the [Base Sepolia faucet](https://docs.base.org/tools/network-faucets)) - -## Install OpenClaw - - - - **macOS / Linux:** - - ```bash Terminal - curl -fsSL https://openclaw.ai/install.sh | bash - ``` - - **Windows (PowerShell):** - - ```powershell Terminal - iwr -useb https://openclaw.ai/install.ps1 | iex - ``` - - Verify the installation: - - ```bash Terminal - openclaw --version - ``` - - - - The onboarding command configures authentication, your gateway settings, and optional messaging channels: - - ```bash Terminal - openclaw onboard --install-daemon - ``` - - Follow the prompts to connect your preferred LLM provider and set up your wallet plugin. - - - - ```bash Terminal - openclaw gateway status - ``` - - If the gateway isn't running, start it: - - ```bash Terminal - openclaw gateway --port 18789 - ``` - - Open the control dashboard at `http://127.0.0.1:18789/` to verify the gateway is live. - - - -## Configure your wallet - -OpenClaw supports the [CDP Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/welcome) — Coinbase's standalone wallet for AI agents. Install the pre-built wallet skills using Vercel's Skills CLI: - -```bash Terminal -npx skills add coinbase/agentic-wallet-skills -``` - -This same command works in Claude Code, Codex, and OpenCode — install the skills package once and your coding tool gains the same onchain capabilities. - -Then ask your agent to authenticate: - -```text -Sign in to my wallet with your@email.com -``` - -Your agent can now send USDC, trade tokens on Base, and pay for API services. Private keys are managed by Coinbase's infrastructure — your agent uses the `awal` CLI and never handles them directly. - -[CDP Agentic Wallet docs →](https://docs.cdp.coinbase.com/agentic-wallet/welcome) - -## Check your balance - -Ask your agent to check its wallet balance. If you're connected via the dashboard (or using Claude Code, Codex, or OpenCode in your terminal): - -```text -Check my ETH balance on Base Sepolia -``` - -OpenClaw invokes the `check-balance` skill, queries the network, and returns the result in the chat. Claude Code and other coding tools handle this the same way — the skill does the work regardless of which assistant runs it. - -## Send a transaction - -```text -Send 0.001 ETH to 0xRecipientAddress on Base Sepolia -``` - -Your agent constructs the transaction, signs it via the wallet plugin, and broadcasts it. The reply includes the transaction hash. - - -Never share your private key or mnemonic phrase in a message to the agent. Wallet credentials should only live in environment variables or your secure config. - - -## Next steps - - - - Learn about wallet options and configure a production-ready wallet. - - - - Let your agent pay for API access per-request using stablecoins. - - - - Deep dive into config.json fields, env vars, and defaults. - - - - Write and register custom skills for your OpenClaw agent. - - diff --git a/docs/ai-agents/quickstart/payments.mdx b/docs/ai-agents/quickstart/payments.mdx new file mode 100644 index 000000000..b07d5eac5 --- /dev/null +++ b/docs/ai-agents/quickstart/payments.mdx @@ -0,0 +1,127 @@ +--- +title: "Get Started with Payments" +description: "Build an agent that makes and accepts x402 payments on Base in under 10 minutes" +keywords: ["x402 quickstart", "agent payments", "OpenClaw payments", "AI agent pay for API", "accept payments agent"] +--- + +This guide gets you from zero to a working agent that makes a paid x402 API request and exposes its own paid endpoint — all in under 10 minutes. + +**What you'll need:** +- Node 22.16+ (Node 24 recommended) +- A funded wallet — complete [wallet setup](/ai-agents/setup/wallet-setup) first + +## Install OpenClaw + + + + **macOS / Linux:** + + ```bash Terminal + curl -fsSL https://openclaw.ai/install.sh | bash + ``` + + **Windows (PowerShell):** + + ```powershell Terminal + iwr -useb https://openclaw.ai/install.ps1 | iex + ``` + + Verify the installation: + + ```bash Terminal + openclaw --version + ``` + + + + ```bash Terminal + openclaw onboard --install-daemon + ``` + + Follow the prompts to connect your LLM provider and set up your wallet plugin. + + + + ```bash Terminal + openclaw gateway --port 18789 + ``` + + Open `http://127.0.0.1:18789/` to verify the gateway is live. + + + + +**Claude Code, Codex, and OpenCode users** — the wallet skills and x402 payment tools below are compatible with any skills-enabled AI coding tool. Run the same `npx skills add` commands and the capabilities work identically. + + +## Configure a wallet + +Install the CDP Agentic Wallet skills: + +```bash Terminal +npx skills add coinbase/agentic-wallet-skills +``` + +Then authenticate: + +```text +Sign in to my wallet with your@email.com +``` + +Or use a Sponge Wallet with native x402 support — see [wallet setup](/ai-agents/setup/wallet-setup) for all options. + +## Make your first x402 payment + +Ask your agent to discover and call a paid API: + +```text +Find a weather API and get the forecast for New York +``` + +The `search-for-service` and `pay-for-service` skills handle discovery, payment, and retries automatically. Your agent pays in USDC, gets the data, and returns the result — no API keys, no subscriptions. + +To make a direct x402 request with Sponge Wallet: + +```bash Terminal +curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" \ + -H "Content-Type: application/json" \ + -d '{ + "url": "https://api.example.com/paid-endpoint", + "method": "GET", + "preferred_chain": "base" + }' +``` + +## Gate your own endpoint with x402 + +Ask your agent to expose a paid API: + +```text +Set up a paid endpoint for my market data at $0.01 per request +``` + +The `monetize-service` skill (`npx skills add coinbase/agentic-wallet-skills`) configures the x402 gating and deploys the endpoint. Other agents can now discover and pay for your service automatically. + +Or use `x402-express` for a custom server — see [Accepting payments](/ai-agents/payments/accepting-payments). + +## Next steps + + + + Deep dive into how x402 works, supported networks, and error handling. + + + + Set up server-side x402 gating with OpenClaw skills or custom middleware. + + + + Configure Bankr, CDP, or Sponge for your agent. + + + + Register your agent for discoverability and identity verification. + + diff --git a/docs/ai-agents/quickstart/trading.mdx b/docs/ai-agents/quickstart/trading.mdx new file mode 100644 index 000000000..40215ae3e --- /dev/null +++ b/docs/ai-agents/quickstart/trading.mdx @@ -0,0 +1,99 @@ +--- +title: "Get Started with Trading" +description: "Build an agent that fetches live market data and executes token swaps on Base" +keywords: ["trading agent quickstart", "OpenClaw trading", "Base trading agent", "token swap agent", "x402 market data"] +--- + +This guide gets you from zero to a working agent that fetches live price data via x402 and executes a token swap on Base. + +**What you'll need:** +- Node 22.16+ (Node 24 recommended) +- A funded wallet — complete [wallet setup](/ai-agents/setup/wallet-setup) first + +## Install OpenClaw + + + + **macOS / Linux:** + + ```bash Terminal + curl -fsSL https://openclaw.ai/install.sh | bash + ``` + + **Windows (PowerShell):** + + ```powershell Terminal + iwr -useb https://openclaw.ai/install.ps1 | iex + ``` + + Verify: + + ```bash Terminal + openclaw --version + ``` + + + + ```bash Terminal + openclaw onboard --install-daemon + ``` + + + + ```bash Terminal + openclaw gateway --port 18789 + ``` + + + + +**Claude Code, Codex, and OpenCode users** — the wallet and trading skills below are compatible with any skills-enabled AI coding tool. Run the same `npx skills add` commands from within your tool. + + +## Configure a trading wallet + +Bankr provides cross-chain wallet access with gas sponsorship and built-in swap support — ideal for trading agents: + +```text +install the bankr skill from https://github.com/BankrBot/skills +``` + +Create a dedicated account at [bankr.bot](https://bankr.bot) and generate an API key at [bankr.bot/api](https://bankr.bot/api). + +For CDP Agentic Wallet or Sponge Wallet, see [wallet setup](/ai-agents/setup/wallet-setup). + +## Execute a swap + +Ask your agent to execute a trade using wallet-native tools: + +```text +Buy $50 of ETH on Base +``` + +With Bankr or CDP Agentic Wallet, built-in swap tools handle the trade — no external DEX integration needed. The wallet constructs, signs, and broadcasts the transaction. + +For best execution on Base, use the preconf endpoint to simulate before signing: + +```text +Simulate buying $50 of ETH then execute if the price impact is below 1% +``` + +## Next steps + + + + Full catalog of x402 data sources for trading agents. + + + + Flashblocks timing, fee calibration, and failure modes on Base. + + + + Configure Bankr, CDP, or Sponge for your agent. + + + + How x402 works for data fetching and payments. + + diff --git a/docs/ai-agents/reference/contracts.mdx b/docs/ai-agents/reference/contracts.mdx index 0bb44da71..90d05b75d 100644 --- a/docs/ai-agents/reference/contracts.mdx +++ b/docs/ai-agents/reference/contracts.mdx @@ -78,11 +78,11 @@ Multiple third-party facilitators run on Base mainnet with varying network suppo ## Related guides - + Register your agent in the ERC-8004 registry and verify requests with ERC-8128. - + Let your agent pay for API access with stablecoins using the x402 protocol. diff --git a/docs/ai-agents/guides/register-and-sign-in-your-agent.mdx b/docs/ai-agents/setup/agent-registration.mdx similarity index 52% rename from docs/ai-agents/guides/register-and-sign-in-your-agent.mdx rename to docs/ai-agents/setup/agent-registration.mdx index 5596eaa50..684199eb3 100644 --- a/docs/ai-agents/guides/register-and-sign-in-your-agent.mdx +++ b/docs/ai-agents/setup/agent-registration.mdx @@ -1,10 +1,10 @@ --- -title: "Register and Sign In With Agent" -description: "Register your agent's identity onchain and authenticate with services using Sign In With Agent (SIWA)" -keywords: ["SIWA", "Sign In With Agent", "agent identity", "ERC-8004", "ERC-8128", "agent verification", "onchain identity Base"] +title: "Agent Registration & Identity" +description: "Register your agent's identity onchain, get a Basename, and authenticate with services using Sign In With Agent (SIWA)" +keywords: ["ERC-8004", "agent registration", "Basename agent", "agent identity", "SIWA", "Sign In With Agent", "ERC-8128", "onchain identity Base"] --- -When your agent calls a service, how does that service know it's really your agent and not an impersonator? When your agent receives a response, how does it know the response came from a legitimate service? Identity, verification, and authentication solve these problems. +When your agent calls a service, how does that service know it's really your agent? When your agent receives a response, how does it know the response is legitimate? Registration and identity verification solve both problems. -## Why identity matters +## Why register? -In a world where agents interact with each other and with services autonomously, trust is the foundation. Without identity: +- **Discoverability** — other agents and services can find your agent by querying the public registry +- **SIWA authentication** — services use your registration to verify that requests genuinely come from your agent +- **Reputation** — the reputation registry accumulates trust signals that other agents can query before interacting with yours -- A service can't verify that a request came from an authorized agent -- Your agent can't verify that a response came from the real service (not a malicious impersonator) -- Other agents can't discover what your agent does or how to interact with it +## Get a Basename for your agent -Identity standards on Base solve all three problems: they let your agent register itself in a public directory, prove its identity with every request, and discover other agents and services. +A Basename gives your agent a human-readable identity (e.g., `myagent.base.eth`) that resolves to its wallet address. Register at [base.org/names](https://www.base.org/names). -## Registry: a public directory for agents +## Register in the ERC-8004 registry -A registry is a public directory where agents and services publish their identity. Any participant can query the registry to resolve an agent's address to its metadata: what it does, where its endpoints live, and which public key it uses for signing. - -On Base, this is implemented through the **ERC-8004** standard. When your agent registers, its entry is stored onchain — anyone can verify it without relying on a central authority. - -A registry entry typically includes: - -- Your agent's name and description -- The endpoints where it can be reached -- A key pair that ties the agent's identity to its cryptographic credentials - -### Register your agent - -There are two ways to register your agent in the ERC-8004 registry: +The [ERC-8004](https://www.8004.org/) standard is an onchain NFT registry where agents publish their identity: name, description, endpoints, and public key. @@ -49,11 +37,15 @@ There are two ways to register your agent in the ERC-8004 registry: -[Learn more about the ERC-8004 standard →](https://www.8004.org/) +A registry entry includes your agent's name and description, the endpoints where it can be reached, and a key pair that ties the agent's identity to its cryptographic credentials. + +The canonical registry addresses are in [contract addresses](/ai-agents/reference/contracts). + +[Learn more about ERC-8004 →](https://www.8004.org/) -## Verification: proving identity at runtime +## Verify identity at runtime (ERC-8128) -Registration tells the world your agent exists. Verification proves it's really your agent making each request. This is handled by the **ERC-8128** standard. +Registration tells the world your agent exists. The **ERC-8128** standard lets your agent prove it's really yours with every request: @@ -65,31 +57,22 @@ Registration tells the world your agent exists. Verification proves it's really - The service looks up your agent's public key from the registry, then checks the signature. If the signature matches, the service knows the request came from your registered agent and not an impersonator. + The service looks up your agent's public key from the registry, then checks the signature. If it matches, the service knows the request came from your registered agent. -This works in both directions: your agent can also verify that a service's response is authentic by checking the service's signature against the registry. +This works in both directions — your agent can verify a service's responses are authentic by checking the service's signature against the registry. -[Learn more about Agent Verification (ERC-8128) →](https://erc8128.slice.so/concepts/overview) +[ERC-8128 specification →](https://erc8128.slice.so/concepts/overview) ## Sign In With Agent (SIWA) -[SIWA](https://siwa.id) (Sign In With Agent) bundles ERC-8004 registration and ERC-8128 request signing into a single SDK — similar to how "Sign in with Google" bundles OAuth and identity into one integration. Instead of wiring up the two standards separately, you integrate SIWA and get both capabilities out of the box. +[SIWA](https://siwa.id) bundles ERC-8004 registration and ERC-8128 signing into a single SDK — similar to how "Sign in with Google" bundles OAuth into one integration. -**Start with SIWA** for the simplest integration path. Use ERC-8004 and ERC-8128 directly only if you need fine-grained control over how your agent registers and how verification is performed. +**Start with SIWA** for the simplest integration path. Use ERC-8004 and ERC-8128 directly only if you need fine-grained control over registration and verification. -### How SIWA works - -1. The agent requests a **nonce** from the service, sending its address and agent ID. -2. The service returns the nonce along with timestamps. -3. The agent builds a SIWA message and **signs it** with its wallet. -4. The agent sends the message and signature to the service. -5. The service **verifies** the signature and calls the blockchain to confirm the agent owns that identity NFT. -6. If verified, the service returns a **receipt**. The agent uses this for subsequent authenticated requests signed with ERC-8128. - ### Agent-side integration Install the SIWA SDK: @@ -161,7 +144,7 @@ const response = await fetch(signedRequest); ### Server-side verification -Services that want to accept SIWA-authenticated agents implement two endpoints: one to issue nonces and one to verify signatures. +Services that accept SIWA-authenticated agents implement two endpoints: one to issue nonces and one to verify signatures. ```typescript TypeScript import { verifySIWA, createSIWANonce } from "@buildersgarden/siwa"; @@ -182,10 +165,16 @@ if (result.success) { } ``` -SIWA ships drop-in middleware for Express, Next.js, Hono, and Fastify. See the [SIWA documentation](https://siwa.id/docs) for framework-specific examples and advanced features including replay protection, criteria-based agent filtering, and x402 payment integration. +SIWA ships drop-in middleware for Express, Next.js, Hono, and Fastify. See the [SIWA documentation](https://siwa.id/docs) for framework-specific examples, replay protection, and x402 payment integration. -## Next step +## Related - - Build services designed for agents and make your app discoverable. - + + + ERC-8004 registry and x402 facilitator addresses on Base. + + + + Pay for API access with stablecoins using the x402 protocol. + + diff --git a/docs/ai-agents/setup/wallet-setup.mdx b/docs/ai-agents/setup/wallet-setup.mdx new file mode 100644 index 000000000..762afe665 --- /dev/null +++ b/docs/ai-agents/setup/wallet-setup.mdx @@ -0,0 +1,103 @@ +--- +title: "Wallet Setup for Agents" +description: "Give your AI agent a dedicated wallet on Base to hold funds, send payments, sign messages, and interact with onchain protocols securely." +keywords: ["AI agent wallet", "Bankr wallet", "CDP agentic wallet", "Sponge wallet", "onchain AI agent", "agent wallet setup"] +--- + +An onchain wallet gives your agent the ability to hold funds, authorize transactions, and sign messages. Without one, your agent can read data but can't pay for services, receive payments, or prove its identity. + + + +## Why your agent needs a dedicated wallet + +An AI agent *could* generate its own wallet by creating a random private key through prompting, but this is unsafe: + +- The private key appears in the agent's conversation context, where it can be logged, cached, or leaked through middleware +- Any system with access to the agent's prompt history could extract the key +- If the key is compromised, all funds in the wallet are permanently lost + +Dedicated wallet services solve this by managing keys in secure infrastructure separated from your agent's runtime. Your agent requests transactions without ever seeing the private key. + +## Choose a wallet + + + + Every Bankr agent gets a cross-chain wallet on Base, Ethereum, Solana, Polygon, and Unichain. Gas is sponsored on supported chains. Built-in swap tools make Bankr ideal for trading agents. + + Install the Bankr skill from your agent chat: + + ```text + install the bankr skill from https://github.com/BankrBot/skills + ``` + + Create a dedicated account at [bankr.bot](https://bankr.bot) and generate an API key at [bankr.bot/api](https://bankr.bot/api). Don't use your personal Bankr account — keep your agent's wallet separate. + + [Bankr docs →](https://docs.bankr.bot) + + + + Coinbase's standalone wallet for AI agents. Authentication is via email OTP — no API keys required in your agent. Private keys stay in Coinbase's secure infrastructure. Native x402 payment support is built in. + + Install the pre-built wallet skills: + + ```bash Terminal + npx skills add coinbase/agentic-wallet-skills + ``` + + Then ask your agent to authenticate: + + ```text + Sign in to my wallet with your@email.com + ``` + + Skills include: `authenticate-wallet`, `fund`, `send-usdc`, `trade`, `pay-for-service`, `monetize-service`, and more. Operates on Base. + + [CDP Agentic Wallet docs →](https://docs.cdp.coinbase.com/agentic-wallet/welcome) + + + + A multi-chain agent wallet with native x402 payment handling, built-in token swaps, and cross-chain bridges across Base, Ethereum, and Solana. Sponge's x402 proxy handles discovery, payment, and retries automatically. + + Register your agent to get a wallet immediately: + + ```bash Terminal + curl -X POST https://api.wallet.paysponge.com/api/agents/register \ + -H "Sponge-Version: 0.2.1" \ + -H "Content-Type: application/json" \ + -d '{"name": "my-agent", "agentFirst": true}' + ``` + + Store the returned `apiKey`: + + ```bash Terminal + export SPONGE_API_KEY=sponge_live_... + ``` + + [Sponge Wallet docs →](https://wallet.paysponge.com/skill.md) + + + + +**Claude Code, Codex, and OpenCode users** — the wallet skills above work with any skills-enabled AI coding tool. Run the same `npx skills add` command from within your coding tool to get the same onchain capabilities. + + +## What your agent can do with a wallet + +Once your agent has a wallet, it can: + +- **Hold stablecoins**: receive and store USDC or other tokens +- **Send and receive payments**: transfer funds to other wallets, pay for API access, or receive payments for services +- **Sign messages**: cryptographically prove that a message or request came from your agent (used for identity verification) +- **Interact with protocols**: call smart contracts to swap tokens, provide liquidity, or use other onchain services + +## Next step + + + Register your agent for discoverability and identity verification. + diff --git a/docs/ai-agents/trading/data-fetching.mdx b/docs/ai-agents/trading/data-fetching.mdx new file mode 100644 index 000000000..324d65006 --- /dev/null +++ b/docs/ai-agents/trading/data-fetching.mdx @@ -0,0 +1,119 @@ +--- +title: "Fetching Market Data" +description: "Use x402 to access live market data from CoinGecko, Alchemy, and other sources — no API key management required" +keywords: ["x402 market data", "trading agent data", "CoinGecko x402", "Alchemy x402", "pay per call data", "agent data fetching"] +--- + +x402 is well-suited for trading data: your agent pays per call in USDC, with no API key registration, subscription management, or rate-limit tiers to negotiate. The agent gets the data, the provider gets paid — that's the entire relationship. + +## Why x402 for market data + +- **No API key management** — your agent pays on demand; no credentials to rotate or store securely +- **Pay only for what you use** — no monthly subscription for data you might not always need +- **Works across any wallet** — Sponge Wallet's x402 proxy, CDP Agentic Wallet skills, and `x402-axios` all handle payment automatically +- **Composable** — your agent can call multiple data providers in the same session, paying each separately + +## Discovering x402-compatible endpoints + +x402-compatible services publish a discovery document at `/.well-known/x402.json`. You can also browse the Bazaar catalog for a curated list of x402 data providers. + +To discover a service with Sponge Wallet: + +```bash Terminal +curl "https://api.wallet.paysponge.com/api/discover?query=price+feed" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" +``` + +## Curated x402 data sources + +### CoinGecko — price feeds + +CoinGecko provides cryptocurrency price feeds, market cap data, and historical OHLCV via x402-enabled endpoints. + +Fetch the current ETH price: + +```bash Terminal +curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" \ + -H "Content-Type: application/json" \ + -d '{ + "url": "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd", + "method": "GET", + "preferred_chain": "base" + }' +``` + +Or use the CDP Agentic Wallet `pay-for-service` skill: + +```text +Get the current ETH price from CoinGecko +``` + +### Alchemy — onchain data + +Alchemy exposes enhanced APIs for onchain data — token balances, NFT metadata, mempool visibility, and decoded transaction history — via x402-gated endpoints. + +Fetch token balances for a wallet: + +```bash Terminal +curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" \ + -H "Content-Type: application/json" \ + -d '{ + "url": "https://base-mainnet.g.alchemy.com/v2/getTokenBalances", + "method": "POST", + "body": { "address": "0xYourAddress" }, + "preferred_chain": "base" + }' +``` + +### Nansen — wallet analytics + +Nansen provides wallet labeling, smart money flow analysis, and on-chain fund tracking. x402 endpoint availability is expanding — check [nansen.ai](https://nansen.ai) for current endpoint status. + +## Making data calls inside an OpenClaw agent + +Install the Sponge Wallet skill or CDP Agentic Wallet skills, then prompt your agent directly: + +```text +Get the current prices of ETH, BTC, and SOL from a paid data source +``` + +```text +Check the token balances at 0xYourWatchAddress on Base +``` + +The agent handles service discovery, payment, and data extraction. For a custom implementation using `x402-axios`: + +```bash Terminal +npm install x402-axios axios +``` + +```typescript TypeScript +import { withPaymentInterceptor } from "x402-axios"; +import axios from "axios"; + +// walletClient must be a viem-compatible WalletClient +const client = withPaymentInterceptor(axios.create(), walletClient); + +// If the endpoint returns 402, the interceptor pays automatically and retries +const response = await client.get("https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd"); +console.log(response.data); +``` + +The interceptor handles the full 402 → pay → retry flow. For wiring a viem `WalletClient` to your setup, see the [x402 client docs](https://docs.cdp.coinbase.com/x402/docs/client-server-model). + +## Related + + + + Execute swaps using Flashblocks timing and Base fee calibration. + + + + Full x402 flow, supported networks, and error handling. + + diff --git a/docs/ai-agents/guides/trading.mdx b/docs/ai-agents/trading/trade-execution.mdx similarity index 79% rename from docs/ai-agents/guides/trading.mdx rename to docs/ai-agents/trading/trade-execution.mdx index c5b3e1e1c..122fb1e2c 100644 --- a/docs/ai-agents/guides/trading.mdx +++ b/docs/ai-agents/trading/trade-execution.mdx @@ -1,29 +1,58 @@ --- -title: 'Trading Tools for Agents' -description: 'Base-specific patterns, fee calibration, and onchain signals for trading agents.' -keywords: ["Flashblocks trading", "machine payments protocol","trading agent Base", "base_transactionStatus", "onchain trading agent EVM", "L1 L2 fee optimization Base"] +title: "Trade Execution on Base" +description: "Base-specific patterns, fee calibration, and onchain signals for trading agents" +keywords: ["Flashblocks trading", "trading agent Base", "base_transactionStatus", "onchain trading agent EVM", "L1 L2 fee optimization Base", "token swap agent"] --- Base offers two structural advantages for trading agents: **Flashblocks** (200ms preconfirmed block state, 10× faster than the 2-second block) and an exposed L1/L2 fee structure that enables explicit cost-vs-speed tradeoffs. This page covers only what is unique to Base — general EVM execution patterns are in the [Ethereum documentation](https://ethereum.org/developers/docs), and Base's RPC methods are in the [JSON-RPC API Reference](/base-chain/reference/json-rpc-api) and [Flashblocks API Reference](/base-chain/flashblocks/api-reference). ---- +## Executing swaps with wallet-native tools + +Bankr, CDP Agentic Wallet, and Sponge Wallet all include built-in swap capabilities — no external DEX integration needed. + +With Bankr: + +```text +Buy $50 of ETH on Base +Swap 100 USDC for ETH at market price +``` + +With CDP Agentic Wallet skills: + +```text +Buy $50 of ETH +Trade 0.01 ETH for USDC +``` + +With Sponge Wallet: + +```bash Terminal +curl -X POST "https://api.wallet.paysponge.com/api/swap" \ + -H "Authorization: Bearer $SPONGE_API_KEY" \ + -H "Sponge-Version: 0.2.1" \ + -H "Content-Type: application/json" \ + -d '{ + "fromToken": "USDC", + "toToken": "ETH", + "amount": "100", + "chain": "base" + }' +``` ## Execution patterns ### Use the preconf endpoint for all reads and submissions -Always connect to `mainnet-preconf.base.org` (or `sepolia-preconf.base.org` for testnet) rather than the standard endpoint. This is the only way to access Flashblocks `pending` state, preconfirmed transaction streams, and `base_transactionStatus`. See [Flashblocks endpoints](/base-chain/flashblocks/app-integration#rpc-endpoints) for the full endpoint list including production provider options. +Always connect to `mainnet-preconf.base.org` (or `sepolia-preconf.base.org` for testnet) rather than the standard endpoint. This is the only way to access Flashblocks `pending` state, preconfirmed transaction streams, and `base_transactionStatus`. See [Flashblocks endpoints](/base-chain/flashblocks/app-integration#rpc-endpoints) for the full list. ### Simulate against preconfirmed state before signing -Call [`eth_simulateV1`](/base-chain/flashblocks/api-reference#eth_simulatev1) against the preconf endpoint with `"blockStateCalls"` targeting the `pending` block before signing any transaction. This catches reverts against current Flashblocks state rather than the last sealed block — which may be up to 2 seconds stale by the time your transaction lands. +Call [`eth_simulateV1`](/base-chain/flashblocks/api-reference#eth_simulatev1) against the preconf endpoint with `"blockStateCalls"` targeting the `pending` block before signing any transaction. This catches reverts against current Flashblocks state rather than the last sealed block — which may be up to 2 seconds stale. ### Poll `base_transactionStatus` instead of blocking on a receipt After submission, [`base_transactionStatus`](/base-chain/flashblocks/api-reference#base_transactionstatus) returns preconfirmed inclusion status within a single Flashblock interval (~200ms). Blocking on `eth_getTransactionReceipt` waits for a full sealed block (up to 2 seconds). For latency-sensitive strategies, poll `base_transactionStatus` first and only fall back to the receipt for finality confirmation. ---- - ## Fee calibration ### L2 priority fee heuristics @@ -42,8 +71,6 @@ Before signing, estimate the L1 cost via the [GasPriceOracle](/base-chain/networ l1FeeUpperBound / (gasLimit × maxFeePerGas + l1FeeUpperBound) > 0.8 ``` ---- - ## Base-specific failure modes Most transaction errors are standard EVM. These are the Base-specific cases that require different handling: @@ -57,32 +84,25 @@ For the full error taxonomy, see [Troubleshooting Transactions](/base-chain/netw **Nonce for concurrent submissions:** Always fetch with `eth_getTransactionCount(address, "pending")`. For parallel submissions, fetch once and increment locally — fetching fresh per call returns the same value for all concurrent requests. ---- - ## Strategy signals -Base exposes data that most chains don't provide at this resolution. The table maps each Base-specific signal to the class of opportunity it enables. +Base exposes data that most chains don't provide at this resolution: | Signal | How to access | Opportunity category | | ------ | ------------- | -------------------- | -| Preconfirmed pending block state (200ms early) | `eth_getBlockByNumber("pending")` on preconf endpoint | Detect price impact before block seals; act on state changes visible to no one else | +| Preconfirmed pending block state (200ms early) | `eth_getBlockByNumber("pending")` on preconf endpoint | Detect price impact before block seals | | Preconfirmed transaction stream | `eth_subscribe("newFlashblockTransactions")` | First-mover on large trades entering the block | -| Preconfirmed logs | `eth_subscribe("pendingLogs", { address, topics })` | Detect liquidation thresholds, pool price events, oracle updates before finality | -| Fee spike detection | `eth_feeHistory` trend over last 5 blocks | Identify congestion onset; adjust routing or pause/resume based on cost | -| L1 base fee trend | `GasPriceOracle.l1BaseFee()` polled over time | Time submissions to minimize L1 data cost; small trades become viable when L1 fee drops | -| Block gas utilization | `gasUsedRatio` from `eth_feeHistory` | Predict upcoming base fee increases; calibrate urgency | +| Preconfirmed logs | `eth_subscribe("pendingLogs", { address, topics })` | Detect liquidation thresholds, oracle updates before finality | +| Fee spike detection | `eth_feeHistory` trend over last 5 blocks | Identify congestion onset; adjust routing or pause | +| L1 base fee trend | `GasPriceOracle.l1BaseFee()` polled over time | Time submissions to minimize L1 data cost | +| Block gas utilization | `gasUsedRatio` from `eth_feeHistory` | Predict upcoming base fee increases | **The Flashblocks advantage:** Most chains expose a pool of pending transactions with uncertain ordering. On Base, the Flashblocks endpoint gives agents a deterministic, ordered view of the next 200ms of chain state before it finalizes. This is an information edge that does not exist on chains with mempool-only visibility. -**On emerging edges:** Execution speed and fee optimization are table stakes. The more durable edge for LLM-based agents is likely in interpreting *why* chain state is changing — correlating onchain signals (large pending swaps, oracle updates, liquidation proximity) with offchain context faster than any rule-based system can. The signals above are the raw inputs; the synthesis is where the edge lives. - ---- - ## Related - [Flashblocks API Reference](/base-chain/flashblocks/api-reference) — `eth_simulateV1`, `base_transactionStatus`, subscription types - [Flashblocks Integration Guide](/base-chain/flashblocks/app-integration) — endpoints, library setup (Wagmi, Viem, Ethers) - [Block Building](/base-chain/network-information/block-building) — Flashblocks timing, per-transaction gas maximum - [Network Fees](/base-chain/network-information/network-fees) — EIP-1559 parameters, GasPriceOracle methods -- [JSON-RPC API Reference](/base-chain/reference/json-rpc-api) — complete RPC method reference - [Troubleshooting Transactions](/base-chain/network-information/troubleshooting-transactions) — full error taxonomy and retry policies diff --git a/docs/docs.json b/docs/docs.json index 9caddfc2a..7835f9bc9 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -469,27 +469,37 @@ "tab": "AI Agents", "groups": [ { - "group": "Introduction", + "group": "Overview", "pages": [ - "ai-agents/index", - "ai-agents/introduction/choosing-a-framework" + "ai-agents/index" ] }, { "group": "Quickstart", "pages": [ - "ai-agents/quickstart/openclaw-claude", - "ai-agents/quickstart/agentkit" + "ai-agents/quickstart/payments", + "ai-agents/quickstart/trading" ] }, { - "group": "Guides", + "group": "Setup", + "pages": [ + "ai-agents/setup/wallet-setup", + "ai-agents/setup/agent-registration" + ] + }, + { + "group": "Payments", + "pages": [ + "ai-agents/payments/x402-protocol", + "ai-agents/payments/accepting-payments" + ] + }, + { + "group": "Trading", "pages": [ - "ai-agents/guides/wallet-setup", - "ai-agents/guides/x402-payments", - "ai-agents/guides/register-and-sign-in-your-agent", - "ai-agents/guides/agent-app", - "ai-agents/guides/trading" + "ai-agents/trading/data-fetching", + "ai-agents/trading/trade-execution" ] }, { @@ -497,7 +507,8 @@ "pages": [ "ai-agents/frameworks/eliza", "ai-agents/frameworks/langchain", - "ai-agents/frameworks/vercel-ai-sdk" + "ai-agents/frameworks/vercel-ai-sdk", + "ai-agents/frameworks/agentkit" ] }, { @@ -2714,27 +2725,63 @@ }, { "source": "/ai-agents/core-concepts/agent-frameworks", - "destination": "/ai-agents/introduction/choosing-a-framework" + "destination": "/ai-agents" }, { "source": "/ai-agents/core-concepts/wallets", - "destination": "/ai-agents/guides/wallet-setup" + "destination": "/ai-agents/setup/wallet-setup" }, { "source": "/ai-agents/core-concepts/payments-and-transactions", - "destination": "/ai-agents/guides/x402-payments" + "destination": "/ai-agents/payments/x402-protocol" }, { "source": "/ai-agents/core-concepts/identity-verification-auth", - "destination": "/ai-agents/guides/identity-siwa" + "destination": "/ai-agents/setup/agent-registration" }, { "source": "/ai-agents/core-concepts/agent-apps", - "destination": "/ai-agents/guides/agent-app" + "destination": "/ai-agents" }, { "source": "/ai-agents/trading", - "destination": "/ai-agents/guides/trading" + "destination": "/ai-agents/trading/trade-execution" + }, + { + "source": "/ai-agents/introduction/choosing-a-framework", + "destination": "/ai-agents" + }, + { + "source": "/ai-agents/quickstart/openclaw-claude", + "destination": "/ai-agents/quickstart/payments" + }, + { + "source": "/ai-agents/quickstart/agentkit", + "destination": "/ai-agents/frameworks/agentkit" + }, + { + "source": "/ai-agents/guides/agent-app", + "destination": "/ai-agents" + }, + { + "source": "/ai-agents/guides/register-and-sign-in-your-agent", + "destination": "/ai-agents/setup/agent-registration" + }, + { + "source": "/ai-agents/guides/wallet-setup", + "destination": "/ai-agents/setup/wallet-setup" + }, + { + "source": "/ai-agents/guides/x402-payments", + "destination": "/ai-agents/payments/x402-protocol" + }, + { + "source": "/ai-agents/guides/trading", + "destination": "/ai-agents/trading/trade-execution" + }, + { + "source": "/ai-agents/guides/identity-siwa", + "destination": "/ai-agents/setup/agent-registration" } ], "integrations": { From 483818cff593d748251f35c8a104e4c3045edf5a Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 24 Mar 2026 22:09:48 +0000 Subject: [PATCH 2/3] add agent demo component --- docs/ai-agents/index.mdx | 4 + docs/snippets/AgentPaymentDemo.jsx | 200 +++++++++++++++++++++++++++++ 2 files changed, 204 insertions(+) create mode 100644 docs/snippets/AgentPaymentDemo.jsx diff --git a/docs/ai-agents/index.mdx b/docs/ai-agents/index.mdx index 354fe254f..ff9012da5 100644 --- a/docs/ai-agents/index.mdx +++ b/docs/ai-agents/index.mdx @@ -4,8 +4,12 @@ description: "Build AI agents that trade, earn, and transact autonomously on Bas keywords: ["AI agents Base", "x402 protocol", "onchain agents", "Base L2", "Build with AI", "OpenClaw", "trading agent", "payment agent"] --- +import { AgentPaymentDemo } from "/snippets/AgentPaymentDemo.jsx" + Base gives your AI agent the tools to operate as an independent economic actor: a wallet to hold and spend funds, identity standards so other agents and services can trust it, and payment protocols for services and commerce. + + ## Choose your path diff --git a/docs/snippets/AgentPaymentDemo.jsx b/docs/snippets/AgentPaymentDemo.jsx new file mode 100644 index 000000000..11e077623 --- /dev/null +++ b/docs/snippets/AgentPaymentDemo.jsx @@ -0,0 +1,200 @@ +import { useState, useEffect } from "react"; + +export const AgentPaymentDemo = () => { + const MONO = "ui-monospace,'Cascadia Code','Source Code Pro',Menlo,Monaco,Consolas,monospace"; + + const C = { + prompt: "#86efac", + muted: "#52525b", + dim: "#3f3f46", + request: "#60a5fa", + error: "#f87171", + paying: "#fbbf24", + success: "#34d399", + value: "#fde68a", + code: "#d4d4d8", + result: "#c4b5fd", + }; + + const STEPS = [ + { + delay: 200, + left: [{ t: "> Get the ETH price from a paid data source", c: "prompt" }], + right: [], + }, + { + delay: 800, + left: [{ t: " searching for ETH/USD endpoint...", c: "muted" }], + right: [], + }, + { + delay: 700, + left: [{ t: " → GET coingecko.com/api/v3/simple/price", c: "request" }], + right: [ + { t: "── Request 1 ─────────────────────────────", c: "dim" }, + { t: "GET /api/v3/simple/price?ids=ethereum", c: "code" }, + { t: "Host: api.coingecko.com", c: "muted"}, + { t: null }, + ], + }, + { + delay: 800, + left: [{ t: " ← 402 Payment Required", c: "error" }], + right: [ + { t: "── Response 1 ────────────────────────────", c: "dim" }, + { t: "HTTP/1.1 402 Payment Required", c: "error" }, + { t: "Payment-Required: {", c: "muted" }, + { t: ' "maxAmountRequired": "0.001",', c: "value" }, + { t: ' "asset": "USDC",', c: "value" }, + { t: ' "network": "base",', c: "value" }, + { t: ' "payTo": "0x742d...c4f2"', c: "value" }, + { t: "}", c: "muted" }, + { t: null }, + ], + }, + { + delay: 1000, + left: [{ t: " paying 0.001 USDC · Sponge Wallet...", c: "paying" }], + right: [], + }, + { + delay: 800, + left: [{ t: " ✓ tx 0xb4f2...91ca confirmed", c: "success" }], + right: [], + }, + { + delay: 600, + left: [{ t: " → retrying with payment signature", c: "request" }], + right: [ + { t: "── Request 2 ─────────────────────────────", c: "dim" }, + { t: "GET /api/v3/simple/price?ids=ethereum", c: "code" }, + { t: "Host: api.coingecko.com", c: "muted" }, + { t: "Payment-Signature: 0x1a9f...c4e2", c: "success" }, + { t: null }, + ], + }, + { + delay: 700, + left: [{ t: " ← 200 OK", c: "success" }], + right: [ + { t: "── Response 2 ────────────────────────────", c: "dim" }, + { t: "HTTP/1.1 200 OK", c: "success" }, + { t: '{"ethereum":{"usd":2847.32}}', c: "code" }, + ], + }, + { + delay: 500, + left: [ + { t: null }, + { t: " ETH $2,847.32 ↑ 2.3% (24h)", c: "result", bold: true }, + ], + right: [], + }, + ]; + + const [step, setStep] = useState(0); + const [running, setRunning] = useState(false); + const [blink, setBlink] = useState(true); + + useEffect(() => { + const t = setTimeout(() => setRunning(true), 600); + return () => clearTimeout(t); + }, []); + + useEffect(() => { + if (!running || step >= STEPS.length) { + if (step >= STEPS.length) setRunning(false); + return; + } + const t = setTimeout(() => setStep(s => s + 1), STEPS[step].delay); + return () => clearTimeout(t); + }, [running, step]); + + useEffect(() => { + const t = setInterval(() => setBlink(b => !b), 530); + return () => clearInterval(t); + }, []); + + const leftLines = STEPS.slice(0, step).flatMap(s => s.left); + const rightLines = STEPS.slice(0, step).flatMap(s => s.right); + const done = step >= STEPS.length; + + const restart = () => { + setStep(0); + setTimeout(() => setRunning(true), 50); + }; + + const renderLine = (item, i) => { + if (!item.t) return
; + return ( +
+ {item.t} +
+ ); + }; + + const paneLabel = (text) => ( +
+ {text} +
+ ); + + return ( +
+ +
+
+
+
+ + x402 payment flow + +
+ +
+
+ {paneLabel("Agent")} + {leftLines.map(renderLine)} + {running && !done && ( +
+ ▋ +
+ )} +
+ +
+ {paneLabel("HTTP Trace")} + {rightLines.map(renderLine)} +
+
+ + {done && ( +
+ +
+ )} +
+ ); +}; From 129106195732f372b9f402a996f553843b0d319f Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 24 Mar 2026 23:18:16 +0000 Subject: [PATCH 3/3] update ai agents section --- docs/ai-agents/frameworks/agentkit.mdx | 183 --------------- docs/ai-agents/frameworks/eliza.mdx | 132 ----------- docs/ai-agents/frameworks/langchain.mdx | 212 ------------------ docs/ai-agents/frameworks/vercel-ai-sdk.mdx | 129 ----------- docs/ai-agents/reference/contracts.mdx | 88 -------- .../building-with-base-account.mdx | 40 ++++ .../base-chain/adding-builder-codes.mdx | 41 ++++ .../base-chain/connecting-to-base-network.mdx | 34 +++ .../skills/base-chain/deploying-contracts.mdx | 32 +++ .../skills/base-chain/running-a-base-node.mdx | 33 +++ docs/ai-agents/skills/index.mdx | 51 +++++ .../convert-farcaster-miniapp-to-app.mdx | 30 +++ .../converting-minikit-to-farcaster.mdx | 31 +++ .../migrating-an-onchainkit-app.mdx | 36 +++ docs/docs.json | 56 ++++- 15 files changed, 373 insertions(+), 755 deletions(-) delete mode 100644 docs/ai-agents/frameworks/agentkit.mdx delete mode 100644 docs/ai-agents/frameworks/eliza.mdx delete mode 100644 docs/ai-agents/frameworks/langchain.mdx delete mode 100644 docs/ai-agents/frameworks/vercel-ai-sdk.mdx delete mode 100644 docs/ai-agents/reference/contracts.mdx create mode 100644 docs/ai-agents/skills/base-account/building-with-base-account.mdx create mode 100644 docs/ai-agents/skills/base-chain/adding-builder-codes.mdx create mode 100644 docs/ai-agents/skills/base-chain/connecting-to-base-network.mdx create mode 100644 docs/ai-agents/skills/base-chain/deploying-contracts.mdx create mode 100644 docs/ai-agents/skills/base-chain/running-a-base-node.mdx create mode 100644 docs/ai-agents/skills/index.mdx create mode 100644 docs/ai-agents/skills/migrations/convert-farcaster-miniapp-to-app.mdx create mode 100644 docs/ai-agents/skills/migrations/converting-minikit-to-farcaster.mdx create mode 100644 docs/ai-agents/skills/migrations/migrating-an-onchainkit-app.mdx diff --git a/docs/ai-agents/frameworks/agentkit.mdx b/docs/ai-agents/frameworks/agentkit.mdx deleted file mode 100644 index bbeaaf8fc..000000000 --- a/docs/ai-agents/frameworks/agentkit.mdx +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: "AgentKit" -description: "Coinbase's developer toolkit for building AI agents with full wallet control in TypeScript or Python" -keywords: ["AgentKit", "CDP AgentKit", "onchain agent Base", "AI agent TypeScript Python", "AgentKit install", "Coinbase AgentKit"] ---- - -AgentKit is Coinbase's developer toolkit for building AI agents that interact with onchain services. You write the agent logic, define its tools, and deploy on your own infrastructure — full control over every aspect of the agent's behavior. - -**When to use AgentKit:** You need full control over your agent's logic, tool definitions, and deployment pipeline in TypeScript or Python. For a skills-based harness with less boilerplate, see [OpenClaw](/ai-agents/quickstart/payments). - -**What you'll need:** -- Node 18+ (TypeScript) or Python 3.10+ (Python) -- A [CDP API key](https://portal.cdp.coinbase.com) (free to create) -- An LLM API key (OpenAI or compatible) - -## Install AgentKit - - - - ```bash Terminal - npm create onchain-agent@latest - cd my-agent - cp .env-local .env - ``` - - Install dependencies: - - ```bash Terminal - npm install - ``` - - - ```bash Terminal - pipx run create-onchain-agent - cd my-agent - cp .env-local .env - ``` - - Install dependencies: - - ```bash Terminal - pip install -r requirements.txt - ``` - - - -## Configure your API keys - -Open `.env` and fill in your credentials: - -```bash .env -CDP_API_KEY_NAME=your_cdp_key_name -CDP_API_KEY_PRIVATE_KEY=your_cdp_private_key -OPENAI_API_KEY=your_openai_key -NETWORK_ID=base-sepolia -``` - -Get your CDP API key from the [CDP Portal](https://portal.cdp.coinbase.com). The key grants access to Coinbase's wallet infrastructure — your agent never touches private keys directly. - -## Create a wallet - -AgentKit creates and manages a wallet through the CDP API. On first run, the scaffolded project automatically creates a wallet and saves it locally: - - - - ```typescript index.ts - import { AgentKit } from "@coinbase/agentkit"; - - const agentkit = await AgentKit.from({ - cdpApiKeyName: process.env.CDP_API_KEY_NAME!, - cdpApiKeyPrivateKey: process.env.CDP_API_KEY_PRIVATE_KEY!, - networkId: "base-sepolia", - }); - - const wallet = agentkit.wallet; - console.log("Wallet address:", wallet.getDefaultAddress()); - ``` - - - ```python main.py - from coinbase_agentkit import AgentKit, AgentKitConfig - - agentkit = AgentKit(AgentKitConfig( - cdp_api_key_name=os.environ["CDP_API_KEY_NAME"], - cdp_api_key_private_key=os.environ["CDP_API_KEY_PRIVATE_KEY"], - network_id="base-sepolia", - )) - - wallet = agentkit.wallet - print("Wallet address:", wallet.default_address) - ``` - - - -## Check your balance - - - - ```typescript - const balances = await wallet.listBalances(); - console.log("Balances:", balances); - ``` - - - ```python - balances = wallet.list_balances() - print("Balances:", balances) - ``` - - - -Fund your wallet on Base Sepolia using the [Base faucet](https://docs.base.org/base-chain/network-information/network-faucets), then re-run the balance check to confirm receipt. - -## Send a transaction - - - - ```typescript - const transfer = await wallet.createTransfer({ - amount: 0.001, - assetId: "eth", - destination: "0xRecipientAddress", - }); - - await transfer.wait(); - console.log("Transaction hash:", transfer.getTransactionHash()); - ``` - - - ```python - transfer = wallet.transfer( - amount=0.001, - asset_id="eth", - destination="0xRecipientAddress", - ) - transfer.wait() - print("Transaction hash:", transfer.transaction_hash) - ``` - - - -## Run the agent - - - - ```bash Terminal - npm run start - ``` - - - ```bash Terminal - python main.py - ``` - - - -## Available actions - -AgentKit's action set covers common onchain operations. Key actions include: - -| Action | Description | -|--------|-------------| -| `get_balance` | Check wallet balance for any token | -| `transfer` | Send tokens to another address | -| `trade` | Swap tokens via the CDP API | -| `deploy_token` | Deploy an ERC-20 token | -| `deploy_nft` | Deploy an ERC-721 collection | -| `get_wallet_details` | Retrieve wallet address and network | -| `request_faucet_funds` | Get testnet tokens | - -For the full action list, see the [AgentKit documentation](https://docs.cdp.coinbase.com/agentkit/docs/welcome). - -## Framework integrations - - - - Combine AgentKit with LangChain for complex agent workflows and tool chaining. - - - - Build streaming AI agents with AgentKit tools and the Vercel AI SDK. - - diff --git a/docs/ai-agents/frameworks/eliza.mdx b/docs/ai-agents/frameworks/eliza.mdx deleted file mode 100644 index 2a073365a..000000000 --- a/docs/ai-agents/frameworks/eliza.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: "Eliza" -description: "Build onchain agents with the Eliza framework and AgentKit on Base" -keywords: ["Eliza framework", "AgentKit Eliza", "Eliza AI agent Base", "onchain Eliza agent", "create-agentkit-app"] ---- - -Eliza is an open-source multi-agent framework with built-in support for AgentKit. The `create-agentkit-app` scaffold sets up an Eliza agent pre-wired with a CDP wallet, ready to run on Base. - - -When creating your CDP API key in the portal, select **ECDSA** as the signature algorithm. The Eliza framework requires ECDSA keys — Ed25519 is not currently supported. - - -## Prerequisites - -- Node 18+ -- A [CDP API key](https://portal.cdp.coinbase.com) -- An LLM API key (OpenAI or compatible) - -## Quickstart - - - - ```bash Terminal - npx create-agentkit-app my-agent - cd my-agent - ``` - - This creates an Eliza agent with AgentKit pre-installed and configured for Base. - - - - ```bash Terminal - cp .env.example .env - ``` - - Open `.env` and fill in your credentials: - - ```bash .env - CDP_API_KEY_NAME=your_cdp_key_name - CDP_API_KEY_PRIVATE_KEY=your_cdp_private_key - OPENAI_API_KEY=your_openai_key - NETWORK_ID=base-sepolia - ``` - - - - ```bash Terminal - pnpm install - ``` - - - - ```bash Terminal - pnpm start - ``` - - The agent starts in interactive mode. You can ask it to check balances, send transactions, and perform other onchain actions. - - - -For a full video walkthrough, see the [Eliza + AgentKit tutorial](https://www.youtube.com/live/DlRR1focAiw). - -## Project structure - -The scaffolded project follows Eliza's character-based structure: - - - - - - - - - - - - - - -### Customizing your agent - -Edit `characters/agent.json` to change the agent's personality: - -```json characters/agent.json -{ - "name": "MyAgent", - "bio": ["I am an onchain agent that can help with Base transactions."], - "lore": [], - "topics": ["crypto", "defi", "base"], - "style": { - "all": ["concise", "helpful"], - "chat": ["friendly"] - }, - "adjectives": ["efficient", "trustworthy"] -} -``` - -## Connecting to Base mainnet - -By default the scaffold targets Base Sepolia. Switch to mainnet: - -```bash .env -NETWORK_ID=base-mainnet -``` - -Fund your agent's wallet address (printed at startup) with ETH and USDC before using mainnet. - -## Available actions - -The scaffold comes with AgentKit's full action set pre-registered: - -| Action | Description | -|--------|-------------| -| `get_wallet_details` | Show the agent's wallet address and network | -| `get_balance` | Check ETH or token balance | -| `native_transfer` | Send ETH to an address | -| `erc20_transfer` | Send an ERC-20 token | -| `trade` | Swap tokens via an onchain DEX | -| `deploy_token` | Deploy a new ERC-20 contract | -| `wrap_eth` | Wrap ETH to WETH | - -## Next steps - - - - Build an agent with AgentKit directly, without Eliza. - - - - Use LangChain instead of Eliza for more complex agent workflows. - - diff --git a/docs/ai-agents/frameworks/langchain.mdx b/docs/ai-agents/frameworks/langchain.mdx deleted file mode 100644 index 066c7ec0b..000000000 --- a/docs/ai-agents/frameworks/langchain.mdx +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: "LangChain" -description: "Combine LangChain with AgentKit to build complex AI agent workflows on Base" -keywords: ["LangChain AgentKit", "LangChain Base", "LangChain onchain agent", "CDP LangChain", "AI agent LangChain TypeScript Python"] ---- - -AgentKit integrates with LangChain, giving your LangChain agent a set of onchain tools it can call to interact with Base. This page covers the setup for both TypeScript and Python. - -## Prerequisites - -- Node 18+ (TypeScript) or Python 3.10+ (Python) -- A [CDP API key](https://portal.cdp.coinbase.com) -- An OpenAI API key (or any LangChain-compatible LLM) - -## Quickstart - - - - - - ```bash Terminal - npm install @coinbase/agentkit-langchain @coinbase/agentkit @langchain/langgraph @langchain/openai - ``` - - - - ```bash Terminal - git clone https://github.com/coinbase/agentkit.git - cd agentkit/typescript - npm install && npm run build - cd examples/langchain-cdp-chatbot - ``` - - - - ```bash Terminal - cp .env.local .env - ``` - - ```bash .env - CDP_API_KEY_NAME=your_cdp_key_name - CDP_API_KEY_PRIVATE_KEY=your_cdp_private_key - OPENAI_API_KEY=your_openai_key - NETWORK_ID=base-sepolia - ``` - - - - ```bash Terminal - npm run start - ``` - - - - - - - - ```bash Terminal - pip install coinbase-agentkit coinbase-agentkit-langchain langchain-openai langgraph - ``` - - - - ```bash Terminal - git clone https://github.com/coinbase/agentkit.git - cd agentkit/python/examples/langchain-cdp-chatbot - ``` - - - - ```bash Terminal - cp .env.local .env - # Edit .env with your credentials - ``` - - - - ```bash Terminal - poetry install - poetry run python chatbot.py - ``` - - - - - -## How it works - -AgentKit provides a set of LangChain-compatible tools. You pass them to a LangChain agent executor, which decides which tools to call based on the user's prompt. - - - - ```typescript chatbot.ts lines - import { AgentKit } from "@coinbase/agentkit"; - import { getLangChainTools } from "@coinbase/agentkit-langchain"; - import { ChatOpenAI } from "@langchain/openai"; - import { createReactAgent } from "@langchain/langgraph/prebuilt"; - - // Initialize AgentKit — reads CDP_API_KEY_NAME and CDP_API_KEY_PRIVATE_KEY from env - const agentKit = await AgentKit.from({ - cdpApiKeyName: process.env.CDP_API_KEY_NAME, - cdpApiKeyPrivateKey: process.env.CDP_API_KEY_PRIVATE_KEY, - }); - - // Get AgentKit tools as LangChain tools - const tools = await getLangChainTools(agentKit); - - // Create a LangChain agent - const llm = new ChatOpenAI({ model: "gpt-4o-mini" }); - const agent = createReactAgent({ llm, tools }); - - // Run the agent - const result = await agent.invoke({ - messages: [{ role: "user", content: "What is my wallet address?" }], - }); - - console.log(result.messages.at(-1)?.content); - ``` - - - - ```python chatbot.py lines - from coinbase_agentkit import AgentKit - from coinbase_agentkit_langchain import get_langchain_tools - from langchain_openai import ChatOpenAI - from langgraph.prebuilt import create_react_agent - - # Initialize AgentKit — reads CDP_API_KEY_NAME and CDP_API_KEY_PRIVATE_KEY from env - agent_kit = AgentKit() - - # Get AgentKit tools as LangChain tools - tools = get_langchain_tools(agent_kit) - - # Create a LangChain agent - llm = ChatOpenAI(model="gpt-4o-mini") - agent = create_react_agent(llm, tools) - - # Run the agent - result = agent.invoke({ - "messages": [{"role": "user", "content": "What is my wallet address?"}] - }) - - print(result["messages"][-1].content) - ``` - - - -## Adding custom tools - -Combine AgentKit tools with your own LangChain tools: - - - - ```typescript - import { tool } from "@langchain/core/tools"; - import { z } from "zod"; - - const myTool = tool( - async ({ query }) => { - return `Result for: ${query}`; - }, - { - name: "my_custom_tool", - description: "Does something custom", - schema: z.object({ query: z.string() }), - } - ); - - const allTools = [...(await getLangChainTools(agentKit)), myTool]; - const agent = createReactAgent({ llm, tools: allTools }); - ``` - - - - ```python - from langchain_core.tools import tool - - @tool - def my_custom_tool(query: str) -> str: - """Does something custom.""" - return f"Result for: {query}" - - all_tools = get_langchain_tools(agent_kit) + [my_custom_tool] - agent = create_react_agent(llm, all_tools) - ``` - - - -## Run on Replit - -Fork a pre-configured template to start without local setup: - -- [TypeScript (EVM) on Replit](https://replit.com/t/coinbase-developer-platform/repls/AgentKitjs-Quickstart-020-EVM-CDP-Wallet/view) -- [Python (EVM) on Replit](https://replit.com/t/coinbase-developer-platform/repls/AgentKitpy-012-EVM/view) -- [TypeScript (Solana) on Replit](https://replit.com/t/coinbase-developer-platform/repls/AgentKitjs-Solana-Quickstart-v020/view) - - -Replit templates store wallet data in `wallet_data.txt`. This file contains your wallet's private key and should not be used in production. See [CDP docs on securing wallets](https://docs.cdp.coinbase.com/server-wallets/v2/introduction/welcome). - - -## Next steps - - - - Configure a production-ready CDP wallet for your LangChain agent. - - - - Add per-request stablecoin payments to your agent. - - diff --git a/docs/ai-agents/frameworks/vercel-ai-sdk.mdx b/docs/ai-agents/frameworks/vercel-ai-sdk.mdx deleted file mode 100644 index 1e78393c1..000000000 --- a/docs/ai-agents/frameworks/vercel-ai-sdk.mdx +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "Vercel AI SDK" -description: "Build web-based AI agents with AgentKit and the Vercel AI SDK on Base" -keywords: ["Vercel AI SDK AgentKit", "AI SDK Base", "Vercel AI onchain agent", "streaming AI agent", "getVercelAITools", "CDP Vercel AI"] ---- - -The Vercel AI SDK is a TypeScript library for building AI-powered applications with React and JavaScript. When combined with AgentKit, your agents can interact with Base onchain while streaming responses to a chat UI — all deployable on Vercel. - -## Prerequisites - -- Node 18+ -- A [CDP API key](https://portal.cdp.coinbase.com) -- An OpenAI API key (or any [Vercel AI SDK-compatible provider](https://sdk.vercel.ai/docs/foundations/providers-and-models#ai-sdk-providers)) - -## Quickstart - - - - ```bash Terminal - npm install @coinbase/agentkit-vercel-ai-sdk @coinbase/agentkit ai @ai-sdk/openai - ``` - - - - ```bash Terminal - git clone https://github.com/coinbase/agentkit.git - cd agentkit/typescript - npm install && npm run build - cd examples/vercel-ai-sdk-cdp-chatbot - ``` - - - - ```bash Terminal - cp .env-local .env - ``` - - ```bash .env - CDP_API_KEY_NAME=your_cdp_key_name - CDP_API_KEY_PRIVATE_KEY=your_cdp_private_key - OPENAI_API_KEY=your_openai_key - ``` - - - - ```bash Terminal - npm start - ``` - - - -## How it works - -`getVercelAITools` converts an AgentKit instance into a tools object compatible with the Vercel AI SDK's `generateText` and `streamText` functions. - -```typescript chatbot.ts lines -import { AgentKit } from "@coinbase/agentkit"; -import { getVercelAITools } from "@coinbase/agentkit-vercel-ai-sdk"; -import { generateText } from "ai"; -import { openai } from "@ai-sdk/openai"; - -// Initialize AgentKit — reads CDP_API_KEY_NAME and CDP_API_KEY_PRIVATE_KEY from env -const agentKit = await AgentKit.from({ - cdpApiKeyName: process.env.CDP_API_KEY_NAME, - cdpApiKeyPrivateKey: process.env.CDP_API_KEY_PRIVATE_KEY, -}); - -const tools = await getVercelAITools(agentKit); - -const { text } = await generateText({ - model: openai("gpt-4o-mini"), - system: "You are an onchain AI assistant with access to a wallet.", - prompt: "What is my wallet address?", - tools, - maxSteps: 10, -}); - -console.log(text); -``` - -The `maxSteps` parameter allows multi-step tool usage — the model can call multiple tools in sequence to fulfill a single request. - -## Using different model providers - -The Vercel AI SDK supports many model providers. Swap `openai` for any supported provider: - - - - ```typescript - import { anthropic } from "@ai-sdk/anthropic"; - - const { text } = await generateText({ - model: anthropic("claude-3-7-sonnet-20250219"), - system: "You are an onchain AI assistant with access to a wallet.", - prompt: "What is my wallet address?", - tools, - maxSteps: 10, - }); - ``` - - - - ```typescript - import { mistral } from "@ai-sdk/mistral"; - - const { text } = await generateText({ - model: mistral("mistral-large-latest"), - system: "You are an onchain AI assistant with access to a wallet.", - prompt: "What is my wallet address?", - tools, - maxSteps: 10, - }); - ``` - - - -See [all supported providers](https://sdk.vercel.ai/docs/foundations/providers-and-models#ai-sdk-providers) in the Vercel AI SDK docs. - -## Next steps - - - - Configure a production-ready CDP wallet for your agent. - - - - Add per-request stablecoin payments to your agent. - - diff --git a/docs/ai-agents/reference/contracts.mdx b/docs/ai-agents/reference/contracts.mdx deleted file mode 100644 index 90d05b75d..000000000 --- a/docs/ai-agents/reference/contracts.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Contract Addresses & Protocol References" -description: "Deployed contract addresses for ERC-8004 agent identity registries and x402 facilitator endpoints on Base" -keywords: ["ERC-8004 contract", "ERC-8128", "x402 facilitator", "Base contract addresses", "agent identity registry", "agent reputation registry"] ---- - -Reference addresses and endpoints for the protocols that power agent identity and payments on Base. - -## ERC-8004 Agent Registry - -ERC-8004 is a deployed onchain protocol with two smart contracts: the **Identity Registry** (ERC-721 NFT registry where agents register their identity) and the **Reputation Registry** (feedback and trust signals). - -### Base Mainnet - -| Contract | Address | -|----------|---------| -| Identity Registry | [`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`](https://basescan.org/address/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432) | -| Reputation Registry | [`0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`](https://basescan.org/address/0x8004BAa17C55a88189AE136b182e5fdA19dE9b63) | - -### Base Sepolia (Testnet) - -| Contract | Address | -|----------|---------| -| Identity Registry | [`0x8004A818BFB912233c491871b3d84c89A494BD9e`](https://sepolia.basescan.org/address/0x8004A818BFB912233c491871b3d84c89A494BD9e) | -| Reputation Registry | [`0x8004B663056A597Dffe9eCcC1965A193B7388713`](https://sepolia.basescan.org/address/0x8004B663056A597Dffe9eCcC1965A193B7388713) | - -These are the canonical registry addresses shared across all ERC-8004 deployments on Base. The same addresses are used by [8004scan.io](https://www.8004scan.io), the Agent0 SDK, and SIWA. - -[ERC-8004 contracts on GitHub →](https://github.com/erc-8004/erc-8004-contracts) - -## ERC-8128 Request Signing - -ERC-8128 is a cryptographic signing standard for HTTP messages — not a deployed smart contract. It defines how agents sign each request using their Ethereum key (EOA via ECDSA, or smart contract accounts via ERC-1271), and how servers verify those signatures. - -There is no contract address to deploy or configure. The standard operates entirely through the HTTP headers `Signature-Input`, `Signature`, and `Content-Digest`. Smart contract account verification uses the standard ERC-1271 `isValidSignature` interface already present on deployed accounts. - -[ERC-8128 specification →](https://erc8128.slice.so/concepts/overview) - -## x402 Payment Facilitators - -x402 facilitators are off-chain services, not a single smart contract. A facilitator verifies payment payloads submitted by clients and settles payments onchain on behalf of servers. Multiple independent facilitators operate on Base. - -### Coinbase CDP Facilitator (recommended) - -The Coinbase facilitator is the default for most integrations and requires a CDP API key: - -| | | -|---|---| -| **API endpoint** | `https://api.cdp.coinbase.com/platform/v2/x402` | -| **Verify path** | `POST /v2/x402/verify` | -| **Settle path** | `POST /v2/x402/settle` | -| **Networks** | Base, Solana | -| **Auth** | CDP API key required | - -[CDP x402 facilitator docs →](https://docs.cdp.coinbase.com/x402/docs/facilitator) - -### Public Testnet Facilitator - -For development and testing without a CDP API key: - -| | | -|---|---| -| **API endpoint** | `https://www.x402.org/facilitator` | -| **Auth** | None required | - -### Third-party Facilitators - -Multiple third-party facilitators run on Base mainnet with varying network support and fee structures. See the [x402 ecosystem page](https://www.x402.org/ecosystem?filter=facilitators) for the current list. - -## Protocol summary - -| Protocol | Type | What it does | -|----------|------|-------------| -| ERC-8004 | Deployed smart contract | Onchain NFT registry mapping agents to public keys and endpoints | -| ERC-8128 | Cryptographic standard | Per-request HTTP message signing using Ethereum keys — no contract | -| x402 | Off-chain service + USDC transfers | Facilitates pay-per-request stablecoin payments between agents and services | - -## Related guides - - - - Register your agent in the ERC-8004 registry and verify requests with ERC-8128. - - - - Let your agent pay for API access with stablecoins using the x402 protocol. - - diff --git a/docs/ai-agents/skills/base-account/building-with-base-account.mdx b/docs/ai-agents/skills/base-account/building-with-base-account.mdx new file mode 100644 index 000000000..633e3e12f --- /dev/null +++ b/docs/ai-agents/skills/base-account/building-with-base-account.mdx @@ -0,0 +1,40 @@ +--- +title: "Building with Base Account" +description: "Skill that teaches your AI coding assistant how to build with the Base Account SDK — auth, payments, subscriptions, sub accounts, and gas sponsorship" +keywords: ["Base Account skill", "SIWB", "Base Pay", "Paymaster", "sub accounts", "spend permissions", "Base Account SDK"] +--- + +The **Building with Base Account** skill teaches your AI coding assistant how to implement Base Account features in your app. Install it once and your agent knows the correct implementation path for authentication, one-tap payments, recurring charges, embedded sub accounts, and gas sponsorship. + +## Install + +```bash Terminal +npx skills add base/base-skills +``` + +Once installed, ask your agent to implement any Base Account feature and it will follow the correct steps automatically. + +## What the skill covers + +| Feature | Description | +|---------|-------------| +| **Sign in with Base (SIWB)** | Build your authentication flow with Base Account | +| **Base Pay** | Accept One-tap USDC payments with a single SDK call | +| **Subscriptions** | Recurring charges via spend permissions | +| **Sub accounts** | Embedded wallets scoped to your app | +| **Paymasters** | Gas sponsorship so users pay no ETH fees | +| **Batch transactions** | Bundle multiple calls into a single user operation | +| **Prolinks** | Shareable payment links for off-app flows | + +## Example prompts + +- "Add Sign in with Base to my Next.js app" +- "Let users pay with USDC using Base Pay" +- "Set up spend permissions for monthly subscriptions" +- "Create a sub account for each user on sign-up" +- "Sponsor gas for all transactions in my app" + +## Reference + +- [Base Account documentation](/base-account) +- [Skill source on GitHub](https://github.com/base/skills/tree/master/skills/building-with-base-account) diff --git a/docs/ai-agents/skills/base-chain/adding-builder-codes.mdx b/docs/ai-agents/skills/base-chain/adding-builder-codes.mdx new file mode 100644 index 000000000..9a4098c07 --- /dev/null +++ b/docs/ai-agents/skills/base-chain/adding-builder-codes.mdx @@ -0,0 +1,41 @@ +--- +title: "Adding Builder Codes" +description: "Skill that teaches your AI agent how to append ERC-8021 attribution data to transactions so your app earns referral fees on Base" +keywords: ["builder codes", "ERC-8021", "Base attribution", "referral fees", "builder code skill", "Privy Wagmi Viem attribution"] +--- + +The **Adding Builder Codes** skill gives your AI coding assistant everything it needs to add ERC-8021 attribution to your app's transactions. This lets Base attribute onchain activity to your app and enables referral fee earnings. + +## Install + +```bash Terminal +npx skills add base/base-skills +``` + +## What the skill covers + +The skill detects your stack and applies the correct integration path: + +| Stack | Approach | +|-------|---------| +| **Privy** | `dataSuffix` plugin in `PrivyProvider` | +| **Wagmi** | `dataSuffix` option in `useWriteContract` / `useSendTransaction` | +| **Viem** | Append suffix when calling `writeContract` or `sendTransaction` | +| **Standard RPC** | Manually append hex suffix to transaction calldata | + +The skill prioritises detection in this order: **Privy → Wagmi → Viem → Standard RPC**. + +## How it works + +Builder Codes are ERC-721 NFTs on Base. Appending your code as an ERC-8021 suffix to transaction calldata attributes that transaction to your app. The gas overhead is minimal — 16 gas per non-zero byte. + +## Example prompts + +- "Add my builder code to all outgoing transactions" +- "Set up builder code attribution for my Wagmi app" +- "How do I earn referral fees on Base?" + +## Reference + +- [Base Builder Codes](https://base.dev) +- [Skill source on GitHub](https://github.com/base/skills/tree/master/skills/adding-builder-codes) diff --git a/docs/ai-agents/skills/base-chain/connecting-to-base-network.mdx b/docs/ai-agents/skills/base-chain/connecting-to-base-network.mdx new file mode 100644 index 000000000..e1dfcf552 --- /dev/null +++ b/docs/ai-agents/skills/base-chain/connecting-to-base-network.mdx @@ -0,0 +1,34 @@ +--- +title: "Connecting to Base Network" +description: "Skill that gives your AI agent Base Mainnet and Sepolia network config — chain IDs, RPC endpoints, and explorer URLs" +keywords: ["Base network", "Base chain ID", "Base RPC", "Base Sepolia", "connect to Base", "Base network config"] +--- + +The **Connecting to Base Network** skill gives your AI coding assistant accurate, up-to-date configuration for Base Mainnet and Base Sepolia so it never has to guess chain IDs or RPC URLs. + +## Install + +```bash Terminal +npx skills add base/base-skills +``` + +## What the skill covers + +| | Base Mainnet | Base Sepolia | +|-|-------------|-------------| +| **Chain ID** | 8453 | 84532 | +| **Network type** | Production | Testnet | + +The skill includes RPC endpoints, WebSocket endpoints, block explorer URLs, and bridge addresses for both networks. + +## Example prompts + +- "Configure my app to connect to Base mainnet" +- "Set up Base Sepolia for testing" +- "What's the chain ID for Base?" +- "Add Base network to my wagmi config" + +## Reference + +- [Base network information](/base-chain/network-information) +- [Skill source on GitHub](https://github.com/base/skills/tree/master/skills/connecting-to-base-network) diff --git a/docs/ai-agents/skills/base-chain/deploying-contracts.mdx b/docs/ai-agents/skills/base-chain/deploying-contracts.mdx new file mode 100644 index 000000000..b7b40b076 --- /dev/null +++ b/docs/ai-agents/skills/base-chain/deploying-contracts.mdx @@ -0,0 +1,32 @@ +--- +title: "Deploying Contracts on Base" +description: "Skill that guides your AI agent through deploying and verifying smart contracts on Base using Foundry" +keywords: ["deploy contracts Base", "Foundry Base", "verify contract Base", "smart contract deployment", "Base Sepolia deploy"] +--- + +The **Deploying Contracts on Base** skill gives your AI coding assistant a complete guide for deploying and verifying smart contracts on Base with Foundry, including common failure modes and fixes. + +## Install + +```bash Terminal +npx skills add base/base-skills +``` + +## What the skill covers + +- Setting up Foundry for Base Mainnet and Base Sepolia +- Running `forge deploy` with the correct RPC and chain ID +- Verifying contracts on Basescan via `forge verify-contract` +- Common deployment failures and how to fix them (gas estimation errors, nonce mismatches, RPC timeouts) + +## Example prompts + +- "Deploy my ERC-20 contract to Base Sepolia" +- "Verify my deployed contract on Basescan" +- "My Foundry deploy is failing with a gas estimation error" +- "Set up my `foundry.toml` for Base" + +## Reference + +- [Base network information](/base-chain/network-information) +- [Skill source on GitHub](https://github.com/base/skills/tree/master/skills/deploying-contracts-on-base) diff --git a/docs/ai-agents/skills/base-chain/running-a-base-node.mdx b/docs/ai-agents/skills/base-chain/running-a-base-node.mdx new file mode 100644 index 000000000..dc7bc88e5 --- /dev/null +++ b/docs/ai-agents/skills/base-chain/running-a-base-node.mdx @@ -0,0 +1,33 @@ +--- +title: "Running a Base Node" +description: "Skill that covers production Base node setup — hardware requirements, networking ports, and syncing guidance" +keywords: ["Base node", "run Base node", "Base full node", "op-geth", "Base node setup", "Base RPC node"] +--- + +The **Running a Base Node** skill gives your AI coding assistant a complete reference for setting up and operating a Base node in production, including hardware specs, port configuration, and sync strategies. + +## Install + +```bash Terminal +npx skills add base/base-skills +``` + +## What the skill covers + +- Minimum and recommended hardware requirements (CPU, RAM, disk) +- Docker Compose and bare-metal setup for `op-geth` and `op-node` +- Required networking ports and firewall rules +- Snap sync vs full sync tradeoffs +- Health check endpoints and monitoring + +## Example prompts + +- "Set up a Base full node with Docker" +- "What hardware do I need to run a Base node?" +- "Configure networking ports for my Base node" +- "My node is stuck syncing — how do I fix it?" + +## Reference + +- [Node providers](/base-chain/tools/node-providers) +- [Skill source on GitHub](https://github.com/base/skills/tree/master/skills/running-a-base-node) diff --git a/docs/ai-agents/skills/index.mdx b/docs/ai-agents/skills/index.mdx new file mode 100644 index 000000000..c0e358f22 --- /dev/null +++ b/docs/ai-agents/skills/index.mdx @@ -0,0 +1,51 @@ +--- +title: "Overview" +description: "Installable skill packs that give AI agents deep knowledge of Base APIs, tools, and migration paths" +keywords: ["Base skills", "AI agent skills", "skills CLI", "Base SDK", "onchain agent tools"] +--- + +Base Skills are structured knowledge packs that plug into AI coding assistants — Claude Code, Cursor, Windsurf, and others. Install a skill and your agent gains step-by-step guidance, security rules, and implementation patterns for that topic without any prompting. + +## Install + +```bash Terminal +npx skills add base/base-skills +``` + +Skills are available to the agent immediately after installation. The agent picks the right skill automatically based on what you're building. + +## Available skills + + + + Auth, payments, subscriptions, sub accounts, and gas sponsorship via the Base Account SDK. + + + + Append ERC-8021 attribution data to transactions across Privy, Wagmi, Viem, and standard RPC. + + + + Chain IDs, RPC endpoints, and explorer URLs for Base Mainnet and Sepolia. + + + + Deploy and verify contracts on Base using Foundry, with common troubleshooting guidance. + + + + Production node setup, hardware requirements, networking ports, and syncing guidance. + + + + Convert a Farcaster Mini App SDK project into a standalone Base web app. + + + + Migrate Mini Apps from MiniKit (OnchainKit) to the native Farcaster SDK. + + + + Replace `@coinbase/onchainkit` with standalone wagmi/viem components. + + diff --git a/docs/ai-agents/skills/migrations/convert-farcaster-miniapp-to-app.mdx b/docs/ai-agents/skills/migrations/convert-farcaster-miniapp-to-app.mdx new file mode 100644 index 000000000..ceee38d95 --- /dev/null +++ b/docs/ai-agents/skills/migrations/convert-farcaster-miniapp-to-app.mdx @@ -0,0 +1,30 @@ +--- +title: "Convert Farcaster Miniapp to App" +description: "Skill that guides your AI agent through converting a Farcaster Mini App SDK project into a standalone Base web app" +keywords: ["Farcaster miniapp to app", "Farcaster SDK migration", "Mini App conversion", "Base web app", "Farcaster skill"] +--- + +The **Convert Farcaster Miniapp to App** skill gives your AI coding assistant a step-by-step plan for converting a Farcaster Mini App SDK project into a regular Base web app. You can optionally keep a small Farcaster-specific surface for users who access from Warpcast. + +## Install + +```bash Terminal +npx skills add base/base-skills +``` + +## What the skill covers + +- Identifying Farcaster-specific SDK calls and UI surfaces +- Replacing Mini App SDK dependencies with standard web equivalents +- Preserving or removing the Farcaster embed manifest +- Optionally keeping a Farcaster-compatible entry point alongside the main app + +## Example prompts + +- "Convert my Farcaster Mini App to a regular web app" +- "Remove the Farcaster SDK from my project and make it a standalone app" +- "Keep my app working in Warpcast but also launch it as a standalone site" + +## Reference + +- [Skill source on GitHub](https://github.com/base/skills/tree/master/skills/convert-farcaster-miniapp-to-app) diff --git a/docs/ai-agents/skills/migrations/converting-minikit-to-farcaster.mdx b/docs/ai-agents/skills/migrations/converting-minikit-to-farcaster.mdx new file mode 100644 index 000000000..c5fe375bd --- /dev/null +++ b/docs/ai-agents/skills/migrations/converting-minikit-to-farcaster.mdx @@ -0,0 +1,31 @@ +--- +title: "Converting MiniKit to Farcaster" +description: "Skill that migrates Mini Apps from MiniKit (OnchainKit) to the native Farcaster SDK with component mappings and common pitfalls" +keywords: ["MiniKit to Farcaster", "OnchainKit MiniKit migration", "Farcaster SDK", "Mini App migration", "MiniKit skill"] +--- + +The **Converting MiniKit to Farcaster** skill gives your AI coding assistant a precise component-by-component migration guide for moving Mini Apps from MiniKit (OnchainKit) to the native Farcaster SDK. + +## Install + +```bash Terminal +npx skills add base/base-skills +``` + +## What the skill covers + +- MiniKit → Farcaster SDK component and hook mappings +- Provider replacement (`MiniKitProvider` → `FarcasterProvider`) +- Context and user data API changes +- Common pitfalls and breaking differences between the two SDKs + +## Example prompts + +- "Migrate my MiniKit app to use the native Farcaster SDK" +- "Replace MiniKitProvider with the Farcaster equivalent" +- "What changed between MiniKit and the Farcaster SDK?" + +## Reference + +- [Mini Apps overview](/mini-apps) +- [Skill source on GitHub](https://github.com/base/skills/tree/master/skills/converting-minikit-to-farcaster) diff --git a/docs/ai-agents/skills/migrations/migrating-an-onchainkit-app.mdx b/docs/ai-agents/skills/migrations/migrating-an-onchainkit-app.mdx new file mode 100644 index 000000000..2cfc993c6 --- /dev/null +++ b/docs/ai-agents/skills/migrations/migrating-an-onchainkit-app.mdx @@ -0,0 +1,36 @@ +--- +title: "Migrating an OnchainKit App" +description: "Skill that replaces @coinbase/onchainkit with standalone wagmi/viem components — provider, wallet, and transaction migration" +keywords: ["OnchainKit migration", "wagmi viem migration", "OnchainKit to wagmi", "remove OnchainKit", "OnchainKit skill"] +--- + +The **Migrating an OnchainKit App** skill gives your AI coding assistant a five-step migration plan for replacing `@coinbase/onchainkit` with standalone `wagmi` and `viem` components. + +## Install + +```bash Terminal +npx skills add base/base-skills +``` + +## What the skill covers + +The migration follows five sequential steps, each with a validation gate before proceeding: + +| Step | What changes | +|------|-------------| +| **Detection** | Scan for OnchainKit imports and identify components in use | +| **Provider** | Replace `OnchainKitProvider` with `WagmiProvider` + `QueryClientProvider` | +| **Wallet** | Build a `WalletConnect` component using wagmi hooks | +| **Transactions** | Replace `Transaction` components with `useWriteContract` and receipt hooks | +| **Cleanup** | Remove remaining OnchainKit imports and optionally uninstall the package | + + +## Example prompts + +- "Migrate my app off OnchainKit" +- "Replace OnchainKitProvider with wagmi" +- "Convert my OnchainKit Transaction component to use wagmi hooks" + +## Reference + +- [Skill source on GitHub](https://github.com/base/skills/tree/master/skills/migrating-an-onchainkit-app) diff --git a/docs/docs.json b/docs/docs.json index 7835f9bc9..88b4b977a 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -503,20 +503,34 @@ ] }, { - "group": "Frameworks", + "group": "Skills", "pages": [ - "ai-agents/frameworks/eliza", - "ai-agents/frameworks/langchain", - "ai-agents/frameworks/vercel-ai-sdk", - "ai-agents/frameworks/agentkit" + "ai-agents/skills/index", + { + "group": "Base Account", + "pages": [ + "ai-agents/skills/base-account/building-with-base-account" + ] + }, + { + "group": "Base Chain", + "pages": [ + "ai-agents/skills/base-chain/adding-builder-codes", + "ai-agents/skills/base-chain/connecting-to-base-network", + "ai-agents/skills/base-chain/deploying-contracts", + "ai-agents/skills/base-chain/running-a-base-node" + ] + }, + { + "group": "Migrations", + "pages": [ + "ai-agents/skills/migrations/convert-farcaster-miniapp-to-app", + "ai-agents/skills/migrations/converting-minikit-to-farcaster", + "ai-agents/skills/migrations/migrating-an-onchainkit-app" + ] + } ] }, - { - "group": "Reference", - "pages": [ - "ai-agents/reference/contracts" - ] - } ] }, { @@ -591,6 +605,26 @@ ] }, "redirects": [ + { + "source": "/ai-agents/reference/contracts", + "destination": "/ai-agents/index" + }, + { + "source": "/ai-agents/frameworks/eliza", + "destination": "/ai-agents/skills/index" + }, + { + "source": "/ai-agents/frameworks/langchain", + "destination": "/ai-agents/skills/index" + }, + { + "source": "/ai-agents/frameworks/vercel-ai-sdk", + "destination": "/ai-agents/skills/index" + }, + { + "source": "/ai-agents/frameworks/agentkit", + "destination": "/ai-agents/skills/index" + }, { "source": "/get-started/migrate-from-onchainkit", "destination": "/onchainkit/migrate-from-onchainkit"