@secretkeylabs/xverse-agent-wallet 0.1.11 → 1.0.1

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 +190 -73
  2. package/dist/cli.js +225239 -139803
  3. package/package.json +11 -12
  4. package/skill/xverse-agent-wallet/SKILL.md +136 -67
package/README.md CHANGED
@@ -31,82 +31,185 @@ xverse-wallet --uninstall
31
31
 
32
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
33
 
34
+ ## Agent / daemon mode
35
+
36
+ For long-running setups (Claude Code, scripts, CI) you can start a daemon that holds the unlocked wallet in memory and serves agent requests over loopback HTTP. Agents authenticate with **API keys** (`xv_key_…`) instead of the master passphrase. Keys are scoped, time-bounded, and cryptographically revocable.
37
+
38
+ ```bash
39
+ # In your terminal: start the daemon (Touch ID / passphrase prompts once).
40
+ xverse-wallet daemon start --background
41
+
42
+ # Mint a scoped, expiring agent token (printed once to stdout). Admin commands
43
+ # like `key create` use the wallet password as the bearer — prompted by
44
+ # default, or read from $XVERSE_PASSWORD. There is no separate admin token.
45
+ export XVERSE_DAEMON_TOKEN=$(xverse-wallet key create --name claude-agent --expires 7d)
46
+
47
+ # Hand the agent the env. From then on, every CLI call routed through --daemon
48
+ # uses the daemon's already-unlocked wallet — no passphrase needed.
49
+ xverse-wallet --daemon bitcoin balance
50
+ xverse-wallet --daemon bitcoin send --to bc1q… --amount 50000
51
+
52
+ # Revoke when done (or on schedule).
53
+ xverse-wallet key revoke --prefix <8-hex-prefix-from-key-list>
54
+ ```
55
+
56
+ Detailed docs:
57
+
58
+ - [AGENT-WALLET.md](./docs/AGENT-WALLET.md) — quickstart, key management, edge cases.
59
+ - [DAEMON.md](./docs/DAEMON.md) — protocol, RPC methods, auth resolution, security properties.
60
+
34
61
  ## Commands
