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.

Agent / daemon mode

For long-running setups (Claude Code, scripts, CI) you can start a daemon that holds the unlocked wallet in memory and serves agent requests over loopback HTTP. Agents authenticate with API keys (xv_key_…) instead of the master passphrase. Keys are scoped, time-bounded, and cryptographically revocable.

# In your terminal: start the daemon (Touch ID / passphrase prompts once).
xverse-wallet daemon start --background

# Mint a scoped, expiring agent token (printed once to stdout). Admin commands
# like `key create` use the wallet password as the bearer — prompted by
# default, or read from $XVERSE_PASSWORD. There is no separate admin token.
export XVERSE_DAEMON_TOKEN=$(xverse-wallet key create --name claude-agent --expires 7d)

# Hand the agent the env. From then on, every CLI call routed through --daemon
# uses the daemon's already-unlocked wallet — no passphrase needed.
xverse-wallet --daemon bitcoin balance
xverse-wallet --daemon bitcoin send --to bc1q… --amount 50000

# Revoke when done (or on schedule).
xverse-wallet key revoke --prefix <8-hex-prefix-from-key-list>

Detailed docs:

• AGENT-WALLET.md — quickstart, key management, edge cases.
• DAEMON.md — protocol, RPC methods, auth resolution, security properties.

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 | | Cross-Chain Payments (powered by Orchestra) | | | bridge routes | List available cross-chain trading pairs | | bridge estimate | Price preview (no API key required) | | bridge deposit | Deposit external assets into your Spark wallet | | bridge submit | Submit a funded deposit with a tx hash | | bridge send | Send BTC or USDB from Spark to an external chain | | bridge status | Check or watch an order's status | | bridge address accumulate | Create a reusable address for recurring deposits | | bridge address liquidate | Create a reusable address for recurring sends | | 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.

Cross-Chain Payments

Move assets between external chains and your Spark wallet — powered by Orchestra. Deposit USDC from Ethereum, Base, or Solana directly into your USDB balance, or send USDB out to any supported chain.

Deposit into Spark

# Preview: get a quote and deposit address
xverse-wallet bridge deposit \
  --from ethereum --asset USDC --amount 10 \
  --to spark --asset-out USDB \
  --refund-address <YOUR_ETH_ADDRESS>

# One-shot: submit and watch until settled (EVM chains auto-detected)
xverse-wallet bridge deposit \
  --from ethereum --asset USDC --amount 10 \
  --to spark --asset-out USDB \
  --refund-address <YOUR_ETH_ADDRESS> \
  --watch

# Solana (and similar auto-monitored chains): Orchestra detects the deposit
# automatically — no manual tx-hash submission needed; --watch polls by quoteId
xverse-wallet bridge deposit \
  --from solana --asset USDC --amount 10 \
  --to spark --asset-out USDB \
  --refund-address <YOUR_SOL_ADDRESS> \
  --watch

Send from Spark

# Preview
xverse-wallet bridge send \
  --asset USDB --amount 10 \
  --to ethereum --asset-out USDC \
  --recipient <YOUR_ETH_ADDRESS>

# Execute: signs the Spark transfer and submits in one step
xverse-wallet bridge send \
  --asset USDB --amount 10 \
  --to ethereum --asset-out USDC \
  --recipient <YOUR_ETH_ADDRESS> \
  --yes --watch

Track orders

# Check a specific order
xverse-wallet bridge status --order <ORDER_ID>

Reusable deposit addresses

Send to a fixed address any time — no per-transaction quote needed:

# Accumulate recurring deposits into Spark (e.g. from Solana)
xverse-wallet bridge address accumulate \
  --from solana --asset USDC --asset-out USDB

# Liquidate Bitcoin L1 deposits out to an external chain
xverse-wallet bridge address liquidate \
  --to ethereum --asset-out USDC --recipient <YOUR_ETH_ADDRESS>

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.

Authentication

The vault is encrypted with an Argon2id-derived key from your password. The password is read from XVERSE_PASSWORD in env, or prompted interactively when commands like wallet reset, wallet export, daemon stop, and key create need it.

XVERSE_PASSWORD=mypass xverse-wallet wallet create
xverse-wallet wallet export        # prompts for password
xverse-wallet key create --name claude-agent --expires 7d   # prompts for password

Admin RPCs to the daemon (mint/revoke API keys, shutdown) use the wallet password as the bearer — there is no separate admin token. See docs/AGENT-WALLET.md for details.

Security

All sensitive data (seed phrases, private keys) is encrypted at rest using AES-256-GCM with an Argon2id-derived key — 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) or a native OS dialog, and the only credential passed to spawned agents is a scoped, revocable API key — the password itself never reaches the agent.

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

For local builds and signed-release builds, see docs/BUILD.md.