Web3agent

查看实际运行效果： The Arena — 11 个 AI Agent 通过 Web3Agent 使用真实资金进行交易。

web3agent

MCP 软件包：web3agent | npm：https://www.npmjs.com/package/web3agent | GitHub：https://github.com/Apegurus/web3agent | 联系方式：[email protected]

链接： 网站 · GitHub · npm · Smithery · The Arena · X / @Web3AgentFi

为你的 AI Agent 提供 EVM 执行和 DeFi 工具：兑换、跨链桥、限价单和触发单、交易所交易、市场数据、研究和钱包管理。提供 190 多种 MCP 工具，只需安装一次。

开箱即用，支持 Claude Code、Cursor、Windsurf、OpenCode 和 Codex。自托管密钥。默认情况下，写入操作会进入确认队列：未经你的批准不会执行，除非你明确禁用确认。

EVM 执行问题已经解决。别再重复构建，直接接入并发布。

---

你可以做什么

安装后，你的 AI Agent 就能通过自然语言执行真实的 DeFi 操作：

• “在 Base 上将 0.1 ETH 兑换为 USDC” — 报价、路由、确认后执行
• “将 500 USDC 从 Arbitrum 跨链桥接到 Optimism” — 通过 LI.FI 跨链，支持 20 多条链
• “设置限价单或触发单，在 ETH 价格达到 2,800 美元时买入” — 通过 Orbs 下达去中心化现货订单
• “取消我在 Binance 上的未结订单” — 通过 CCXT 访问交易所，并按方法进行风险分类
• “我在 Base 上有多少 USDC 余额？” — 只读查询 EVM 和 ERC-20 余额
• “展示 APY 高于 5% 的收益机会” — 研究工具、协议分析和尽职调查

常见工作流无需处理 ABI 或构建交易。如果你提供或注册 ABI，或者可以查询区块浏览器 ABI，则也可读取和写入通用合约。Agent 会处理路由、交易准备和确认队列。你批准后，它就会执行。

---

面向 Agent 高级用户的快速入门

npx web3agent init

此命令会检测 Claude Code、Cursor、Windsurf、OpenCode 或 Codex，并自动配置 MCP 服务。重启宿主后，然后询问：

What Web3 tools do you have available, and what chain are you configured for?

对于其他支持 MCP 的宿主，请配置一个运行以下命令的 stdio 服务：

npx web3agent

通用 MCP 配置格式如下：

{
  "web3agent": {
    "type": "stdio",
    "command": "npx",
    "args": ["web3agent"]
  }
}

默认情况下，写入操作需要确认；除非明确启用，否则不会通过 MCP 暴露钱包密钥。

如需涵盖人工和 Agent 设置的分步指南，请参阅 docs/guides/universal-access.md。

Smithery 本地捆绑包

Smithery URL 发布要求托管 Streamable HTTP MCP 端点。Web3Agent 以本地 stdio/npm 服务的形式分发，因此 Smithery 分发使用 MCPB 捆绑包：

pnpm run mcpb:check
smithery mcp publish dist/web3agent.mcpb -n Apegurus/web3agent

生成的 MCPB 是一个轻量本地捆绑包，会通过 npm exec --package [email protected] 启动已发布的 npm 软件包。

为什么选择 Web3Agent

• 一行安装。 npx web3agent init 会自动配置 Claude Code、Cursor、Windsurf、OpenCode 或 Codex。对于受支持的宿主，无需手动编辑配置。
• 自主托管密钥。 密钥保留在你的环境中，默认不会在 Agent 可见的 MCP 流程中暴露钱包机密，并且所有写入操作都会经过确认队列，除非你主动禁用该队列。
• 经实战验证的基础设施。 基于 GOAT SDK、LI.FI、Orbs、Blockscout、Etherscan、DexScreener 等生产级 Web3 基础设施构建。
• 已投入生产。 为 Orbzy 和 The Arena 提供支持，AI Agent 可通过 Web3Agent 使用真实资金进行交易。
• 统一的 MCP 接口。 通过一台服务即可使用兑换、跨链桥、订单、市场数据、研究、代币解析、钱包生命周期和 Agent 支付协议。

适用对象

• 需要在无需重新构建协议集成的情况下执行 Web3 操作的 AI Agent 构建者
• 希望为内部工具、研究 Agent 或交易 Agent 添加 MCP 支持的 DeFi 团队
• 正在开发支持钱包的 Agent、兑换、跨链桥和市场工作流的开发者
• 希望获取只读链上数据并使用明确确认写入流程的 MCP 宿主用户

