agent-wallet (blockchain-skill)

Toolkit that lets any AI agent operate a wallet directly on-chain: create wallets, receive, send, swap, bridge, sign, deploy and verify Solidity contracts, and learn how deployed contracts work. Keys are generated and stored on your own machine (encrypted keystore v3), and transactions go straight to public RPC endpoints. No MetaMask, no exchange, no custodial anything.

Ships three faces over one engine: a CLI (agent-wallet <verb>), an MCP server (stdio), and Claude Code skills. Same verbs, same JSON envelope everywhere.

Install

• CLI: npx agent-wallet help
• Skills: npx skills add hec-ovi/blockchain-skill
• Plugin: /plugin marketplace add hec-ovi/blockchain-skill
• MCP: register the server from .mcp.json (node bin/agent-wallet.ts mcp)

Requires Node >= 22.18 (runs the TypeScript directly). Put secrets in a git-ignored .env (see .env.example); the CLI and MCP server load it automatically. At minimum set AGENT_WALLET_PASSPHRASE (encrypts the keystore).

Capabilities

Area	Verbs	Networks
Wallet	wallet-create, wallet-import, wallet-list, wallet-addresses	EVM + Bitcoin
Read	balance, utxos, fees, tx	EVM + Bitcoin
Send	send (native, ERC-20, BTC, sweep)	EVM + Bitcoin
Swap	swap-quote, swap (CoW, Kyber, Uniswap)	EVM
Bridge	bridge-quote, bridge, bridge-status (LI.FI)	EVM to EVM
Contracts	contract-compile, contract-deploy, contract-call, contract-write, contract-learn	EVM
Funding	faucet (self-serve testnet gas)	Base Sepolia, Ethereum Sepolia

Every default backend is keyless. Optional keys (Etherscan, LI.FI) only raise limits.

Funding (self-serve gas)

An agent can load its own testnet gas headlessly, no captcha or browser, with the faucet verb:

agent-wallet faucet --network base-sepolia --token eth

It uses the Coinbase CDP faucet and needs a free API key (CDP_API_KEY_ID, CDP_API_KEY_SECRET) in .env or ~/.agent-wallet/config.json. Get one at portal.cdp.coinbase.com. Base Sepolia and Ethereum Sepolia are supported, with eth, usdc, eurc, and cbbtc. Bitcoin test faucets still require a human, so use an EVM testnet for automated funding.

Safety

Mainnet is denied until you allow it in ~/.agent-wallet/config.json ({"gate":{"allowMainnet":true}} or a per-chain allowlist, plus optional per-tx caps). Every state-changing operation passes a deterministic gate before anything is signed. Reads are never gated.

What we verified

The toolkit was checked at three levels: an automated suite, live calls against real public networks, and a full run driven by a separate AI agent acting as a first-time user.

Automated suite. npm test runs 95 tests with no external network: schema and contract tests for every layer, key derivation checked against the official BIP-86 and BIP-84 vectors, Bitcoin coin selection, envelope validation, and end-to-end runs of the real CLI and MCP server.

Live public-network checks (opt in with RUN_LIVE=1): balance and tip reads on Ethereum Sepolia and Bitcoin signet, a keyless Sourcify ABI fetch for WETH, and live swap and bridge quotes from CoW, KyberSwap, and LI.FI.

Agent-driven, end to end. A separate model (Claude Haiku), given only the skill and the CLI, was asked in plain language to create a wallet, hand over an address, check a balance, and send funds. Every command it produced was well-formed and correct, the send landed on-chain, and the safety gate refused a mainnet send with a clear reason. One ambiguity showed up (it assumed a network when none was named), so the skill now tells the agent to ask first.

On Base Sepolia (real, clickable). In one run the agent funded a fresh wallet, sent a transfer, deployed the Counter contract, and called increment() (count went from 41 to 42, confirmed by a raw call straight to the chain). It funded itself through the CDP faucet first, with no human faucet visit:

• Wallet: https://sepolia.basescan.org/address/0xE5f6d3E30259EC65CB373de402647DA3D6Bd7E84
• Faucet funding: https://sepolia.basescan.org/tx/0x34adadc142150cbd51bf5c8f44766c5fcd0cc7ae4aeb53ec52247a6af25f6ff5
• Transfer: https://sepolia.basescan.org/tx/0x1e1a51bea96eb6e8b727a0dfcc4a978b2b6ad236ac199f2224d4b48992ad7f97
• Contract: https://sepolia.basescan.org/address/0xbeaf85138e51c30fe3511f78e7bf868356ec7373
• Deploy tx: https://sepolia.basescan.org/tx/0x924108df1061ddd917e0785127512a67027d69f3af326c5952488bcce54d5d10
• increment(): https://sepolia.basescan.org/tx/0xd5e42c9da194487ba261cb6c481cda6a19b7a18c42105a87007c7496ba7236ec

Architecture

Contract-isolated layers under layers/, coupled only through one JSON envelope. Each layer owns its CONTRACT.md, schema/, src/, and tests/. docs/INDEX.md maps what you want to change to the one folder to open. See docs/ARCHITECTURE.md and docs/RESEARCH.md for the design and the 2026 stack choices.

Layer order, easy to hard: core, keys, chains, read, sign, gate, send, learn, contracts, swap, bridge, faucet, agentio (the CLI + MCP surface).