wallet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wallet Skill

钱包工具

Manages encrypted BIP39 wallets stored locally at

~/.aibtc/

. Provides full lifecycle operations for Stacks L2 and Bitcoin L1 (native SegWit + Taproot) addresses. Wallets are AES-GCM encrypted with a password and never stored in plaintext.

管理本地存储在

~/.aibtc/

路径下的加密BIP39钱包。为Stacks L2和Bitcoin L1（原生SegWit + Taproot）地址提供全生命周期操作。钱包通过密码进行AES-GCM加密，绝不会以明文形式存储。

Usage

使用方法

bun run wallet/wallet.ts <subcommand> [options]

bun run wallet/wallet.ts <subcommand> [options]

Subcommands

子命令

create

Create a new wallet with a generated 24-word BIP39 mnemonic.

bun run wallet/wallet.ts create --name <name> --password <password> [--network mainnet|testnet]

Options:

```
--name
```
(required) — Label for the wallet (e.g. "main", "trading")
```
--password
```
(required, min 8 chars) — Encryption password (sensitive)
```
--network
```
(optional) —
```
mainnet
```
or
```
testnet
```
(default:
```
testnet
```
)

Output:

json

{
  "success": true,
  "walletId": "...",
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." },
  "Stacks (L2)": { "Address": "SP..." },
  "network": "testnet",
  "mnemonic": "word1 word2 ... word24",
  "warning": "CRITICAL: Save this mnemonic..."
}

使用生成的24词BIP39助记词创建新钱包。

bun run wallet/wallet.ts create --name <name> --password <password> [--network mainnet|testnet]

选项：

```
--name
```
（必填）——钱包的标签（例如"main"、"trading"）
```
--password
```
（必填，最少8字符）——加密密码（敏感信息）
```
--network
```
（可选）——
```
mainnet
```
或
```
testnet
```
（默认值：
```
testnet
```
）

输出：

json

{
  "success": true,
  "walletId": "...",
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." },
  "Stacks (L2)": { "Address": "SP..." },
  "network": "testnet",
  "mnemonic": "word1 word2 ... word24",
  "warning": "CRITICAL: Save this mnemonic..."
}

import

Import an existing wallet from a BIP39 mnemonic phrase.

bun run wallet/wallet.ts import --name <name> --mnemonic "<24 words>" --password <password> [--network mainnet|testnet]

Options:

```
--name
```
(required) — Label for the wallet
```
--mnemonic
```
(required) — 24-word BIP39 mnemonic (sensitive)
```
--password
```
(required, min 8 chars) — Encryption password (sensitive)
```
--network
```
(optional) —
```
mainnet
```
or
```
testnet
```
(default:
```
testnet
```
)

Output:

json

{
  "success": true,
  "walletId": "...",
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." },
  "Stacks (L2)": { "Address": "SP..." },
  "network": "testnet"
}

通过BIP39助记词短语导入现有钱包。

bun run wallet/wallet.ts import --name <name> --mnemonic "<24 words>" --password <password> [--network mainnet|testnet]

选项：

```
--name
```
（必填）——钱包的标签
```
--mnemonic
```
（必填）——24词BIP39助记词（敏感信息）
```
--password
```
（必填，最少8字符）——加密密码（敏感信息）
```
--network
```
（可选）——
```
mainnet
```
或
```
testnet
```
（默认值：
```
testnet
```
）

输出：

json

{
  "success": true,
  "walletId": "...",
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." },
  "Stacks (L2)": { "Address": "SP..." },
  "network": "testnet"
}

unlock

Unlock a wallet to enable transactions. Session persists in-process memory until locked or timeout.

bun run wallet/wallet.ts unlock --password <password> [--wallet-id <id>]

Options:

```
--password
```
(required) — Wallet password (sensitive)
```
--wallet-id
```
(optional) — Wallet ID to unlock (uses active wallet if omitted)

Output:

json

{
  "success": true,
  "walletId": "...",
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." },
  "Stacks (L2)": { "Address": "SP..." },
  "network": "testnet"
}

解锁钱包以启用交易功能。会话信息会保留在进程内存中，直到锁定或超时。

bun run wallet/wallet.ts unlock --password <password> [--wallet-id <id>]

选项：

```
--password
```
（必填）——钱包密码（敏感信息）
```
--wallet-id
```
（可选）——要解锁的钱包ID（如果省略则使用当前活跃钱包）

输出：

json

