{
  "markdown": "[![npm version](https://img.shields.io/npm/v/web3agent.svg)](https://www.npmjs.com/package/web3agent)\n[![npm downloads](https://img.shields.io/npm/dw/web3agent.svg)](https://www.npmjs.com/package/web3agent)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/Apegurus/web3agent.svg)](https://github.com/Apegurus/web3agent)\n[![smithery badge](https://smithery.ai/badge/Apegurus/web3agent)](https://smithery.ai/servers/Apegurus/web3agent)\n\n> **See it in production:** [The Arena](https://arena.web3agent.fi) — 11 AI agents trade real capital through Web3Agent.\n\n# web3agent\n\n> MCP package: `web3agent` | npm: <https://www.npmjs.com/package/web3agent> | GitHub: <https://github.com/Apegurus/web3agent> | Contact: <hello@apeguru.dev>\n\n**Links:** [Website](https://web3agent.fi) · [GitHub](https://github.com/Apegurus/web3agent) · [npm](https://www.npmjs.com/package/web3agent) · [Smithery](https://smithery.ai/servers/Apegurus/web3agent) · [The Arena](https://arena.web3agent.fi) · [X / @Web3AgentFi](https://x.com/Web3AgentFi)\n\nGive your AI agent EVM execution and DeFi tooling: swaps, bridges, limit and trigger orders, exchange trading, market data, research, wallet management. 190+ MCP tools. One install.\n\nWorks out of the box with Claude Code, Cursor, Windsurf, OpenCode, and Codex. Self-custodial. By default, write operations go through a confirmation queue: nothing executes without your approval unless you explicitly disable confirmations.\n\nEVM execution is a solved problem. Stop rebuilding it. Plug in and ship.\n\n---\n\n## What you can do\n\nOnce installed, your AI agent can execute real DeFi operations in plain language:\n\n- **\"Swap 0.1 ETH for USDC on Base\"** — quoted, routed, confirmation-gated, executed\n- **\"Bridge 500 USDC from Arbitrum to Optimism\"** — cross-chain via LI.FI, 20+ chains\n- **\"Set a limit or trigger order to buy ETH at $2,800\"** — decentralized Spot orders via Orbs\n- **\"Cancel my open orders on Binance\"** — CCXT exchange access with per-method risk classification\n- **\"What's my USDC balance on Base?\"** — read-only EVM and ERC-20 balance checks\n- **\"Show me yield opportunities above 5% APY\"** — research tools, protocol analysis, due diligence\n\nCommon flows avoid ABI handling and transaction building. Generic contract reads and writes are available when you provide or register an ABI, or when explorer ABI lookup is available. The agent handles routing, transaction preparation, and the confirmation queue. You approve, it executes.\n\n---\n\n## Quickstart for agent power users\n\n```bash\nnpx web3agent init\n```\n\nThis detects Claude Code, Cursor, Windsurf, OpenCode, or Codex and configures the MCP server automatically. Restart your host, then ask:\n\n```text\nWhat Web3 tools do you have available, and what chain are you configured for?\n```\n\nFor any other MCP-capable host, configure a stdio server that runs:\n\n```bash\nnpx web3agent\n```\n\nThe generic MCP config shape is:\n\n```json\n{\n  \"web3agent\": {\n    \"type\": \"stdio\",\n    \"command\": \"npx\",\n    \"args\": [\"web3agent\"]\n  }\n}\n```\n\nWrites are confirmation-gated by default, and wallet secrets are not exposed through MCP unless explicitly enabled.\n\nFor a step-by-step guide covering both human and agent setups, see [docs/guides/universal-access.md](docs/guides/universal-access.md).\n\n### Smithery local bundle\n\nSmithery URL publishing requires a hosted Streamable HTTP MCP endpoint. Web3Agent is distributed as a local stdio/npm server, so Smithery distribution uses an MCPB bundle instead:\n\n```bash\npnpm run mcpb:check\nsmithery mcp publish dist/web3agent.mcpb -n Apegurus/web3agent\n```\n\nThe generated MCPB is a thin local bundle that launches the published npm package with `npm exec --package web3agent@0.6.2`.\n\n## Why Web3Agent\n\n- **One-line install.** `npx web3agent init` auto-configures Claude Code, Cursor, Windsurf, OpenCode, or Codex. No manual config edits for supported hosts.\n- **Self-custodial.** Keys stay in your environment, wallet secrets are kept out of agent-visible MCP flows by default, and every write goes through the confirmation queue unless you intentionally disable it.\n- **Battle-tested infrastructure.** Built on GOAT SDK, LI.FI, Orbs, Blockscout, Etherscan, DexScreener, and other production Web3 rails.\n- **Live in production.** Powers Orbzy and [The Arena](https://arena.web3agent.fi), where AI agents trade real capital through Web3Agent.\n- **One MCP surface.** Swaps, bridges, orders, market data, research, token resolution, wallet lifecycle, and agent-payment protocols are available through one server.\n\n## Who it is for\n\n- AI agent builders who need Web3 execution without rebuilding protocol integrations\n- DeFi teams adding MCP support to internal tools, research agents, or trading agents\n- Developers prototyping wallet-aware agents, swaps, bridges, and market workflows\n- MCP host users who want read-only chain data plus explicit-confirmation write flows\n\n### Copy-paste prompts\n\nUse these after installation to get to value quickly:\n\n```text\nList the supported chains and tell me which Web3 tools are safest to try first.\n```\n\n```text\nResolve USDC, WETH, and DEGEN on Base. Show token addresses and decimals.\n```\n\n```text\nQuote swapping 0.01 ETH to USDC on Base, but do not execute anything.\n```\n\n```text\nShow yield opportunities above 5% APY and explain the main protocol risks.\n```\n\n```text\nExplain this wallet's recent activity on Base: 0x0000000000000000000000000000000000000000\n```\n\n---\n\n## Supported hosts\n\n| Host        | Config location                                 |\n| ----------- | ----------------------------------------------- |\n| Claude Code | `~/.claude/mcp.json`                            |\n| Cursor      | `.cursor/mcp.json`                              |\n| Windsurf    | `~/.codeium/windsurf/mcp_config.json`           |\n| OpenCode    | `.opencode/config.json`                         |\n| Codex       | `.codex/config.toml`                            |\n| OpenClaw    | agent-mediated self-install via canonical guide |\n\n---\n\n## Supported chains\n\nBasic EVM operations use viem's chain registry and can target any viem-supported EVM chain when RPC access is available.\n\nEnhanced swap and order integrations currently cover Ethereum, Base, Arbitrum, Optimism, Polygon, Linea, BSC, Avalanche, Sonic, Mode, Blast, Celo, and Gnosis. Token resolution, explorer, LI.FI, and market/research tools have provider-specific coverage; LI.FI bridge quotes and execution support 20+ chains through LI.FI's own chain list.\n\n**Default:** Base (8453). Override with the `CHAIN_ID` env var or pass `chainId` per call.\n\n---\n\n## What's included\n\n| Capability          | Provider                        | Notes                                                                    |\n| ------------------- | ------------------------------- | ------------------------------------------------------------------------ |\n| On-chain state      | Native EVM tools                | Balances, contract reads/writes, gas, ENS, multicall (27 tools)          |\n| Swaps               | GOAT / Uniswap / Balancer       | Same-chain, ERC-20/721                                                   |\n| Aggregated swaps    | Orbs Liquidity Hub              | Optimal pricing via solver network                                       |\n| Cross-chain bridges | LI.FI                           | 20+ chains                                                               |\n| Lending             | GOAT SDK / protocol integrations | Aave, Morpho, and major money-market surfaces where supported           |\n| Advanced orders     | Orbs                            | Spot market, limit, TWAP, stop-loss, take-profit, delayed orders         |\n| Exchange trading    | CCXT                            | Public/private access across 100+ exchanges (6 tools)                    |\n| Block explorer      | Blockscout + Etherscan          | Address info, tx history, NFTs, contract ABIs, network stats (35 tools)  |\n| Market data         | DefiLlama / CoinGecko / Binance | TVL, prices, DEX volume, stablecoin stats, sentiment (20 tools)          |\n| Research            | DefiLlama / on-chain            | Contract security, yield analysis, whale tracking, governance (13 tools) |\n| Token resolution    | Built-in registry + DexScreener | Symbol-to-address, long-tail assets                                      |\n| Wallet management   | web3agent + Open Wallet Standard | CLI/MCP lifecycle, encrypted OWS vault when configured, legacy fallback  |\n| Confirmation queue  | Built-in                        | Write operations require explicit approval by default                    |\n| Agent protocols     | aGDP / ACP / ERC-8183 / x402 / ERC-8004 | Agent marketplace, cooperation, payments                         |\n| Price data          | CoinGecko                       | Requires `COINGECKO_API_KEY`                                             |\n| 0x swaps            | 0x                              | Requires `ZEROX_API_KEY`                                                 |\n\n---\n\n## Starter templates\n\n```bash\nnpx web3agent create\n```\n\nScaffolds a ready-to-run project from one of three bundled templates:\n\n- **Vercel AI SDK** — chat agent with tool calling\n- **Mastra** — agent framework with web3agent tools\n- **MCP-host** — lightweight MCP client\n\nEach starter uses the same `web3agent` lifecycle surfaces as MCP and CLI.\n\n---\n\n## Examples\n\nRoot examples are included in the npm package:\n\n```bash\n# Safe import-only previews\nnode examples/swap.mjs\nnode examples/bridge.mjs\n\n# Read-only live quote examples\nnode examples/swap.mjs --quote\nnode examples/bridge.mjs --quote\n\n# Prepared external-wallet flows\nWEB3AGENT_EXAMPLE_ACCOUNT=0x... node examples/swap.mjs --prepare\nWEB3AGENT_EXAMPLE_ACCOUNT=0x... node examples/bridge.mjs --prepare\n```\n\nThe examples default to small USDC-denominated flows and only prepare wallet actions when you pass `--prepare`.\n\n## Quickstart examples\n\n### Agent that prepares a swap on Base\n\n```js\nimport { prepareOperation, resolveCanonicalTokenSync } from \"web3agent\";\n\nconst chainId = 8453;\nconst usdc = resolveCanonicalTokenSync({ chainId, symbol: \"USDC\" });\nconst weth = resolveCanonicalTokenSync({ chainId, symbol: \"WETH\" });\n\nif (!usdc || !weth) throw new Error(\"Missing canonical token\");\n\nconst intent = await prepareOperation({\n  integration: \"orbs\",\n  kind: \"swap\",\n  account: \"0xYourWallet\",\n  chainId,\n  fromToken: usdc.address,\n  toToken: weth.address,\n  fromAmount: \"10000000\",\n  slippagePct: 0.5,\n});\n\nconsole.log(intent.nextActions);\n```\n\n### Agent that prepares a bridge from Ethereum to Arbitrum\n\n```js\nimport { prepareOperation, resolveCanonicalTokenSync } from \"web3agent\";\n\nconst fromChainId = 1;\nconst toChainId = 42161;\nconst from = resolveCanonicalTokenSync({ chainId: fromChainId, symbol: \"USDC\" });\nconst to = resolveCanonicalTokenSync({ chainId: toChainId, symbol: \"USDC\" });\n\nif (!from || !to) throw new Error(\"Missing canonical token\");\n\nconst bridge = await prepareOperation({\n  integration: \"lifi\",\n  kind: \"bridge\",\n  account: \"0xYourWallet\",\n  fromChainId,\n  toChainId,\n  fromToken: from.address,\n  toToken: to.address,\n  fromAmount: \"1000000\",\n});\n\nconsole.log(bridge.nextActions);\n```\n\n### Agent that monitors a wallet\n\n```js\nimport { getAddressInfo, getTransactionHistory, listSupportedChains } from \"web3agent\";\n\nconst address = \"0x0000000000000000000000000000000000000000\";\nconst chainId = 8453;\n\nconst [chains, info, history] = await Promise.all([\n  listSupportedChains(),\n  getAddressInfo({ address, chainId }),\n  getTransactionHistory({ address, chainId, pageSize: 5 }),\n]);\n\nconsole.log({\n  supportedChains: chains.chains.length,\n  wallet: info,\n  recentTransactions: history.transactions,\n});\n```\n\n---\n\n## For crypto teams\n\nUse web3agent when you want AI agents to discover or interact with your protocol without every team rebuilding wallet, chain, token, quote, explorer, and confirmation plumbing.\n\nIntegration surfaces:\n\n- **MCP tools** for Claude Code, Cursor, Windsurf, OpenCode, Codex, and other MCP hosts\n- **Programmatic SDK** from `web3agent` for app-owned agents and browser-wallet flows\n- **Prepared operations** for protocols that need users or apps to sign externally\n- **Confirmation-gated writes** so execution never bypasses an explicit approval path by default\n\nGood first integration targets:\n\n- token, market, and position reads\n- quote and simulation tools\n- prepared wallet actions for browser/app signing\n- protocol-specific research or risk tools\n\nFor protocol support or integration questions, open an issue at <https://github.com/Apegurus/web3agent/issues> or contact <hello@apeguru.dev>.\n\n---\n\n## Usage\n\n```bash\n# Initialize for your host (run once)\nnpx web3agent init\n\n# Start the MCP server\nnpx web3agent\n\n# CLI fallback (for non-MCP hosts or scripting)\nnpx web3agent tools list --json\nnpx web3agent tools call resolve_token --input '{\"symbol\":\"USDC\",\"chainId\":8453}' --json\nnpx web3agent doctor --json\n\n# Local-only wallet secret flows (requires OWS_PASSPHRASE >= 12 chars and an interactive TTY)\nOWS_PASSPHRASE='...' npx web3agent wallet generate\nOWS_PASSPHRASE='...' npx web3agent wallet generate --mnemonic\nOWS_PASSPHRASE='...' npx web3agent wallet activate --from-file ./secret.txt --type private-key\n\n# Options\nnpx web3agent --help\nnpx web3agent --version\n```\n\nWallet secret MCP tools are disabled by default so private keys and mnemonics do not enter an AI agent's inference context. Use the local `web3agent wallet ...` commands above for safe generation/import. If you explicitly accept the risk of agent-visible secrets, set `WEB3AGENT_ALLOW_AGENT_VISIBLE_SECRETS=1` to re-enable the legacy MCP behavior.\n\n`wallet_deactivate` only deactivates the current runtime session and returns to read-only ephemeral mode. Use confirmation-gated `wallet_delete` when you intentionally want to permanently remove persisted wallet material.\n\n### Wallet security defaults\n\nBy default, web3agent keeps wallet secrets out of MCP tool responses and agent-visible inputs. The local `web3agent wallet ...` commands are the recommended way to generate or import private keys and mnemonics because they require an interactive TTY and refuse JSON secret output. Set `WEB3AGENT_ALLOW_AGENT_VISIBLE_SECRETS=1` only if you explicitly accept that private keys or mnemonics can be sent through the MCP host and visible to the agent/inference provider.\n\nFor persisted server-side wallets, setting `OWS_PASSPHRASE` is **not mandatory, but strongly recommended**. When it is set on macOS/Linux and OWS is available, web3agent uses the Open Wallet Standard encrypted vault instead of the legacy filesystem-protected wallet store. The OWS spec minimum is 12 characters; web3agent warns on weak runtime passphrases and local wallet generation/import rejects shorter values. Use a 16+ character mixed passphrase in production. Configure it in the process that runs web3agent, whether that is `npx web3agent` as an MCP server or an app/service using `createRuntime({ env: { OWS_PASSPHRASE: \"...\" } })`.\n\nIf `OWS_PASSPHRASE` is missing, empty, OWS is unavailable, the platform is Windows, or `OWS_FORCE_LEGACY=1` is set, web3agent falls back to legacy wallet storage protected by file permissions only. Migrating a legacy `wallet.json` leaves a plaintext `wallet.json.migrated` rollback backup; delete it after verifying OWS access. For multi-agent services, run separate wallet-using runtimes in separate processes until per-runtime wallet isolation is supported.\n\n---\n\n## Programmatic usage\n\n### Root API\n\nUse the package root for stable, typed EVM capabilities from another app or agent layer.\n\n```javascript\nimport {\n  getChain,\n  listChainTokens,\n  resolveCanonicalTokenSync,\n  resolveToken,\n} from \"web3agent\";\n\nconst chain = getChain(8453);\nconst usdc = resolveCanonicalTokenSync({ symbol: \"USDC\", chainId: 8453 });\nconst tokens = listChainTokens({ chainId: 8453 });\nconst discovered = await resolveToken({ symbol: \"DEGEN\", chainId: 8453 });\n\nconsole.log(\n  chain?.name,\n  usdc?.address,\n  discovered.address,\n  tokens.tokens.length,\n);\n```\n\nUse `resolveCanonicalToken()` for well-known registry tokens and native-token aliases. Use `resolveToken()` when you also want DexScreener discovery fallback for long-tail assets.\n\n### Browser wallet flows\n\nUse the root API when your app owns the signer (e.g. a browser wallet via wagmi or AppKit).\n\n```javascript\nimport {\n  prepareOperation,\n  resumeOperation,\n  simulateTransaction,\n} from \"web3agent\";\n```\n\n1. `prepareOperation(...)` returns the next wallet actions plus `resumeState`\n2. Your app executes those actions with the browser wallet\n3. `resumeOperation(...)` continues until the operation completes\n\nTransaction actions are only considered complete once you return a confirmed result:\n\n```javascript\n{ type: \"transaction\", txHash: \"0x...\", status: \"confirmed\" }\n```\n\n`resumeOperation()` independently verifies the receipt before advancing.\n\nArchitecture notes: [docs/architecture/browser-wallet-operations.md](docs/architecture/browser-wallet-operations.md)\n\n### Runtime API\n\nUse `web3agent/runtime` when you need tool discovery, generic invocation, or upstream passthrough tools.\n\n```javascript\nimport { createRuntime } from \"web3agent/runtime\";\n\nconst runtime = await createRuntime();\n\ntry {\n  console.log(runtime.getHealth());\n  console.log(\n    runtime\n      .listTools()\n      .slice(0, 5)\n      .map((tool) => tool.name),\n  );\n  const result = await runtime.invokeTool(\"list_supported_chains\");\n  console.log(result.structuredContent);\n} finally {\n  await runtime.shutdown();\n}\n```\n\n---\n\n## Environment variables\n\nSee [WEB3_CONTEXT.md](WEB3_CONTEXT.md) for the full environment variable reference.\n\nFor authenticated exchange access via CCXT tools, set `CCXT_CONFIG_PATH` to a JSON file containing named accounts and exchange credentials.\n\n---\n\n## Known limitations\n\n- Blockscout explorer tools work on 8 chains only (Ethereum, Polygon, Arbitrum, Optimism, Base, Gnosis, Scroll, zkSync Era)\n- Yield tooling is read-only research; protocol-specific execution beyond first-class tools uses ABI-backed EVM calls\n- 0x and CoinGecko plugins require their respective API keys\n- MCP hosts cannot open a browser wallet prompt directly — MCP can prepare, simulate, and submit signed payloads, but signing requires your app to handle the wallet interaction\n\n---\n\n## Requirements\n\n- Node.js 22+\n- pnpm (for development)\n\n---\n\n## License\n\nMIT\n",
  "bytes": 18476,
  "sha": "eb8290d1b8d1a7c087f566c06473b675dfb4fa8814cfa0620ac704e0f47ba638",
  "repo_slug": "apegurus/web3agent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_apegurus_web3agent_dec28eef/readme"
}