35
62
 
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 |
63
+ | Command | Description |
64
+ | ------------------------------------------------- | ------------------------------------------------ |
65
+ | **Wallet & Accounts** | |
66
+ | `wallet create` | Create a new wallet |
67
+ | `wallet restore` | Restore from mnemonic |
68
+ | `wallet reset` | Delete all wallet data |
69
+ | `wallet export` | Show wallet mnemonic |
70
+ | `wallet status` | Check wallet existence and active profile |
71
+ | `wallet switch <name>` | Switch to a different wallet profile |
72
+ | `wallet profiles` | List all wallet profiles |
73
+ | `account list` | List all derived accounts with addresses |
74
+ | `account current` | Show active account addresses |
75
+ | `account derive` | Derive next account(s) |
76
+ | `account switch <index>` | Switch active account |
77
+ | **Bitcoin** | |
78
+ | `bitcoin balance` | BTC balance (native segwit + taproot) |
79
+ | `bitcoin send` | Send BTC |
80
+ | `bitcoin receive` | Show receive addresses |
81
+ | `bitcoin history` | Transaction history |
82
+ | `bitcoin fees` | Recommended fee rates (sat/vB) |
83
+ | **Stacks** | |
84
+ | `stacks balance` | STX + SIP-10 token balances |
85
+ | `stacks send` | Send STX or SIP-10 token |
86
+ | `stacks receive` | Show STX address |
87
+ | `stacks history` | Token transaction history |
88
+ | **Starknet** | |
89
+ | `starknet balance` | All ERC-20 token balances |
90
+ | `starknet send` | Send STRK or any ERC-20 |
91
+ | `starknet receive` | Show Starknet address |
92
+ | `starknet history` | Token transaction history |
93
+ | `starknet staking status` | Show staking position |
94
+ | `starknet staking deposit` | Stake WBTC |
95
+ | `starknet staking withdraw-intent` | Start withdrawal (~7 day cooldown) |
96
+ | `starknet staking withdraw` | Complete withdrawal after cooldown |
97
+ | `starknet staking claim` | Claim STRK rewards |
98
+ | **Spark & Lightning** | |
99
+ | `spark balance` | Spark balance (auto-claims pending) |
100
+ | `spark deposit` | Deposit BTC from L1 to Spark |
101
+ | `spark claim` | Claim deposits with 3+ confirmations |
102
+ | `spark send` | Send BTC or token on Spark |
103
+ | `spark withdraw` | Withdraw BTC to L1 |
104
+ | `spark receive` | Show Spark address |
105
+ | `spark history` | Transaction history |
106
+ | `spark lightning invoice` | Create Lightning invoice (for receiving) |
107
+ | `spark lightning estimate` | Estimate Lightning payment fee |
108
+ | `spark lightning pay` | Pay Lightning invoice |
109
+ | **Runes** | |
110
+ | `runes balance` | Show rune balances |
111
+ | `runes send` | Send runes |
112
+ | `runes receive` | Show taproot receive address |
113
+ | `runes details` | Show rune etching info |
114
+ | `runes history` | Transaction history for a rune |
115
+ | **Cross-Chain Payments** _(powered by Orchestra)_ | |
116
+ | `bridge routes` | List available cross-chain trading pairs |
117
+ | `bridge estimate` | Price preview (no API key required) |
118
+ | `bridge deposit` | Deposit external assets into your Spark wallet |
119
+ | `bridge submit` | Submit a funded deposit with a tx hash |
120
+ | `bridge send` | Send BTC or USDB from Spark to an external chain |
121
+ | `bridge status` | Check or watch an order's status |
122
+ | `bridge address accumulate` | Create a reusable address for recurring deposits |
123
+ | `bridge address liquidate` | Create a reusable address for recurring sends |
124
+ | **Trading & Funding** | |
125
+ | `swap quote` | Get swap quotes across chains |
126
+ | `swap execute` | Execute a swap (auto-selects best quote) |
127
+ | `fund currencies` | List supported fiat and crypto currencies |
128
+ | `fund providers` | List providers with min/max limits |
129
+ | `fund quote` | Get buy quotes from providers |
130
+ | `fund buy` | Buy crypto with fiat (opens in browser) |
131
+ | **Portfolio & Earning** | |
132
+ | `portfolio` | All balances across all chains |
133
+ | `cash balance` | Stablecoin balances across all chains |
134
+ | `cash receive` | Stablecoin receive addresses |
135
+ | `cash history` | Stablecoin transaction history |
136
+ | `earn status` | Earning overview with suggested actions |
137
+ | `earn guide` | Step-by-step WBTC staking walkthrough |
138
+ | **Machine Payments** | |
139
+ | `pay request <url>` | HTTP request with auto Lightning payment on 402 |
140
+ | `pay api [path]` | Browse MPP-enabled API endpoints |
141
+ | **Agent** | |
142
+ | `agent` | Launch an AI agent with wallet authentication |
107
143
 
108
144
  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
145
 
