Wallet RPCs

Note: BTX enforces PQ (post-quantum) policy: only descriptor wallets are supported (descriptors=true). Current transparent receive and change addresses are P2MR only (p2mr, btx1z...).

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

restorewalletbundle (v0.33.1+)

Create and load a native descriptor wallet from a verified browser .btxwallet plaintext recovery file.

btx-cli restorewalletbundle "webwallet" "/secure/offline/btx-wallet.btxwallet.json" null true

importwalletbundle (v0.33.1+)

Import a verified browser bundle into the currently selected existing blank descriptor wallet.

btx-cli -rpcwallet="webwallet" importwalletbundle "/secure/offline/btx-wallet.btxwallet.json" true

exportwalletbundle (v0.33.1+)

Export a compatible single-seed descriptor wallet as a plaintext browser recovery file. This file can spend funds; prefer backupwalletbundlearchive for routine encrypted native backups.

btx-cli -rpcwallet="webwallet" exportwalletbundle "/secure/offline/webwallet.btxwallet.json"

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

أنشئ أرشيف bundle مشفراً للمحفظة في ملف واحد. عند ترك include_viewing_keys بدون تحديد، سيتم استخدام القيمة الافتراضية الخاصة بنظام الخصوصية النشط.

Parameter	Type	Required	Description
destination	string	Yes	Destination archive file path

btx-cli -stdinbundlepassphrase backupwalletbundlearchive "/backups/wallet.bundle.btx"

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 -stdinbundlepassphrase restorewalletbundlearchive "restored" "/backups/wallet.bundle.btx"

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

Legacy compatibility RPC for dumping a single imported private key. This is not the current backup path for PQ P2MR descriptor wallets; use backupwalletbundlearchive and listdescriptors for current wallets. The wallet must be unlocked.

Parameter	Type	Required	Description
address	string	Yes	Wallet-owned address for a compatible imported key

btx-cli dumpprivkey "<wallet-owned-address>"

Returns a private key string accepted by importprivkey for compatible legacy keys.

importprivkey

Import a compatible private key into the wallet. Current P2MR descriptor receive/change paths should be restored from descriptor and wallet backups instead of single-key imports.

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

btx-cli importprivkey "<private-key>"

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 "mr(pqhd(<extended-pq-pubkey>/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	Supported option is p2mr. Other address types are rejected.

btx-cli getnewaddress "donations" "p2mr"

Returns a new btx1z... BTX address string. Omitting address_type uses the wallet's P2MR default.

getrawchangeaddress

Generate a raw change address for manual raw-transaction workflows. BTX change is P2MR only.

Parameter	Type	Required	Description
address_type	string	No	Supported option is p2mr. Legacy, SegWit, and bech32m change types are rejected.

btx-cli getrawchangeaddress "p2mr"

Returns a new btx1z... change address.

addpqmultisigaddress

Create an n-of-m post-quantum multisig P2MR address. Legacy addmultisigaddress is disabled by BTX PQ policy.

Parameter	Type	Required	Description
nrequired	number	Yes	Required signature threshold
keys	array	Yes	ML-DSA-44 hex, SLH-DSA hex, or pk_slh(hex) public keys
label	string	No	Wallet label
sort	boolean	No (default false)	Sort keys lexicographically before building the descriptor

btx-cli addpqmultisigaddress 2 '["<mldsa_key_hex_1>","<mldsa_key_hex_2>","pk_slh(<slh_key_hex>)"]' "treasury" true

Returns address, redeemScript, and the imported P2MR multisig descriptor.

shielded wallet status

Shielded wallet accounting, viewing, strict shielded-to-transparent exits, and recovery surfaces are current. Private z-to-z sends, re-shielding, z_shieldfunds, z_shieldcoinbase, and z_fundpsbt are historical/pre-sunset compatibility paths or disabled after shielded pool credits are disabled at height 125000.

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).