可直接复制的提示词

安装后使用以下提示词，快速开始：

List the supported chains and tell me which Web3 tools are safest to try first.

Resolve USDC, WETH, and DEGEN on Base. Show token addresses and decimals.

Quote swapping 0.01 ETH to USDC on Base, but do not execute anything.

Show yield opportunities above 5% APY and explain the main protocol risks.

Explain this wallet's recent activity on Base: 0x0000000000000000000000000000000000000000

---

支持的宿主

宿主	配置位置
Claude Code	~/.claude/mcp.json
Cursor	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
OpenCode	.opencode/config.json
Codex	.codex/config.toml
OpenClaw	通过规范指南由 Agent 引导完成自安装

---

支持的链

基本的 EVM 操作使用 viem 的链注册表；只要 RPC 可用，即可面向任何 viem 支持的 EVM 链。

增强型兑换和订单集成目前覆盖 Ethereum、Base、Arbitrum、Optimism、Polygon、Linea、BSC、Avalanche、Sonic、Mode、Blast、Celo 和 Gnosis。代币解析、区块浏览器、LI.FI 以及市场／研究工具的支持范围因服务提供商而异；LI.FI 跨链桥报价和执行通过 LI.FI 自有链列表支持 20 多条链。

默认值： Base（8453）。可通过 CHAIN_ID 环境变量覆盖，或在每次调用时传入 chainId。

---

包含的功能

功能	提供方	备注
链上状态	原生 EVM 工具	余额、合约读写、Gas、ENS、多调用（27 个工具）
兑换	GOAT / Uniswap / Balancer	同链兑换、ERC-20/721
聚合兑换	Orbs Liquidity Hub	通过求解器网络实现最优定价
跨链桥	LI.FI	支持 20 多条链
借贷	GOAT SDK / 协议集成	在支持的情况下提供 Aave、Morpho 和主要货币市场功能
高级订单	Orbs	现货市场、限价、TWAP、止损、止盈、延迟订单
交易所交易	CCXT	跨 100 多家交易所提供公共／私有访问（6 个工具）
区块浏览器	Blockscout + Etherscan	地址信息、交易历史、NFT、合约 ABI、网络统计（35 个工具）
市场数据	DefiLlama / CoinGecko / Binance	TVL、价格、DEX 交易量、稳定币统计、情绪（20 个工具）
研究	DefiLlama / 链上数据	合约安全、收益分析、巨鲸追踪、治理（13 个工具）
代币解析	内置注册表 + DexScreener	符号转地址、长尾资产
钱包管理	web3agent + Open Wallet Standard	CLI/MCP 生命周期、配置后使用加密 OWS 金库、旧版回退
确认队列	内置	默认情况下，写入操作需要明确批准
Agent 协议	aGDP / ACP / ERC-8183 / x402 / ERC-8004	Agent 市场、协作、支付
价格数据	CoinGecko	需要 COINGECKO_API_KEY
0x 兑换	0x	需要 ZEROX_API_KEY

---

入门模板

npx web3agent create

可从三个内置模板中搭建一个开箱即用的项目：

• Vercel AI SDK — 支持工具调用的聊天 Agent
• Mastra — 集成 web3agent 工具的 Agent 框架
• MCP-host — 轻量级 MCP 客户端

每个入门模板都使用与 MCP 和 CLI 相同的 web3agent 生命周期接口。

---

示例

根目录中的示例已包含在 npm 包中：

# Safe import-only previews
node examples/swap.mjs
node examples/bridge.mjs

# Read-only live quote examples
node examples/swap.mjs --quote
node examples/bridge.mjs --quote

# Prepared external-wallet flows
WEB3AGENT_EXAMPLE_ACCOUNT=0x... node examples/swap.mjs --prepare
WEB3AGENT_EXAMPLE_ACCOUNT=0x... node examples/bridge.mjs --prepare

示例默认使用小额 USDC 计价的流程，只有传入 --prepare 时才会准备钱包操作。

快速入门示例

准备在 Base 上兑换的 Agent

import { prepareOperation, resolveCanonicalTokenSync } from "web3agent";

