# Xverse Agent Wallet

## **The first Bitcoin-native wallet built for AI agents.**

Xverse Agent Wallet is a headless, developer-first wallet that gives AI agents the ability to hold, send, receive, swap, and trade assets across Bitcoin and its layer 2s — without a browser extension, without a UI, and without human intervention.

Agentic wallets are emerging across EVM and Solana ecosystems. Bitcoin has been left behind. Xverse fills that gap — with native support for Bitcoin L1, Spark (Lightning), Starknet, and Stacks from day one. 

### ⚡ What makes it different

Xverse Agent Wallet isn't an embedded wallet with an agent wrapper. It's purpose-built infrastructure for autonomous Bitcoin operations:

* **Bitcoin-native** — built on the same `xverse-core` that powers the Xverse wallet used by millions. Same derivation paths, same transaction builders, same vault encryption.
* **Multi-chain from birth** — your agent can hold BTC, trade on Starknet DEXes (AVNU), swap on Flashnet (Spark), pay Lightning invoices, and manage Runes — all from one wallet.
* **Headless CLI** — no browser, no popups. Every operation is a CLI command with `--json` output. Built for scripts, bots, and AI agent frameworks.
* **Machine-payable APIs** — built-in support for the Machine Payments Protocol (MPP). Your agent can call paid APIs and settle over Lightning automatically — no checkout flows, no human approval.
* **Self-custodial** — the agent owns its keys. The vault is encrypted at rest with a passphrase from an environment variable, compatible with any secret manager.

### 🚀 What your agent can do

#### 💲 Agentic Payments

Pay and get paid on Lightning rails via Spark. Sub-cent fees, sub-second settlement. Your agent can create invoices, pay invoices, and call MPP-enabled APIs that settle over Lightning automatically.

#### 📈 Agentic Trading

Execute spot trades across integrated DEXes — AVNU on Starknet, Flashnet on Spark, Dotswap and Sats Terminal for Runes. Quote, compare, and execute from the command line.

#### 🏦 Treasury Management

Sweep profits to cold BTC storage, rebalance between stables and BTC, harvest staking rewards, and manage funds across hot wallets and cold vaults.

#### 📊 Portfolio Intelligence

Query balances across all chains, scan multiple accounts, and monitor your full asset allocation — Bitcoin, Starknet, Spark, Stacks, Runes, stablecoins, and staking positions — in a single command.

### 🏗️ Architecture

```
┌──────────────────────────────────────┐
│           AI Agent (any framework)   │
│  ┌──────────────────────────────┐    │
│  │   xverse-wallet CLI          │    │
│  │   (wraps xverse-core)        │    │
│  │                               │    │
│  │   • Wallet creation & vault   │    │
│  │   • Balance retrieval         │    │
│  │   • Sign & broadcast txns    │    │     ┌──────────────┐
│  │   • BTC / Spark / Starknet / │────┼────▶│  Blockchain  │
│  │     Stacks / Runes / LN      │    │     │  Networks    │
│  └──────────────────────────────┘    │     └──────────────┘
└──────────────────────────────────────┘
```

The CLI wraps `xverse-core` directly — the same library that powers the Xverse browser extension and mobile app. If something works in the CLI, it works everywhere.

### 📦 Install

```bash
npx @secretkeylabs/xverse-agent-wallet --install
```

### ⚡ Quickstart

Run the command in your terminal to start Claude Code with wallet access. It will handle wallet setup and password authentication automatically.

```bash
xverse-wallet agent
```

For other AI agents, use:

```bash
xverse-wallet agent --agent <provider>
```

From here, explore the capabilities your agent needs:

| I want to...                        | Start here                                                                                                |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Pay or receive on Lightning         | [Spark & Lightning](https://docs.xverse.app/xverse-agentic-wallet/capabilities/spark-and-lightning)       |
| Call paid APIs over Lightning       | [Machine Payments (MPP)](https://docs.xverse.app/xverse-agentic-wallet/guides/agentic-lightning-commerce) |
| Trade on Starknet DEXes             | [Starknet Trading Guide](https://docs.xverse.app/xverse-agentic-wallet/guides/agentic-starknet-trading)   |
| Trade on Flashnet (Spark)           | [Flashnet Trading Guide](https://docs.xverse.app/xverse-agentic-wallet/guides/agentic-flashnet-trading)   |
| Manage balances across all chains   | [Portfolio & Treasury](https://docs.xverse.app/xverse-agentic-wallet/capabilities/portfolio-and-treasury) |
| Swap between any assets/chains      | [Swaps](https://docs.xverse.app/xverse-agentic-wallet/capabilities/swaps)                                 |
| Manage and send Runes on Bitcoin L1 | [Runes](https://docs.xverse.app/xverse-agentic-wallet/capabilities/runes)                                 |

### 🤝 Join the community

Building with the Xverse Agent Wallet? Join our [developer forum](https://discord.gg/tN84HhSDrz) to connect with the team and other builders.


---

# 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/xverse-agent-wallet.md?ask=<question>
```

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.