@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