const chainId = 8453;
const usdc = resolveCanonicalTokenSync({ chainId, symbol: "USDC" });
const weth = resolveCanonicalTokenSync({ chainId, symbol: "WETH" });

if (!usdc || !weth) throw new Error("Missing canonical token");

const intent = await prepareOperation({
  integration: "orbs",
  kind: "swap",
  account: "0xYourWallet",
  chainId,
  fromToken: usdc.address,
  toToken: weth.address,
  fromAmount: "10000000",
  slippagePct: 0.5,
});

console.log(intent.nextActions);

准备从 Ethereum 跨链桥接到 Arbitrum 的 Agent

import { prepareOperation, resolveCanonicalTokenSync } from "web3agent";

const fromChainId = 1;
const toChainId = 42161;
const from = resolveCanonicalTokenSync({ chainId: fromChainId, symbol: "USDC" });
const to = resolveCanonicalTokenSync({ chainId: toChainId, symbol: "USDC" });

if (!from || !to) throw new Error("Missing canonical token");

const bridge = await prepareOperation({
  integration: "lifi",
  kind: "bridge",
  account: "0xYourWallet",
  fromChainId,
  toChainId,
  fromToken: from.address,
  toToken: to.address,
  fromAmount: "1000000",
});

console.log(bridge.nextActions);

监控钱包的 Agent

import { getAddressInfo, getTransactionHistory, listSupportedChains } from "web3agent";

const address = "0x0000000000000000000000000000000000000000";
const chainId = 8453;

const [chains, info, history] = await Promise.all([
  listSupportedChains(),
  getAddressInfo({ address, chainId }),
  getTransactionHistory({ address, chainId, pageSize: 5 }),
]);

console.log({
  supportedChains: chains.chains.length,
  wallet: info,
  recentTransactions: history.transactions,
});

---

面向加密团队

如果你希望 AI Agent 能够发现或与协议交互，又不想让每个团队都重新构建钱包、链、代币、报价、区块浏览器和确认流程，可以使用 web3agent。

集成方式：

• MCP 工具，适用于 Claude Code、Cursor、Windsurf、OpenCode、Codex 及其他 MCP 宿主
• 编程式 SDK，来自 web3agent，适用于应用自有 Agent 和浏览器钱包流程
• 预备操作，适用于需要用户或应用在外部签名的协议
• 需确认的写入操作，确保默认情况下执行不会绕过明确的批准流程

适合作为首次集成目标的功能：

• 代币、市场和持仓读取
• 报价和模拟工具
• 用于浏览器/应用签名的预备钱包操作
• 特定协议的研究或风险工具

如有协议支持或集成方面的问题，请在 https://github.com/Apegurus/web3agent/issues 提交 issue，或联系 [email protected]。

---

用法

# Initialize for your host (run once)
npx web3agent init

# Start the MCP server
npx web3agent

# CLI fallback (for non-MCP hosts or scripting)
npx web3agent tools list --json
npx web3agent tools call resolve_token --input '{"symbol":"USDC","chainId":8453}' --json
npx web3agent doctor --json

# Local-only wallet secret flows (requires OWS_PASSPHRASE >= 12 chars and an interactive TTY)
OWS_PASSPHRASE='...' npx web3agent wallet generate
OWS_PASSPHRASE='...' npx web3agent wallet generate --mnemonic
OWS_PASSPHRASE='...' npx web3agent wallet activate --from-file ./secret.txt --type private-key

# Options
npx web3agent --help
npx web3agent --version

默认情况下，钱包密钥 MCP 工具处于禁用状态，因此私钥和助记词不会进入 AI Agent 的推理上下文。请使用上文中的本地 web3agent wallet ... 命令安全地生成/导入钱包。如果你明确接受 Agent 可见机密信息带来的风险，可设置 WEB3AGENT_ALLOW_AGENT_VISIBLE_SECRETS=1，重新启用旧版 MCP 行为。

wallet_deactivate 只会停用当前运行时会话，并恢复为只读的临时模式。如果你确实要永久删除已持久化的钱包材料，请使用需确认的 wallet_delete。

钱包安全默认设置

默认情况下，web3agent 会确保钱包机密信息不会出现在 MCP 工具响应和 Agent 可见的输入中。建议使用本地 web3agent wallet ... 命令生成或导入私钥和助记词，因为这些命令需要交互式 TTY，并会拒绝输出包含机密信息的 JSON。只有在你明确接受私钥或助记词可能通过 MCP 宿主发送且对 Agent/推理服务提供方可见时，才设置 WEB3AGENT_ALLOW_AGENT_VISIBLE_SECRETS=1。

