🚀Getting Started
This page walks you through installing the Xverse Agent 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
npx @secretkeylabs/xverse-agent-wallet --installThis installs the CLI globally and drops a Claude Code skill into ~/.claude/skills/xverse-agent-wallet/SKILL.md that teaches AI agents how to operate every command.
Verify the installation:
xverse-wallet --helpTwo ways to run
There are two ways to use the wallet:
Agent mode
xverse-wallet agent
Letting Claude Code (or another AI agent) run the wallet for you. Handles wallet setup and auth automatically.
Direct mode
xverse-wallet <cmd>
Running CLI commands yourself, in scripts, or from a custom agent framework.
For agent mode, see Agent Mode. For everything else, keep reading.
Authentication
The CLI encrypts your wallet vault at rest using a passphrase provided via environment variable. Set it before any direct-mode wallet operation:
This pattern is compatible with any secret manager (AWS Secrets Manager, HashiCorp Vault, 1Password CLI, etc.).
Your password is the only thing protecting your funds. Use a strong, unique one.
Create a wallet
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):
To restore an existing wallet:
Tip: The leading space before the command prevents the mnemonic from being saved in shell history.
Check your wallet
Output modes
Every command supports three output modes:
(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:
Switching vs. on-demand
You can either switch the active profile/account (persistent) or target one on-demand (one-off):
Use on-demand (-a, -p) for quick queries. Use switching when you want all subsequent commands to target a specific context.
Creating a new profile
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": truein JSON mode. Nothing is broadcast.With
--yes: the transaction is signed and broadcast.
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.
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):
Supports BTC, STX, WBTC, STRK, and USDC. Most providers require a $20+ minimum.
Receive from another wallet:
Send BTC to the native address from any exchange or wallet.
Check your balances:
Next steps
With your wallet created and funded, explore the capabilities:
🚀 Getting Started
This page walks you through installing the Xverse Agent 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
This installs the CLI globally and drops a Claude Code skill into ~/.claude/skills/xverse-agent-wallet/SKILL.md that teaches AI agents how to operate every command.
Verify the installation:
Two ways to run
There are two ways to use the wallet:
Agent mode
xverse-wallet agent
Letting Claude Code (or another AI agent) run the wallet for you. Handles wallet setup and auth automatically.
Direct mode
xverse-wallet <cmd>
Running CLI commands yourself, in scripts, or from a custom agent framework.
For agent mode, see Agent Mode. For everything else, keep reading.
Authentication
The CLI encrypts your wallet vault at rest using a passphrase provided via environment variable. Set it before any direct-mode wallet operation:
This pattern is compatible with any secret manager (AWS Secrets Manager, HashiCorp Vault, 1Password CLI, etc.).
Your password is the only thing protecting your funds. Use a strong, unique one.
Create a wallet
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):
To restore an existing wallet:
Tip: The leading space before the command prevents the mnemonic from being saved in shell history.
Check your wallet
Output modes
Every command supports three output modes:
(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:
Switching vs. on-demand
You can either switch the active profile/account (persistent) or target one on-demand (one-off):
Use on-demand (-a, -p) for quick queries. Use switching when you want all subsequent commands to target a specific context.
Creating a new profile
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": truein JSON mode. Nothing is broadcast.With
--yes: the transaction is signed and broadcast.
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.
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):
Supports BTC, STX, WBTC, STRK, and USDC. Most providers require a $20+ minimum.
Receive from another wallet:
Send BTC to the native address from any exchange or wallet.
Check your balances:
Next steps
With your wallet created and funded, explore the capabilities:
Run with Claude Code
Send and receive BTC on L1
Lightning payments via Spark
Machine-payable API calls
Trade on Starknet
Swap across chains
Full portfolio overview
Last updated