{
  "success": true,
  "walletId": "...",
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." },
  "Stacks (L2)": { "Address": "SP..." },
  "network": "testnet"
}

lock

Lock the wallet, clearing sensitive key material from memory.

bun run wallet/wallet.ts lock

Output:

json

{ "success": true, "message": "Wallet is now locked." }

锁定钱包，从内存中清除敏感密钥材料。

bun run wallet/wallet.ts lock

输出：

json

{ "success": true, "message": "Wallet is now locked." }

list

List all available wallets with metadata (no sensitive data).

bun run wallet/wallet.ts list

Output:

json

{
  "wallets": [
    {
      "id": "...",
      "name": "main",
      "btcAddress": "bc1q...",
      "address": "SP...",
      "network": "testnet",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "isActive": true,
      "isUnlocked": false
    }
  ],
  "totalCount": 1
}

列出所有可用钱包及其元数据（无敏感数据）。

bun run wallet/wallet.ts list

输出：

json

{
  "wallets": [
    {
      "id": "...",
      "name": "main",
      "btcAddress": "bc1q...",
      "address": "SP...",
      "network": "testnet",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "isActive": true,
      "isUnlocked": false
    }
  ],
  "totalCount": 1
}

switch

Switch the active wallet (requires unlock after switching).

bun run wallet/wallet.ts switch --wallet-id <id>

Options:

```
--wallet-id
```
(required) — Wallet ID to activate

Output:

json

{
  "success": true,
  "activeWalletId": "...",
  "address": "SP...",
  "network": "testnet"
}

切换活跃钱包（切换后需要重新解锁）。

bun run wallet/wallet.ts switch --wallet-id <id>

选项：

```
--wallet-id
```
（必填）——要激活的钱包ID

输出：

json

{
  "success": true,
  "activeWalletId": "...",
  "address": "SP...",
  "network": "testnet"
}

delete

Permanently delete a wallet (requires password + confirmation).

bun run wallet/wallet.ts delete --wallet-id <id> --password <password> --confirm DELETE

Options:

```
--wallet-id
```
(required) — Wallet ID to delete
```
--password
```
(required) — Wallet password for verification (sensitive)
```
--confirm
```
(required) — Must be exactly
```
DELETE
```

Output:

json

{
  "success": true,
  "deletedWalletId": "...",
  "message": "Wallet deleted permanently."
}

永久删除钱包（需要密码+确认）。

bun run wallet/wallet.ts delete --wallet-id <id> --password <password> --confirm DELETE

选项：

```
--wallet-id
```
（必填）——要删除的钱包ID
```
--password
```
（必填）——用于验证的钱包密码（敏感信息）
```
--confirm
```
（必填）——必须输入确切的
```
DELETE
```
字符串

输出：

json

{
  "success": true,
  "deletedWalletId": "...",
  "message": "Wallet deleted permanently."
}

export

Export the mnemonic phrase for a wallet (requires password + safety acknowledgment).

bun run wallet/wallet.ts export --password <password> --confirm I_UNDERSTAND_THE_RISKS [--wallet-id <id>]

Options:

```
--password
```
(required) — Wallet password (sensitive)
```
--confirm
```
(required) — Must be exactly
```
I_UNDERSTAND_THE_RISKS
```
```
--wallet-id
```
(optional) — Wallet ID (uses active wallet if omitted)

Output:

json

{
  "walletId": "...",
  "mnemonic": "word1 word2 ... word24",
  "warning": "SECURITY WARNING: ..."
}

导出钱包的助记词短语（需要密码+风险确认）。

bun run wallet/wallet.ts export --password <password> --confirm I_UNDERSTAND_THE_RISKS [--wallet-id <id>]

选项：

```
--password
```
（必填）——钱包密码（敏感信息）
```
--confirm
```
（必填）——必须输入确切的
```
I_UNDERSTAND_THE_RISKS
```
字符串
```
--wallet-id
```
（可选）——钱包ID（如果省略则使用当前活跃钱包）

输出：

json

{
  "walletId": "...",
  "mnemonic": "word1 word2 ... word24",
  "warning": "SECURITY WARNING: ..."
}

rotate-password

Change the wallet encryption password (atomic with backup/verify/rollback).

bun run wallet/wallet.ts rotate-password --old-password <pass> --new-password <pass> [--wallet-id <id>]

Options:

