MCW (Multi-Chain CLI Wallet & Agentic Framework)

A non-custodial multi-chain wallet, HD sub-account engine, multi-seed profile manager, DEX aggregator, and agentic framework for Bitcoin, Ethereum, Solana, and Tron. Built for humans via an interactive CLI and for AI agents via Model Context Protocol (MCP).

---

🌟 Key Features

• 🔑 Single Seed, 4 Blockchains: Deterministically derives Bitcoin (tb1q/bc1q), Ethereum (0x...), Solana (Base58), and Tron (T...) addresses from a single BIP-39 mnemonic phrase.
• 👤 BIP-44 HD Sub-Account Indexing (mcw account): Derive infinite independent sub-accounts (Account #0, #1, #2...) from a single seed phrase without needing new backups.
• 💼 Multi-Seed Profile Vaults (mcw wallet): Manage multiple completely separate seed phrases (e.g. trading-bot, personal, client-vault) with isolated encryption keys.
• 🛡️ Policy Guardrails & Spend Limits (mcw policy): Protect against rogue agent actions with per-transaction limits, 24-hour rolling spend caps, and address whitelists/blacklists.
• 🔄 Built-in DEX Aggregator (mcw swap): Automated testnet/mainnet swap routing across Uniswap V3 (EVM) and Jupiter Aggregator (Solana).
• 🔬 Pre-Flight Transaction Simulation: Dry-run transactions using eth_call and Solana simulateTransaction before broadcast to view gas consumption and asset deltas.
• 🪙 Multi-Chain Smart Contract Tokens: Track, auto-detect, and transfer ERC-20 (Ethereum/Sepolia/L2s), SPL (Solana Devnet/Mainnet), and TRC-20 (Tron Shasta/Nile/Mainnet) tokens.
• 📜 Local Audit Memory (mcw history): Persistent logging of all agent transactions, swaps, and memos for multi-session agent recall.
• 🔐 Gnosis Safe Multisig Integration (mcw safe): Formulate multi-sig proposals and generate EIP-712 typed data for hardware wallet (Ledger/Trezor) approval.
• 🤖 Standard MCP Daemon (20+ Tools): Exposes JSON-RPC tools for AI agents (Claude Code, Cursor, Grok, Gemini CLI).
• 📦 Programmatic TypeScript SDK (@deviykee/mcw): Direct SDK for LangChain, Vercel AI SDK, and autonomous bot developers.

---

🚀 Quick Start (Zero-Install)

Run instantly using npx:

# Initialize a new wallet (or restore with existing seed phrase)
npx @deviykee/mcw init

# List or derive sub-accounts from your seed
npx @deviykee/mcw account list
npx @deviykee/mcw account create "Trading Bot Account"

# Manage multiple seed phrase profiles
npx @deviykee/mcw wallet list
npx @deviykee/mcw wallet create bot-profile

# Check live multi-chain balances
npx @deviykee/mcw balance

# Auto-detect and track any token contract on-chain
npx @deviykee/mcw token add 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238

# Swap tokens via DEX router
npx @deviykee/mcw swap 0.1 ETH USDC

---

📦 Global Installation

npm install -g @deviykee/mcw@latest

---

🛠️ CLI Commands & Usage

1. Initialize Wallet

mcw init

2. BIP-44 HD Sub-Account Indexing (mcw account)

Derive multiple independent accounts from your single master seed phrase:

mcw account list                  # View all derived sub-accounts and multi-chain addresses
mcw account create "Agent Bot"    # Derive Account #1 with dedicated keys
mcw account switch 1              # Set Account #1 as the active account

3. Multi-Seed Profile Vaults (mcw wallet)

Manage multiple independent seed phrases with isolated encrypted vaults:

mcw wallet list                   # List all wallet profiles
mcw wallet create trading-vault   # Generate fresh seed phrase in new profile
mcw wallet import personal-vault  # Import existing seed phrase into new profile
mcw wallet switch trading-vault   # Switch active profile
mcw wallet delete old-vault       # Delete a profile vault

4. View Balances

mcw balance         # Live table across BTC, ETH, SOL, TRX & Custom Chains
mcw balance eth     # Specific chain balance

5. Multi-Chain Token Management (ERC-20, SPL, TRC-20)

# 1. 1-Command Auto-Detection & Tracking (Auto-fetches symbol, name, decimals on-chain)
mcw token add 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238   # Sepolia USDC (ERC-20)
mcw token add TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs           # Shasta USDT (TRC-20)

# 2. Check token balances
mcw token balance
mcw token balance usdc-eth

# 3. Transfer tokens
mcw token send usdc-eth 10 0xRecipientAddress...
mcw token send usdt-trx 50 TRecipientAddress...

# 4. List all configured tokens
mcw token list

6. Built-in DEX Aggregation (mcw swap)

mcw swap 0.1 ETH USDC        # Uniswap V3 swap quote & execution
mcw swap 0.5 SOL USDC sol    # Jupiter DEX swap on Solana

7. Policy Guardrails & Spend Limits (mcw policy)

# View active policies
mcw policy list

# Set maximum spend per tx and 24h rolling limit
mcw policy set-limit eth 0.5 2.0

# Add trusted recipient to whitelist
mcw policy whitelist eth 0x1234567890123456789012345678901234567890

# Block malicious address
mcw policy blacklist eth 0xBadActorAddress...

# Enable/Disable guardrails
mcw policy toggle

8. Local Audit Logging (mcw history)

mcw history        # View recent transactions and agent memos
mcw history eth 10 # Filter by chain and limit

9. Gnosis Safe Multisig Proposal (mcw safe)

mcw safe propose 0xSafeAddress... 0xRecipientAddress... 0.1

10. Custom EVM Chains & RPC Overrides (mcw config)

# Toggle Tron testnet flavor
mcw config tron shasta
mcw config tron nile

# Custom RPC override
mcw config set-rpc eth https://your-alchemy-node.com
mcw config list

---

🤖 AI Agent MCP Server Integration

MCW implements the official @modelcontextprotocol/sdk JSON-RPC specification over stdio.

MCP Configuration (claude_desktop_config.json / Cursor / Grok)

{
  "mcpServers": {
    "mcw": {
      "command": "npx",
      "args": ["-y", "@deviykee/mcw", "mcp"]
    }
  }
}

Available MCP Tools

Tool Name	Type	Description
list_accounts	Read	Lists all HD sub-accounts derived under active seed
create_account	Action	Derives a new HD sub-account from current seed
switch_account	Action	Switches active account index for subsequent operations
list_wallets	Read	Lists all independent seed phrase wallet profiles
create_wallet	Action	Generates a new wallet profile with fresh seed
switch_wallet	Action	Switches active wallet profile
get_addresses	Read	Returns public addresses and derivation paths across all chains
get_balance	Read	Live native balances for BTC, ETH, SOL, TRX, and Custom Chains
get_token_balance	Read	Real-time smart contract balances (ERC-20, SPL, TRC-20)
add_token	Action	Auto-detects chain and metadata on-chain to track new tokens
swap_tokens	Action	DEX routing and quotation with human approval gate
simulate_transaction	Action	Pre-flight dry run simulation with asset delta tracking
get_transaction_history	Read	Local audit memory and past transaction logs
get_policies	Read	Spend limits and safety guardrails status
propose_safe_transaction	Action	Formulate Gnosis Safe multi-sig proposals with EIP-712 hash
build_transaction	Action	Validates policy, simulates call, and queues for approval
sign_and_send_transaction	Auth	Signs and broadcasts pending transaction with human password

---

📦 Programmatic TypeScript SDK

Developers can import McwWallet directly into TypeScript / JavaScript applications:

import { McwWallet, DexSwapper, PolicyEngine, listWallets } from '@deviykee/mcw';

// 1. Instantiate wallet with master seed
const wallet = new McwWallet('your twelve word mnemonic seed phrase...', 'testnet');

// Account #0 (Main Account)
const mainAddresses = wallet.getAddresses(0);
console.log('Account 0 ETH:', mainAddresses.eth);

// Account #1 (Sub-Account)
const botAddresses = wallet.getAddresses(1);
console.log('Account 1 ETH:', botAddresses.eth);

// Query balance for Account 1
const balance = await wallet.getBalance('eth', 1);

// Pre-flight transaction simulation
const sim = await wallet.simulate('eth', '0xRecipient...', '0.1');
console.log('Simulation Status:', sim.status, 'Gas:', sim.gasOrFeeEstimated);

// Get DEX swap quote
const quote = await DexSwapper.getQuote('eth', 'testnet', 'ETH', 'USDC', '0.5');
console.log(`Expected Output: ${quote.expectedAmountOut} USDC via ${quote.dexName}`);

---

📜 Attribution & License

• Author: deviykee (eokorie1911@gmail.com)
• License: Creative Commons Attribution 4.0 International (CC-BY-4.0)