@secretkeylabs/xverse-agent-wallet 0.1.6

package/skill/xverse-agent-wallet/SKILL.md

@@ -0,0 +1,774 @@
+---
+name: xverse-agent-wallet
+description: 'Use the xverse-wallet CLI to manage Bitcoin, Stacks, Starknet, Spark, and Runes wallets. Trigger when the user wants to check crypto balances, send crypto, manage wallet accounts, swap tokens, stake, or interact with Lightning Network via CLI.'
+---
+
+# xverse-wallet CLI
+
+A headless wallet CLI for Bitcoin, Stacks, Starknet, Spark L2, Runes, and Lightning.
+
+## Prerequisites
+
+- The `xverse-wallet` binary must be on PATH (installed via `npm i -g @secretkeylabs/xverse-agent-wallet`)
+- **Auth check:** On first wallet interaction, run `xverse-wallet bitcoin balance --json` as a quick probe. If it fails with "XVERSE_PASSWORD env var is required" or "Vault not initialised", tell the user:
+
+  > Wallet is not authenticated in this session. Run `xverse-wallet agent` in your terminal to start Claude Code with wallet access. It will handle wallet setup and password authentication automatically.
+  > For other AI agents, use `xverse-wallet agent --agent <provider>`.
+
+  Then stop — do not proceed with wallet operations until the user restarts via `xverse-wallet agent`.
+
+- Data is stored at `~/.local/share/xverse-headless/` by default (override with `XDG_DATA_HOME`)
+
+## Output Modes
+
+ALWAYS use `--json` when you need to parse command output programmatically.
+
+- Default: human-readable tables
+- `--json`: structured JSON output
+- `-q` / `--quiet`: single value output (e.g. just a txid or address)
+
+## Global Options
+
+All commands accept these options:
+
+- `-a, --account <index>` — temporarily run a command on a different account without switching (default: current selected account)
+- `-p, --profile <name>` — run against a specific wallet profile without switching (default: active profile)
+- `--json` — JSON output
+- `-q, --quiet` — minimal single-value output
+
+### Profiles vs Accounts
+
+The CLI supports **profiles** (separate wallets) and **accounts** (derived addresses within a wallet). Every command runs against the currently active profile and account by default.
+
+**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 vs On-Demand
+
+There are two ways to target a different profile or account:
+
+**Switching (persistent)** — changes the default for all subsequent commands:
+
+```bash
+wallet switch trading          # switch active profile
+account switch 2               # switch active account
+```
+
+**On-demand (one-off)** — runs a single command without changing the default:
+
+```bash
+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`) when checking balances or running quick queries. Use switching when you want all subsequent commands to target a specific profile/account.
+
+## Transaction Safety
+
+All send/execute commands support a **dry-run pattern**: without `--yes` they show a preview and return `"dryRun": true` in `--json` mode. Add `--yes` to actually execute.
+
+**CRITICAL RULE: NEVER run any command with `--yes` without explicitly asking the user first if they want to execute it.** Always run the command without `--yes` first to get a preview, show the preview to the user, and only add `--yes` after the user explicitly confirms they want to proceed. This applies to ALL commands that accept `--yes` — sends, swaps, deposits, withdrawals, staking, Lightning payments, and wallet reset.
+
+## Commands
+
+### wallet — Wallet Lifecycle
+
+| Command                | Description                             | Key Options                                                  |
+| ---------------------- | --------------------------------------- | ------------------------------------------------------------ |
+| `wallet create`        | Create new wallet                       | `--show-mnemonic` to display seed phrase                     |
+| `wallet restore`       | Restore from mnemonic                   | Inline: `XVERSE_MNEMONIC="..." xverse-wallet wallet restore` |
+| `wallet reset`         | Delete all wallet data                  | `--yes` required to confirm                                  |
+| `wallet export`        | Show wallet mnemonic                    |                                                              |
+| `wallet status`        | Check if wallet exists + active profile | No authentication needed                                     |
+| `wallet switch <name>` | Switch to a different wallet profile    | Creates profile dir if new                                   |
+| `wallet profiles`      | List all wallet profiles                | Active profile marked with `*`                               |
+
+**Creating a new profile:**
+
+```bash
+wallet switch trading
+XVERSE_MNEMONIC="word1 word2 ..." wallet restore
+wallet switch default   # switch back
+```
+
+### account — Account Management
+
+| Command           | Description                              | Key Options             |
+| ----------------- | ---------------------------------------- | ----------------------- |
+| `account list`    | List all derived accounts with addresses |                         |
+| `account current` | Show active account addresses            |                         |
+| `account derive`  | Derive next account(s)                   | `--count <n>` (max 100) |
+| `account switch`  | Switch active account                    | `<index>` (positional)  |
+
+### bitcoin — Bitcoin L1
+
+| Command           | Description                               | Key Options                                                                |
+| ----------------- | ----------------------------------------- | -------------------------------------------------------------------------- |
+| `bitcoin fees`    | Show recommended fee rates (sat/vB)       |                                                                            |
+| `bitcoin receive` | Show native segwit + taproot addresses    |                                                                            |
+| `bitcoin balance` | Show BTC balance (native, taproot, total) | `--accounts 0-4`                                                           |
+| `bitcoin history` | Transaction history                       | `--offset <n>`, `--limit <n>`                                              |
+| `bitcoin send`    | Send BTC                                  | `--to <addr>`, `--amount <btc>` (e.g. 0.001), `--fee-rate <rate>`, `--yes` |
+
+Amount is in BTC (e.g. `0.001` = 100,000 sats).
+
+**Note:** `bitcoin balance` shows `native` (spendable, used for sends/deposits) and `taproot` (may be locked by ordinals/runes). Only native segwit balance is spendable for BTC sends and Spark deposits.
+
+### runes — Runes
+
+| Command         | Description                    | Key Options                                                                       |
+| --------------- | ------------------------------ | --------------------------------------------------------------------------------- |
+| `runes receive` | Show taproot receive address   |                                                                                   |
+| `runes balance` | Show rune balances             | `--filter <regex>`                                                                |
+| `runes details` | Show rune etching info         | `--rune <name or ID>` (required)                                                  |
+| `runes send`    | Send runes                     | `--to <addr>`, `--rune <name or ID>`, `--amount <raw-int>`, `--fee-rate`, `--yes` |
+| `runes history` | Transaction history for a rune | `--rune <name or ID>` on current address (required), `--offset`, `--limit`        |
+
+Rune amount is a raw integer (not decimal). Use `runes details` to check divisibility.
+
+### stacks — Stacks (STX)
+
+| Command          | Description                      | Key Options                                                                                                            |
+| ---------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `stacks receive` | Show STX address                 |                                                                                                                        |
+| `stacks balance` | Show STX + SIP-10 token balances | `--filter <regex>`                                                                                                     |
+| `stacks send`    | Send STX or SIP-10 token         | `--token <name>` (e.g. "STX" or SIP-10 name), `--to <addr>`, `--amount <value>`, `--memo`, `--fee <microSTX>`, `--yes` |
+| `stacks history` | Token transaction history        | `--token <symbol>` (required), `--limit <n>`                                                                           |
+
+Amount is in human-readable units (e.g. `1.5` STX).
+
+### starknet — Starknet
+
+| Command            | Description                    | Key Options                                                                                                |
+| ------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `starknet receive` | Show Starknet address          |                                                                                                            |
+| `starknet balance` | Show all ERC-20 token balances | `--filter <regex>`                                                                                         |
+| `starknet history` | Token transaction history      | `--token <symbol>` (required), `--limit`, `--cursor`                                                       |
+| `starknet send`    | Send STRK or any ERC-20        | `--to <addr>`, `--amount <value>`, `--token <contract>` (default: STRK), `--fee-token <contract>`, `--yes` |
+
+Sponsorship is automatic when available. If unavailable, `--fee-token <contract-address>` is required from a token you have balance
+
+#### starknet staking — WBTC Staking
+
+| Command                            | Description                        | Key Options                                                |
+| ---------------------------------- | ---------------------------------- | ---------------------------------------------------------- |
+| `starknet staking status`          | Show staking position              |                                                            |
+| `starknet staking deposit`         | Stake WBTC                         | `--token wbtc`, `--amount <value>`, `--fee-token`, `--yes` |
+| `starknet staking withdraw-intent` | Start withdrawal (~7 day cooldown) | `--amount <wbtc>`, `--fee-token`, `--yes`                  |
+| `starknet staking withdraw`        | Complete withdrawal after cooldown | `--fee-token`, `--yes`                                     |
+| `starknet staking claim`           | Claim STRK rewards                 | `--fee-token`, `--yes`                                     |
+
+### spark — Spark L2
+
+| Command          | Description                              | Key Options                                                                                  |
+| ---------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `spark balance`  | Show Spark balance (auto-claims pending) | `--accounts 0-4`                                                                             |
+| `spark receive`  | Show Spark address                       |                                                                                              |
+| `spark deposit`  | Deposit BTC from L1 to Spark             | `--amount <btc>`, `--fee-rate`, `--yes`. Without `--amount` shows deposit address + pending. |
+| `spark claim`    | Claim deposits with 3+ confirmations     |                                                                                              |
+| `spark send`     | Send BTC or token on Spark               | `--token <name>` (e.g. BTC), `--to <addr>`, `--amount <value>`, `--yes`                      |
+| `spark withdraw` | Withdraw BTC to L1                       | `--amount <btc>`, `--to <addr>` (optional), `--speed slow/medium/fast`, `--yes`              |
+| `spark history`  | Transaction history                      | `--token <name>` (required), `--offset`, `--limit`                                           |
+
+#### spark lightning — Lightning Network
+
+Lightning is powered by Spark L2. **You need BTC on Spark** to pay Lightning invoices or create invoices for receiving.
+
+| Command                    | Description                              | Key Options                                                                                  |
+| -------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `spark lightning invoice`  | Create Lightning invoice (for receiving) | `--amount <sats>` (required), `--memo`                                                       |
+| `spark lightning estimate` | Estimate payment fee                     | `--invoice <bolt11>` (required), `--amount <sats>` (for 0-amount invoices)                   |
+| `spark lightning pay`      | Pay Lightning invoice                    | `--invoice <bolt11>` (required), `--max-fee <sats>` (default: 5), `--amount <sats>`, `--yes` |
+
+Lightning amounts are in sats.
+
+**Important Lightning funding notes:**
+
+- You need enough Spark BTC for the **payment amount + routing fee**. A 1-sat payment with `--max-fee 10` needs at least 11 sats.
+- `spark balance` auto-claims incoming Spark transfers. Always run it before attempting Lightning payments.
+- To fund Lightning, check ALL accounts for Spark BTC: `for i in 0 1 2; do echo "Account $i:"; xverse-wallet -a $i spark balance --json; done`
+- If needed, transfer between accounts: `xverse-wallet -a 2 spark send --token BTC --to <account-0-spark-addr> --amount 0.0001 --json`
+- `pay request` supports `-a <index>` to pay from a specific account.
+
+### cash — Stablecoin Operations
+
+Unified view of stablecoins across all chains: USDC (Starknet), USDB (Spark), USDCx (Stacks).
+
+| Command        | Description                                 | Key Options               |
+| -------------- | ------------------------------------------- | ------------------------- |
+| `cash balance` | Show stablecoin balances across all chains  |                           |
+| `cash receive` | Show receive addresses for each stablecoin  |                           |
+| `cash history` | Stablecoin transaction history (all chains) | `--limit <n>`, `--cursor` |
+
+```bash
+# Check all stablecoin balances at once
+cash balance --json
+# Get addresses to receive stablecoins
+cash receive --json
+# View stablecoin activity
+cash history --json
+```
+
+### pay — Machine-Payable HTTP Requests (MPP/Lightning)
+
+Make HTTP requests to APIs that accept Lightning payments via the Machine Payments Protocol (MPP). Automatically detects 402 Payment Required, pays the Lightning invoice, and retries.
+
+| Command             | Description                                     | Key Options                                                                                |
+| ------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `pay request <url>` | HTTP request with auto Lightning payment on 402 | `--method GET\|POST`, `--body <json>`, `--header <key:value>`, `--max-fee <sats>`, `--yes` |
+| `pay api [path]`    | Browse MPP-enabled API endpoints                | `--search <term>`, `--refresh`, `--json`                                                   |
+
+Without `--yes`, `pay request` shows a cost preview (sats) without paying.
+
+```bash
+# Preview cost (dry run — no payment)
+pay request https://api.secretkeylabs.io/v1/bitcoin/price --json
+# POST with body (preview)
+pay request https://api.secretkeylabs.io/v1/rpc/bitcoin/tx --method POST --body '{"tx":"0200..."}' --json
+# Discover available endpoints
+pay api --json
+# Search for rune-related endpoints
+pay api --search rune --json
+# Get parameter details for a specific endpoint
+pay api /v1/bitcoin/address/{address}/utxo --json
+```
+
+Requires BTC on Spark for Lightning payments. The command handles the full MPP flow: initial request → 402 challenge → Lightning payment → credential retry → response.
+
+#### MPP API Endpoint Catalog (api.secretkeylabs.io)
+
+All endpoints below are MPP-enabled (Lightning-paid). Use `pay request` to call them. Use `pay api <path> --json` for full parameter details. Networks: mainnet `api.secretkeylabs.io`, signet `api-signet.secretkeylabs.io`, testnet4 `api-testnet4.secretkeylabs.io`.
+
+**Bitcoin:**
+
+- `GET /v1/bitcoin/price` — BTC price
+- `GET /v1/bitcoin/mempool/fee-estimates` — Fee rate estimates
+- `GET /v1/bitcoin/mempool/stats` — Mempool projected block stats
+- `GET /v1/bitcoin/tx/{txid}` — Transaction details
+- `GET /v1/bitcoin/tx/{txid}/hex` — Raw transaction hex
+- `GET /v1/bitcoin/address/{address}/balance` — Confirmed + unconfirmed balance
+- `GET /v1/bitcoin/address/{address}/utxo` — Confirmed UTXOs
+- `GET /v1/bitcoin/address/{address}/summary` — Address summary with tx IDs
+- `GET /v1/bitcoin/address/{address}/txs/unconfirmed` — Unconfirmed transactions
+- `GET /v2/bitcoin/address/{address}/utxo` — Mempool-aware UTXOs (v2)
+
+**Ordinals & Inscriptions:**
+
+- `GET /v1/ordinals/address/{address}/utxo` — Ordinals UTXOs (inscriptions, rare sats, runes)
+- `GET /v1/ordinals/address/{address}/inscriptions` — Confirmed inscriptions
+- `GET /v1/ordinals/address/{address}/collections` — Inscription collections
+- `GET /v1/ordinals/collections` — List all collections
+- `GET /v1/ordinals/collections/{collectionId}` — Collection metadata
+- `GET /v1/inscriptions/{inscriptionId}` — Inscription details
+- `GET /v1/ordinals/tx/{txid}` — Ordinal tx info
+
+**Runes:**
+
+- `GET /v1/ordinals/address/{address}/runes` — Rune balances for address
+- `GET /v1/runes/{identifier}` — Rune info + pricing
+- `GET /v1/runes` — Search runes by name
+- `GET /v1/runes/{identifier}/holders` — Rune holders
+- `GET /v1/runes/{identifier}/activity` — Rune activity
+- `GET /v1/runes/stats/top-by-volume` — Top runes by volume
+- `GET /v1/runes/address/{address}/utxo` — Rune UTXOs
+- `GET /v2/runes/address/{address}/balance` — Confirmed + unconfirmed rune balance (v2)
+
+**BRC-20:**
+
+- `GET /v1/ordinals/address/{address}/brc20` — BRC-20 balances
+- `GET /v1/brc20/ticker/{ticker}` — Token info + pricing
+- `GET /v1/brc20/address/{address}/ticker/{ticker}/activity` — Transfer history
+
+**Spark:**
+
+- `GET /v1/spark/address/{address}` — Address summary
+- `GET /v1/spark/address/{address}/btkn` — Token balances
+- `GET /v1/spark/address/{address}/transactions` — Transaction history
+- `GET /v1/spark/tokens/{identifier}` — Token details
+- `GET /v1/spark/tx/{txid}` — Transaction details
+- `GET /v1/spark/btkn/stats/rankings` — Top BTKN tokens
+
+**Blocks & RPC:**
+
+- `GET /v1/block/current` — Current block info
+- `GET /v1/block/height/{height}` — Block by height
+- `POST /v1/rpc/bitcoin/tx` — Broadcast transaction
+- `POST /v2/rpc/bitcoin` — JSON-RPC (any method)
+
+**Swaps & Portfolio:**
+
+- `POST /v1/swaps/get-quotes` — Get swap quotes
+- `POST /v1/swaps/get-destination-tokens` — Available swap destinations
+- `GET /v1/portfolio` — Portfolio addresses
+- `GET /v1/portfolio/history` — Daily balance history
+
+Run `pay api --json` for the full list of all ~140 endpoints with descriptions.
+
+### portfolio — Full Portfolio Overview
+
+Single command to see ALL balances across every chain, including staking positions and stablecoins.
+
+| Command     | Description                                                       | Key Options                              |
+| ----------- | ----------------------------------------------------------------- | ---------------------------------------- |
+| `portfolio` | Show all assets across Bitcoin, Stacks, Starknet, Spark + staking | `--accounts 0-4` to scan a range (max 5) |
+
+Tags in output: `staked`, `unclaimed rewards`, `withdrawing`, `stable`, `rune`.
+
+**Always use `portfolio --accounts 0-4 --json` when searching for funds** — assets may be on a different account than the default. The output includes an `account` field per row when `--accounts` is used. Max 5 accounts per query; only existing accounts are returned.
+
+### earn — Earning Opportunities
+
+Guided staking experience: shows WBTC balance, staking position, claimable STRK rewards, and actionable next steps.
+
+| Command       | Description                                               | Key Options |
+| ------------- | --------------------------------------------------------- | ----------- |
+| `earn status` | Full earning overview with suggested actions              |             |
+| `earn guide`  | Explain how WBTC staking works with step-by-step commands |             |
+
+`earn status` is the single command to answer "how do I make money?" — it checks WBTC balance, staking position, unclaimed rewards, and pending withdrawals, then prints exactly which commands to run next.
+
+### swap — Cross-Asset Swaps
+
+Token format: `protocol:ticker` or `protocol:contract.name` — examples:
+
+- `bitcoin:BTC`, `runes:840000:3`, `starknet:WBTC`, `starknet:STRK`
+- `stacks:STX`, `stacks:SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token`, `spark:BTC`
+
+| Command        | Description                              | Key Options                                                                                                   |
+| -------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `swap quote`   | Get swap quotes                          | `--from <token>`, `--to <token>`, `--amount <value>`, `--provider <code>`                                     |
+| `swap execute` | Execute a swap (auto-selects best quote) | `--from <token>`, `--to <token>`, `--amount <value>`, `--provider`, `--slippage <pct>`, `--fee-rate`, `--yes` |
+
+Swap examples:
+
+```bash
+# BTC <-> Runes
+swap quote --from bitcoin:BTC --to runes:840000:3 --amount 0.01
+swap quote --from runes:840000:3 --to bitcoin:BTC --amount 1000
+
+# BTC <-> Starknet (cross-chain via Atomiq)
+swap quote --from bitcoin:BTC --to starknet:WBTC --amount 0.005
+swap quote --from starknet:WBTC --to bitcoin:BTC --amount 0.005
+swap quote --from bitcoin:BTC --to starknet:STRK --amount 0.01
+
+# BTC <-> Stacks
+swap quote --from bitcoin:BTC --to stacks:STX --amount 0.01
+swap quote --from stacks:STX --to bitcoin:BTC --amount 100
+swap quote --from bitcoin:BTC --to stacks:SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token --amount 0.001
+
+# BTC <-> Spark (L1 to L2 and back)
+swap quote --from bitcoin:BTC --to spark:BTC --amount 0.001
+swap quote --from spark:BTC --to bitcoin:BTC --amount 0.001
+```
+
+### fund — Buy Crypto with Fiat (On-Ramp)
+
+Buy crypto using credit card, bank transfer, Apple Pay, etc. via on-ramp providers (MoonPay, Revolut, Banxa, etc.).
+Supported crypto: BTC, STX, WBTC, STRK, USDC. Fiat currency and payment method are auto-detected from geo-location.
+
+| Command           | Description                                     | Key Options                                                                                    |
+| ----------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `fund currencies` | List supported fiat and crypto currencies       |                                                                                                |
+| `fund providers`  | List providers with min/max limits for a pair   | `--fiat <code>`, `--crypto <symbol>`                                                           |
+| `fund quote`      | Get buy quotes from providers                   | `--crypto <symbol>`, `--amount <fiat>`, `--fiat <code>`, `--method <id>`                       |
+| `fund buy`        | Initiate purchase — opens in browser by default | `--crypto <symbol>`, `--amount <fiat>`, `--provider <name>`, `--fiat`, `--method`, `--no-open` |
+
+Key behaviors:
+
+- `--fiat` and `--method` auto-detect from geo-location if omitted
+- `--provider` auto-selects the best available provider if omitted (fetches quotes, picks first success)
+- If the auto-detected payment method has no results, falls back to `creditcard`
+- `fund buy` opens the checkout URL in the default browser. Use `--no-open` to just print the URL
+- Each provider has minimum/maximum amounts (typically $20–$30k for BTC). Use `fund providers` to check limits
+
+Fund examples:
+
+```bash
+# Simplest — auto-detect everything, opens browser
+fund buy --crypto BTC --amount 100
+# Buy STX with USD
+fund buy --crypto STX --amount 50 --fiat usd
+# Buy WBTC on Starknet (auto-falls back to creditcard if needed)
+fund buy --crypto WBTC --amount 100
+# Check which providers support a pair and their limits
+fund providers --fiat usd --crypto BTC
+# Get detailed quotes before buying
+fund quote --crypto BTC --amount 100 --json
+# Pick a specific provider
+fund buy --crypto BTC --amount 100 --provider moonpay
+# Just get the URL without opening browser
+fund buy --crypto BTC --amount 100 --no-open --quiet
+```
+
+## Token Guide
+
+### BTC-pegged tokens
+
+All of these represent Bitcoin on different layers — they are pegged 1:1 to BTC:
+
+| Token       | Layer      | Description                                         | How to get                                                                                         |
+| ----------- | ---------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| BTC         | Bitcoin L1 | Native Bitcoin                                      | `fund buy --crypto BTC` or receive externally                                                      |
+| BTC (Spark) | Spark L2   | BTC on Spark, instant transfers + Lightning         | `spark deposit` or `swap execute --from bitcoin:BTC --to spark:BTC`                                |
+| WBTC        | Starknet   | Wrapped BTC on Starknet, stakeable for STRK rewards | `swap execute --from bitcoin:BTC --to starknet:WBTC` or `fund buy --crypto WBTC`                   |
+| sBTC        | Stacks     | BTC on Stacks                                       | `swap execute --from bitcoin:BTC --to stacks:SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token` |
+
+### Stablecoins (USD-pegged)
+
+| Token | Layer    | How to get                                                                       |
+| ----- | -------- | -------------------------------------------------------------------------------- |
+| USDC  | Starknet | `fund buy --crypto USDC` or `swap execute --from bitcoin:BTC --to starknet:USDC` |
+| USDC  | Stacks   | `stacks send` / receive — available as SIP-10 token                              |
+| USDB  | Spark L2 | Available as Spark token — `spark send --token USDB`                             |
+
+### Native chain tokens
+
+| Token | Layer    | Description                                      | How to get                                                                   |
+| ----- | -------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
+| STX   | Stacks   | Native Stacks token, used for gas and governance | `fund buy --crypto STX` or `swap execute --from bitcoin:BTC --to stacks:STX` |
+| STRK  | Starknet | Native Starknet token, earned via WBTC staking   | `fund buy --crypto STRK` or earned via `starknet staking claim`              |
+
+## Getting Tokens
+
+- **Buy with fiat**: `fund buy --crypto BTC --amount 100` (see fund section above)
+- **Swap between chains**: `swap execute --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --yes` (see swap section)
+- **Receive from others**: use `<chain> receive --json` for any supported chain
+
+## Moving Assets Across Layers
+
+**Prefer same-chain swaps when possible** — they settle in seconds. Cross-chain routes involving BTC L1 require block confirmations (~10 min per block) and are slow and expensive.
+
+### Fast (same-chain, seconds)
+
+| Route                   | Method                                                 | Speed   |
+| ----------------------- | ------------------------------------------------------ | ------- |
+| STRK → WBTC (Starknet)  | `swap execute --from starknet:STRK --to starknet:WBTC` | Instant |
+| USDC → WBTC (Starknet)  | `swap execute --from starknet:USDC --to starknet:WBTC` | Instant |
+| Any Starknet token swap | `swap execute --from starknet:<X> --to starknet:<Y>`   | Instant |
+| Any Spark token swap    | `swap execute --from spark:<X> --to spark:<Y>`         | Instant |
+
+### Slow (cross-chain, minutes to hours)
+
+| Route                  | Method                                                      | Time                 |
+| ---------------------- | ----------------------------------------------------------- | -------------------- |
+| BTC L1 → Spark L2      | `spark deposit` then `spark claim`                          | ~3 blocks (~30 min)  |
+| Spark L2 → BTC L1      | `spark withdraw`                                            | Depends on `--speed` |
+| BTC L1 → Starknet WBTC | `swap execute --from bitcoin:BTC --to starknet:WBTC`        | ~10-30 min           |
+| Starknet WBTC → BTC L1 | `swap execute --from starknet:WBTC --to bitcoin:BTC`        | ~10-30 min           |
+| BTC L1 → Stacks sBTC   | `swap execute --from bitcoin:BTC --to stacks:...sbtc-token` | ~10-30 min           |
+
+### Funding Spark for Lightning
+
+To fund Spark BTC (needed for Lightning payments via `pay request`), follow this priority order:
+
+**1. Check all accounts first** — another account may already have Spark BTC:
+
+```bash
+# Scan all accounts at once
+portfolio --accounts 0-4 --json
+# Filter for Spark BTC in the results — look for chain:"Spark", asset:"BTC on Spark"
+# If found on another account, use -a to pay from that account directly:
+xverse-wallet -a 2 pay request https://api.example.com/data --json
+```
+
+**2. Same-chain swap on Spark** (instant, if pairs available):
+
+```bash
+swap quote --from spark:USDB --to spark:BTC --json
+```
+
+**3. L1 deposit** (slow — ~30 min for 3 block confirmations):
+
+```bash
+# Check native segwit balance (not taproot — taproot may be locked by ordinals)
+bitcoin balance --json
+# Deposit to Spark
+spark deposit --amount 0.0001 --yes
+# Wait ~30 min for 3 confirmations, then:
+spark claim
+```
+
+**4. Cross-chain swap then deposit** (slowest):
+
+```bash
+swap execute --from starknet:STRK --to bitcoin:BTC --amount 10 --yes
+# Wait for swap to complete, then deposit to Spark
+spark deposit --amount 0.0001 --yes
+# Wait for confirmations, then claim
+spark claim
+```
+
+## Earning
+
+Use `earn status` to see your position, claimable rewards, and suggested next actions.
+Use `earn guide` for a step-by-step walkthrough of WBTC staking.
+
+## Common Workflows
+
+### Bootstrap: Create a New Wallet
+
+```bash
+export XVERSE_PASSWORD="your-password"
+xverse-wallet wallet create --show-mnemonic --json
+xverse-wallet account list --json
+# Fund the wallet: buy BTC with fiat (auto-selects provider, opens browser)
+xverse-wallet fund buy --crypto BTC --amount 100
+# Or receive BTC from an external wallet
+xverse-wallet bitcoin receive --json
+```
+
+### Bootstrap: Restore an Existing Wallet
+
+```bash
+export XVERSE_PASSWORD="your-password"
+# Leading space prevents the mnemonic from being saved in shell history
+ XVERSE_MNEMONIC="word1 word2 ..." xverse-wallet wallet restore --json
+xverse-wallet account list --json
+# Derive more accounts if needed
+xverse-wallet account derive --count 3 --json
+```
+
+### Check All Balances
+
+```bash
+# First check how many accounts exist
+xverse-wallet account list --json
+# Then query all of them (adjust range to match account count)
+xverse-wallet portfolio --accounts 0-4 --json
+# Current account only
+xverse-wallet portfolio --json
+```
+
+### Send BTC (preview then execute)
+
+```bash
+xverse-wallet bitcoin send --to <address> --amount 0.001 --json
+xverse-wallet bitcoin send --to <address> --amount 0.001 --yes --json
+```
+
+### Cross-Chain Swap
+
+```bash
+xverse-wallet swap quote --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --json
+xverse-wallet swap execute --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --yes --json
+```
+
+### Lightning Payment
+
+```bash
+xverse-wallet spark lightning estimate --invoice <bolt11> --json
+xverse-wallet spark lightning pay --invoice <bolt11> --yes --json
+```
+
+### Earning / Staking
+
+```bash
+xverse-wallet earn status --json
+xverse-wallet earn guide
+```
+
+### Portfolio Overview
+
+```bash
+xverse-wallet portfolio --json
+```
+
+## Agentic Workflows
+
+### Agentic Lightning Commerce (Bet 1 — 1st Priority)
+
+Lightning via Spark is the core payment primitive for machine-to-machine commerce. Sub-cent fees, <500ms settlement.
+
+**Merchant flow — accept payments:**
+
+```bash
+# 1. Ensure BTC is on Spark (fund if needed)
+spark balance --json
+# If no Spark BTC, deposit from L1:
+spark deposit --amount 0.01 --yes
+# Wait ~30 min for 3 confirmations, then:
+spark claim
+
+# 2. Create invoice for a payment
+spark lightning invoice --amount 50000 --memo "Order #1234" --json
+# Returns: encoded invoice string — give this to the payer
+
+# 3. Verify payment received
+spark balance --json
+spark history --token BTC --limit 1 --json
+```
+
+**Payer flow — pay Lightning invoices directly:**
+
+```bash
+# Estimate the fee
+spark lightning estimate --invoice <bolt11> --json
+# Pay
+spark lightning pay --invoice <bolt11> --yes --json
+```
+
+**Payer flow — pay MPP-enabled APIs automatically:**
+
+```bash
+# The `pay request` command handles the full 402 → Lightning → retry flow
+pay request https://api.example.com/v1/data --json
+# Agent just calls the API — payment happens transparently
+```
+
+**Continuous commerce loop:**
+An agent can loop: create invoices → poll `spark history` for new transactions → process orders → periodically sweep profits to cold BTC storage via `spark withdraw`.
+
+### Treasury Management
+
+Patterns for managing funds across hot wallets (Spark/Starknet) and cold storage (BTC L1).
+
+**Sweep to cold BTC vault:**
+
+```bash
+# Sweep Spark → BTC L1
+spark withdraw --amount <btc> --speed fast --yes
+# Sweep Starknet WBTC → BTC L1
+swap execute --from starknet:WBTC --to bitcoin:BTC --amount <wbtc> --yes
+# Sweep Starknet STRK → BTC L1
+swap execute --from starknet:STRK --to bitcoin:BTC --amount <strk> --yes
+# Sweep Stacks STX → BTC L1
+swap execute --from stacks:STX --to bitcoin:BTC --amount <stx> --yes
+```
+
+**Rebalance between stables and BTC:**
+
+```bash
+# Check current allocation
+portfolio --json
+cash balance --json
+# Convert BTC to stables
+swap execute --from bitcoin:BTC --to starknet:USDC --amount 0.01 --yes
+# Convert stables back to BTC
+swap execute --from starknet:USDC --to bitcoin:BTC --amount 100 --yes
+```
+
+**Periodic reward harvesting:**
+
+```bash
+# Check and claim staking rewards
+earn status --json
+starknet staking claim --yes
+# Optionally convert STRK rewards to BTC
+swap execute --from starknet:STRK --to bitcoin:BTC --amount <strk> --yes
+```
+
+### Agentic Trading (Bet 2 — 2nd Priority)
+
+Use `swap quote` + `swap execute` for spot trading across all integrated DEXes (AVNU on Starknet, Flashnet on Spark, Dotswap/Sats Terminal for Runes).
+
+**Quote → Execute pattern:**
+
+```bash
+# Get quotes from all providers
+swap quote --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --json
+# Execute with best provider
+swap execute --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --yes --json
+# Or specify a provider
+swap execute --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --provider <code> --yes --json
+```
+
+**DCA (Dollar-Cost Averaging) pattern:**
+An agent can periodically execute small swaps:
+
+```bash
+# Run periodically (e.g. daily):
+swap execute --from starknet:USDC --to starknet:WBTC --amount 10 --yes --json
+```
+
+**Rebalancing pattern:**
+
+```bash
+# 1. Check portfolio
+portfolio --json
+# 2. If overweight in one asset, swap to target allocation
+swap execute --from starknet:WBTC --to starknet:STRK --amount <excess> --yes
+# 3. Verify new allocation
+portfolio --json
+```
+
+**Cross-chain arbitrage:**
+
+```bash
+# Compare prices across chains
+swap quote --from bitcoin:BTC --to starknet:WBTC --amount 0.01 --json
+swap quote --from bitcoin:BTC --to spark:BTC --amount 0.01 --json
+# Execute on the best rate
+```
+
+## Guided Funding — `/xverse-agent-wallet guided-funding`
+
+Triggered automatically when a **new wallet is created** via `xverse-wallet agent`. The wallet is empty — guide the user through funding it.
+
+1. **Show their wallet identity:**
+
+   ```bash
+   xverse-wallet wallet status --json
+   xverse-wallet account current --json
+   ```
+
+   Display the active profile and their addresses so they know where funds will arrive.
+
+2. **Ask how they'd like to fund their wallet.** Present these options:
+
+   - **Buy with fiat** (easiest): `xverse-wallet fund buy --crypto BTC --amount <amount>` — opens a checkout page in the browser. They can also buy STX, WBTC, STRK, or USDC.
+   - **Receive from another wallet**: show their Bitcoin receive address (`xverse-wallet bitcoin receive --json`) and explain they can send BTC from any exchange or wallet to that address.
+   - **Skip for now**: they can fund later anytime.
+
+3. **If they choose to buy**, walk them through `fund buy` interactively — ask which crypto and how much, then run the command. Remind them of provider minimums (~$20+).
+
+4. **After funding** (or skipping), briefly mention what they can do next: stake WBTC for rewards, use Spark for instant Lightning payments, swap between chains. Don't overwhelm — just plant the seeds.
+
+Keep it conversational. This is their first interaction with the wallet.
+
+## Onboarding Strategy — `/xverse-agent-wallet onboarding-strategy`
+
+When the user invokes `/xverse-agent-wallet onboarding-strategy` (or this is triggered automatically after a fresh wallet setup via `xverse-wallet agent`), follow this exact sequence:
+
+1. **Show wallet and account info:**
+
+   ```bash
+   xverse-wallet wallet status --json
+   xverse-wallet account current --json
+   ```
+
+   Display the active profile, data path, and current account addresses to the user so they can see their wallet identity.
+
+2. **Scan all accounts for balances:**
+
+   ```bash
+   xverse-wallet portfolio --accounts 0-4 --json
+   ```
+
+3. **If the wallet has balances**, summarize what they have across chains and suggest actionable next steps based on their holdings:
+
+   - BTC on L1 → suggest staking (swap to WBTC, stake for STRK rewards), Spark deposit for Lightning, or holding
+   - WBTC on Starknet → suggest staking if not already staked (`earn status --json`)
+   - STRK rewards → suggest claiming and compounding or converting to BTC
+   - Stablecoins → mention they can swap to BTC or hold
+   - Runes/tokens → mention swap options
+   - Present 2-3 concrete strategies with the exact commands to execute them
+
+4. **If the wallet has NO balances on any account**, tell the user their wallet is empty and ask if they'd like to fund it. If yes:
+   - Suggest `fund buy --crypto BTC --amount <amount>` to buy with fiat (simplest)
+   - Show their receive addresses (`bitcoin receive --json`) so they can receive from an external wallet
+   - Mention they can also buy STX, WBTC, STRK, or USDC directly via `fund buy`
+
+Keep the tone concise and action-oriented. Present strategies as numbered options the user can pick from, not walls of text.
+
+## Tips & Gotchas
+
+- **Always check `portfolio --accounts 0-4 --json` first** before suggesting actions — understand what the user has across all chains and all accounts.
+- **BTC native vs taproot**: Only native segwit balance is spendable for sends and Spark deposits. Taproot balance may be locked by ordinals/runes. Check `bitcoin balance --json` to see the split.
+- **Lightning needs payment + fee budget**: A 1-sat invoice with `--max-fee 10` needs 11+ sats on Spark. Always ensure enough headroom.
+- **Check ALL accounts for funds**: Use `portfolio --accounts 0-4 --json` to scan everything. Funds might be on a different account than the default. Use `-a <index>` to operate on a specific account.
+- **Prefer same-chain operations**: Same-chain swaps (Starknet→Starknet, Spark→Spark) settle in seconds. Cross-chain involving BTC L1 takes ~10-30 minutes due to block confirmations.
+- **`spark balance` auto-claims**: Running `spark balance` automatically claims incoming Spark transfers. Run it before operations that need Spark BTC.
+- **Fund buy minimums**: Most on-ramp providers require $20+ minimum. Use `fund providers --fiat usd --crypto BTC` to check limits.
+- **Dry-run by default**: All send/execute/buy commands preview without `--yes`. Always preview first, then confirm with `--yes`.