Wallet RPCs

Note: BTX enforces PQ (post-quantum) policy: only descriptor wallets are supported (descriptors=true). Legacy wallets are disabled.

createwallet

Create a new wallet. BTX wallets use descriptor-based key management with post-quantum key support.

Parameter	Type	Required	Description
wallet_name	string	Yes	Name for the new wallet
disable_private_keys	boolean	No (default false)	Create a watch-only wallet
blank	boolean	No (default false)	Create a blank wallet with no keys or HD seed
passphrase	string	No	Encrypt the wallet with this passphrase
avoid_reuse	boolean	No (default false)	Track coin reuse for improved privacy
descriptors	boolean	No (default true)	Must be true on BTX
load_on_startup	boolean	No	Automatically load wallet on node startup
external_signer	boolean	No (default false)	Use an external signer (hardware wallet)

btx-cli createwallet "mywallet"

btx-cli createwallet "encrypted" false false "mypassphrase"

Returns name (wallet name) and warning (any caveats).

loadwallet

Load a wallet from the wallet directory.

Parameter	Type	Required	Description
filename	string	Yes	Wallet name or path
load_on_startup	boolean	No	Automatically load on startup

btx-cli loadwallet "mywallet"

unloadwallet

Unload a wallet. If no wallet name is given, unloads the default wallet.

Parameter	Type	Required	Description
wallet_name	string	No	Wallet name to unload (default: caller's wallet)
load_on_startup	boolean	No	Update load-on-startup setting

btx-cli unloadwallet "mywallet"

listwallets

Returns a list of currently loaded wallets. For full information on each wallet, use getwalletinfo.

btx-cli listwallets

Returns an array of wallet name strings.

getwalletinfo

Returns an object containing various wallet state information.

btx-cli getwalletinfo

Key response fields:

Field	Description
walletname	Wallet name
walletversion	Wallet format version
format	Database format (sqlite)
balance	Confirmed balance
unconfirmed_balance	Unconfirmed balance
immature_balance	Immature coinbase balance
txcount	Total transaction count
keypoolsize	Pre-generated external keys
unlocked_until	Unlock expiry (encrypted wallets only)
descriptors	Whether this wallet uses descriptors (always true on BTX)
private_keys_enabled	Whether private keys are available
scanning	Rescan progress or false

backupwallet

Safely copy the current wallet file to the specified destination.

Parameter	Type	Required	Description
destination	string	Yes	Destination file path

btx-cli backupwallet "/backups/wallet.dat"

backupwalletbundle

Create a comprehensive wallet bundle backup that includes the wallet database, descriptor metadata, and PQ key material in a single directory.

Parameter	Type	Required	Description
destination	string	Yes	Destination directory path

btx-cli backupwalletbundle "/backups/bundle/"

Run z_verifywalletintegrity before backing up to confirm all key material is present.

backupwalletbundlearchive

Create a wallet bundle backup and compress it into a single archive file.

Parameter	Type	Required	Description
destination	string	Yes	Destination archive file path

btx-cli backupwalletbundlearchive "/backups/wallet-bundle.tar.gz"

restorewalletbundlearchive

Restore a wallet from a bundle archive previously created by backupwalletbundlearchive.

Parameter	Type	Required	Description
wallet_name	string	Yes	Name for the restored wallet
archive_path	string	Yes	Path to the bundle archive

btx-cli restorewalletbundlearchive "restored" "/backups/wallet-bundle.tar.gz"

encryptwallet

Encrypts the wallet with a passphrase. This is a one-time operation -- once encrypted, the passphrase cannot be removed, only changed. The node will shut down after encryption; restart it afterward.

Parameter	Type	Required	Description
passphrase	string	Yes	The wallet passphrase (must not be empty)

btx-cli encryptwallet "my-secure-passphrase"

Important: Shielded keys require an encrypted wallet. Encrypt before using any shielded features.

walletpassphrase

Unlock the wallet for the specified number of seconds. Required before signing transactions or deriving shielded keys on an encrypted wallet.

Parameter	Type	Required	Description
passphrase	string	Yes	The wallet passphrase
timeout	number	Yes	Seconds to keep the wallet unlocked (max 1073741824)

btx-cli walletpassphrase "my-secure-passphrase" 600

walletpassphrasechange

Change the wallet passphrase.

Parameter	Type	Required	Description
oldpassphrase	string	Yes	Current passphrase
newpassphrase	string	Yes	New passphrase

btx-cli walletpassphrasechange "old-passphrase" "new-passphrase"

dumpprivkey

Reveal the private key for a given address in WIF format. The wallet must be unlocked.

Parameter	Type	Required	Description
address	string	Yes	BTX address to dump the key for

btx-cli dumpprivkey "btx1z..."

Returns the WIF-encoded private key string.

importprivkey

Add a private key to the wallet.

Parameter	Type	Required	Description
privkey	string	Yes	WIF-encoded private key
label	string	No (default "")	Label for the address
rescan	boolean	No (default true)	Rescan blockchain for transactions

btx-cli importprivkey "5KJvs..."

listdescriptors

List all descriptors imported into a descriptor-enabled wallet. Includes PQ descriptors with pqhd() and mr() key expressions.

Parameter	Type	Required	Description
private	boolean	No (default false)	Include private key information

btx-cli listdescriptors

Returns wallet_name and an array of descriptors, each with desc (descriptor string), timestamp, active, internal, and range.

getdescriptorinfo

Analyze a descriptor string and return its canonical form, checksum, and properties.

Parameter	Type	Required	Description
descriptor	string	Yes	The output descriptor to analyze

btx-cli getdescriptorinfo "wpkh([d34db33f/84'/0'/0']xpub.../0/*)#checksum"

Returns descriptor (canonical form with checksum), checksum, isrange, issolvable, and hasprivatekeys.

getnewaddress

Generate a new receiving address. On BTX, this produces a P2MR (Merklized Root) address backed by post-quantum keys.

Parameter	Type	Required	Description
label	string	No (default "")	Label for the address
address_type	string	No	Address type (bech32m default on BTX)

btx-cli getnewaddress "donations"

Returns a new BTX address string.

migratewallet

Migrate a legacy wallet to a descriptor wallet. On BTX, this is required since only descriptor wallets are supported.

Parameter	Type	Required	Description
wallet_name	string	No	Name of the wallet to migrate (default: current wallet)
passphrase	string	No	Passphrase if the wallet is encrypted

btx-cli migratewallet

Returns wallet_name, watchonly_name (if watch-only scripts were separated), solvables_name (if solvable scripts were separated), and backup_path (path to the backup of the original wallet).