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.

Usage

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:

{
  "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:

{
  "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:

{
  "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:

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

list

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

bun run wallet/wallet.ts list

Output:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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