# 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 ```bash npx @secretkeylabs/xverse-agent-wallet --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: ```bash xverse-wallet --help ``` ### Two ways to run There are two ways to use the wallet: | Mode | Command | Best for | | --------------- | --------------------- | -------------------------------------------------------------------------------------------------------------- | | **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 ` | Running CLI commands yourself, in scripts, or from a custom agent framework. | For agent mode, see [Agent Mode](https://claude.ai/chat/agent-mode.md). 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: ```bash export XVERSE_PASSWORD="your-secure-passphrase" ``` 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 ```bash 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): ```bash xverse-wallet wallet create --show-mnemonic --json ``` To restore an existing wallet: ```bash XVERSE_MNEMONIC="word1 word2 ... word12" xverse-wallet wallet restore --json ``` > **Tip:** The leading space before the command prevents the mnemonic from being saved in shell history. ### Check your wallet ```bash # 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: ```bash 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): ```bash # 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. #### Creating a new profile ```bash xverse-wallet wallet switch trading XVERSE_MNEMONIC="word1 word2 ..." xverse-wallet wallet restore xverse-wallet wallet switch default # switch back ``` ### 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. ```bash # 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`. ### 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): ```bash 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:** ```bash xverse-wallet bitcoin receive --json ``` Send BTC to the `native` address from any exchange or wallet. **Check your balances:** ```bash xverse-wallet portfolio --accounts 0-4 --json ``` ### 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 ```bash npx @secretkeylabs/xverse-agent-wallet --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: ```bash xverse-wallet --help ``` ### Two ways to run There are two ways to use the wallet: | Mode | Command | Best for | | --------------- | --------------------- | -------------------------------------------------------------------------------------------------------------- | | **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 ` | Running CLI commands yourself, in scripts, or from a custom agent framework. | For agent mode, see [Agent Mode](https://claude.ai/chat/agent-mode.md). 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: ```bash export XVERSE_PASSWORD="your-secure-passphrase" ``` 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 ```bash 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): ```bash xverse-wallet wallet create --show-mnemonic --json ``` To restore an existing wallet: ```bash XVERSE_MNEMONIC="word1 word2 ... word12" xverse-wallet wallet restore --json ``` > **Tip:** The leading space before the command prevents the mnemonic from being saved in shell history. ### Check your wallet ```bash # 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: ```bash 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): ```bash # 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. #### Creating a new profile ```bash xverse-wallet wallet switch trading XVERSE_MNEMONIC="word1 word2 ..." xverse-wallet wallet restore xverse-wallet wallet switch default # switch back ``` ### 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. ```bash # 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`. ### 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): ```bash 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:** ```bash xverse-wallet bitcoin receive --json ``` Send BTC to the `native` address from any exchange or wallet. **Check your balances:** ```bash xverse-wallet portfolio --accounts 0-4 --json ``` ### Next steps With your wallet created and funded, explore the capabilities: | Capability | Page | | ---------------------------- | ------------------------------------------------------------------------------------- | | Run with Claude Code | [Agent Mode](/xverse-agentic-wallet/agent-mode.md) | | Send and receive BTC on L1 | [Bitcoin](/xverse-agentic-wallet/capabilities/bitcoin.md) | | Lightning payments via Spark | [Spark & Lightning](/xverse-agentic-wallet/capabilities/spark-and-lightning.md) | | Machine-payable API calls | [Machine Payments (MPP)](/xverse-agentic-wallet/guides/agentic-lightning-commerce.md) | | Trade on Starknet | [Starknet](/xverse-agentic-wallet/guides/agentic-starknet-trading.md) | | Swap across chains | [Swaps](/xverse-agentic-wallet/capabilities/swaps.md) | | Full portfolio overview | [Portfolio & Treasury](/xverse-agentic-wallet/capabilities/portfolio-and-treasury.md) | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.xverse.app/xverse-agentic-wallet/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.