wallet

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": "...",

import

Import an existing wallet from a BIP39 mnemonic phrase.

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:

unlock

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

Options:

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

Output:

lock

Lock the wallet, clearing sensitive key material from memory.

Output:

list

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

Output:

switch

Switch the active wallet (requires unlock after switching).

Options:

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

Output:

delete

Permanently delete a wallet (requires password + confirmation).

Options:

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

Output:

export

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

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:

rotate-password

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

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:

set-timeout

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

Options:

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

Output:

status

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

Output:

info

Get the active wallet's address and session info.

Output:

stx-balance

Get the STX balance for a wallet address.

Options:

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

Output:

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