diff --git a/docs/ai-agents/core-concepts/agent-frameworks.mdx b/docs/ai-agents/core-concepts/agent-frameworks.mdx deleted file mode 100644 index c55112e4d..000000000 --- a/docs/ai-agents/core-concepts/agent-frameworks.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "Frameworks" -description: "Choose the right framework for building and running AI agents on Base" -keywords: ["AI agent frameworks Base", "OpenClaw Base", "onchain AI agent", "build AI agent 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 - -| | BANKR | OpenClaw | Agent SDK | -|---|---|---|---| -| **What it is** | A managed Agent API, plus skill and wallet plugins for OpenClaw | An open-source personal AI assistant that runs across multiple channels (Discord, Telegram, web) | A developer toolkit for building custom agents with full control over behavior and integrations | -| **Language** | Any (REST API) for Agent API; TypeScript for OpenClaw plugins | TypeScript | TypeScript / Python | -| **Hosting** | Agent API is managed by BANKR; OpenClaw plugins run in your self-hosted agent | Self-hosted | Self-hosted | -| **Best for** | Agent API for adding onchain capabilities without managing infrastructure; OpenClaw plugins for adding onchain skills to a self-hosted agent | Running a multi-channel assistant with pre-built skills and plugin support | Production agents where you need full control over logic, integrations, and deployment | - -## BANKR - -BANKR offers two ways to work with agents on Base. The **BANKR Agent API** is a hosted agent you interact with through a REST API: you send prompts and receive results, including the ability to execute trades and check balances, without building or deploying your own agent. This is the fastest way to add onchain agent capabilities to an existing application. - -BANKR also provides **skills and wallet plugins for OpenClaw**. If you're building with OpenClaw, you can install BANKR's skill packages to give your self-hosted agent wallet capabilities, token swaps, and other onchain actions without using the managed API. - -Use the BANKR Agent API when you want onchain agent capabilities without managing infrastructure. Use BANKR's OpenClaw plugins when you want BANKR's onchain skills inside your own self-hosted agent. - -[Get started with BANKR Agent API →](https://docs.bankr.bot/getting-started/quick-start) - -[Browse BANKR skills for OpenClaw →](https://github.com/BankrBot/openclaw-skills) - -## OpenClaw - -OpenClaw is an open-source AI assistant that connects to multiple messaging platforms out of the box. It comes with a plugin system for adding skills (pre-built actions your agent can perform) and handles the infrastructure for receiving messages, processing them, and responding across channels. - -Use OpenClaw when you want to run a conversational agent across Discord, Telegram, or web and extend it with community-built plugins. - -[Get started with OpenClaw →](https://docs.openclaw.ai/start/getting-started) - -## Agent SDK - -Coinbase's Agent SDK gives you the building blocks to create 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 Agent SDK when you're building a production agent and want full control over its architecture. - -[Get started with Agent SDK →](https://docs.cdp.coinbase.com/agent-kit/welcome) - - -**How to choose:** Use the **BANKR Agent API** to call an agent via API without building one, or add **BANKR's skill plugins** to an OpenClaw agent for onchain capabilities. Use **OpenClaw** if you need a multi-channel chatbot with plugins. Use **Agent SDK** if you want full control over logic, integrations, and deployment. - - -## Next step - - - Give your agent the ability to hold funds and make payments. - diff --git a/docs/ai-agents/core-concepts/identity-verification-auth.mdx b/docs/ai-agents/core-concepts/identity-verification-auth.mdx deleted file mode 100644 index ecbda67db..000000000 --- a/docs/ai-agents/core-concepts/identity-verification-auth.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "Identity, Verification, and Auth" -description: "Make your agent discoverable and verifiable so other agents and services can trust it" ---- - -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. - - - -## Why identity matters - -In a world where agents interact with each other and with services autonomously, trust is the foundation. Without identity: - -- 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 - -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. - -## Registry: a public directory for agents - -A registry is a public directory where agents and services publish their identity. Any participant can query the registry to resolve an agent's name 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, which means 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 - -[Learn more about Agent Registry (ERC-8004) →](https://www.8004.org/) - -## Verification: proving identity at runtime - -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. - - - - Your agent registers its identity and public key in the ERC-8004 registry. This is a one-time setup step. - - - - When your agent calls a service, it signs the request using its private key. This creates a cryptographic signature unique to that specific request. - - - - 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. - - - -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. - -[Learn more about Agent Verification (ERC-8128) →](https://erc8128.slice.so/concepts/overview) - -## Sign In With Agent (SIWA) - -SIWA bundles registry and verification into a single SDK, similar to how "Sign in with Google" bundles OAuth and identity verification into one integration. Instead of wiring up ERC-8004 and ERC-8128 separately, you integrate SIWA and get both capabilities out of the box. - -With SIWA, your agent can: - -- **Register its identity** in the onchain directory -- **Authenticate into services** by proving it is the registered agent -- **Sign every request** so services can verify authenticity - -SIWA is the fastest path to giving your agent a verifiable identity. Use ERC-8004 and ERC-8128 directly only if you need more granular control over the registration and verification process. - -[Learn more at siwa.id →](https://siwa.id) - - -**Start with SIWA** for the simplest integration path. Use ERC-8004 and ERC-8128 directly if you need fine-grained control over how your agent registers and how verification is performed. - - -## Next step - - - Build services designed for agents and make your app discoverable. - diff --git a/docs/ai-agents/core-concepts/payments-and-transactions.mdx b/docs/ai-agents/core-concepts/payments-and-transactions.mdx deleted file mode 100644 index 043c2aa49..000000000 --- a/docs/ai-agents/core-concepts/payments-and-transactions.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Payments and Transactions" -description: "How your agent pays for services, receives payments, and executes onchain actions" -keywords: ["x402 protocol","autonomous agent payments", "machine payments protocol","programmatic payments","AI agent payments", "agentic payments", "agent stablecoin payments", "x402 Base", "onchain agent actions", "HTTP 402 payment required", "agentic commerce", "AI agent transactions Base"] ---- - -Your agent has a wallet. Now it needs to use it. This page covers two key concepts: how your agent pays for services automatically using the x402 protocol, and how skills define the actions your agent can perform. - - - -## x402: pay-per-request with stablecoins - -x402 lets your agent pay for API requests using stablecoins without subscriptions or API keys. Your agent requests a resource, the server tells it the price, your agent pays, and the server delivers the data. - -The name comes from HTTP status code `402 Payment Required`, which has been reserved in the HTTP specification since the 1990s but was never widely adopted. x402 finally puts it to use. - -### 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 details: how much it costs, which stablecoin to pay in, and where to send the payment. - - - - Your agent's wallet constructs and sends a onchain payment based on the server's instructions. This happens automatically, no human approval needed. - - - - Once the payment is confirmed, the server returns the requested data. The entire flow takes seconds. - - - -This model is powerful for agents because it requires no pre-existing relationship between your agent and the service. Any agent with a funded wallet can pay for any x402-enabled API on the fly. - -[Learn more about x402 →](https://www.x402.org/) - -## Skills: actions your agent can perform - -Skills are typed function definitions that describe an action your agent can invoke. Each skill specifies a name, expected inputs, and return type similar to a tool or function schema in any LLM tool-use integration. Your agent parses these definitions at runtime and calls them when relevant. - -Skills cover actions like checking a token balance, executing a swap, sending a payment, or calling a smart contract. - -### What a skill looks like - -A skill definition includes the action name, a description of what it does, the required inputs, and the expected output. Here's a simplified example: - -```json Title "Conceptual skill definition" -{ - "skill": "check-balance", - "description": "Check the token balance of a wallet address", - "inputs": { - "wallet_address": "The address to check", - "token": "The token symbol (e.g., USDC, ETH)" - }, - "output": "The current balance of the specified token" -} -``` - -Your agent reads this definition, understands what inputs it needs to provide, and calls the skill when it's relevant to the task at hand. - -### Skill providers - - - - **What they are:** Pre-built skills for agents running on OpenClaw. BANKR skills cover common actions like token swaps, balance checks, and DeFi interactions. - - **Best for:** Agents using OpenClaw or BANKR that need ready-to-use onchain capabilities. - - [Browse BANKR skills →](https://github.com/BankrBot/openclaw-skills) - - - - **What they are:** Skills provided by Coinbase's developer platform. CDP skills integrate with the Agentic Wallet and cover wallet management, token operations, and protocol interactions. - - **Best for:** Agents using Agent SDK with a CDP Agentic Wallet. - - [Browse CDP skills →](https://docs.cdp.coinbase.com/agentic-wallet/skills/overview) - - - -## Next step - - - Make your agent discoverable and verifiable so other agents and services can trust it. - diff --git a/docs/ai-agents/core-concepts/wallets.mdx b/docs/ai-agents/core-concepts/wallets.mdx deleted file mode 100644 index 82567699c..000000000 --- a/docs/ai-agents/core-concepts/wallets.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "AI Agent Wallets" -description: "Give your AI agent a dedicated wallet on Base to hold funds, send payments, sign messages, and interact with onchain protocols securely." -"og:title": "AI Agent Wallets – Base Documentation" -"og: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"] ---- - -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. Here's why: - -- 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 options - - - - **What it is:** A wallet service designed for agents running on OpenClaw. BANKR manages the private keys and exposes wallet actions as skills your agent can call. - - **Best for:** Agents built with OpenClaw or BANKR that need a quick wallet integration with pre-built skills. - - **How it works:** Install the BANKR wallet skill, and your agent gains the ability to check balances, send tokens, and interact with DeFi protocols. Keys are stored and managed by BANKR. - - [Get started →](https://github.com/BankrBot/openclaw-skills) - - - - **What it is:** Coinbase's wallet infrastructure for AI agents. It provides API-based wallet management with enterprise-grade key security through Coinbase's infrastructure. - - **Best for:** Agents built with Agent SDK that need production-ready wallet infrastructure with Coinbase-backed security. - - **How it works:** Create wallets through the CDP API. Your agent requests transactions via the API, and CDP handles signing and broadcasting. Keys are managed in Coinbase's secure enclave, your agent never touches them directly. - - [Get started →](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/frameworks/eliza.mdx b/docs/ai-agents/frameworks/eliza.mdx new file mode 100644 index 000000000..344bff52a --- /dev/null +++ b/docs/ai-agents/frameworks/eliza.mdx @@ -0,0 +1,132 @@ +--- +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 new file mode 100644 index 000000000..f1cab6ed9 --- /dev/null +++ b/docs/ai-agents/frameworks/langchain.mdx @@ -0,0 +1,212 @@ +--- +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 new file mode 100644 index 000000000..f2c7a714c --- /dev/null +++ b/docs/ai-agents/frameworks/vercel-ai-sdk.mdx @@ -0,0 +1,129 @@ +--- +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/core-concepts/agent-apps.mdx b/docs/ai-agents/guides/agent-app.mdx similarity index 80% rename from docs/ai-agents/core-concepts/agent-apps.mdx rename to docs/ai-agents/guides/agent-app.mdx index d95088231..4ad7d3bde 100644 --- a/docs/ai-agents/core-concepts/agent-apps.mdx +++ b/docs/ai-agents/guides/agent-app.mdx @@ -1,7 +1,7 @@ --- -title: "Agent Apps" -description: "Build services designed for agents and make your app discoverable" -keywords: ["agent app", "base agent app", "AI agent discovery", "build for AI agents"] +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"; @@ -10,12 +10,16 @@ An agent app is a service built with AI agents as the primary user. Instead of r + +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: @@ -28,9 +32,9 @@ The `/.well-known/` convention is a standard way to host metadata at a predictab ### What goes in a SKILL.md -Your `SKILL.md` file describes what your app does, what endpoints are available, and how to use them. Here's a conceptual template: +Your `SKILL.md` file describes what your app does, what endpoints are available, and how to use them: -```markdown Title "SKILL.md template" +```markdown SKILL.md template # Your App Name ## Description @@ -48,7 +52,7 @@ What your app does, in plain language. 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. +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 @@ -56,16 +60,12 @@ Agents aren't humans. They don't browse, guess, or interpret visual cues. When b - **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/core-concepts/payments-and-transactions) so agents can pay per request without pre-registration +- **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/core-concepts/identity-verification-auth). 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. - - -The Agent App Framework is experimental. APIs and conventions may change as the standard evolves. - +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. diff --git a/docs/ai-agents/guides/register-and-sign-in-your-agent.mdx b/docs/ai-agents/guides/register-and-sign-in-your-agent.mdx new file mode 100644 index 000000000..5596eaa50 --- /dev/null +++ b/docs/ai-agents/guides/register-and-sign-in-your-agent.mdx @@ -0,0 +1,191 @@ +--- +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"] +--- + +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. + + + +## Why identity matters + +In a world where agents interact with each other and with services autonomously, trust is the foundation. Without identity: + +- 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 + +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. + +## Registry: a public directory for agents + +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: + + + + Use 8004scan.io to register and explore registered agents through a web interface — no code required. + + + Use the Agent0 SDK to register your agent programmatically and manage its onchain profile. + + + +[Learn more about the ERC-8004 standard →](https://www.8004.org/) + +## Verification: proving identity at runtime + +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. + + + + Your agent registers its identity and public key in the ERC-8004 registry. This is a one-time setup step. + + + + When your agent calls a service, it signs the request using its private key. This creates a cryptographic signature unique to that specific request. + + + + 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. + + + +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. + +[Learn more about Agent Verification (ERC-8128) →](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. + + +**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. + + +### 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: + +```bash Terminal +npm install @buildersgarden/siwa +``` + +Choose a signer based on your wallet provider. SIWA supports private keys, Bankr, Circle, Openfort, Privy, and smart contract accounts: + +```typescript TypeScript +import { createLocalAccountSigner } from "@buildersgarden/siwa/signer"; +import { privateKeyToAccount } from "viem/accounts"; + +const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); +const signer = createLocalAccountSigner(account); +``` + +Request a nonce from the service, then sign and submit a SIWA message: + +```typescript TypeScript +import { signSIWAMessage } from "@buildersgarden/siwa"; + +// Step 1: Request a nonce from the service +const nonceResponse = await fetch("https://api.example.com/siwa/nonce", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ address: await signer.getAddress() }), +}); +const { nonce, issuedAt } = await nonceResponse.json(); + +// Step 2: Sign the SIWA message +const { message, signature } = await signSIWAMessage( + { + domain: "api.example.com", + uri: "https://api.example.com/siwa", + agentId: 42, // your ERC-8004 token ID + agentRegistry: "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432", + chainId: 8453, + nonce, + issuedAt, + }, + signer +); + +// Step 3: Submit for verification and receive a receipt +const verifyResponse = await fetch("https://api.example.com/siwa/verify", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ message, signature }), +}); +const { receipt } = await verifyResponse.json(); +``` + +Use the receipt to sign subsequent requests with ERC-8128: + +```typescript TypeScript +import { signAuthenticatedRequest } from "@buildersgarden/siwa/erc8128"; + +const request = new Request("https://api.example.com/action", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ action: "transfer" }), +}); + +const signedRequest = await signAuthenticatedRequest(request, receipt, signer, 8453); +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. + +```typescript TypeScript +import { verifySIWA, createSIWANonce } from "@buildersgarden/siwa"; +import { createReceipt } from "@buildersgarden/siwa/receipt"; +import { createPublicClient, http } from "viem"; +import { base } from "viem/chains"; + +const client = createPublicClient({ chain: base, transport: http() }); + +// POST /siwa/nonce +const { nonce, issuedAt } = await createSIWANonce({ address, agentId, agentRegistry }, client); + +// POST /siwa/verify +const result = await verifySIWA(message, signature, "api.example.com", nonceValid, client); +if (result.success) { + const { receipt } = createReceipt({ address: result.address, agentId: result.agentId }); + return { receipt }; +} +``` + +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. + +## Next step + + + Build services designed for agents and make your app discoverable. + diff --git a/docs/ai-agents/trading.mdx b/docs/ai-agents/guides/trading.mdx similarity index 99% rename from docs/ai-agents/trading.mdx rename to docs/ai-agents/guides/trading.mdx index 6d62b3719..c5b3e1e1c 100644 --- a/docs/ai-agents/trading.mdx +++ b/docs/ai-agents/guides/trading.mdx @@ -1,5 +1,5 @@ --- -title: 'Trading on Base' +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"] --- diff --git a/docs/ai-agents/guides/wallet-setup.mdx b/docs/ai-agents/guides/wallet-setup.mdx new file mode 100644 index 000000000..7afc754ad --- /dev/null +++ b/docs/ai-agents/guides/wallet-setup.mdx @@ -0,0 +1,145 @@ +--- +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 new file mode 100644 index 000000000..86e4ec9bf --- /dev/null +++ b/docs/ai-agents/guides/x402-payments.mdx @@ -0,0 +1,235 @@ +--- +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 + + + Make your agent discoverable and verifiable so other agents and services can trust it. + diff --git a/docs/ai-agents/index.mdx b/docs/ai-agents/index.mdx index 341b2714b..cd51c14d2 100644 --- a/docs/ai-agents/index.mdx +++ b/docs/ai-agents/index.mdx @@ -1,46 +1,60 @@ --- 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"] +keywords: ["AI agents Base", "x402 protocol", "onchain agents", "Base L2", "Build with AI", "Base MCP server", "AgentKit", "OpenClaw"] --- 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 skills and a funded wallet +- **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 +## 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. + + + + Coinbase's developer toolkit for building custom agents in TypeScript or Python. Full control over logic, integrations, and deployment. + + + +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 how you'll build and run your agent (self-hosted SDK, open-source assistant, or managed API) +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 payments and skills** — let your agent pay for services via x402 and perform onchain actions through pre-built skills +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 -## Core concepts +## Guides - - Choose between Agent SDK, OpenClaw, and BANKR — each offers a different level of control and hosting. - - - - Your agent needs a wallet to hold funds and authorize transactions. Learn why dedicated wallets matter and which option fits your setup. + + Give your agent a dedicated wallet to hold funds and authorize transactions. - - How your agent pays for API access with stablecoins (x402) and performs onchain actions through skills. + + Pay for API access with stablecoins and accept payments from other agents. - - How your agent proves who it is, verifies other agents, and authenticates into services. + + Register and verify your agent's identity using Sign In With Agent. - - Build services with agents as the primary user. Expose structured endpoints and make your app discoverable. + + Build services with agents as the primary user and make them discoverable. diff --git a/docs/ai-agents/introduction/choosing-a-framework.mdx b/docs/ai-agents/introduction/choosing-a-framework.mdx new file mode 100644 index 000000000..c6dd951d3 --- /dev/null +++ b/docs/ai-agents/introduction/choosing-a-framework.mdx @@ -0,0 +1,53 @@ +--- +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/quickstart/agentkit.mdx b/docs/ai-agents/quickstart/agentkit.mdx new file mode 100644 index 000000000..aad1bebe5 --- /dev/null +++ b/docs/ai-agents/quickstart/agentkit.mdx @@ -0,0 +1,175 @@ +--- +title: "AgentKit Quickstart" +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"] +--- + +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. + +**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/tools/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 + +Start the interactive chatbot that the scaffold provides: + + + + ```bash Terminal + npm run start + ``` + + + ```bash Terminal + python main.py + ``` + + + +## Next steps + + + + Learn about CDP Agentic Wallet options and production configuration. + + + + Let your agent pay for API access per-request using stablecoins. + + + + Combine AgentKit with LangChain for more complex agent workflows. + + + + Register and verify your agent's identity onchain. + + diff --git a/docs/ai-agents/quickstart/openclaw.mdx b/docs/ai-agents/quickstart/openclaw.mdx new file mode 100644 index 000000000..bcf864e79 --- /dev/null +++ b/docs/ai-agents/quickstart/openclaw.mdx @@ -0,0 +1,125 @@ +--- +title: "OpenClaw & Claude Code Quickstart" +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/reference/contracts.mdx b/docs/ai-agents/reference/contracts.mdx new file mode 100644 index 000000000..0bb44da71 --- /dev/null +++ b/docs/ai-agents/reference/contracts.mdx @@ -0,0 +1,88 @@ +--- +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/docs.json b/docs/docs.json index 7789898e6..4423c2593 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -12,36 +12,9 @@ "options": [ "copy", "view", - + "assistant", "claude", - { - "title": "Chat with Claude about this page", - "description": "Ask Claude about this page", - "icon": "https://img.icons8.com/ios-glyphs/30/claude-ai.png", - "href": { - "base": "https://claude.ai/new", - "query": [ - { - "key": "q", - "value": "Read from $path so I can ask questions about it." - } - ] - } - }, - { - "title": "Chat with ChatGPT about this page", - "description": "Ask ChatGPT about this page", - "icon": "OpenAI", - "href": { - "base": "https://chatgpt.com/", - "query": [ - { - "key": "q", - "value": "Read from $path so I can ask questions about it." - } - ] - } - } + "chatgpt" ] }, "api": { @@ -497,22 +470,40 @@ "groups": [ { "group": "Introduction", - "pages": ["ai-agents/index"] + "pages": [ + "ai-agents/index", + "ai-agents/introduction/choosing-a-framework" + ] }, { - "group": "Core Concepts", + "group": "Quickstart", "pages": [ - "ai-agents/core-concepts/agent-frameworks", - "ai-agents/core-concepts/wallets", - "ai-agents/core-concepts/payments-and-transactions", - "ai-agents/core-concepts/identity-verification-auth", - "ai-agents/core-concepts/agent-apps" + "ai-agents/quickstart/openclaw", + "ai-agents/quickstart/agentkit" ] }, { - "group": "Trading & Execution", + "group": "Guides", "pages": [ - "ai-agents/trading" + "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" + ] + }, + { + "group": "Frameworks", + "pages": [ + "ai-agents/frameworks/eliza", + "ai-agents/frameworks/langchain", + "ai-agents/frameworks/vercel-ai-sdk" + ] + }, + { + "group": "Reference", + "pages": [ + "ai-agents/reference/contracts" ] } ] @@ -2720,6 +2711,30 @@ { "source": "/mini-apps/mini-apps/quickstart/migrate-to-standard-web-app", "destination": "/mini-apps/quickstart/migrate-to-standard-web-app" + }, + { + "source": "/ai-agents/core-concepts/agent-frameworks", + "destination": "/ai-agents/introduction/choosing-a-framework" + }, + { + "source": "/ai-agents/core-concepts/wallets", + "destination": "/ai-agents/guides/wallet-setup" + }, + { + "source": "/ai-agents/core-concepts/payments-and-transactions", + "destination": "/ai-agents/guides/x402-payments" + }, + { + "source": "/ai-agents/core-concepts/identity-verification-auth", + "destination": "/ai-agents/guides/identity-siwa" + }, + { + "source": "/ai-agents/core-concepts/agent-apps", + "destination": "/ai-agents/guides/agent-app" + }, + { + "source": "/ai-agents/trading", + "destination": "/ai-agents/guides/trading" } ], "integrations": {