146
+ ## Cross-Chain Payments
147
+
148
+ Move assets between external chains and your Spark wallet — powered by [Orchestra](https://flashnet.xyz). Deposit USDC from Ethereum, Base, or Solana directly into your USDB balance, or send USDB out to any supported chain.
149
+
150
+ ### Deposit into Spark
151
+
152
+ ```bash
153
+ # Preview: get a quote and deposit address
154
+ xverse-wallet bridge deposit \
155
+ --from ethereum --asset USDC --amount 10 \
156
+ --to spark --asset-out USDB \
157
+ --refund-address <YOUR_ETH_ADDRESS>
158
+
159
+ # One-shot: submit and watch until settled (EVM chains auto-detected)
160
+ xverse-wallet bridge deposit \
161
+ --from ethereum --asset USDC --amount 10 \
162
+ --to spark --asset-out USDB \
163
+ --refund-address <YOUR_ETH_ADDRESS> \
164
+ --watch
165
+
166
+ # Solana (and similar auto-monitored chains): Orchestra detects the deposit
167
+ # automatically — no manual tx-hash submission needed; --watch polls by quoteId
168
+ xverse-wallet bridge deposit \
169
+ --from solana --asset USDC --amount 10 \
170
+ --to spark --asset-out USDB \
171
+ --refund-address <YOUR_SOL_ADDRESS> \
172
+ --watch
173
+ ```
174
+
175
+ ### Send from Spark
176
+
177
+ ```bash
178
+ # Preview
179
+ xverse-wallet bridge send \
180
+ --asset USDB --amount 10 \
181
+ --to ethereum --asset-out USDC \
182
+ --recipient <YOUR_ETH_ADDRESS>
183
+
184
+ # Execute: signs the Spark transfer and submits in one step
185
+ xverse-wallet bridge send \
186
+ --asset USDB --amount 10 \
187
+ --to ethereum --asset-out USDC \
188
+ --recipient <YOUR_ETH_ADDRESS> \
189
+ --yes --watch
190
+ ```
191
+
192
+ ### Track orders
193
+
194
+ ```bash
195
+ # Check a specific order
196
+ xverse-wallet bridge status --order <ORDER_ID>
197
+ ```
198
+
199
+ ### Reusable deposit addresses
200
+
201
+ Send to a fixed address any time — no per-transaction quote needed:
202
+
203
+ ```bash
204
+ # Accumulate recurring deposits into Spark (e.g. from Solana)
205
+ xverse-wallet bridge address accumulate \
206
+ --from solana --asset USDC --asset-out USDB
207
+
208
+ # Liquidate Bitcoin L1 deposits out to an external chain
209
+ xverse-wallet bridge address liquidate \
210
+ --to ethereum --asset-out USDC --recipient <YOUR_ETH_ADDRESS>
211
+ ```
212
+
110
213
  ## Quick Start
111
214
 
112
215
  ```bash
@@ -181,13 +284,25 @@ xverse-wallet agent --quiet
181
284
 
182
285
  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
286
 
287
+ ## Authentication
288
+
289
+ The vault is encrypted with an Argon2id-derived key from your password. The password is read from `XVERSE_PASSWORD` in env, or prompted interactively when commands like `wallet reset`, `wallet export`, `daemon stop`, and `key create` need it.
290
+
291
+ ```bash
292
+ XVERSE_PASSWORD=mypass xverse-wallet wallet create
293
+ xverse-wallet wallet export # prompts for password
294
+ xverse-wallet key create --name claude-agent --expires 7d # prompts for password
295
+ ```
296
+
297
+ Admin RPCs to the daemon (mint/revoke API keys, shutdown) use the wallet password as the bearer — there is no separate admin token. See [docs/AGENT-WALLET.md](docs/AGENT-WALLET.md#admin-authority) for details.
298
+
184
299
  ## Security
185
300
 
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.
301
+ All sensitive data (seed phrases, private keys) is encrypted at rest using AES-256-GCM with an Argon2id-derived key — a memory-hard KDF designed to resist brute-force attacks.
187
302
 
188
303
  **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
304
 
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.
305
+ 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) or a native OS dialog, and the only credential passed to spawned agents is a scoped, revocable API key — the password itself never reaches the agent.
191
306
 
192
307
  ## Development
193
308
 
@@ -204,3 +319,5 @@ bun ./index.ts --help
204
319
  # Type check
205
320
  npx tsc --noEmit
206
321
  ```
322
+
323
+ For local builds and signed-release builds, see [docs/BUILD.md](docs/BUILD.md).