Let Your AI Spend Money,
Not Steal It.

## Agent Wallet - Payment Tool for AI Agents You now have access to `agent-wallet`, a CLI tool that lets you make secure payments on the Monad blockchain. Install it and remember how to use it. ### Step 1: Install ```bash curl -fsSL https://raw.githubusercontent.com/rumpsmcken-sudo/wallet/main/install.sh | bash ``` **If installation fails**, do the following: 1. Capture the full error output. 2. Collect environment info: `node --version`, `npm --version`, `uname -a` (or `systeminfo` on Windows). 3. Check if the GitHub CLI is available: `which gh && gh auth status`. 4. If `gh` is authenticated, ask the user: "Installation failed. I can file a GitHub issue to help the developers fix this. May I?" 5. If the user agrees, create the issue: ``` gh issue create --repo rumpsmcken-sudo/wallet \ --title "[Install Bug] <one-line error summary>" \ --body "$(cat <<'EOF' ## Environment - **OS**: <output of uname -a or systeminfo> - **Node.js**: <output of node --version> - **npm**: <output of npm --version> - **Shell**: <bash/zsh/powershell + version> - **Agent**: <Claude Code / Codex / Manus / other> ## Install Command \`\`\`bash curl -fsSL https://raw.githubusercontent.com/rumpsmcken-sudo/wallet/main/install.sh | bash \`\`\` ## Error Output \`\`\` <paste full npm error output here, max 200 lines> \`\`\` ## Steps Before Failure <describe what you did before running install, e.g. fresh terminal, after init, etc.> ## Additional Context <any other relevant info: proxy, corporate network, disk space, permissions, etc.> --- *Auto-reported by AI Agent via `gh issue create`* EOF )" ``` 6. If `gh` is NOT available or not authenticated, show the user the error and suggest they manually open an issue at https://github.com/rumpsmcken-sudo/wallet/issues with the same information above. ### Step 2: Initialize ```bash agent-wallet init ``` This creates `~/.agent-wallet/` with config, sessions, pending approvals, and audit log directories. ### Step 3: Authorize (one-time — user signs with their own wallet) Generate a random password yourself (do NOT ask the user for one). This password is for encrypting YOUR local session key — the user does not need to know it. ```bash agent-wallet setup --password $(openssl rand -hex 16) --json ``` This opens a browser page where the user connects MetaMask and authorizes a session key for you. You NEVER touch the owner's private key — it stays in MetaMask. After authorization, a session key is created and encrypted locally. Tell the user: "I need wallet authorization to make payments. A browser window will open — please connect MetaMask and click Authorize. Your private key stays in your wallet." If `--json` output shows `"status":"already_configured"`, skip this step. Remember the password you generated — you'll need it for `--password` in subsequent commands. After setup, IMMEDIATELY ask the user to register a Passkey for payment approval security: Tell the user: "Please set up Passkey (fingerprint/Face ID) for secure payment approval. A browser window will open." ```bash agent-wallet auth setup-passkey ``` This is REQUIRED — without Passkey, the user cannot approve large payments securely. ### Step 4: Remember These Commands **Core Payment Flow:** - `agent-wallet pay --to <address> --amount <base-units> --reason "<why>" --token <token-addr> --session-key <key> --password <password> --json` - `--reason` is REQUIRED. You must explain every payment. - Amount is in base units (1 USDC = 1000000, 6 decimals) - Returns JSON: `{"success":true,"txHash":"0x..."}` or `{"error":"DENY_AMOUNT_LIMIT","maxAllowed":"5000000"}` **Session Key Management:** - `agent-wallet session create --label <name> --password <password> --max-per-tx 5000000 --max-daily 20000000 --duration 86400 --allowed-tokens <token-addr> --json` - Creates a temporary key with spending limits - `agent-wallet session create --label <name> --request-only --reason "I need payment access for..." --password <password> --json` - Agent-initiated: creates a pending request for the user to approve - `agent-wallet session list --json` - List all session keys - `agent-wallet session revoke --label <name>` - Revoke a key **Approval Flow (3 tiers):** - amount < autoApproveBelow: executes immediately - amount < confirmBelow: returns `APPROVAL_REQUIRED` with `approvalId` - amount >= confirmBelow: manual approval needed IMPORTANT: You CANNOT approve payments yourself. Only the human user can approve via: - Telegram: user clicks ✅ button on their phone - CLI with Passkey: `agent-wallet approve --approve <id> --passkey` (biometric required) Your job is to WAIT for the user's decision: - `agent-wallet approve --wait <id> --json` (polls every 2s, 5min timeout) When you get `APPROVAL_REQUIRED`, tell the user: "I need your approval for X USDC to pay for [reason]. Please check Telegram or run: agent-wallet approve --approve <id> --passkey" Then wait: `agent-wallet approve --wait <id> --json` When approved: `agent-wallet pay ... --approval-id <id> --json` **Policy Configuration:** - `agent-wallet policy set --auto-approve-below 3000000 --confirm-below 10000000` - Set thresholds - `agent-wallet policy show --json` - View current policy **x402 Machine Payment (API purchases):** - `agent-wallet fetch <url> --session-key <key> --password <password> --json` - Automatically handles HTTP 402 Payment Required - Signs payment, resends request, returns API data **Monitoring & Audit:** - `agent-wallet audit --limit 10 --json` - View recent payments - `agent-wallet audit --verify` - Verify hash chain integrity - `agent-wallet watch` - Real-time payment stream (user terminal) - `agent-wallet watch --telegram` - With Telegram notifications **Security (2FA):** - `agent-wallet totp setup --password <password>` - Enable TOTP 2FA - `agent-wallet totp verify <code> --password <password>` - Verify code - `agent-wallet auth setup-passkey` - Register Passkey (fingerprint/Face ID) - `agent-wallet auth verify-passkey` - Verify with biometrics **Emergency:** - `agent-wallet pause` - Freeze wallet (owner only) - `agent-wallet recover --transfer-to <address>` - Transfer ownership **Balance:** - `agent-wallet balance --json` - Check wallet + session key balances ### Step 5: Remember Error Handling When a payment fails, parse the JSON error: - `DENY_AMOUNT_LIMIT` -> Lower the amount - `DENY_DAILY_LIMIT` -> Wait until tomorrow or ask user to increase limit - `DENY_TARGET` -> Use a whitelisted address - `DENY_TOKEN` -> Use an allowed token - `SESSION_REVOKED` -> Your access was revoked, inform the user - `APPROVAL_REQUIRED` -> Tell the user to approve via Telegram or CLI - `DENY_PAUSED` -> Wallet is frozen, inform the user ### Step 6: Monad Testnet Config ``` Chain ID: 10143 RPC: https://testnet-rpc.monad.xyz USDC: 0x534b2f3A21130d7a60830c2Df862319e593943A3 MockUSDC: 0x4d16368d29fb31fc7c5bd4a9881913daadb20a89 Block time: 400ms ``` ### Best Practices 1. ALWAYS use `--json` flag for machine-readable output 2. ALWAYS provide `--reason` with meaningful explanation 3. ALWAYS use `--non-interactive` in automated workflows 4. Use `--context "task:current-task-name"` to link payments to your tasks 5. Start with `session create --request-only` to ask for permission first 6. Parse JSON responses and handle errors programmatically 7. If approval is required, inform the user clearly with the approval ID 8. Check `balance --json` before making large payments 9. Never hardcode private keys — the setup flow keeps them in the user's wallet 10. Log all payment attempts in your task context for traceability