# Xverse Agentic Wallet

## 🤖 Xverse Agentic Wallet

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

Xverse Agentic 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 Agentic 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
npm install -g @secretkeylabs/xverse-wallet-cli
```

### ⚡ Quickstart

```bash
# 1. Set your vault passphrase
export XVERSE_PASSWORD="your-secure-passphrase"

# 2. Create a new wallet
xverse-wallet wallet create --json

# 3. Check your addresses
xverse-wallet account current --json

# 4. Fund via fiat on-ramp (opens browser checkout)
xverse-wallet fund buy --crypto BTC --amount 100

# 5. See everything you own
xverse-wallet portfolio --json
```

From here, explore the capabilities your agent needs:

| I want to...                      | Start here                                                                 |
| --------------------------------- | -------------------------------------------------------------------------- |
| Pay or receive on Lightning       | [Spark & Lightning](https://claude.ai/chat/spark-and-lightning.md)         |
| Call paid APIs over Lightning     | [Machine Payments (MPP)](https://claude.ai/chat/machine-payments-mpp.md)   |
| Trade on Starknet DEXes           | [Starknet Trading Guide](https://claude.ai/chat/guide-starknet-trading.md) |
| Trade on Flashnet (Spark)         | [Flashnet Trading Guide](https://claude.ai/chat/guide-flashnet-trading.md) |
| Trade Runes on Bitcoin L1         | [Runes](https://claude.ai/chat/runes.md)                                   |
| Manage balances across all chains | [Portfolio & Treasury](https://claude.ai/chat/portfolio-and-treasury.md)   |
| Swap between any assets/chains    | [Swaps](https://claude.ai/chat/swaps.md)                                   |

### 🤝 Join the community

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