{"id":"22517297-7ffc-4817-baae-8c5aa3569692","slug":"wallet-agent","kind":"mcp","name":"wallet-agent","summary":"MCP server for Web3 wallet interactions on EVM-compatible chains","owner":"wallet-agent","repoUrl":"https://github.com/wallet-agent/wallet-agent","license":"MIT","licenseTier":"permissive","trust":"community","stars":6,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-08-04T06:14:05.000Z","addedAt":"2026-10-21T08:01:06.181Z","logoUrl":"https://avatars.githubusercontent.com/u/224811987?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","data-analytics"],"tags":["blockchain","ethereum","evm","wagmi","wallet","web3"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T02:15:47.011Z","sample":false,"url":"https://conduits.dev/tools/wallet-agent","language":"TypeScript","transports":["stdio"],"install":{"npm":"wallet-agent"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Wallet Agent\n\n![WalletAgent](https://wallet-agent.ai/og-image.png)\n\n[![CI](https://github.com/wallet-agent/wallet-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/wallet-agent/wallet-agent/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/wallet-agent/wallet-agent/graph/badge.svg)](https://codecov.io/gh/wallet-agent/wallet-agent)\n\nMCP server enabling Web3 wallet interactions in AI tools such as Claude Code and Cursor, with support for mock wallets during testing and real wallets via private-key import.\n\n> ⚠️ **WARNING: Beta Software** \n> \n> This is beta software under active development. **DO NOT use on mainnet or with wallets containing real funds.** This software has not been audited and may contain bugs that could result in loss of funds. Use only on testnets or local development environments.\n\n## Quick Start\n\n### Claude Code\n\n```bash\nclaude mcp add wallet-agent bunx wallet-agent@latest\n```\n\nVerify with `/mcp` in Claude Code.\n\n### Cursor\n\nAdd to your `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"wallet-agent\": {\n      \"command\": \"bunx\",\n      \"args\": [\"wallet-agent\"]\n    }\n  }\n}\n```\n\nThen restart Cursor.\n\n## Usage Examples\n\n### Basic Flow\n```\n\"Connect to 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266\"\n\"Check my balance\"\n\"Send 0.1 ETH to shanev.eth\"\n\"Switch to Polygon\"\n```\n\n### Token Operations\n```\n\"Transfer 100 USDC to 0x...\"\n\"Get my DOGE balance\"\n\"Approve USDC spending for 0xDEX...\"\n```\n\n### Contract Development with Wagmi\nFirst load your wagmi-generated contracts:\n```\n\"Load wagmi config from ./src/generated.ts\"\n\"List all available contracts\"\n```\n\nThen explore and analyze contracts:\n```\n\"Extract ABI for MyToken contract in human-readable format\"\n\"List all view functions for MyToken\"  \n\"Analyze MyToken contract capabilities\"\n\"Export MyToken ABI to ./abis/MyToken.json\"\n```\n\n### Contract Testing & Validation\nTest contracts safely without gas costs:\n```\n\"Test contract function transfer for MyToken\"\n\"Simulate balanceOf function for MyToken with account 0x...\"\n\"Dry run transaction: approve 1000 USDC for 0xDEX...\"\n\"Test contract MyNFT with view functions only\"\n```\n\nExample output for contract analysis:\n```\n🔬 **Contract Analysis: MyToken**\n\n📊 **Overview:**\n- Functions: 15 total\n- Events: 3\n- Custom Errors: 2\n\n🔧 **Function Breakdown:**\n- View (read-only): 8\n- Non-payable (state-changing): 6  \n- Payable (accepts ETH): 1\n\n🏷️ **Detected Standards:**\n- ERC-20\n- Ownable\n\n💡 **Recommendations:**\n- This is a token contract - use token transfer tools\n- This contract has an owner - check ownership functions  \n- Contract accepts ETH payments - ensure proper value handling\n```\n\n## Supported Chains\n\n### Built-in Chains\nWallet Agent includes the following chains by default:\n- **Anvil** (Local, Chain ID: 31337) - Default chain for local development\n- **Ethereum Mainnet** (Chain ID: 1) - Using public RPC\n- **Sepolia** (Chain ID: 11155111) - Ethereum testnet\n- **Polygon** (Chain ID: 137) - Polygon PoS mainnet\n\n⚠️ **Note**: Built-in chains use public RPC endpoints which may have rate limits. For production use, consider adding custom chains with your own RPC endpoints.\n\n### Custom Chain Support\nAdd any EVM-compatible chain with the `add_custom_chain` tool:\n- Local development networks (Anvil, Hardhat, Ganache)\n- Layer 2 networks (Base, Arbitrum, Optimism)\n- Alternative L1s (BNB Chain, Avalanche)\n- Private/enterprise networks\n\n## Available Tools\n\n### Wallet Management\n- `connect_wallet` - Connect to a wallet using the specified address\n- `disconnect_wallet` - Disconnect the currently connected wallet\n- `get_accounts` - Get the list of available mock accounts\n- `get_current_account` - Get the currently connected account information\n- `get_wallet_info` - Get current wallet configuration info\n- `get_balance` - Get the balance of an address\n\n### Transaction Operations\n- `send_transaction` - Send a transaction\n- `estimate_gas` - Estimate gas for a transaction before sending\n- `get_transaction_status` - Get the status of a transaction by its hash\n- `get_transaction_receipt` - Get detailed receipt of a mined transaction\n- `simulate_transaction` - Simulate a contract transaction before sending\n\n### Signing\n- `sign_message` - Sign a message with the connected wallet\n- `sign_typed_data` - Sign EIP-712 typed data\n\n### Chain Management\n- `switch_chain` - Switch to a different chain\n- `add_custom_chain` - Add a custom EVM-compatible blockchain network\n- `update_custom_chain` - Update an existing custom chain's configuration\n- `remove_custom_chain` - Remove a previously added custom chain\n\n### Token Operations (ERC-20)\n- `transfer_token` - Transfer ERC-20 tokens to another address\n- `approve_token` - Approve ERC-20 token spending\n- `get_token_balance` - Get ERC-20 token balance\n- `get_token_info` - Get ERC-20 token information (name, symbol, decimals)\n\n### NFT Operations (ERC-721)\n- `transfer_nft` - Transfer an ERC-721 NFT to another address\n- `get_nft_owner` - Get the owner of an ERC-721 NFT\n- `get_nft_info` - Get ERC-721 NFT information (name, symbol, tokenURI)\n\n### Contract Operations\n- `load_wagmi_config` - Load contract ABIs from a Wagmi-generated file\n- `list_contracts` - List all available contracts from Wagmi config\n- `read_contract` - Read from a smart contract using Wagmi-generated ABIs\n- `write_contract` - Write to a smart contract using Wagmi-generated ABIs\n\n### Contract ABI Analysis\n- `extract_wagmi_abi` - Extract ABI for a specific contract in JSON, TypeScript, or human-readable format\n- `list_wagmi_functions` - List all callable functions for a contract with filtering by mutability\n- `list_wagmi_events` - List all events that a contract can emit\n- `export_wagmi_abi` - Export contract ABI to a file in JSON or TypeScript format\n- `analyze_wagmi_contract` - Analyze contract capabilities and detect standards (ERC-20, ERC-721, etc.)\n\n### Contract Testing & Validation\n- `simulate_contract_call` - Simulate contract function calls without gas costs or state changes\n- `test_contract_function` - Generate and run multiple test scenarios for a contract function\n- `test_contract` - Analyze all functions in a contract and provide testing guidance\n- `dry_run_transaction` - Preview transaction effects before execution\n\n### Private Key Management\n- `import_private_key` - Import a private key from environment variable or file\n- `list_imported_wallets` - List all imported private key wallets\n- `remove_private_key` - Remove an imported private key\n- `set_wallet_type` - Switch between mock and private key wallets\n\n### Encrypted Key Management\n- `create_encrypted_keystore` - Create a new encrypted key store with master password\n- `unlock_keystore` - Unlock encrypted key store for session access\n- `lock_keystore` - Lock key store and clear decrypted keys from memory\n- `import_encrypted_private_key` - Import private key into encrypted store\n- `list_encrypted_keys` - List all encrypted keys (addresses and labels only)\n- `remove_encrypted_key` - Remove encrypted key from store\n- `update_key_label` - Update label for an encrypted key\n- `change_keystore_password` - Change master password for encrypted keys\n- `get_keystore_status` - Get current encrypted key store status\n\n### ENS\n- `resolve_ens_name` - Resolve an ENS name to an Ethereum address (mainnet only)\n\n## Contract ABI Analysis (Wagmi Integration)\n\nWallet Agent provides powerful tools for analyzing smart contracts generated by Wagmi. Perfect for developers working with TypeScript contract interactions.\n\n### Getting Started\n\n1. **Generate contracts with Wagmi CLI**:\n   ```bash\n   bunx @wagmi/cli generate\n   ```\n\n2. **Load contracts into Wallet Agent**:\n   ```\n   \"Load wagmi config from ./src/generated.ts\"\n   ```\n\n### Key Features\n\n#### 🔍 **ABI Extraction**\nExtract contract ABIs in multiple formats:\n```\n\"Extract ABI for MyToken in JSON format\"\n\"Extract ABI for MyNFT in TypeScript format\" \n\"Extract ABI for MyContract in human-readable format\"\n```\n\n#### 📋 **Function Analysis**\nAnalyze contract functions with filtering:\n```\n\"List all functions for MyToken\"\n\"List only view functions for MyContract\"\n\"List payable functions for MyPayableContract\"\n```\n\n#### 📡 **Event Discovery**\nDiscover all contract events:\n```\n\"List all events for MyToken\"\n```\n\n#### 💾 **ABI Export**\nExport ABIs to files for external use:\n```\n\"Export MyToken ABI to ./abis/MyToken.json\"\n\"Export MyContract ABI to ./types/contracts.ts in TypeScript format\"\n```\n\n#### 🔬 **Smart Contract Analysis**\nGet comprehensive contract analysis with standard detection:\n```\n\"Analyze MyToken contract capabilities\"\n```\n\n**Detects Standards:**\n- **ERC-20** - Token contracts\n- **ERC-721** - NFT contracts  \n- **ERC-1155** - Multi-token contracts\n- **Ownable** - Contracts with ownership\n- **AccessControl** - Role-based permissions\n- **Upgradeable** - Proxy patterns\n\n**Function Categories:**\n- **View** - Read-only functions\n- **Pure** - No state access\n- **Payable** - Accept ETH payments\n- **Non-payable** - State-changing functions\n\n### Real-World Examples\n\n#### Analyzing a DeFi Token\n```\n\"Load wagmi config from ./src/generated.ts\"\n\"Analyze USDCToken contract capabilities\"\n```\n\nOutput shows:\n- ERC-20 compliance ✓\n- 12 functions (8 view, 4 non-payable)\n- Standard Transfer/Approval events\n- Recommendations for token operations\n\n#### Working with NFT Collections\n```\n\"List all functions for MyNFTCollection\"\n\"List all events for MyNFTCollection\"  \n\"Export MyNFTCollection ABI to ./metadata/nft-abi.json\"\n```\n\nPerfect for:\n- Frontend integration\n- Contract verification\n- Documentation generation\n- Testing preparation\n\n#### Development Workflow Integration\n```\n# After contract deployment\n\"Load wagmi config from ./src/generated.ts\"\n\"Analyze all contracts\"\n\"Export all ABIs to ./build/contracts/\"\n\n# For specific contract work  \n\"List view functions for MyContract\"\n\"Extract ABI for MyContract in human-readable format\"\n```\n\nThe human-readable format is perfect for understanding contract interfaces at a glance, while JSON/TypeScript exports integrate seamlessly with your development toolchain.\n\n## Contract Testing & Validation\n\nWallet Agent provides advanced tools for testing smart contracts safely and efficiently. Test contract behavior without spending gas or affecting blockchain state.\n\n### Key Features\n\n#### 🧪 **Safe Contract Simulation**\nTest contract functions without gas costs using `eth_call`:\n```\n\"Simulate transfer function for MyToken with recipient 0x123... and amount 1000\"\n\"Simulate balanceOf function for MyToken with account 0x456...\"\n```\n\n#### 🎯 **Automated Test Generation**\nGenerate comprehensive test scenarios automatically:\n```\n\"Test contract function transfer for MyToken\"\n\"Test contract function approve for MyToken\" \n```\n\n#### 🔍 **Contract Function Analysis**\nAnalyze all functions in a contract:\n```\n\"Test contract MyToken\"\n\"Test contract MyNFT with view functions only\"\n```\n\n#### 🔮 **Transaction Preview**\nPreview transaction effects before execution:\n```\n\"Dry run transaction: transfer 100 USDC to 0x123...\"\n\"Dry run transaction: mint NFT with tokenId 42\"\n```\n\n### Test Scenarios\n\nThe automated test generator creates scenarios based on function parameters:\n\n**For functions with numeric parameters:**\n- ✅ **Basic Success** - Valid typical values\n- ✅ **Zero Values** - Test with zero amounts\n- ✅ **Maximum Values** - Test with maximum uint256 values\n\n**For functions with address parameters:**\n- ✅ **Valid Address** - Normal Ethereum addresses\n- ❌ **Zero Address** - Tests `0x0` address handling (expected to fail)\n\n**For functions with complex parameters:**\n- ✅ **Mixed Scenarios** - Combination of edge cases\n\n### Real-World Examples\n\n#### Testing a DeFi Token Contract\n\n```\n\"Load wagmi config from ./src/generated.ts\"\n\"Test contract function transfer for USDCToken\"\n```\n\n**Sample Output:**\n```\n🧪 Function Test Results: USDCToken.transfer()\n\n📊 Summary:\n- Total Tests: 4\n- Passed: 3 ✅  \n- Failed: 1 ❌\n- Success Rate: 75%\n\n📋 Test Scenarios:\n\n**Basic Success** - ✅ PASS\nTest transfer with typical valid inputs\n📤 Returned: true\n\n**Zero Values** - ✅ PASS  \nTest transfer with zero values for numeric inputs\n📤 Returned: true\n\n**Maximum Values** - ✅ PASS\nTest transfer with maximum values for numeric inputs\n📤 Returned: true\n\n**Zero Address** - ❌ FAIL\nTest transfer with zero address (0x0)\n🚨 Reason: ERC20: transfer to the zero address\n\n💡 Recommendations:\n- Review failed test cases to understand function behavior\n- Consider edge cases when calling this function\n- Add proper error handling in your application\n```\n\n#### Simulating Complex DeFi Operations\n\n```\n\"Simulate swap function for MyDEX with tokenIn USDC, tokenOut WETH, amount 1000\"\n```\n\n**Benefits:**\n- ✅ **Gas-free testing** - No transaction fees\n- ✅ **State preservation** - Blockchain state unchanged  \n- ✅ **Error detection** - Catch reverts before execution\n- ✅ **Return value preview** - See function outputs\n\n#### Contract Development Workflow\n\n1. **Deploy Contract** (to testnet/local)\n   ```\n   \"Load wagmi config from ./src/generated.ts\"\n   ```\n\n2. **Analyze Contract Functions** \n   ```\n   \"Test contract MyNewContract\"\n   ```\n\n3. **Test Critical Functions**\n   ```\n   \"Test contract function mint for MyNewContract\"\n   \"Test contract function burn for MyNewContract\"\n   ```\n\n4. **Simulate Before Execution**\n   ```\n   \"Dry run transaction: mint NFT with tokenId 1 to 0x123...\"\n   ```\n\n5. **Execute with Confidence**\n   ```\n   \"Write contract MyNewContract function mint with args [1, '0x123...']\"\n   ```\n\n### Security Benefits\n\n#### Pre-execution Validation\n- **Revert Detection**: Identify transactions that would fail\n- **Gas Estimation**: Preview gas requirements\n- **Parameter Validation**: Test edge cases and invalid inputs\n- **State Requirements**: Verify preconditions are met\n\n#### Smart Testing\n- **Automatic Scenarios**: No manual test case creation\n- **Edge Case Coverage**: Tests boundary conditions\n- **Standard Patterns**: Recognizes common validation patterns\n- **Error Analysis**: Detailed revert reason extraction\n\n### Integration with Development Tools\n\nPerfect for:\n- **Frontend Development** - Test contract calls before user interactions\n- **Smart Contract Testing** - Complement traditional test suites  \n- **DeFi Protocol Integration** - Validate complex multi-step operations\n- **Contract Auditing** - Discover edge cases and potential issues\n- **Documentation** - Generate examples of contract behavior\n\n### Best Practices\n\n1. **Test Before Deploy**: Use simulation during contract development\n2. **Validate User Inputs**: Test with edge cases before user interactions\n3. **Batch Testing**: Use `test_contract` to analyze entire contracts\n4. **Preview Transactions**: Always dry-run high-value operations\n5. **Document Behavior**: Use test results to understand contract logic\n\nThe contract testing tools integrate seamlessly with Wagmi ABI extraction, providing a complete contract development and interaction workflow.\n\n## User Instructions\n\nCustomize wallet behavior using natural language instructions! Create an `instructions.md` file to personalize how Wallet Agent operates.\n\n### Global Instructions\nCreate `~/.wallet-agent/instructions.md` for user-wide preferences:\n\n```markdown\n# My Wallet Instructions\n\n## Gas Settings\n- Always use \"fast\" gas prices for DEX trades\n- Use \"standard\" gas for simple transfers  \n- Warn me if gas cost exceeds $20\n\n## Security Rules\n- Never approve unlimited token allowances\n- Always simulate high-value transactions first\n- Require confirmation for new contracts\n\n## Multi-chain Preferences\n- Prefer Polygon for small transfers (<$100)\n- Use Arbitrum for DeFi to save fees\n- Default to mainnet for large transfers (>$1000)\n```\n\n### Project Instructions\nCreate `.wallet-agent/instructions.md` in your project for context-specific behavior:\n\n```markdown\n# Project Instructions\n\n## For This DApp\n- Use conservative gas settings\n- Always simulate before executing\n- Show detailed transaction breakdowns\n- Prefer Layer 2 networks when possible\n```\n\n### How It Works\n- AI agents automatically read your instructions via the `wallet://instructions` MCP resource\n- **Project instructions override global instructions** for maximum flexibility\n- Instructions are written in plain English - no code required!\n- Supports gas preferences, security rules, multi-chain settings, error handling, and more\n\n### Example Customizations\n- **Gas Strategy**: \"Use slow gas for non-urgent transactions\"\n- **Security**: \"Always double-check recipient addresses\"  \n- **Multi-chain**: \"Prefer Polygon for transfers under $50\"\n- **Error Handling**: \"Auto-retry failed transactions with 10% higher gas\"\n- **Display**: \"Show both ETH and USD values for all transactions\"\n\nThe AI agent will automatically apply your preferences when performing wallet operations!\n\n## Real Wallets (Development Only)\n\n⚠️ **NEVER paste private keys in chat!**\n\n### Option 1: Encrypted Key Store (Recommended)\nThe most secure way to manage private keys:\n\n```bash\n# Create encrypted key store\n\"Create encrypted keystore with master password\"\n\"Import encrypted private key from WALLET_PRIVATE_KEY with master password\"\n\"Set wallet type to privateKey\"\n\"Connect to my wallet\"\n```\n\n**Security Features:**\n- AES-256-GCM authenticated encryption\n- PBKDF2 key derivation (100,000 iterations)  \n- Session-based access (30-minute timeout)\n- Automatic memory clearing on lock\n- File stored with restrictive permissions\n\n### Option 2: Environment Variable\n```bash\n# When adding server\nclaude mcp add wallet-agent bunx wallet-agent -e WALLET_PRIVATE_KEY=0x...\n\n# Or in shell\nexport WALLET_PRIVATE_KEY=\"0x...\"\n```\nThen: \"Import private key from WALLET_PRIVATE_KEY\"\n\n### Option 3: Secure File\n```bash\necho \"0x...\" > ~/.wallet-key\nchmod 600 ~/.wallet-key\n```\nThen: \"Import private key from ~/.wallet-key\"\n\n### Standard Workflow\n1. \"Set wallet type to privateKey\" \n2. \"Connect to my wallet\"\n3. Use normally\n\n## Mock Accounts\n\nPre-configured for testing:\n- `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`\n- `0x70997970C51812dc3A010C7d01b50e0d17dc79C8`\n- `0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC`\n\n## Development\n\n```bash\ngit clone https://github.com/wallet-agent/wallet-agent.git\ncd wallet-agent\nbun install\nbun run dev\n```\n\nFor local testing:\n```bash\nclaude mcp add wallet-agent bun /path/to/wallet-agent/dist/index.ts\n```\n\n### Testing\n\nSee the [Testing Guide](test/README.md) for comprehensive testing documentation, including:\n- Running tests in mock and real blockchain modes\n- Testing with Anvil\n- Writing new tests\n- CI/CD integration\n\n## Security\n\n### Encrypted Key Management\n- **AES-256-GCM**: Industry-standard authenticated encryption\n- **PBKDF2**: 100,000 iterations for key derivation (OWASP recommended)\n- **Session Security**: 30-minute timeout with automatic lock\n- **Memory Protection**: Keys cleared on session end\n- **File Security**: Restrictive permissions (600) on encrypted storage\n\n### General Security\n- Private keys never logged or transmitted over network\n- Support for environment variables and secure file storage\n- Mock wallets for safe testing\n- Use testnets for development\n- Audit code before mainnet use\n"}