@vaulx/vaulx

Agent wallet MCP server implementing the Agent Payment Protocol. Gives Claude Code (or any MCP client) its own wallet — send ETH/SOL, swap tokens, check balances, auto-pay via APP-compliant elicitation hooks.

Supports EVM chains (Ethereum, Base, Sepolia) and Solana (mainnet, devnet).

Quick Start

npx @vaulx/vaulx init

This will:

1. Generate both EVM (secp256k1) and Solana (Ed25519) keys (stored in OS keychain or ~/.vaulx/wallets/default/.env)
2. Create a spending policy (~/.vaulx/wallets/default/wallet-policy.json)
3. Register the MCP server in ~/.mcp.json (no secrets — only the .env path)
4. Register the auto-payment hook in ~/.claude/settings.json

Every wallet holds both an EVM and Solana address — use the same wallet on any supported chain.

Then restart Claude Code — vaulx will auto-connect.

Supported Chains

Chain	ID	Alias	Native
Ethereum	1	ethereum	ETH
Base	8453	base	ETH
Base Sepolia	84532	base-sepolia	ETH
Sepolia	11155111	sepolia	ETH
Solana	solana	solana	SOL
Solana Devnet	solana-devnet	solana-devnet	SOL

Multi-Wallet

Create and manage multiple isolated wallets:

npx @vaulx/vaulx init --name defi       # Create named wallet
npx @vaulx/vaulx list                   # List all wallets
npx @vaulx/vaulx switch defi            # Switch active wallet
npx @vaulx/vaulx active                 # Show active wallet
npx @vaulx/vaulx delete defi            # Delete wallet

Each wallet has its own .env, spending policy, and transaction database under ~/.vaulx/wallets/{name}/.

Interactive Mode

Run vaulx without arguments to get an interactive menu:

npx @vaulx/vaulx

# vaulx — Agent Wallet Manager
#
# ? What do you want to do?
#   1. Create new wallet (init)
#   2. List wallets
#   3. Switch wallet
#   ...

MCP Wallet Management

Manage wallets directly from Claude Code — no terminal needed:

Tool	Description
list_wallets	List all wallets with EVM/Solana addresses and active status
switch_wallet	Hot-swap active wallet (no server restart)
create_wallet	Generate a new wallet (both EVM + Solana) and optionally switch to it

Fund Your Wallet

After init, fund the address shown:

EVM Testnets:

• Base Sepolia: https://www.alchemy.com/faucets/base-sepolia
• Sepolia: https://www.alchemy.com/faucets/ethereum-sepolia

Solana Devnet:

• https://faucet.solana.com

MCP Tools

Tool	Description	EVM	Solana
send_transaction	Send native token (ETH/SOL)	✓	✓
send_token	Send tokens (ERC20/SPL)	✓	✓
approve_token	Approve spending (ERC20 approve / SPL delegate)	✓	✓
revoke_token	Revoke approval (ERC20 / SPL delegate)	✓	✓
swap_token	Swap tokens (Uniswap V3 / Jupiter)	✓	✓
sign_message	Sign a message	✓	✓
sign_bytes	Sign raw bytes (Ed25519)	—	✓
sign_and_send_raw_transaction	Sign + submit raw transaction	—	✓
withdraw	Withdraw native/tokens (full balance support)	✓	✓
get_address	Wallet address + mode	✓	✓
get_balance	Native + token balances	✓	✓
get_transactions	Transaction history	✓	✓
get_spending	Daily/total spend + remaining limits	✓	✓
list_wallets	List all wallets with active status	✓	✓
switch_wallet	Hot-swap active wallet (no restart)	✓	✓
create_wallet	Generate new wallet	✓	✓

MCP Resources

URI	Description
wallet://address	Wallet address
wallet://balance	Balance (default chain)
wallet://balance/{chainId}	Balance on specific chain
wallet://tokens	Known tokens
wallet://transactions	Transaction history
wallet://spending	Spend limits + usage
wallet://policy	Current policy config
wallet://chains	Supported chains
wallet://allowance	Token allowances
wallet://balances	All balances

HTTP API

Runs on http://127.0.0.1:18420 alongside the MCP server.

Method	Path	Auth	Description
GET	/health	No	Health check
GET	/deposit	No	Deposit page with faucet links
GET	/address	Yes	Wallet address
GET	/balance/:chainId	Yes	Balance
POST	/api/send-transaction	Yes	Send transaction
POST	/api/sign-bytes	Yes	Sign raw bytes (Solana)
POST	/api/sign-and-send-raw-transaction	Yes	Sign + submit raw tx (Solana)

Auth: Authorization: Bearer {WALLET_AUTH_TOKEN}.

Spending Policy

Conforms to the Agent Payment Protocol Spending Policy schema. Set via vaulx init prompts, or edit ~/.vaulx/wallets/{name}/wallet-policy.json directly.

Field	Description
maxPerTx	Max per transaction (smallest unit: wei/lamports)
maxPerDay	Daily spend limit
maxTotal	Lifetime spend limit
allowedTokens	Allowed token symbols (e.g. ["ETH"], ["SOL", "USDC"])
allowedRecipients	Whitelist (empty = no restriction)
blockedRecipients	Blacklist
allowedOperations	send, send_token, sign, withdraw, approve, swap
expiresAt	Policy expiry (ISO 8601)
chainOverrides	Per-chain policy overrides (see below)

Default: 0.1 ETH per tx, 0.5 ETH per day (EVM). Solana defaults to 1 SOL per tx, 5 SOL per day. New wallets allow both ETH and SOL by default.

Chain-specific Policy Overrides

Use chainOverrides to set different limits per chain:

{
  "maxPerTx": "100000000000000000",
  "allowedTokens": ["ETH"],
  "chainOverrides": {
    "solana-devnet": {
      "maxPerTx": "1000000000",
      "allowedTokens": ["SOL", "USDC"]
    }
  }
}

Advanced: Smart Account Mode

npx @vaulx/vaulx setup

Deploys an ERC-4337 smart account with Pimlico paymaster (gas-sponsored). Requires PIMLICO_API_KEY. EVM only.

Auto-Payment Hook

hooks/handle-payment.js is a Claude Code elicitation hook that implements the Agent Payment Protocol. When a server requests payment via the [x-agent-payment:{...}] discovery tag, vaulx automatically detects the request, evaluates the spending policy, and pays on behalf of the agent.

Compatible with any MCP server that issues APP-compliant payment requests, including lynq's agentPayment() middleware. The legacy [x-lynq-payment:{...}] tag is still detected for backward compatibility.

Extensibility: Payment detection is isolated in detectPayment() (hooks/handle-payment.js). To support a non-APP payment protocol, swap this single function.

Security

• Private keys (EVM + Solana) are stored in OS keychain (macOS Keychain / Linux libsecret) by default
• Falls back to ~/.vaulx/wallets/{name}/.env (chmod 600) when keychain is unavailable
• ~/.mcp.json contains the file path, not the key itself
• HTTP server binds to 127.0.0.1 only
• Spending policy enforces per-tx, daily, and total limits