wallet

Original：🇺🇸 English
Translated
1 scriptsChecked / no sensitive code detected

Manage encrypted BIP39 wallets stored at ~/.aibtc/. Create, import, unlock, lock, list, switch, delete, export, rotate passwords, set auto-lock timeouts, and check status or info for Stacks and Bitcoin addresses.

15installs
Sourceaibtcdev/skills
Added on

NPX Install

npx skill4agent add aibtcdev/skills wallet

Tags

Translated version includes tags in frontmatter
wallet-managementbip39-walletsbitcoin-stacksencryption-securitycli-tool

SKILL.md Content

View Translation Comparison →

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

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

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." }

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
}

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

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."
}

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

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."
}

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."
}

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..." }
}

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..." }
}

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

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