web3agent

Give your AI agent full EVM execution. Swaps, bridges, lending, staking, limit orders, exchange trading. 17 chains. 150+ tools. One install.

Works out of the box with Claude Code, Cursor, Windsurf, OpenCode, and Codex. Self-custodial. Every write operation goes through a confirmation queue: nothing executes without your approval.

EVM execution is a solved problem. Stop rebuilding it. Plug in and ship.

What you can do

Once installed, your AI agent can execute real DeFi operations in plain language:

• "Swap 0.1 ETH for USDC on Base" — routed, simulated, confirmed, executed
• "Bridge 500 USDC from Arbitrum to Optimism" — cross-chain via LI.FI, 20+ chains
• "Set a limit order to buy ETH at $2,800" — decentralized dLIMIT via Orbs
• "Cancel my open orders on Binance" — CCXT exchange access with per-method risk classification
• "What's my wallet balance across all my chains?" — read-only, no confirmation needed
• "Show me yield opportunities above 5% APY" — research tools, protocol analysis, due diligence

No ABI. No transaction building. No chain-switching. The agent handles routing, simulation, and the confirmation queue. You approve, it executes.

Install

npx web3agent init

Detects your AI agent host and configures it automatically.

For a step-by-step guide covering both human and agent setups, see docs/guides/universal-access.md.

Supported hosts

| Host | Config location | |------|-----------------| | 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-mediated self-install via canonical guide |

Supported chains

Ethereum, Base, Arbitrum, Optimism, Polygon, Linea, BSC, Avalanche, zkSync Era, Scroll, Mode, Blast, Mantle, Celo, Gnosis, Sepolia, Base Sepolia.

Default: Base (8453). Override with the CHAIN_ID env var or pass chainId per call.

What's included

| Capability | Provider | Notes | |------------|----------|-------| | On-chain state | EVM MCP | Balances, contract reads/writes, gas, ENS, multicall (25 tools) | | Swaps | GOAT / Uniswap / Balancer | Same-chain, ERC-20/721 | | Aggregated swaps | Orbs Liquidity Hub | Optimal pricing via solver network | | Cross-chain bridges | LI.FI | 20+ chains | | Advanced orders | Orbs | dTWAP, dLIMIT | | Exchange trading | CCXT | Public/private access across 100+ exchanges (6 tools) | | Block explorer | Blockscout + Etherscan | Address info, tx history, NFTs, contract ABIs, network stats (35 tools) | | Market data | DefiLlama / CoinGecko / Binance | TVL, prices, DEX volume, stablecoin stats, sentiment (20 tools) | | Research | DefiLlama / on-chain | Contract security, yield analysis, whale tracking, governance (13 tools) | | Token resolution | Built-in registry + DexScreener | Symbol-to-address, long-tail assets | | Wallet management | Built-in | Generate, persist, activate, derive, sign | | Confirmation queue | Built-in | Write operations require explicit approval | | Agent protocols | AGDP / ACP / x402 / ERC-8004 | Agent marketplace, cooperation, payments | | Price data | CoinGecko | Requires COINGECKO_API_KEY | | 0x swaps | 0x | Requires ZEROX_API_KEY |

Starter templates

npx web3agent create

Scaffolds a ready-to-run project from one of three bundled templates:

• Vercel AI SDK — chat agent with tool calling
• Mastra — agent framework with web3agent tools
• MCP-host — lightweight MCP client

Each starter uses the same web3agent lifecycle surfaces as MCP and CLI.

Usage

# 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

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

Programmatic usage

Root API

Use the package root for stable, typed EVM capabilities from another app or agent layer.

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);

Use resolveCanonicalToken() for well-known registry tokens and native-token aliases. Use resolveToken() when you also want DexScreener discovery fallback for long-tail assets.

Browser wallet flows

Use the root API when your app owns the signer (e.g. a browser wallet via wagmi or AppKit).

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

1. prepareOperation(...) returns the next wallet actions plus resumeState
2. Your app executes those actions with the browser wallet
3. resumeOperation(...) continues until the operation completes

Transaction actions are only considered complete once you return a confirmed result:

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

resumeOperation() independently verifies the receipt before advancing.

Architecture notes: docs/architecture/browser-wallet-operations.md

Runtime API

Use web3agent/runtime when you need tool discovery, generic invocation, or upstream passthrough tools.

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();
}

Environment variables

See WEB3_CONTEXT.md for the full environment variable reference.

For authenticated exchange access via CCXT tools, set CCXT_CONFIG_PATH to a JSON file containing named accounts and exchange credentials.

Known limitations

• Blockscout explorer tools work on 8 chains only (Ethereum, Polygon, Arbitrum, Optimism, Base, Gnosis, Scroll, zkSync Era)
• Stop-loss and take-profit orders (dSLTP) are not yet available
• 0x and CoinGecko plugins require their respective API keys
• 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

Requirements

• Node.js 22+
• pnpm (for development)

License

MIT