Xverse Wallet CLI

A headless, developer-first Bitcoin wallet CLI for agents and automation. Supports Bitcoin, Stacks, Starknet, Spark L2, Runes, and Lightning.

Installation

npm i -g @secretkeylabs/xverse-agent-wallet

Or run without installing:

npx @secretkeylabs/xverse-agent-wallet --help

Claude Code Skill

The CLI ships with a Claude Code skill that teaches AI agents how to use every command. Install it so agents can operate the wallet autonomously:

# Via the CLI (after installing globally)
xverse-wallet --install

# Or via npx (one-shot)
npx @secretkeylabs/xverse-agent-wallet --install

# To uninstall
xverse-wallet --uninstall

The skill is installed to ~/.claude/skills/xverse-agent-wallet/SKILL.md and covers all commands, token guides, agentic workflows, and common patterns. See .claude/skills/xverse-agent-wallet/SKILL.md for the full reference.

Commands

| Command | Description | | ---------------------------------- | ----------------------------------------------- | | Wallet & Accounts | | | wallet create | Create a new wallet | | wallet restore | Restore from mnemonic | | wallet reset | Delete all wallet data | | wallet export | Show wallet mnemonic | | wallet status | Check wallet existence and active profile | | wallet switch <name> | Switch to a different wallet profile | | wallet profiles | List all wallet profiles | | account list | List all derived accounts with addresses | | account current | Show active account addresses | | account derive | Derive next account(s) | | account switch <index> | Switch active account | | Bitcoin | | | bitcoin balance | BTC balance (native segwit + taproot) | | bitcoin send | Send BTC | | bitcoin receive | Show receive addresses | | bitcoin history | Transaction history | | bitcoin fees | Recommended fee rates (sat/vB) | | Stacks | | | stacks balance | STX + SIP-10 token balances | | stacks send | Send STX or SIP-10 token | | stacks receive | Show STX address | | stacks history | Token transaction history | | Starknet | | | starknet balance | All ERC-20 token balances | | starknet send | Send STRK or any ERC-20 | | starknet receive | Show Starknet address | | starknet history | Token transaction history | | starknet staking status | Show staking position | | starknet staking deposit | Stake WBTC | | starknet staking withdraw-intent | Start withdrawal (~7 day cooldown) | | starknet staking withdraw | Complete withdrawal after cooldown | | starknet staking claim | Claim STRK rewards | | Spark & Lightning | | | spark balance | Spark balance (auto-claims pending) | | spark deposit | Deposit BTC from L1 to Spark | | spark claim | Claim deposits with 3+ confirmations | | spark send | Send BTC or token on Spark | | spark withdraw | Withdraw BTC to L1 | | spark receive | Show Spark address | | spark history | Transaction history | | spark lightning invoice | Create Lightning invoice (for receiving) | | spark lightning estimate | Estimate Lightning payment fee | | spark lightning pay | Pay Lightning invoice | | Runes | | | runes balance | Show rune balances | | runes send | Send runes | | runes receive | Show taproot receive address | | runes details | Show rune etching info | | runes history | Transaction history for a rune | | Trading & Funding | | | swap quote | Get swap quotes across chains | | swap execute | Execute a swap (auto-selects best quote) | | fund currencies | List supported fiat and crypto currencies | | fund providers | List providers with min/max limits | | fund quote | Get buy quotes from providers | | fund buy | Buy crypto with fiat (opens in browser) | | Portfolio & Earning | | | portfolio | All balances across all chains | | cash balance | Stablecoin balances across all chains | | cash receive | Stablecoin receive addresses | | cash history | Stablecoin transaction history | | earn status | Earning overview with suggested actions | | earn guide | Step-by-step WBTC staking walkthrough | | Machine Payments | | | pay request <url> | HTTP request with auto Lightning payment on 402 | | pay api [path] | Browse MPP-enabled API endpoints | | Agent | | | agent | Launch an AI agent with wallet authentication |

Run xverse-wallet --help for the full command tree. See the skill for detailed options and examples.

Quick Start

export XVERSE_PASSWORD="your-password"

# Create a new wallet
xverse-wallet wallet create --show-mnemonic --json

# Or restore from mnemonic (leading space hides from shell history)
 XVERSE_MNEMONIC="word1 word2 ..." xverse-wallet wallet restore --json

# Check all balances
xverse-wallet portfolio --json

# See all commands
xverse-wallet --help

Profiles & Accounts

The CLI supports profiles (separate wallets) and accounts (derived addresses within a wallet).

Profiles are independent wallets — each has its own mnemonic, accounts, and data. Use profiles to manage multiple wallets (e.g. default, trading, savings).

Accounts are BIP-44 derived addresses within a single wallet. Account 0 is created automatically. Derive more with account derive.

Switching (persistent)

Changes the default for all subsequent commands:

xverse-wallet wallet switch trading    # switch active profile
xverse-wallet account switch 2         # switch active account

On-demand (one-off)

Runs a single command without changing the default:

# Different account
xverse-wallet -a 2 bitcoin balance --json

# Different profile
xverse-wallet -p trading spark balance --json

# Both
xverse-wallet -p trading -a 2 bitcoin balance --json

Creating a new profile

xverse-wallet wallet switch trading
XVERSE_MNEMONIC="word1 word2 ..." xverse-wallet wallet restore
xverse-wallet wallet switch default   # switch back

Use on-demand (-a, -p) when checking balances or running quick queries. Use switching when you want all subsequent commands to target a specific profile/account.

Agent Mode

Let an AI agent (e.g. Claude Code) operate the wallet autonomously. Handles wallet creation/restore, password authentication, and launches the agent with full CLI access:

# Launch Claude Code with wallet access (default)
xverse-wallet agent

# Non-interactive (requires XVERSE_PASSWORD env var)
xverse-wallet agent --quiet

On first run with no wallet, it interactively prompts to create or restore. On subsequent runs, it prompts for the password, authenticates, and launches the agent with XVERSE_PASSWORD set so all CLI commands work within the session.

Security

All sensitive data (seed phrases, private keys) is encrypted at rest using AES-256-GCM. The encryption key is derived from your password via Argon2id, a memory-hard KDF designed to resist brute-force attacks.

Your password is the only thing protecting your funds. Use a strong, unique password — if someone gains access to the encrypted vault file and your password is weak, they can derive your keys and steal your assets.

No plaintext secrets are ever written to disk. Session state is ephemeral and cleared on process exit. In agent mode, the password is prompted from stdin (masked) and passed to the agent process as an environment variable — it is never written to disk or shell history.

Development

# Install core deps (from repo root)
npm install

# Install CLI deps
cd headless && npm install

# Run CLI
bun ./index.ts --help

# Type check
npx tsc --noEmit