What is web3agent?
web3agent is an open-source package that gives AI coding agents full blockchain capabilities. One install. One command. Over 100 tools covering swaps, bridges, wallet management, on-chain data, market research, and the emerging agentic economy.
It works as an MCP proxy server that AI hosts like Claude Code, Cursor, and Windsurf discover automatically, and as a programmatic SDK that TypeScript projects import directly.
web3agent requires Node.js 22 or later. Earlier versions are not supported. Run node --version to check before installing.
Three ways to use it
1. MCP server (recommended for AI agents)
The primary use case. Start the server and your AI host discovers all tools automatically via the MCP protocol over stdio transport.
npx web3agent init # auto-detects your AI host and writes the config
npx web3agent # starts the MCP stdio server
Once running, your AI agent can call tools like orbs_swap, evm_read_contract, blockscout_get_address, and 100+ others without any additional setup.
2. Programmatic SDK
For TypeScript projects that need blockchain capabilities at the code level, install web3agent as a dependency and import functions directly.
npm install web3agent
import { prepareSwapIntent, getSwapQuote, resolveToken } from "web3agent";
const quote = await getSwapQuote({
fromToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
toToken: "0x4200000000000000000000000000000000000006", // WETH on Base
fromAmount: "100000000", // 100 USDC (6 decimals)
chainId: 8453,
});
3. CLI fallback
For quick inspection and scripting without a running server, the CLI exposes every tool directly.
npx web3agent tool call server_status --input '{}' --json
npx web3agent tools list --json
npx web3agent tools describe resolve_token --json
What it can do
Token swaps and orders
Powered by Orbs Protocol (Liquidity Hub, dTWAP, dLIMIT, Spot orders):
- Same-chain swaps with aggregated liquidity
- Time-weighted average price (TWAP) orders that split large trades over time
- Limit orders that execute at a target price
- Stop-loss and take-profit orders
- Order status polling and history
Cross-chain bridges
Powered by LI.FI, covering 20+ chains:
- Bridge quotes with fee and time estimates
- Bridge execution with status tracking
- Intent-based bridging for browser-wallet signing flows
Contract interaction
Powered by viem and the GOAT SDK:
- Read any contract function (
evm_read_contract) - Write to contracts with confirmation gating (
evm_write_contract) - Deploy contracts from bytecode
- ENS name resolution and reverse lookup
- ERC-20 transfers and approvals
- Uniswap and Balancer pool interactions
- Gas estimation and simulation
Blockchain data
Powered by Blockscout (indexed data) and viem (live on-chain state):
- Account balances, transaction history, token holdings
- NFT metadata and ownership
- Contract ABIs and source code verification status
- Block data and event logs
- Token transfers and approvals
Market data and research
Powered by CoinGecko, DexScreener, and 0x:
- Token prices, TVL, trading volumes
- Protocol sentiment and trending tokens
- Yield opportunities and liquidity pool data
- Security analysis and holder distribution
- Governance proposals and voting data
Wallet management
- Generate and activate wallets
- Derive addresses from mnemonics
- Confirmation queue for write operations (enabled by default)
- Treasury policy engine with per-transaction and daily USD limits
Agentic economy
- ACP (Agent Cooperation Protocol): create, fund, and complete agent jobs via Virtuals ACPRouter
- aGDP: hire agents and manage offerings on the Virtuals marketplace
- ERC-8004: on-chain agent identity and reputation registry
- X-402: HTTP-native stablecoin payments for agents
Supported chains
web3agent supports 17 EVM-compatible chains. The default is Base (8453).
| Chain | Chain ID |
|---|---|
| Ethereum | 1 |
| Base | 8453 (default) |
| Arbitrum | 42161 |
| Optimism | 10 |
| Polygon | 137 |
| Linea | 59144 |
| BSC | 56 |
| Avalanche | 43114 |
| zkSync Era | 324 |
| Scroll | 534352 |
| Mode | 34443 |
| Blast | 81457 |
| Mantle | 5000 |
| Celo | 42220 |
| Gnosis | 100 |
| Sepolia | 11155111 |
| Base Sepolia | 84532 |
Override the default with the CHAIN_ID environment variable, or pass chainId as a parameter on any individual tool call.
Integration map
| Integration | Tool prefix | What it provides |
|---|---|---|
| Orbs Protocol | orbs_ | Liquidity Hub swaps, dTWAP, dLIMIT, Spot orders |
| LI.FI | lifi_ | Cross-chain bridges and swaps |
| GOAT SDK | varies | Uniswap, Balancer, ERC-20/721, ENS, DexScreener, 0x, CoinGecko |
| Blockscout | blockscout_ | Indexed blockchain data |
| EVM (viem) | evm_ | Live on-chain state, contract reads/writes, gas |
| ACP | acp_ | Agent Cooperation Protocol jobs |
| aGDP | agdp_ | Agent marketplace |
| ERC-8004 | erc8004_ | On-chain agent identity |
| X-402 | x402_ | HTTP-native stablecoin payments |
Quick start
# Install for your AI host (auto-detects Claude Code, Cursor, Windsurf, etc.)
npx web3agent init
# Start the MCP server
npx web3agent
# Verify it's working
npx web3agent tool call server_status --input '{}' --json
That's it. Your AI agent now has full blockchain access.
Project details
| Version | 0.4.0 |
| License | MIT |
| Runtime | Node.js 22+ |
| Language | TypeScript (ESM) |
| Package | npm: web3agent |
| Source | github.com/Apegurus/web3agent |
| Author | Apeguru |