对于已持久化的服务端钱包，设置 OWS_PASSPHRASE 并非强制要求，但强烈建议设置。在 macOS/Linux 上设置该变量且 OWS 可用时，web3agent 会使用 Open Wallet Standard 加密保险库，而非旧版受文件系统权限保护的钱包存储。OWS 规范要求的最短长度为 12 个字符；web3agent 会对较弱的运行时密码短语发出警告，本地钱包生成/导入也会拒绝较短的值。生产环境中请使用 16 个或更多字符、包含多种字符类型的密码短语。请在运行 web3agent 的进程中配置此变量，无论是将 npx web3agent 用作 MCP 服务，还是在使用 createRuntime({ env: { OWS_PASSPHRASE: "..." } }) 的应用/服务中。

如果缺少 OWS_PASSPHRASE、其值为空、OWS 不可用、平台为 Windows，或设置了 OWS_FORCE_LEGACY=1，web3agent 就会回退到仅受文件权限保护的旧版钱包存储。迁移旧版 wallet.json 会留下一个明文的 wallet.json.migrated 回滚备份；确认能够访问 OWS 后，请将其删除。对于多 Agent 服务，在支持按运行时隔离钱包之前，请将使用钱包的不同运行时置于不同进程中运行。

---

编程式用法

根 API

在其他应用或 Agent 层中使用包根目录，获取稳定且类型化的 EVM 功能。

import {
  getChain,
  listChainTokens,
  resolveCanonicalTokenSync,
  resolveToken,
} from "web3agent";

const chain = getChain(8453);
const usdc = resolveCanonicalTokenSync({ symbol: "USDC", chainId: 8453 });
const tokens = listChainTokens({ chainId: 8453 });
const discovered = await resolveToken({ symbol: "DEGEN", chainId: 8453 });

console.log(
  chain?.name,
  usdc?.address,
  discovered.address,
  tokens.tokens.length,
);

对于注册表中的知名代币和原生代币别名，请使用 resolveCanonicalToken()。如果还需要针对长尾资产进行 DexScreener 发现回退，请使用 resolveToken()。

浏览器钱包流程

当你的应用拥有签名器时（例如通过 wagmi 或 AppKit 使用浏览器钱包），请使用根 API。

import {
  prepareOperation,
  resumeOperation,
  simulateTransaction,
} from "web3agent";

1. prepareOperation(...) 返回后续钱包操作以及 resumeState
2. 你的应用通过浏览器钱包执行这些操作
3. resumeOperation(...) 会继续执行，直到操作完成

只有在你返回已确认的结果后，交易操作才会被视为完成：

{ type: "transaction", txHash: "0x...", status: "confirmed" }

resumeOperation() 会独立验证收据，然后继续执行。

架构说明：docs/architecture/browser-wallet-operations.md

运行时 API

当你需要发现工具、进行通用调用或使用上游透传工具时，请使用 web3agent/runtime。

import { createRuntime } from "web3agent/runtime";

const runtime = await createRuntime();

try {
  console.log(runtime.getHealth());
  console.log(
    runtime
      .listTools()
      .slice(0, 5)
      .map((tool) => tool.name),
  );
  const result = await runtime.invokeTool("list_supported_chains");
  console.log(result.structuredContent);
} finally {
  await runtime.shutdown();
}

---

环境变量

完整的环境变量参考，请参阅 WEB3_CONTEXT.md。

要通过 CCXT 工具访问经过身份验证的交易所，请将 CCXT_CONFIG_PATH 设置为一个 JSON 文件，其中包含命名账户和交易所凭据。

---

已知限制

• Blockscout 浏览器工具仅支持 8 条链（Ethereum、Polygon、Arbitrum、Optimism、Base、Gnosis、Scroll、zkSync Era）
• 收益工具仅用于只读研究；使用一流工具之外的协议特定执行需通过基于 ABI 的 EVM 调用
• 0x 和 CoinGecko 插件需要各自的 API 密钥
• MCP 主机无法直接打开浏览器钱包提示框——MCP 可以准备、模拟并提交已签名的负载，但签名需要由你的应用处理钱包交互

---

要求

• Node.js 22+
• pnpm（用于开发）

---

许可证

MIT