Keypo Wallet

keypo-wallet

A CLI that turns your Mac into a programmable hardware wallet. Private keys are P-256 keys stored in the Apple Secure Enclave — they never leave the hardware, and Apple cannot extract them. The wallet uses EIP-7702 smart account delegation with ERC-4337 account abstraction for transaction submission.

Install: brew install keypo-us/tap/keypo-wallet This installs both keypo-wallet (Rust CLI) and keypo-signer (Swift CLI for Secure Enclave operations).

Source: https://github.com/keypo-us/keypo-cli

CLI Usage Rule

Before using any keypo-wallet command for the first time in a session, run keypo-wallet <command> --help to learn the exact flags, syntax, and examples. The --help output is the authoritative reference for each command — it includes usage patterns, all available flags, example invocations, and output format documentation.

keypo-wallet send --help       # learn send flags before sending
keypo-wallet balance --help    # learn balance flags before querying
keypo-wallet wallet-list --help  # learn wallet-list options

Do not guess flag names or assume positional arguments. Every command documents its interface via --help.

Core Concepts

Secure Enclave keys. All signing keys are P-256 (secp256r1) keys generated inside the Mac's Secure Enclave. The private key material is hardware-bound and non-exportable.

EIP-7702 delegation. Each wallet is a standard EOA that delegates execution to the KeypoAccount smart contract via EIP-7702, giving EOAs smart account capabilities without deploying a separate contract.

ERC-4337 bundler. Transactions are submitted as UserOperations through an ERC-4337 bundler (default: Pimlico, any v0.7 bundler works).

Key policies. Each key has a signing policy:

• open — No restrictions. Best for agent-controlled wallets.
• passcode — Requires device passcode per signature.
• bio — Requires Touch ID per signature.

For agent use, always use open. The passcode and bio policies block automated workflows.

ERC-7821 batch execution. Multi-call operations use batch mode 0x01. Single calls must also use mode 0x01 with a 1-element array. Mode 0x00 is invalid.

Signer keys ≠ wallet accounts. keypo-wallet list shows all P-256 keys in the Secure Enclave. Not all keys have a wallet account — only keys that have been through keypo-wallet setup have an account entry in ~/.keypo/accounts.json. Running wallet-info or balance on a key without an account will fail. Always discover wallets from wallet-list or accounts.json, not list.

Setup Workflow

1. Initialize configuration

keypo-wallet init

Prompts for RPC URL, bundler URL, and optional paymaster URL. Saves to ~/.keypo/config.toml. You can also use config set, config show, and config edit.

Config resolution precedence: CLI flag > environment variable > config file.

Environment variables: KEYPO_RPC_URL, KEYPO_BUNDLER_URL, KEYPO_PAYMASTER_URL, KEYPO_PAYMASTER_POLICY_ID.

2. Create a key and set up the smart account

keypo-wallet setup --key <key-name> --key-policy open

Creates a P-256 key, signs an EIP-7702 delegation to the KeypoAccount contract, and registers the public key as the owner. Requires ~$1 ETH for gas. The account is saved to ~/.keypo/accounts.json.

Querying Wallet State

Always use keypo-wallet commands to check wallets and balances. Do not make raw RPC calls or use curl/cast for balance queries.

For any request asking for a "detailed overview", "all balances", or "token balances": you need both keypo-wallet (for ETH balances and wallet metadata) AND the portfolio-tracker skill (for ERC-20 token discovery). keypo-wallet balance only shows ETH — it cannot discover ERC-20 tokens.

List all wallets

keypo-wallet wallet-list

Shows label, address, chains, and ETH balance for every wallet. Run keypo-wallet wallet-list --help to see format and filtering options.

wallet-list does not include signing policy. To get policies for all wallets at once, read the accounts file:

cat ~/.keypo/accounts.json | python3 -c "
import sys, json
accounts = json.load(sys.stdin)
for name, acct in accounts.items():
    policy = acct.get('key_policy', acct.get('policy', 'unknown'))
    print(f'  {name}: {policy}')
"

Get details for a specific wallet

keypo-wallet wallet-info --key <key-name>   # full details + live balance (requires RPC)
keypo-wallet info --key <key-name>          # local state only, no RPC (faster)

Query balances

keypo-wallet balance --key <key-name>                              # ETH balance
keypo-wallet balance --key <key-name> --token <erc20-address>      # ERC-20 balance

Run keypo-wallet balance --help for structured query files (--query), output formats (--format), and other options.

keypo-wallet balance only shows ETH by default. It does not check for ERC-20 tokens unless you pass a specific --token <address>. A wallet showing only ETH does NOT mean it has no other tokens — it means you haven't checked.

Whenever the user asks for a "detailed overview", "token balances", "what's in my wallet", or any request that implies completeness, you MUST also run the portfolio-tracker skill to discover ERC-20 tokens. Do not skip this step just because balance returned ETH results. The portfolio-tracker is the only way to discover what tokens a wallet holds.

Sending Transactions