🤖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

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:

xverse-wallet --uninstall

Launch an agent with wallet access

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:

xverse-wallet agent --agent <provider>

Non-interactive mode

For automated environments (CI, scripts, scheduled jobs):

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 <btc> --speed fast.

• "Call the Xverse rune price API for DOG and tell me the floor." → Agent runs pay request <url> --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.

• Building a Lightning commerce agent? See the Agentic Lightning Commerce guide.

• Building a trading agent? See the Starknet Trading guide or Flashnet Trading guide.