Agent Wallet

Agent-native secure payment system on Monad. Session keys with on-chain policy enforcement, 3-tier approval, Telegram notifications, Passkey biometric verification, and full audit trails.

Monad Blitz V2 Hackathon -- Agentic Payment Track

Quick Start

Install

curl -fsSL https://raw.githubusercontent.com/rumpsmcken-sudo/wallet/main/install.sh | bash

Setup (one-time)

# 1. Initialize config directory
agent-wallet init

# 2. Authorize — opens browser, user connects MetaMask
#    Agent generates session key locally, user signs authorization on-chain
#    Agent NEVER touches the owner's private key
agent-wallet setup --password $(openssl rand -hex 16)

# 3. Register Passkey for secure payment approval (REQUIRED)
agent-wallet auth setup-passkey

After setup:

• Agent has an encrypted session key with spending limits
• Owner's private key stays in MetaMask
• Large payments require Passkey (fingerprint/Face ID) approval

Make Payments

# Small payment (auto-approved)
agent-wallet pay --to 0x... --amount 500000 --reason "API call" \
  --session-key 0x... --password <pwd> --json

# Large payment (requires human approval)
agent-wallet pay --to 0x... --amount 15000000 --reason "Service purchase" \
  --session-key 0x... --password <pwd> --json
# Returns: {"approvalRequired": true, "approvalId": "apr_xxx"}

# User approves (interactive — Passkey biometric)
agent-wallet approve

# Or via Telegram (user taps button on phone)
agent-wallet approve --wait apr_xxx --json

Architecture

User (MetaMask)                    Agent (CLI)
     |                                |
     |-- setup: sign createWallet --->|
     |-- setup: sign registerKey ---->|
     |                                |
     |   [Agent works autonomously]   |
     |                                |-- pay (small) --> auto-execute
     |                                |-- pay (large) --> APPROVAL_REQUIRED
     |<-- Telegram/Passkey approval --|
     |                                |-- pay --approval-id --> execute

Key principle: Agent never touches the owner's private key. It only holds a session key with on-chain enforced limits.

Commands

Command	Description
init	Initialize ~/.agent-wallet/
setup	Authorize agent via browser (MetaMask)
pay	Execute payment
session create	Create new session key
session list	List session keys
session revoke	Revoke a session key
session revoke-all	Emergency: revoke ALL keys
session rotate	Rotate session key
session update-permissions	Update session key limits
approve	Interactive payment approval (Passkey)
approve --wait <id>	Poll for approval (Agent mode)
policy set	Set approval thresholds
policy show	Show current policy
config set-telegram	Configure Telegram notifications
config show	Show configuration
fetch <url>	HTTP request with x402 auto-payment
audit	View audit log
audit --verify	Verify hash chain integrity
watch --telegram	Real-time monitoring + Telegram
auth setup-passkey	Register Passkey (fingerprint/Face ID)
auth verify-passkey	Verify Passkey
totp setup	Enable TOTP 2FA
pause	Emergency pause wallet
recover	Recovery operations
balance	Check balances

Security Model

Agent cannot approve its own payments

• Small payments (< 1 USDC): auto-execute via session key
• Medium payments (1-10 USDC): require human confirmation
• Large payments (>= 10 USDC): require manual approval

Approval methods (human-only):

• Passkey: agent-wallet approve (interactive, biometric)
• Telegram: user taps button on phone
• TOTP: 6-digit code + separate verification password

The Agent can only approve --wait <id> to poll for the result.

On-chain policy enforcement

9 checks enforced by PolicyEngine contract:

1. Wallet paused?
2. Session key expired?
3. Session key not yet active?
4. Cooldown period?
5. Per-transaction limit?
6. Daily spending limit?
7. Weekly spending limit?
8. Target address whitelist?
9. Token whitelist?
10. Method selector whitelist?

Audit trail

Every payment (success or failure) is logged to ~/.agent-wallet/audit.jsonl with SHA-256 hash chain for tamper detection:

agent-wallet audit --verify  # Verify chain integrity
agent-wallet audit --limit 10 --json  # Query recent entries
agent-wallet audit --format csv  # Export

Monad Testnet

Chain ID:     10143
RPC:          https://testnet-rpc.monad.xyz
Block time:   400ms
USDC:         0x534b2f3A21130d7a60830c2Df862319e593943A3
MockUSDC:     0x4d16368d29fb31fc7c5bd4a9881913daadb20a89

Shared contracts:

• WalletFactory: 0xaadb127b146e24d134344c7fd850f0f955595a35
• PolicyEngine: 0x31f97d0be2c5879c3f359284048253935b1746bb
• PasskeyVerifier: 0xc10ef3ccb30dd48ebd393d20981aa86f113061ed

For AI Agents

Paste the system prompt from agent-wallet.pages.dev into your AI agent (Claude Code, Codex, Manus, etc.) for full command reference and error handling guidance.

License

MIT