Wallet Agent

Wallet Agent

[](https://github.com/wallet-agent/wallet-agent/actions/workflows/ci.yml) [](https://codecov.io/gh/wallet-agent/wallet-agent)

MCP 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.

> ⚠️ WARNING: Beta Software > > 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.

Quick Start

Claude Code

claude mcp add wallet-agent bunx wallet-agent@latest

Verify with /mcp in Claude Code.

Cursor

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "wallet-agent": {
      "command": "bunx",
      "args": ["wallet-agent"]
    }
  }
}

Then restart Cursor.

Usage Examples

Basic Flow

"Connect to 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
"Check my balance"
"Send 0.1 ETH to shanev.eth"
"Switch to Polygon"

Token Operations

"Transfer 100 USDC to 0x..."
"Get my DOGE balance"
"Approve USDC spending for 0xDEX..."

Contract Development with Wagmi

First load your wagmi-generated contracts:

"Load wagmi config from ./src/generated.ts"
"List all available contracts"

Then explore and analyze contracts:

"Extract ABI for MyToken contract in human-readable format"
"List all view functions for MyToken"  
"Analyze MyToken contract capabilities"
"Export MyToken ABI to ./abis/MyToken.json"

Contract Testing & Validation

Test contracts safely without gas costs:

"Test contract function transfer for MyToken"
"Simulate balanceOf function for MyToken with account 0x..."
"Dry run transaction: approve 1000 USDC for 0xDEX..."
"Test contract MyNFT with view functions only"

Example output for contract analysis:

🔬 **Contract Analysis: MyToken**

📊 **Overview:**
- Functions: 15 total
- Events: 3
- Custom Errors: 2

🔧 **Function Breakdown:**
- View (read-only): 8
- Non-payable (state-changing): 6  
- Payable (accepts ETH): 1

🏷️ **Detected Standards:**
- ERC-20
- Ownable

💡 **Recommendations:**
- This is a token contract - use token transfer tools
- This contract has an owner - check ownership functions  
- Contract accepts ETH payments - ensure proper value handling

Supported Chains

Built-in Chains

Wallet Agent includes the following chains by default:

• Anvil (Local, Chain ID: 31337) - Default chain for local development
• Ethereum Mainnet (Chain ID: 1) - Using public RPC
• Sepolia (Chain ID: 11155111) - Ethereum testnet
• Polygon (Chain ID: 137) - Polygon PoS mainnet

⚠️ 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.

Custom Chain Support

Add any EVM-compatible chain with the add_custom_chain tool:

• Local development networks (Anvil, Hardhat, Ganache)
• Layer 2 networks (Base, Arbitrum, Optimism)
• Alternative L1s (BNB Chain, Avalanche)
• Private/enterprise networks

Available Tools

Wallet Management

• connect_wallet - Connect to a wallet using the specified address
• disconnect_wallet - Disconnect the currently connected wallet
• get_accounts - Get the list of available mock accounts
• get_current_account - Get the currently connected account information
• get_wallet_info - Get current wallet configuration info
• get_balance - Get the balance of an address

Transaction Operations

• send_transaction - Send a transaction
• estimate_gas - Estimate gas for a transaction before sending
• get_transaction_status - Get the status of a transaction by its hash
• get_transaction_receipt - Get detailed receipt of a mined transaction
• simulate_transaction - Simulate a contract transaction before sending

Signing

• sign_message - Sign a message with the connected wallet
• sign_typed_data - Sign EIP-712 typed data

Chain Management

• switch_chain - Switch to a different chain
• add_custom_chain - Add a custom EVM-compatible blockchain network
• update_custom_chain - Update an existing custom chain's configuration
• remove_custom_chain - Remove a previously added custom chain

Token Operations (ERC-20)

• transfer_token - Transfer ERC-20 tokens to another address
• approve_token - Approve ERC-20 token spending
• get_token_balance - Get ERC-20 token balance
• get_token_info - Get ERC-20 token information (name, symbol, decimals)

NFT Operations (ERC-721)

• transfer_nft - Transfer an ERC-721 NFT to another address
• get_nft_owner - Get the owner of an ERC-721 NFT
• get_nft_info - Get ERC-721 NFT information (name, symbol, tokenURI)

Contract Operations

• load_wagmi_config - Load contract ABIs from a Wagmi-generated file
• list_contracts - List all available contracts from Wagmi config
• read_contract - Read from a smart contract using Wagmi-generated ABIs
• write_contract - Write to a smart contract using Wagmi-generated ABIs

Contract ABI Analysis

• extract_wagmi_abi - Extract ABI for a specific contract in JSON, TypeScript, or human-readable format
• list_wagmi_functions - List all callable functions for a contract with filtering by mutability
• list_wagmi_events - List all events that a contract can emit
• export_wagmi_abi - Export contract ABI to a file in JSON or TypeScript format
• analyze_wagmi_contract - Analyze contract capabilities and detect standards (ERC-20, ERC-721, etc.)

