web3Agent

Deploy autonomous AI agents on Arbitrum with isolated wallets, onchain actions, and ERC-8004 identity registration

Warning

EXPERIMENTAL, NOT FOR PRODUCTION USE Use at your own risk. Do not use with real funds without fully understanding the code.

---

Quick Start

# 1. Clone and install
git clone https://github.com/anthropics/web3agent.git
cd web3agent
npm install

# 2. Setup master wallet (generates key, shows QR code)
npm run setup

# 3. Configure .env
#    - Add your OPENROUTER_API_KEY (or ANTHROPIC_API_KEY / OPENAI_API_KEY)
#    - Add your RPC_URL (Alchemy endpoint for Arbitrum Sepolia)
#    - MASTER_PRIVATE_KEY is auto-generated by setup

# 4. Create an agent (interactive: pick actions/tools, fund, register, chat)
npm run create-agent

---

What It Does

• Deploy agents, create isolated wallets, fund from a master wallet, register on ERC-8004, and start chatting, all in one command.
• Three-level actions, composable onchain actions built on viem and LangChain. Level 1 (Actions) bundles tools + skills for quick setup. Level 2 (Tools) gives standalone DynamicStructuredTool instances. Level 3 (Dynamic) generates tools from any contract ABI.
• Multi-provider LLM, works with OpenRouter (default, auto-routes to best model), Anthropic (Claude), or OpenAI. Uses the @openrouter/sdk natively.

---

Architecture

web3agent/
  src/
    core/
      config.ts         Network & RPC configuration
      wallet.ts         Agent + master wallet management
      orchestrator.ts   LangChain agent orchestration
      llm.ts            Multi-provider LLM (OpenRouter, Anthropic, OpenAI)
      agent-skills.ts   Skill discovery & dynamic loading
      registry.ts       ERC-8004 registration
      types.ts          Shared types
    actions/
      index.ts          Exports all three levels + action factories
      types.ts          Skill & Action interfaces
      tools/
        send-eth.tool.ts            Send ETH (viem + DynamicStructuredTool)
        token-balance.tool.ts       Check ETH/ERC-20 balances
        fetch-contract-abi.tool.ts  Fetch ABI from block explorer (experimental)
        call-contract.tool.ts       Call any verified contract function (experimental)
      skills/
        transfer-eth.skill.ts   Agent prompt context for ETH transfers
        token-balance.skill.ts  Agent prompt context for balance checks
    cli/
      create-agent.ts   Interactive agent builder (wallet + fund + register + chat)
      chat.ts           Interactive chat with an existing agent
      setup.ts          First-run master wallet setup
      test-workflow.ts  End-to-end test
    index.ts            Public API barrel
  agents/               Runtime data (gitignored)
    <agent-name>/
      wallet.json       Agent private key (never committed)

---

CLI Commands

npm run create-agent

Interactive agent builder: prompts for name, lets you pick actions and tools, funds the agent, registers on ERC-8004, and opens chat.

npm run create-agent                                    # fully interactive
npm run create-agent -- --name my-agent                 # skip name prompt
npm run create-agent -- --name my-agent --fund 0.005    # custom fund amount
npm run create-agent -- --name my-agent --skip-register # skip ERC-8004

npm run deploy

Legacy deploy (no action selection). Creates wallet, funds, registers, and opens chat.

npm run deploy -- --name my-agent

npm run chat

Open an interactive chat with an existing agent. Loads actions from agent-config.json if available.

npm run chat -- --agent my-agent

npm run setup

First-run setup. Generates a master wallet private key, saves it to .env, and displays a QR code for funding.

npm run test

End-to-end test: creates an agent, funds it, and asks the agent to check its balance.

---

Actions

Actions use a three-level architecture. See src/actions/README.md for full documentation.

Level 1 — Actions (quick setup)

Import a bundled action and hand it to your agent:

import { TransferEthAction } from "web3agent"

const transfer = TransferEthAction()
const tools = transfer.tools // includes send_eth + get_token_balance
const systemPrompt = transfer.skill.context

Level 2 — Tools (standalone)

Use individual tools without the skill wrapper:

import { sendEthTool, tokenBalanceTool } from "web3agent"

Level 3 — Dynamic (any contract)

The agent discovers and calls any verified contract at runtime:

import { fetchContractAbiTool, callContractTool } from "web3agent"
// Agent calls fetch_contract_abi to discover functions, then call_contract to execute

Available Actions

Action	Tools	Description
TransferEthAction()	send_eth, get_token_balance	Transfer ETH with balance checks and safety confirmations

---

Environment Variables

Copy .env.example to .env and fill in:

Variable	Required	Description
LLM_PROVIDER	No	openrouter (default), anthropic, or openai
OPENROUTER_API_KEY	If using OpenRouter	Get one at openrouter.ai/keys
ANTHROPIC_API_KEY	If using Anthropic	Get one at console.anthropic.com
OPENAI_API_KEY	If using OpenAI	Get one at platform.openai.com
LLM_MODEL	No	Override default model (e.g. anthropic/claude-sonnet-4)
RPC_URL	Yes	Full RPC endpoint URL (e.g. Alchemy)
MASTER_PRIVATE_KEY	Yes	Auto-generated by npm run setup
NETWORK	No	arbitrum-sepolia (default), arbitrum-one, robinhood-testnet
ARBISCAN_API_KEY	No	For contract ABI tools, higher rate limits on Arbiscan API

---

Networks

Network	Chain ID	Status
Arbitrum Sepolia	421614	Default, recommended for development
Arbitrum One	42161	Mainnet
Robinhood Testnet	23888	Experimental

---

Security

• Never commit .env or agents/*/wallet.json — both are in .gitignore
• The master wallet private key is used only to fund agent wallets
• Agent private keys are stored locally in agents/<name>/wallet.json
• Agent runtime data in agents/ is gitignored

---

License

Apache 2.0, see LICENSE.