```
--old-password
```
(required) — Current password (sensitive)
```
--new-password
```
(required, min 8 chars) — New password (sensitive)
```
--wallet-id
```
(optional) — Wallet ID (uses active wallet if omitted)

Output:

json

{
  "success": true,
  "walletId": "...",
  "message": "Password rotated. Use unlock with the new password."
}

更换钱包加密密码（操作具有原子性，包含备份、验证、回滚机制）。

bun run wallet/wallet.ts rotate-password --old-password <pass> --new-password <pass> [--wallet-id <id>]

选项：

```
--old-password
```
（必填）——当前密码（敏感信息）
```
--new-password
```
（必填，最少8字符）——新密码（敏感信息）
```
--wallet-id
```
（可选）——钱包ID（如果省略则使用当前活跃钱包）

输出：

json

{
  "success": true,
  "walletId": "...",
  "message": "Password rotated. Use unlock with the new password."
}

set-timeout

Set the auto-lock timeout in minutes (0 = never auto-lock).

bun run wallet/wallet.ts set-timeout --minutes <n>

Options:

```
--minutes
```
(required) — Minutes until auto-lock (0 = disabled)

Output:

json

{
  "success": true,
  "autoLockMinutes": 15,
  "message": "Auto-lock set to 15 minutes."
}

设置自动锁定超时时间（单位：分钟，0表示永不自动锁定）。

bun run wallet/wallet.ts set-timeout --minutes <n>

选项：

```
--minutes
```
（必填）——自动锁定前的分钟数（0表示禁用）

输出：

json

{
  "success": true,
  "autoLockMinutes": 15,
  "message": "Auto-lock set to 15 minutes."
}

status

Get wallet readiness status: whether a wallet exists, is active, and is unlocked.

bun run wallet/wallet.ts status

Output:

json

{
  "message": "Wallet is locked. Unlock to perform transactions.",
  "readyForTransactions": false,
  "isUnlocked": false,
  "currentNetwork": "testnet",
  "wallet": { "id": "...", "address": "SP...", "btcAddress": "bc1q..." }
}

获取钱包就绪状态：是否存在钱包、是否为活跃状态、是否已解锁。

bun run wallet/wallet.ts status

输出：

json

{
  "message": "Wallet is locked. Unlock to perform transactions.",
  "readyForTransactions": false,
  "isUnlocked": false,
  "currentNetwork": "testnet",
  "wallet": { "id": "...", "address": "SP...", "btcAddress": "bc1q..." }
}

info

Get the active wallet's address and session info.

bun run wallet/wallet.ts info

Output:

json

{
  "status": "ready",
  "network": "testnet",
  "Stacks (L2)": { "Address": "SP..." },
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." }
}

获取活跃钱包的地址和会话信息。

bun run wallet/wallet.ts info

输出：

json

{
  "status": "ready",
  "network": "testnet",
  "Stacks (L2)": { "Address": "SP..." },
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." }
}

stx-balance

Get the STX balance for a wallet address.

bun run wallet/wallet.ts stx-balance [--address <addr>]

Options:

```
--address
```
(optional) — Stacks address to check (uses active wallet if omitted)

Output:

json

{
  "address": "SP...",
  "network": "testnet",
  "balance": { "stx": "100 STX", "microStx": "100000000" },
  "locked": { "stx": "0 STX", "microStx": "0" }
}

获取钱包地址的STX余额。

bun run wallet/wallet.ts stx-balance [--address <addr>]

选项：

```
--address
```
（可选）——要查询的Stacks地址（如果省略则使用当前活跃钱包）

输出：

json

{
  "address": "SP...",
  "network": "testnet",
  "balance": { "stx": "100 STX", "microStx": "100000000" },
  "locked": { "stx": "0 STX", "microStx": "0" }
}

Security Notes

安全说明

Mnemonics are AES-GCM encrypted before being written to disk
Passwords never appear in stored files
Use
```
lock
```
after sensitive operations to clear keys from memory
```
export
```
and
```
delete
```
require explicit confirmation strings to prevent accidents
```
rotate-password
```
is atomic: original keystore is backed up and restored on failure

助记词在写入磁盘前会经过AES-GCM加密
密码绝不会出现在存储的文件中
完成敏感操作后使用
```
lock
```
命令从内存中清除密钥
```
export
```
和
```
delete
```
命令需要明确的确认字符串以防止误操作
```
rotate-password
```
操作具有原子性：原始密钥库会被备份，若操作失败则会恢复原始备份