Contract Testing & Validation

• simulate_contract_call - Simulate contract function calls without gas costs or state changes
• test_contract_function - Generate and run multiple test scenarios for a contract function
• test_contract - Analyze all functions in a contract and provide testing guidance
• dry_run_transaction - Preview transaction effects before execution

Private Key Management

• import_private_key - Import a private key from environment variable or file
• list_imported_wallets - List all imported private key wallets
• remove_private_key - Remove an imported private key
• set_wallet_type - Switch between mock and private key wallets

Encrypted Key Management

• create_encrypted_keystore - Create a new encrypted key store with master password
• unlock_keystore - Unlock encrypted key store for session access
• lock_keystore - Lock key store and clear decrypted keys from memory
• import_encrypted_private_key - Import private key into encrypted store
• list_encrypted_keys - List all encrypted keys (addresses and labels only)
• remove_encrypted_key - Remove encrypted key from store
• update_key_label - Update label for an encrypted key
• change_keystore_password - Change master password for encrypted keys
• get_keystore_status - Get current encrypted key store status

ENS

• resolve_ens_name - Resolve an ENS name to an Ethereum address (mainnet only)

Contract ABI Analysis (Wagmi Integration)

Wallet Agent provides powerful tools for analyzing smart contracts generated by Wagmi. Perfect for developers working with TypeScript contract interactions.

Getting Started

1. Generate contracts with Wagmi CLI:

``bash bunx @wagmi/cli generate ``

1. Load contracts into Wallet Agent:

`` "Load wagmi config from ./src/generated.ts" ``

Key Features

🔍 ABI Extraction

Extract contract ABIs in multiple formats:

"Extract ABI for MyToken in JSON format"
"Extract ABI for MyNFT in TypeScript format" 
"Extract ABI for MyContract in human-readable format"

📋 Function Analysis

Analyze contract functions with filtering:

"List all functions for MyToken"
"List only view functions for MyContract"
"List payable functions for MyPayableContract"

📡 Event Discovery

Discover all contract events:

"List all events for MyToken"

💾 ABI Export

Export ABIs to files for external use:

"Export MyToken ABI to ./abis/MyToken.json"
"Export MyContract ABI to ./types/contracts.ts in TypeScript format"

🔬 Smart Contract Analysis

Get comprehensive contract analysis with standard detection:

"Analyze MyToken contract capabilities"

Detects Standards:

• ERC-20 - Token contracts
• ERC-721 - NFT contracts
• ERC-1155 - Multi-token contracts
• Ownable - Contracts with ownership
• AccessControl - Role-based permissions
• Upgradeable - Proxy patterns

Function Categories:

• View - Read-only functions
• Pure - No state access
• Payable - Accept ETH payments
• Non-payable - State-changing functions

Real-World Examples

Analyzing a DeFi Token

"Load wagmi config from ./src/generated.ts"
"Analyze USDCToken contract capabilities"

Output shows:

• ERC-20 compliance ✓
• 12 functions (8 view, 4 non-payable)
• Standard Transfer/Approval events
• Recommendations for token operations

Working with NFT Collections

"List all functions for MyNFTCollection"
"List all events for MyNFTCollection"  
"Export MyNFTCollection ABI to ./metadata/nft-abi.json"

Perfect for:

• Frontend integration
• Contract verification
• Documentation generation
• Testing preparation

Development Workflow Integration

# After contract deployment
"Load wagmi config from ./src/generated.ts"
"Analyze all contracts"
"Export all ABIs to ./build/contracts/"

# For specific contract work  
"List view functions for MyContract"
"Extract ABI for MyContract in human-readable format"

The human-readable format is perfect for understanding contract interfaces at a glance, while JSON/TypeScript exports integrate seamlessly with your development toolchain.

Contract Testing & Validation

Wallet Agent provides advanced tools for testing smart contracts safely and efficiently. Test contract behavior without spending gas or affecting blockchain state.

Key Features

🧪 Safe Contract Simulation

Test contract functions without gas costs using eth_call:

"Simulate transfer function for MyToken with recipient 0x123... and amount 1000"
"Simulate balanceOf function for MyToken with account 0x456..."

🎯 Automated Test Generation

Generate comprehensive test scenarios automatically:

"Test contract function transfer for MyToken"
"Test contract function approve for MyToken" 

🔍 Contract Function Analysis

Analyze all functions in a contract:

"Test contract MyToken"
"Test contract MyNFT with view functions only"

🔮 Transaction Preview

Preview transaction effects before execution:

"Dry run transaction: transfer 100 USDC to 0x123..."
"Dry run transaction: mint NFT with tokenId 42"

Test Scenarios

