Wallet Commands

The wallet namespace provides HD wallet management, address derivation, transaction signing, and balance queries.

Commands Overview

CommandDescription
createCreate a new wallet or restore from mnemonic
addressesDisplay wallet addresses
utxosList UTXOs in the wallet
balanceGet wallet balance
sendSend a transaction
signSign a PSBT
create-txCreate an unsigned transaction
sign-txSign a transaction
decode-txDecode a transaction
broadcast-txBroadcast a transaction
fee-ratesGet current fee rates
historyGet transaction history
mnemonicDisplay wallet mnemonic
freeze/unfreezeFreeze/unfreeze UTXOs
backupBackup the wallet

wallet create

Create a new HD wallet or restore from a mnemonic.

# Create new wallet with random mnemonic
alkanes-cli wallet create --passphrase "your-secure-passphrase"

# Restore from existing mnemonic
alkanes-cli wallet create "word1 word2 word3 ... word12" \
  --passphrase "your-passphrase"

# Specify output file
alkanes-cli wallet create --passphrase "your-passphrase" \
  --output /custom/path/wallet.json

wallet addresses

Display all derived addresses from the wallet.

alkanes-cli -p mainnet \
  --wallet-file ~/.alkanes/wallet.json \
  --passphrase "your-passphrase" \
  wallet addresses

wallet balance

Get the BTC balance of the wallet.

alkanes-cli -p mainnet \
  --jsonrpc-url https://mainnet.subfrost.io/v4/jsonrpc \
  --wallet-file ~/.alkanes/wallet.json \
  --passphrase "your-passphrase" \
  wallet balance

wallet send

Send BTC to an address.

alkanes-cli -p mainnet \
  --jsonrpc-url https://mainnet.subfrost.io/v4/jsonrpc \
  --wallet-file ~/.alkanes/wallet.json \
  --passphrase "your-passphrase" \
  wallet send <ADDRESS> <AMOUNT_SATS> \
  --fee-rate 10 \
  -y  # Auto-confirm

wallet fee-rates

Get current network fee rate estimates.

alkanes-cli -p mainnet \
  --jsonrpc-url https://mainnet.subfrost.io/v4/jsonrpc \
  wallet fee-rates

# Output:
# Fast: 15 sat/vB
# Medium: 8 sat/vB
# Slow: 3 sat/vB

wallet sign

Sign a PSBT (Partially Signed Bitcoin Transaction).

alkanes-cli -p mainnet \
  --wallet-file ~/.alkanes/wallet.json \
  --passphrase "your-passphrase" \
  wallet sign --psbt <PSBT_BASE64>

wallet broadcast-tx

Broadcast a signed transaction to the network.

alkanes-cli -p mainnet \
  --jsonrpc-url https://mainnet.subfrost.io/v4/jsonrpc \
  wallet broadcast-tx --file /path/to/signed_tx.hex

wallet freeze / unfreeze

Freeze or unfreeze specific UTXOs to prevent them from being spent.

# Freeze a UTXO
alkanes-cli wallet freeze <TXID>:<VOUT>

# Unfreeze a UTXO
alkanes-cli wallet unfreeze <TXID>:<VOUT>

Complete TypeScript Example

import {
  createKeystore,
  unlockKeystore,
  createWallet,
  createProvider,
  AddressType
} from '@alkanes/ts-sdk';
import * as bitcoin from 'bitcoinjs-lib';

async function main() {
  // Create wallet
  const { keystore, mnemonic } = await createKeystore('password123', {
    network: 'mainnet'
  });

  console.log('Mnemonic (save securely!):', mnemonic);

  // Unlock and use
  const unlocked = await unlockKeystore(keystore, 'password123');
  const wallet = createWallet(unlocked);

  // Get addresses
  const taprootAddr = wallet.getReceivingAddress(0);
  const segwitAddr = wallet.deriveAddress(AddressType.P2WPKH, 0);

  console.log('Taproot:', taprootAddr);
  console.log('SegWit:', segwitAddr);

  // Create provider
  const provider = createProvider({
    url: 'https://mainnet.subfrost.io/v4/jsonrpc',
    network: bitcoin.networks.bitcoin,
    networkType: 'mainnet',
  });

  // Check balance
  const balance = await provider.getBalance(taprootAddr);
  console.log('Balance:', balance);
}