web3agent

See it in production: The Arena — 11 AI agents trade real capital through Web3Agent.

web3agent

MCP package: web3agent | npm: https://www.npmjs.com/package/web3agent | GitHub: https://github.com/Apegurus/web3agent | Contact:

Links: Website · GitHub · npm · Smithery · The Arena · X / @Web3AgentFi

Give 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.

Works 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.

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" — quoted, routed, confirmation-gated, executed
• "Bridge 500 USDC from Arbitrum to Optimism" — cross-chain via LI.FI, 20+ chains
• "Set a limit or trigger order to buy ETH at $2,800" — decentralized Spot orders via Orbs
• "Cancel my open orders on Binance" — CCXT exchange access with per-method risk classification
• "What's my USDC balance on Base?" — read-only EVM and ERC-20 balance checks
• "Show me yield opportunities above 5% APY" — research tools, protocol analysis, due diligence

Common 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.

---

Quickstart for agent power users

npx web3agent init

This detects Claude Code, Cursor, Windsurf, OpenCode, or Codex and configures the MCP server automatically. Restart your host, then ask:

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

For any other MCP-capable host, configure a stdio server that runs:

npx web3agent

The generic MCP config shape is:

{

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

Writes are confirmation-gated by default, and wallet secrets are not exposed through MCP unless explicitly enabled.

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

Smithery local bundle

Smithery 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:

pnpm run mcpb:check

smithery mcp publish dist/web3agent.mcpb -n Apegurus/web3agent

The generated MCPB is a thin local bundle that launches the published npm package with npm exec --package web3agent@0.6.2.

Why Web3Agent

• One-line install. npx web3agent init auto-configures Claude Code, Cursor, Windsurf, OpenCode, or Codex. No manual config edits for supported hosts.
• 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.
• Battle-tested infrastructure. Built on GOAT SDK, LI.FI, Orbs, Blockscout, Etherscan, DexScreener, and other production Web3 rails.
• Live in production. Powers Orbzy and The Arena, where AI agents trade real capital through Web3Agent.
• One MCP surface. Swaps, bridges, orders, market data, research, token resolution, wallet lifecycle, and agent-payment protocols are available through one server.

Who it is for

• AI agent builders who need Web3 execution without rebuilding protocol integrations
• DeFi teams adding MCP support to internal tools, research agents, or trading agents
• Developers prototyping wallet-aware agents, swaps, bridges, and market workflows
• MCP host users who want read-only chain data plus explicit-confirmation write flows

Copy-paste prompts

Use these after installation to get to value quickly:

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

---

Supported hosts

---

Supported chains

Basic EVM operations use viem's chain registry and can target any viem-supported EVM chain when RPC access is available.

Enhanced 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.

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

---

What's included

---

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.

---

Examples

Root examples are included in the npm package:

# 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

The examples default to small USDC-denominated flows and only prepare wallet actions when you pass --prepare.

Quickstart examples

Agent that prepares a swap on Base

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

Agent that prepares a bridge from Ethereum to Arbitrum

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 that monitors a wallet

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

---

For crypto teams

Use 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.

Integration surfaces:

-