The automated test generator creates scenarios based on function parameters:

For functions with numeric parameters:

• ✅ Basic Success - Valid typical values
• ✅ Zero Values - Test with zero amounts
• ✅ Maximum Values - Test with maximum uint256 values

For functions with address parameters:

• ✅ Valid Address - Normal Ethereum addresses
• ❌ Zero Address - Tests 0x0 address handling (expected to fail)

For functions with complex parameters:

• ✅ Mixed Scenarios - Combination of edge cases

Real-World Examples

Testing a DeFi Token Contract

"Load wagmi config from ./src/generated.ts"
"Test contract function transfer for USDCToken"

Sample Output:

🧪 Function Test Results: USDCToken.transfer()

📊 Summary:
- Total Tests: 4
- Passed: 3 ✅  
- Failed: 1 ❌
- Success Rate: 75%

📋 Test Scenarios:

**Basic Success** - ✅ PASS
Test transfer with typical valid inputs
📤 Returned: true

**Zero Values** - ✅ PASS  
Test transfer with zero values for numeric inputs
📤 Returned: true

**Maximum Values** - ✅ PASS
Test transfer with maximum values for numeric inputs
📤 Returned: true

**Zero Address** - ❌ FAIL
Test transfer with zero address (0x0)
🚨 Reason: ERC20: transfer to the zero address

💡 Recommendations:
- Review failed test cases to understand function behavior
- Consider edge cases when calling this function
- Add proper error handling in your application

Simulating Complex DeFi Operations

"Simulate swap function for MyDEX with tokenIn USDC, tokenOut WETH, amount 1000"

Benefits:

• ✅ Gas-free testing - No transaction fees
• ✅ State preservation - Blockchain state unchanged
• ✅ Error detection - Catch reverts before execution
• ✅ Return value preview - See function outputs

Contract Development Workflow

1. Deploy Contract (to testnet/local)

`` "Load wagmi config from ./src/generated.ts" ``

1. Analyze Contract Functions

`` "Test contract MyNewContract" ``

1. Test Critical Functions

`` "Test contract function mint for MyNewContract" "Test contract function burn for MyNewContract" ``

1. Simulate Before Execution

`` "Dry run transaction: mint NFT with tokenId 1 to 0x123..." ``

1. Execute with Confidence

`` "Write contract MyNewContract function mint with args [1, '0x123...']" ``

Security Benefits

Pre-execution Validation

• Revert Detection: Identify transactions that would fail
• Gas Estimation: Preview gas requirements
• Parameter Validation: Test edge cases and invalid inputs
• State Requirements: Verify preconditions are met

Smart Testing

• Automatic Scenarios: No manual test case creation
• Edge Case Coverage: Tests boundary conditions
• Standard Patterns: Recognizes common validation patterns
• Error Analysis: Detailed revert reason extraction

Integration with Development Tools

Perfect for:

• Frontend Development - Test contract calls before user interactions
• Smart Contract Testing - Complement traditional test suites
• DeFi Protocol Integration - Validate complex multi-step operations
• Contract Auditing - Discover edge cases and potential issues
• Documentation - Generate examples of contract behavior

Best Practices

1. Test Before Deploy: Use simulation during contract development
2. Validate User Inputs: Test with edge cases before user interactions
3. Batch Testing: Use test_contract to analyze entire contracts
4. Preview Transactions: Always dry-run high-value operations
5. Document Behavior: Use test results to understand contract logic

The contract testing tools integrate seamlessly with Wagmi ABI extraction, providing a complete contract development and interaction workflow.

User Instructions

Customize wallet behavior using natural language instructions! Create an instructions.md file to personalize how Wallet Agent operates.

Global Instructions

Create ~/.wallet-agent/instructions.md for user-wide preferences:

# My Wallet Instructions

## Gas Settings
- Always use "fast" gas prices for DEX trades
- Use "standard" gas for simple transfers  
- Warn me if gas cost exceeds $20

## Security Rules
- Never approve unlimited token allowances
- Always simulate high-value transactions first
- Require confirmation for new contracts

## Multi-chain Preferences
- Prefer Polygon for small transfers ($1000)

Project Instructions

Create .wallet-agent/instructions.md in your project for context-specific behavior:

# Project Instructions

## For This DApp
- Use conservative gas settings
- Always simulate before executing
- Show detailed transaction breakdowns
- Prefer Layer 2 networks when possible

How It Works

• AI agents automatically read your instructions via the wallet://instructions MCP resource
• Project instructions override global instructions for maximum flexibility
• Instructions are written in plain English - no code required!
• Supports gas preferences, security rules, multi-chain setting

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wallet-agent
• Source: wallet-agent/wallet-agent
• License: MIT
• Homepage: https://wallet-agent.ai/

Install and usage instructions live in the source repository linked above.