@secretkeylabs/xverse-agent-wallet 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +206 -0
  2. package/dist/cli.js +380401 -0
  3. package/package.json +43 -0
  4. package/skill/xverse-agent-wallet/SKILL.md +774 -0
package/README.md ADDED
@@ -0,0 +1,206 @@
1
+ # Xverse Wallet CLI
2
+
3
+ A headless, developer-first Bitcoin wallet CLI for agents and automation. Supports Bitcoin, Stacks, Starknet, Spark L2, Runes, and Lightning.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm i -g @secretkeylabs/xverse-agent-wallet
9
+ ```
10
+
11
+ Or run without installing:
12
+
13
+ ```bash
14
+ npx @secretkeylabs/xverse-agent-wallet --help
15
+ ```
16
+
17
+ ## Claude Code Skill
18
+
19
+ The CLI ships with a Claude Code skill that teaches AI agents how to use every command. Install it so agents can operate the wallet autonomously:
20
+
21
+ ```bash
22
+ # Via the CLI (after installing globally)
23
+ xverse-wallet --install
24
+
25
+ # Or via npx (one-shot)
26
+ npx @secretkeylabs/xverse-agent-wallet --install
27
+
28
+ # To uninstall
29
+ xverse-wallet --uninstall
30
+ ```
31
+
32
+ The skill is installed to `~/.claude/skills/xverse-agent-wallet/SKILL.md` and covers all commands, token guides, agentic workflows, and common patterns. See [.claude/skills/xverse-agent-wallet/SKILL.md](../.claude/skills/xverse-agent-wallet/SKILL.md) for the full reference.
33
+
34
+ ## Commands
35
+
36
+ | Command | Description |
37
+ | ---------------------------------- | ----------------------------------------------- |
38
+ | **Wallet & Accounts** | |
39
+ | `wallet create` | Create a new wallet |
40
+ | `wallet restore` | Restore from mnemonic |
41
+ | `wallet reset` | Delete all wallet data |
42
+ | `wallet export` | Show wallet mnemonic |
43
+ | `wallet status` | Check wallet existence and active profile |
44
+ | `wallet switch <name>` | Switch to a different wallet profile |
45
+ | `wallet profiles` | List all wallet profiles |
46
+ | `account list` | List all derived accounts with addresses |
47
+ | `account current` | Show active account addresses |
48
+ | `account derive` | Derive next account(s) |
49
+ | `account switch <index>` | Switch active account |
50
+ | **Bitcoin** | |
51
+ | `bitcoin balance` | BTC balance (native segwit + taproot) |
52
+ | `bitcoin send` | Send BTC |
53
+ | `bitcoin receive` | Show receive addresses |
54
+ | `bitcoin history` | Transaction history |
55
+ | `bitcoin fees` | Recommended fee rates (sat/vB) |
56
+ | **Stacks** | |
57
+ | `stacks balance` | STX + SIP-10 token balances |
58
+ | `stacks send` | Send STX or SIP-10 token |
59
+ | `stacks receive` | Show STX address |
60
+ | `stacks history` | Token transaction history |
61
+ | **Starknet** | |
62
+ | `starknet balance` | All ERC-20 token balances |
63
+ | `starknet send` | Send STRK or any ERC-20 |
64
+ | `starknet receive` | Show Starknet address |
65
+ | `starknet history` | Token transaction history |
66
+ | `starknet staking status` | Show staking position |
67
+ | `starknet staking deposit` | Stake WBTC |
68
+ | `starknet staking withdraw-intent` | Start withdrawal (~7 day cooldown) |
69
+ | `starknet staking withdraw` | Complete withdrawal after cooldown |
70
+ | `starknet staking claim` | Claim STRK rewards |
71
+ | **Spark & Lightning** | |
72
+ | `spark balance` | Spark balance (auto-claims pending) |
73
+ | `spark deposit` | Deposit BTC from L1 to Spark |
74
+ | `spark claim` | Claim deposits with 3+ confirmations |
75
+ | `spark send` | Send BTC or token on Spark |
76
+ | `spark withdraw` | Withdraw BTC to L1 |
77
+ | `spark receive` | Show Spark address |
78
+ | `spark history` | Transaction history |
79
+ | `spark lightning invoice` | Create Lightning invoice (for receiving) |
80
+ | `spark lightning estimate` | Estimate Lightning payment fee |
81
+ | `spark lightning pay` | Pay Lightning invoice |
82
+ | **Runes** | |
83
+ | `runes balance` | Show rune balances |
84
+ | `runes send` | Send runes |
85
+ | `runes receive` | Show taproot receive address |
86
+ | `runes details` | Show rune etching info |
87
+ | `runes history` | Transaction history for a rune |
88
+ | **Trading & Funding** | |
89
+ | `swap quote` | Get swap quotes across chains |
90
+ | `swap execute` | Execute a swap (auto-selects best quote) |
91
+ | `fund currencies` | List supported fiat and crypto currencies |
92
+ | `fund providers` | List providers with min/max limits |
93
+ | `fund quote` | Get buy quotes from providers |
94
+ | `fund buy` | Buy crypto with fiat (opens in browser) |
95
+ | **Portfolio & Earning** | |
96
+ | `portfolio` | All balances across all chains |
97
+ | `cash balance` | Stablecoin balances across all chains |
98
+ | `cash receive` | Stablecoin receive addresses |
99
+ | `cash history` | Stablecoin transaction history |
100
+ | `earn status` | Earning overview with suggested actions |
101
+ | `earn guide` | Step-by-step WBTC staking walkthrough |
102
+ | **Machine Payments** | |
103
+ | `pay request <url>` | HTTP request with auto Lightning payment on 402 |
104
+ | `pay api [path]` | Browse MPP-enabled API endpoints |
105
+ | **Agent** | |
106
+ | `agent` | Launch an AI agent with wallet authentication |
107
+
108
+ Run `xverse-wallet --help` for the full command tree. See the [skill](../.claude/skills/xverse-agent-wallet/SKILL.md) for detailed options and examples.
109
+
110
+ ## Quick Start
111
+
112
+ ```bash
113
+ export XVERSE_PASSWORD="your-password"
114
+
115
+ # Create a new wallet
116
+ xverse-wallet wallet create --show-mnemonic --json
117
+
118
+ # Or restore from mnemonic (leading space hides from shell history)
119
+ XVERSE_MNEMONIC="word1 word2 ..." xverse-wallet wallet restore --json
120
+
121
+ # Check all balances
122
+ xverse-wallet portfolio --json
123
+
124
+ # See all commands
125
+ xverse-wallet --help
126
+ ```
127
+
128
+ ## Profiles & Accounts
129
+
130
+ The CLI supports **profiles** (separate wallets) and **accounts** (derived addresses within a wallet).
131
+
132
+ **Profiles** are independent wallets — each has its own mnemonic, accounts, and data. Use profiles to manage multiple wallets (e.g. `default`, `trading`, `savings`).
133
+
134
+ **Accounts** are BIP-44 derived addresses within a single wallet. Account 0 is created automatically. Derive more with `account derive`.
135
+
136
+ ### Switching (persistent)
137
+
138
+ Changes the default for all subsequent commands:
139
+
140
+ ```bash
141
+ xverse-wallet wallet switch trading # switch active profile
142
+ xverse-wallet account switch 2 # switch active account
143
+ ```
144
+
145
+ ### On-demand (one-off)
146
+
147
+ Runs a single command without changing the default:
148
+
149
+ ```bash
150
+ # Different account
151
+ xverse-wallet -a 2 bitcoin balance --json
152
+
153
+ # Different profile
154
+ xverse-wallet -p trading spark balance --json
155
+
156
+ # Both
157
+ xverse-wallet -p trading -a 2 bitcoin balance --json
158
+ ```
159
+
160
+ ### Creating a new profile
161
+
162
+ ```bash
163
+ xverse-wallet wallet switch trading
164
+ XVERSE_MNEMONIC="word1 word2 ..." xverse-wallet wallet restore
165
+ xverse-wallet wallet switch default # switch back
166
+ ```
167
+
168
+ Use on-demand (`-a`, `-p`) when checking balances or running quick queries. Use switching when you want all subsequent commands to target a specific profile/account.
169
+
170
+ ## Agent Mode
171
+
172
+ Let an AI agent (e.g. Claude Code) operate the wallet autonomously. Handles wallet creation/restore, password authentication, and launches the agent with full CLI access:
173
+
174
+ ```bash
175
+ # Launch Claude Code with wallet access (default)
176
+ xverse-wallet agent
177
+
178
+ # Non-interactive (requires XVERSE_PASSWORD env var)
179
+ xverse-wallet agent --quiet
180
+ ```
181
+
182
+ On first run with no wallet, it interactively prompts to create or restore. On subsequent runs, it prompts for the password, authenticates, and launches the agent with `XVERSE_PASSWORD` set so all CLI commands work within the session.
183
+
184
+ ## Security
185
+
186
+ All sensitive data (seed phrases, private keys) is encrypted at rest using AES-256-GCM. The encryption key is derived from your password via Argon2id, a memory-hard KDF designed to resist brute-force attacks.
187
+
188
+ **Your password is the only thing protecting your funds.** Use a strong, unique password — if someone gains access to the encrypted vault file and your password is weak, they can derive your keys and steal your assets.
189
+
190
+ No plaintext secrets are ever written to disk. Session state is ephemeral and cleared on process exit. In agent mode, the password is prompted from stdin (masked) and passed to the agent process as an environment variable — it is never written to disk or shell history.
191
+
192
+ ## Development
193
+
194
+ ```bash
195
+ # Install core deps (from repo root)
196
+ npm install
197
+
198
+ # Install CLI deps
199
+ cd headless && npm install
200
+
201
+ # Run CLI
202
+ bun ./index.ts --help
203
+
204
+ # Type check
205
+ npx tsc --noEmit
206
+ ```