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