# Agent Mode The fastest way to put an AI agent in control of your wallet. The CLI ships with a **Claude Code skill** and a built-in **agent launcher** that handles wallet setup, password authentication, and gives the agent full access to every CLI command. ### Why this matters If you're building agentic workflows, you don't want to wire up wallet auth, prompt for passwords, manage env vars, and teach the agent every command yourself. Agent mode does all of that for you. * **One command to install:** `npx @secretkeylabs/xverse-agent-wallet --install` installs the CLI and the Claude Code skill in one go. * **One command to launch:** `xverse-wallet agent` boots Claude Code with the wallet authenticated. * **No plaintext secrets on disk:** the password is prompted from stdin, masked, and passed as an env var to the agent process. *** ### 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`. The skill teaches AI agents how to operate the wallet — every command, every option, token guides, agentic workflows, and common patterns. Once installed, Claude Code automatically picks it up the next time you launch an agent session. To uninstall: ```bash xverse-wallet --uninstall ``` ### Launch an agent with wallet access ```bash xverse-wallet agent ``` What this does: 1. **Checks for an existing wallet.** On first run, it interactively prompts you to create a new wallet or restore from a mnemonic. 2. **Prompts for your password** (masked stdin input). 3. **Authenticates the vault.** 4. **Launches Claude Code** with `XVERSE_PASSWORD` set in the agent's environment, so every CLI command works inside the session without re-auth. From the agent's perspective, it can run any CLI command — `portfolio`, `bitcoin send`, `swap execute`, `pay request`, `spark lightning pay` — and they all just work. #### Other agent providers The default agent is Claude Code, but the launcher can target other providers: ```bash xverse-wallet agent --agent ``` #### Non-interactive mode For automated environments (CI, scripts, scheduled jobs): ```bash export XVERSE_PASSWORD="your-secure-passphrase" xverse-wallet agent --quiet ``` In quiet mode, the launcher skips the password prompt and uses the env var directly. ### Security model * The password is **prompted from stdin** with masked input — it never appears in your shell history. * It's **passed to the agent subprocess as an environment variable**, then cleared from the launcher's memory. * It is **never written to disk**. * The vault itself is encrypted at rest with a passphrase from an environment variable, compatible with any secret manager. * Session state is **ephemeral** — it's cleared when the agent process exits. ### What the agent can do once it's running Once the agent is launched, it has access to the full CLI command tree. Some examples of what you can ask Claude Code to do: * *"Show me all my balances across every chain and account."* → Agent runs `xverse-wallet portfolio --accounts 0-4 --json` and summarizes the result. * *"DCA $50 of USDC into WBTC on Starknet."* → Agent runs `xverse-wallet swap execute --from starknet:USDC --to starknet:WBTC --amount 50` (preview), shows you the quote, then executes with `--yes` after confirmation. * *"Pay this Lightning invoice: lnbc..."* → Agent estimates the fee with `spark lightning estimate`, shows you the cost, and pays with `spark lightning pay --yes`. * *"Sweep my Spark profits to cold storage."* → Agent checks the Spark balance, then runs `spark withdraw --amount --speed fast`. * *"Call the Xverse rune price API for DOG and tell me the floor."* → Agent runs `pay request --yes` (which auto-pays the Lightning fee via MPP) and parses the response. > **Safety note:** The skill teaches the agent to **always preview transactions before executing them**. The agent should never run a `--yes` command without first showing you the dry-run output and getting your confirmation. ### What the skill covers The installed skill (`~/.claude/skills/xverse-agent-wallet/SKILL.md`) is a comprehensive reference covering: * Every CLI command, with options and examples * Token format guide (BTC-pegged tokens, stablecoins, native chain tokens) * How to move assets across layers (fast same-chain vs slow cross-chain routes) * Funding strategies (fiat on-ramp, swaps, deposits) * Agentic workflows (Lightning commerce, treasury management, trading patterns) * Common gotchas (native vs taproot BTC, multi-account scanning, Lightning fee budgets) * Onboarding strategies for new wallets ### Next steps * New to the CLI? Start with [Getting Started](https://claude.ai/chat/getting-started.md). * Building a Lightning commerce agent? See the [Agentic Lightning Commerce guide](https://claude.ai/chat/guide-lightning-commerce.md). * Building a trading agent? See the [Starknet Trading guide](https://claude.ai/chat/guide-starknet-trading.md) or [Flashnet Trading guide](https://claude.ai/chat/guide-flashnet-trading.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/agent-mode.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.