agent-wallet (blockchain-skill)

Toolkit that lets any AI agent operate a wallet directly on-chain: create wallets, receive, send, swap, wrap, 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.

Two faces over one engine: a self-contained CLI (agent-wallet <verb>) and one fat agent skill replicated to every discovery convention (repo root, skills/, Claude and Codex plugin dirs). Same verbs, same JSON envelope everywhere.

Install

Agent CLI (plug and play)

/skills add hec-ovi/blockchain-skill

That copies the skill pack (including the bundled CLI at dist/agent-wallet.mjs) into the workspace. The agent then resolves the CLI, runs agent-wallet init once, and uses the verbs. No second bootstrap script.

Other skill installers: npx skills add hec-ovi/blockchain-skill, Claude /plugin marketplace add hec-ovi/blockchain-skill.

Host CLI (optional)

Requires Node >= 22.18.

npm install
npm run build
./agent-wallet init
./agent-wallet help

Fallback host bootstrap: bash bin/init.sh or curl -fsSL https://raw.githubusercontent.com/hec-ovi/blockchain-skill/HEAD/bin/init.sh | bash.

Put secrets in a git-ignored .env (see .env.example); the CLI loads it automatically. At minimum set AGENT_WALLET_PASSPHRASE (encrypts the keystore).

Related MCP server: waiaas

How agents use it

1. Resolve CLI (on PATH, or .noob/skills/agent-wallet/agent-wallet, or node …/dist/agent-wallet.mjs).

2. agent-wallet init once per session (doctor + data dir).

3. Verbs: wallet-create, wallet-export, balance, send, swap, wrap, contract-*, …

Each verb is one process: JSON envelope on stdout, then exit. Not a long-running server.

Fund testnets by sending from an external wallet or a public testnet drip site. This toolkit does not drip gas.

Capabilities

Every default backend is keyless. Optional Etherscan key only raises contract-learn limits.

Safety

Mainnet and testnets are allowed by default. To lock mainnets, set {"gate":{"allowMainnet":false}} in ~/.agent-wallet/config.json (optional per-chain allowlist and per-tx caps). Every state-changing operation still passes the gate before sign; reads are never gated.

What we verified

Automated suite. npm test builds the bundle, then runs contract tests for every layer, BIP-86/BIP-84 vectors, coin selection, envelope validation, real CLI e2e (source + bundle), and tests/check_skill.sh (skill copies byte-identical, versions lockstep, launcher + dist/agent-wallet.mjs present).

Live public-network checks (opt in with RUN_LIVE=1): Sepolia and Bitcoin signet reads, Sourcify ABI fetch, CoW / Kyber quotes.

Agent benchmark: dual noob peers on Sepolia with a local mid-size model (see bottom of this README).

Architecture

Layers under layers/ each own CONTRACT.md, schema/, src/, and tests/. Cross-layer TypeScript imports are limited to published modules (import-boundary test); the CLI composition root is agentio. Outbound agent I/O is one JSON envelope. See docs/ARCHITECTURE.md and docs/INDEX.md.

Layer order: core, keys, chains, read, sign, gate, send, learn, contracts, swap, agentio (CLI + init).

Release artifact: npm run build writes dist/agent-wallet.mjs (single Node ESM file). Skill installs and the package ship that file so agents need only Node.

Agent benchmark: dual noob peers on Sepolia

Live end-to-end of agent-wallet 0.4.2 through the noob agent CLI (not a scripted harness that calls verbs for the agent). Two workspaces, two wallets, natural-language prompts. Every tx below confirmed on Ethereum Sepolia.

Setup

Out of scope for this run: Solidity authoring / deploy / write, Bitcoin, mainnet.

Keys in per-workspace keystore v3; gas funded externally (toolkit has no faucet). Agent ran init, then verbs from short English prompts (send …, wrap …, swap exactly …, send … USDC …).

On-chain matrix (agent-driven)

Also agent-OK (reads): balance (native + token), fees, chain-check, tx, swap-quote, contract-learn (WETH), wallet-export.

Sepolia WETH 0x7b79995e5f793A07Bc00c21412e50Ecae098E7f9, USDC 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238.

Date: 2026-07-27 · agent-wallet 0.4.2 · noob 0.5.1 · model Qwen3.6-35B-A3B Q8_0 local.