🚀Getting Started

This page walks you through installing the Xverse Agentic Wallet CLI, creating your first wallet, and understanding the core concepts you'll need for everything else.

Prerequisites

• Node.js 18+ installed

• A terminal (the CLI is headless — no browser or GUI required)

Install

npm install -g @secretkeylabs/xverse-wallet-cli

Verify the installation:

xverse-wallet --version

Authentication

The CLI encrypts your wallet vault at rest using a passphrase provided via environment variable. Set it before any wallet operation:

export XVERSE_PASSWORD="your-secure-passphrase"

This follows the standard 12-factor app pattern and is compatible with any secret manager (AWS Secrets Manager, HashiCorp Vault, 1Password CLI, etc.).

For AI agent frameworks: If you're launching the CLI from an agent, pass XVERSE_PASSWORD as an environment variable to the subprocess. The agent never needs to handle keys directly.

Create a wallet

xverse-wallet wallet create --json

This generates a new BIP-39 mnemonic, encrypts it into a local vault, and derives your first account (account 0) with addresses for all supported chains.

To display the mnemonic (for backup):

xverse-wallet wallet create --show-mnemonic --json

To restore an existing wallet:

XVERSE_MNEMONIC="word1 word2 ... word12" xverse-wallet wallet restore --json

Tip: Add a leading space before the command to prevent the mnemonic from being saved in shell history.

Check your wallet

# Wallet status (no auth needed)
xverse-wallet wallet status --json

# Current account addresses
xverse-wallet account current --json

# All accounts
xverse-wallet account list --json

Output modes

Every command supports three output modes:

Flag	Output	Use when...
(default)	Human-readable tables	You're exploring interactively
--json	Structured JSON	Your agent parses the output
-q/--quiet	Single value (e.g. just an address or txid)	You need one value for piping

Always use --json when your agent needs to parse the output programmatically.

Profiles and accounts

The CLI supports two levels of organization:

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

Accounts are BIP-44 derived addresses within a single wallet. Account 0 is created automatically. You can derive more:

xverse-wallet account derive --count 3 --json

Switching vs. on-demand

You can either switch the active profile/account (persistent) or target one on-demand (one-off):

# Persistent — changes default for all subsequent commands
xverse-wallet wallet switch trading
xverse-wallet account switch 2

# On-demand — one command only, doesn't change the default
xverse-wallet -a 2 bitcoin balance --json          # different account
xverse-wallet -p trading spark balance --json       # different profile
xverse-wallet -p trading -a 2 bitcoin balance --json # both

Use on-demand (-a, -p) for quick queries. Use switching when you want all subsequent commands to target a specific context.

Transaction safety: dry-run by default

All commands that modify state (send, swap execute, spark deposit, etc.) support a dry-run pattern:

• Without --yes: the command shows a preview and returns "dryRun": true in JSON mode. Nothing is broadcast.

• With --yes: the transaction is signed and broadcast.

# Preview (safe)
xverse-wallet bitcoin send --to bc1q... --amount 0.001 --json

# Execute (irreversible)
xverse-wallet bitcoin send --to bc1q... --amount 0.001 --yes --json

Always preview first, then confirm. If you're building an agent, have it show the preview to the user (or log it) before adding --yes.

Data storage

Wallet data is stored at ~/.local/share/xverse-headless/ by default. Override with the XDG_DATA_HOME environment variable. The vault is JSON-based (not IndexedDB), making it easy to inspect and debug.

Fund your wallet

Once created, your wallet is empty. Fund it in one of these ways:

Buy with fiat (easiest — opens a checkout page in your browser):

xverse-wallet fund buy --crypto BTC --amount 100

Supports BTC, STX, WBTC, STRK, and USDC. Most providers require a $20+ minimum.

Receive from another wallet:

xverse-wallet bitcoin receive --json

Send BTC to the native address from any exchange or wallet.

Check your balances:

xverse-wallet portfolio --accounts 0-4 --json

Next steps

With your wallet created and funded, explore the capabilities:

Capability	Page
Send and receive BTC on L1	Bitcoin
Lightning payments via Spark	Spark & Lightning
Machine-payable API calls	Machine Payments (MPP)
Trade on Starknet	Starknet
Swap across chains	Swaps
Full portfolio overview	Portfolio & Treasury