# 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

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

Verify the installation:

```bash
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:

```bash
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

```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:** Add a leading space before the command to prevent 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.

### 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`.

### 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):

```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                                                                     |
| ---------------------------- | ------------------------------------------------------------------------ |
| Send and receive BTC on L1   | [Bitcoin](https://claude.ai/chat/bitcoin.md)                             |
| Lightning payments via Spark | [Spark & Lightning](https://claude.ai/chat/spark-and-lightning.md)       |
| Machine-payable API calls    | [Machine Payments (MPP)](https://claude.ai/chat/machine-payments-mpp.md) |
| Trade on Starknet            | [Starknet](https://claude.ai/chat/starknet.md)                           |
| Swap across chains           | [Swaps](https://claude.ai/chat/swaps.md)                                 |
| Full portfolio overview      | [Portfolio & Treasury](https://claude.ai/chat/portfolio-and-treasury.md) |