`Wallet` (Class)¶

descriptor `property` ¶

descriptor: Optional[WalletDescriptor]

The descriptor of the currently open wallet, or None if no wallet is open.

is_open `property` ¶

is_open: bool

Whether a wallet file is currently open.

is_synced `property` ¶

is_synced: bool

Whether the wallet's UTXO state is synced with the network.

rpc `property` ¶

rpc: RpcClient

The underlying wRPC client used by this wallet.

new ¶

__new__(network_id: None | NetworkId | str = None, encoding: None | Encoding | str = None, url: Optional[str] = None, resolver: Optional[Resolver] = None) -> Wallet

Create a new Wallet instance.

Constructs a wallet backed by the local file store and an internal wRPC client. The wallet is created in a closed state. Call wallet_open (or wallet_create) to open or initialize a wallet file.

PARAMETER	DESCRIPTION
`network_id`	The network to operate on. May be a NetworkId or string. TYPE: `None \| NetworkId \| str` DEFAULT: `None`
`encoding`	The wRPC encoding (Borsh or JSON). Defaults to Borsh. TYPE: `None \| Encoding \| str` DEFAULT: `None`
`url`	Optional explicit wRPC server URL. TYPE: `Optional[str]` DEFAULT: `None`
`resolver`	Optional Resolver to discover wRPC endpoints. TYPE: `Optional[Resolver]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Wallet`	A new Wallet instance. TYPE: `Wallet`

RAISES	DESCRIPTION
`Exception`	If the underlying wallet store or RPC client cannot be initialized.

accounts_activate ¶

accounts_activate(account_ids: None | Sequence[AccountId | str] = None) -> None

Activate one or more accounts so they begin tracking UTXOs.

PARAMETER	DESCRIPTION
`account_ids`	Optional list of hex-encoded account ids. If None, activates all accounts. TYPE: `None \| Sequence[AccountId \| str]` DEFAULT: `None`

accounts_commit_reveal ¶

accounts_commit_reveal(wallet_secret: str, account_id: AccountId | str, address_type: CommitRevealAddressKind | str, address_index: int, script_sig: str | bytes | list[int], commit_amount_sompi: int, reveal_fee_sompi: int, payment_secret: Optional[str] = None, fee_rate: Optional[float] = None, payload: None | str | bytes | list[int] = None) -> list[Hash]

Execute a commit-reveal transaction pair against an account-derived address.

Submits the commit transaction (locking funds to a P2SH script derived from script_sig) followed by the reveal transaction (spending those funds back).

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`account_id`	Hex-encoded id of the source account. TYPE: `AccountId \| str`
`address_type`	The CommitRevealAddressKind selecting which derivation chain to use. TYPE: `CommitRevealAddressKind \| str`
`address_index`	Derivation index for the commit address. TYPE: `int`
`script_sig`	Raw script bytes used to construct the commit P2SH. TYPE: `str \| bytes \| list[int]`
`commit_amount_sompi`	Amount to lock in the commit transaction. TYPE: `int`
`reveal_fee_sompi`	Fee paid by the reveal transaction. TYPE: `int`
`payment_secret`	Optional payment secret if the source key data is encrypted with one. TYPE: `Optional[str]` DEFAULT: `None`
`fee_rate`	Optional explicit fee rate for the commit transaction. TYPE: `Optional[float]` DEFAULT: `None`
`payload`	Optional binary payload to embed in the reveal transaction. TYPE: `None \| str \| bytes \| list[int]` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[Hash]`	list[Hash]: Ids of the submitted commit and reveal transactions.

accounts_commit_reveal_manual ¶

accounts_commit_reveal_manual(wallet_secret: str, account_id: AccountId | str, script_sig: str | bytes | list[int], reveal_fee_sompi: int, payment_secret: Optional[str] = None, fee_rate: Optional[float] = None, payload: None | str | bytes | list[int] = None, start_destination: Optional[Sequence[PaymentOutput]] = None, end_destination: Optional[Sequence[PaymentOutput]] = None) -> list[Hash]

Execute a commit-reveal transaction pair with explicit start and end destinations.

Lower-level variant of accounts_commit_reveal that lets the caller specify both the commit (start) and reveal (end) destinations directly instead of deriving an address from the account.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`account_id`	Hex-encoded id of the source account. TYPE: `AccountId \| str`
`script_sig`	Raw script bytes used to construct the commit P2SH. TYPE: `str \| bytes \| list[int]`
`reveal_fee_sompi`	Fee paid by the reveal transaction. TYPE: `int`
`payment_secret`	Optional payment secret if the source key data is encrypted with one. TYPE: `Optional[str]` DEFAULT: `None`
`fee_rate`	Optional explicit fee rate for the commit transaction. TYPE: `Optional[float]` DEFAULT: `None`
`payload`	Optional binary payload to embed in the reveal transaction. TYPE: `None \| str \| bytes \| list[int]` DEFAULT: `None`
`start_destination`	Optional outputs for the commit transaction. Defaults to change. TYPE: `Optional[Sequence[PaymentOutput]]` DEFAULT: `None`
`end_destination`	Optional outputs for the reveal transaction. Defaults to change. TYPE: `Optional[Sequence[PaymentOutput]]` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[Hash]`	list[Hash]: Ids of the submitted commit and reveal transactions.

accounts_create_bip32 ¶

accounts_create_bip32(wallet_secret: str, prv_key_data_id: PrvKeyDataId | str, payment_secret: Optional[str] = None, account_name: Optional[str] = None, account_index: Optional[int] = None) -> AccountDescriptor

Create a new BIP32 (HD) account from existing private key data.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`prv_key_data_id`	Id of the private key data entry to derive from. TYPE: `PrvKeyDataId \| str`
`payment_secret`	Optional payment secret if the private key data is encrypted with one. TYPE: `Optional[str]` DEFAULT: `None`
`account_name`	Optional human-readable name for the account. TYPE: `Optional[str]` DEFAULT: `None`
`account_index`	Optional explicit BIP32 account index. Defaults to the next available. TYPE: `Optional[int]` DEFAULT: `None`

RETURNS	DESCRIPTION
`AccountDescriptor`	Descriptor of the newly created account. TYPE: `AccountDescriptor`

accounts_create_keypair ¶

accounts_create_keypair(wallet_secret: str, prv_key_data_id: PrvKeyDataId | str, ecdsa: bool, account_name: Optional[str] = None) -> AccountDescriptor

Create a new keypair (single-key) account from existing private key data.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`prv_key_data_id`	Id of the private key data entry to use. TYPE: `PrvKeyDataId \| str`
`ecdsa`	If True, derive an ECDSA address; otherwise derive a Schnorr address. TYPE: `bool`
`account_name`	Optional human-readable name for the account. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`AccountDescriptor`	Descriptor of the newly created account. TYPE: `AccountDescriptor`

accounts_create_new_address ¶

accounts_create_new_address(account_id: AccountId | str, address_kind: NewAddressKind | str) -> Address

Generate a new receive or change address for an account.

PARAMETER	DESCRIPTION
`account_id`	Hex-encoded id of the account. TYPE: `AccountId \| str`
`address_kind`	The NewAddressKind (Receive or Change) to derive. TYPE: `NewAddressKind \| str`

RETURNS	DESCRIPTION
`Address`	The newly derived address. TYPE: `Address`

accounts_discovery ¶

accounts_discovery(discovery_kind: AccountsDiscoveryKind | str, address_scan_extent: int, account_scan_extent: int, bip39_mnemonic: str, bip39_passphrase: Optional[str] = None) -> int

Scan a BIP39 mnemonic for previously used accounts and addresses.

Performs a discovery sweep to determine the highest account index that has been used on-chain. Useful when restoring a wallet from a mnemonic.

PARAMETER	DESCRIPTION
`discovery_kind`	The discovery scheme (AccountsDiscoveryKind or string). TYPE: `AccountsDiscoveryKind \| str`
`address_scan_extent`	How many consecutive unused addresses to scan before stopping. TYPE: `int`
`account_scan_extent`	How many consecutive unused accounts to scan before stopping. TYPE: `int`
`bip39_mnemonic`	The BIP39 mnemonic phrase to scan. TYPE: `str`
`bip39_passphrase`	Optional BIP39 passphrase. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`int`	The last account index found to be in use. TYPE: `int`

accounts_ensure_default ¶

accounts_ensure_default(wallet_secret: str, account_kind: AccountKind, payment_secret: Optional[str] = None, mnemonic_phrase: Optional[str] = None) -> AccountDescriptor

Ensure a default account of the given kind exists, creating one if needed.

Only bip32 accounts are supported upstream; any other account_kind raises an exception. If a new account is created, its private key data is generated from mnemonic_phrase if supplied (with payment_secret as the BIP39 passphrase) or from a freshly generated mnemonic otherwise.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`account_kind`	The AccountKind of the default account to ensure. TYPE: `AccountKind`
`payment_secret`	Optional BIP39 passphrase used when generating new key data. TYPE: `Optional[str]` DEFAULT: `None`
`mnemonic_phrase`	Optional mnemonic phrase to seed the account. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`AccountDescriptor`	Descriptor of the existing or newly created default account. TYPE: `AccountDescriptor`

accounts_enumerate ¶

accounts_enumerate() -> list[AccountDescriptor]

Enumerate all accounts in the open wallet.

RETURNS	DESCRIPTION
`list[AccountDescriptor]`	list[AccountDescriptor]: Descriptors for every account in the wallet.

accounts_estimate ¶

accounts_estimate(account_id: AccountId | str, priority_fee_sompi: Fees | dict, fee_rate: Optional[float] = None, payload: None | str | bytes | list[int] = None, destination: Optional[Sequence[PaymentOutput]] = None) -> GeneratorSummary

Estimate the fees and structure of a prospective send without submitting.

Runs the transaction generator against the account's UTXOs to produce a summary of what a real send would look like.

PARAMETER	DESCRIPTION
`account_id`	Hex-encoded id of the source account. TYPE: `AccountId \| str`
`priority_fee_sompi`	Priority fee specification (Fees object or dict). TYPE: `Fees \| dict`
`fee_rate`	Optional explicit fee rate (sompi per gram of mass). TYPE: `Optional[float]` DEFAULT: `None`
`payload`	Optional binary payload to embed in the transaction. TYPE: `None \| str \| bytes \| list[int]` DEFAULT: `None`
`destination`	Optional list of PaymentOutputs. If None, the entire sweepable balance is routed to the account's change address (useful for compounding/sweeping UTXOs). TYPE: `Optional[Sequence[PaymentOutput]]` DEFAULT: `None`

RETURNS	DESCRIPTION
`GeneratorSummary`	Summary of the estimated transaction(s). TYPE: `GeneratorSummary`

accounts_get ¶

accounts_get(account_id: AccountId | str) -> AccountDescriptor

Fetch the AccountDescriptor for an account.

PARAMETER	DESCRIPTION
`account_id`	Hex-encoded id of the account to look up. TYPE: `AccountId \| str`

RETURNS	DESCRIPTION
`AccountDescriptor`	Descriptor of the requested account. TYPE: `AccountDescriptor`

accounts_get_utxos ¶

accounts_get_utxos(account_id: AccountId | str, addresses: None | Sequence[Address | str] = None, min_amount_sompi: Optional[int] = None) -> list[dict]

List UTXOs available to an account, optionally filtered.

PARAMETER	DESCRIPTION
`account_id`	Hex-encoded id of the account. TYPE: `AccountId \| str`
`addresses`	Optional list of Address objects to restrict results to. TYPE: `None \| Sequence[Address \| str]` DEFAULT: `None`
`min_amount_sompi`	Optional minimum UTXO value to include, in sompi. TYPE: `Optional[int]` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[dict]`	list[dict]: Serialized UTXO entries belonging to the account.

accounts_import_bip32 ¶

accounts_import_bip32(wallet_secret: str, prv_key_data_id: PrvKeyDataId | str, payment_secret: Optional[str] = None, account_name: Optional[str] = None, account_index: Optional[int] = None) -> AccountDescriptor

Import a BIP32 (HD) account from existing private key data.

Like accounts_create_bip32, but uses the import code path which performs address discovery before adding the account.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`prv_key_data_id`	Id of the private key data entry to derive from. TYPE: `PrvKeyDataId \| str`
`payment_secret`	Optional payment secret if the private key data is encrypted with one. TYPE: `Optional[str]` DEFAULT: `None`
`account_name`	Optional human-readable name for the account. TYPE: `Optional[str]` DEFAULT: `None`
`account_index`	Optional explicit BIP32 account index. TYPE: `Optional[int]` DEFAULT: `None`

RETURNS	DESCRIPTION
`AccountDescriptor`	Descriptor of the imported account. TYPE: `AccountDescriptor`

accounts_import_keypair ¶

accounts_import_keypair(wallet_secret: str, prv_key_data_id: PrvKeyDataId | str, ecdsa: bool, account_name: Optional[str] = None) -> AccountDescriptor

Import a keypair (single-key) account from existing private key data.

Like accounts_create_keypair, but routes through the import path which runs an address-discovery scan before adding the account. The scan is effectively a no-op for keypair accounts (no HD derivation).

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`prv_key_data_id`	Id of the private key data entry to use. TYPE: `PrvKeyDataId \| str`
`ecdsa`	If True, derive an ECDSA address; otherwise derive a Schnorr address. TYPE: `bool`
`account_name`	Optional human-readable name for the account. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`AccountDescriptor`	Descriptor of the imported account. TYPE: `AccountDescriptor`

accounts_rename ¶

accounts_rename(wallet_secret: str, account_id: AccountId | str, name: Optional[str] = None) -> None

Rename an account.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`account_id`	Hex-encoded id of the account to rename. TYPE: `AccountId \| str`
`name`	New account name, or None to clear the name. TYPE: `Optional[str]` DEFAULT: `None`

accounts_send ¶

accounts_send(wallet_secret: str, account_id: AccountId | str, priority_fee_sompi: Fees | dict, payment_secret: Optional[str] = None, fee_rate: Optional[float] = None, payload: None | str | bytes | list[int] = None, destination: Optional[Sequence[PaymentOutput]] = None) -> GeneratorSummary

Send funds from an account, signing and submitting the resulting transactions.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`account_id`	Hex-encoded id of the source account. TYPE: `AccountId \| str`
`priority_fee_sompi`	Priority fee specification (Fees object or dict). TYPE: `Fees \| dict`
`payment_secret`	Optional payment secret if the source key data is encrypted with one. TYPE: `Optional[str]` DEFAULT: `None`
`fee_rate`	Optional explicit fee rate (sompi per gram of mass). TYPE: `Optional[float]` DEFAULT: `None`
`payload`	Optional binary payload to embed in the transaction. TYPE: `None \| str \| bytes \| list[int]` DEFAULT: `None`
`destination`	Optional list of PaymentOutputs. If None, the entire sweepable balance is routed to the account's change address (useful for compounding/sweeping UTXOs). TYPE: `Optional[Sequence[PaymentOutput]]` DEFAULT: `None`

RETURNS	DESCRIPTION
`GeneratorSummary`	Summary of the submitted transaction(s). TYPE: `GeneratorSummary`

accounts_transfer ¶

accounts_transfer(wallet_secret: str, source_account_id: AccountId | str, destination_account_id: AccountId | str, transfer_amount_sompi: int, payment_secret: Optional[str] = None, fee_rate: Optional[float] = None, priority_fee_sompi: None | Fees | dict = None) -> dict

Transfer funds between two accounts in the same wallet.

Unlike funds sent to an external address, transferred funds are available immediately on transaction acceptance (no maturity wait).

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`source_account_id`	Hex-encoded id of the sending account. TYPE: `AccountId \| str`
`destination_account_id`	Hex-encoded id of the receiving account. TYPE: `AccountId \| str`
`transfer_amount_sompi`	Amount to transfer in sompi. TYPE: `int`
`payment_secret`	Optional payment secret if the source key data is encrypted with one. TYPE: `Optional[str]` DEFAULT: `None`
`fee_rate`	Optional explicit fee rate (sompi per gram of mass). TYPE: `Optional[float]` DEFAULT: `None`
`priority_fee_sompi`	Optional priority fee specification. Defaults to `SenderPays(0)`. TYPE: `None \| Fees \| dict` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict`	The transfer response, including generator summary and transaction ids. TYPE: `dict`

add_event_listener ¶

add_event_listener(event: WalletEventType | str, callback: Callable[..., None], *args: Any, **kwargs: Any) -> None

Register a Python callback for a wallet event.

PARAMETER	DESCRIPTION
`event`	The WalletEventType (or string) to listen for. Use "all" to receive every event. TYPE: `WalletEventType \| str`
`callback`	A callable invoked with `(event, args, kwargs)` when the event fires. TYPE:* `Callable[..., None]`
`*args`	Positional arguments forwarded to the callback. TYPE: `Any` DEFAULT: `()`
`**kwargs`	Keyword arguments forwarded to the callback. TYPE: `Any` DEFAULT: `{}`

batch ¶

batch() -> None

Begin a batched storage transaction.

Subsequent wallet operations are coalesced into a single storage write until flush is called.

connect ¶

connect(block_async_connect: Optional[bool] = None, strategy: Optional[str] = None, url: Optional[str] = None, timeout_duration: Optional[int] = None, retry_interval: Optional[int] = None) -> None

Connect the wallet's wRPC client to a Kaspa node.

PARAMETER	DESCRIPTION
`block_async_connect`	If True, await connection completion before resolving. TYPE: `Optional[bool]` DEFAULT: `None`
`strategy`	Optional connection strategy ("retry" or "fallback"). TYPE: `Optional[str]` DEFAULT: `None`
`url`	Optional explicit wRPC server URL override. TYPE: `Optional[str]` DEFAULT: `None`
`timeout_duration`	Optional connection timeout in milliseconds. TYPE: `Optional[int]` DEFAULT: `None`
`retry_interval`	Optional retry interval in milliseconds. TYPE: `Optional[int]` DEFAULT: `None`

disconnect ¶

disconnect() -> None

Disconnect the wallet's wRPC client from the Kaspa node.

exists ¶

exists(name: Optional[str] = None) -> bool

Check if a wallet file exists in the local store.

PARAMETER	DESCRIPTION
`name`	Optional wallet filename to check. If None, checks the default wallet. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if the wallet file exists, False otherwise. TYPE: `bool`

fee_rate_estimate ¶

fee_rate_estimate() -> dict

Fetch the current fee rate estimate from the connected node.

RETURNS	DESCRIPTION
`dict`	Fee rate estimates at low, normal, and priority levels. TYPE: `dict`

fee_rate_poller_disable ¶

fee_rate_poller_disable() -> None

Disable the background fee rate poller, if running.

fee_rate_poller_enable ¶

fee_rate_poller_enable(interval_seconds: int) -> None

Enable a background poller that periodically refreshes fee rate estimates.

PARAMETER	DESCRIPTION
`interval_seconds`	How often the poller should query the node, in seconds. TYPE: `int`

flush ¶

flush(wallet_secret: str) -> None

Flush any pending batched changes to storage.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`

Note

Calling flush outside of an active batch panics in the upstream local store. Always pair flush with a prior batch.

get_status ¶

get_status(name: Optional[str] = None) -> dict

Fetch the wallet runtime status.

PARAMETER	DESCRIPTION
`name`	Optional wallet name. If None, reports the status of the active wallet. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict`	Status information including connection state, sync state, and selected network. TYPE: `dict`

prv_key_data_create ¶

prv_key_data_create(wallet_secret: str, secret: str, kind: PrvKeyDataVariantKind | str, payment_secret: Optional[str] = None, name: Optional[str] = None) -> PrvKeyDataId

Create and store a new private key data entry.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`secret`	The secret value. For Mnemonic, the BIP39 phrase. For Bip39Seed and ExtendedPrivateKey, the encoded string. For SecretKey, a 64-character hex-encoded secp256k1 key. TYPE: `str`
`kind`	The variant kind of `secret` (Mnemonic, Bip39Seed, ExtendedPrivateKey, or SecretKey). TYPE: `PrvKeyDataVariantKind \| str`
`payment_secret`	Optional additional secret used to encrypt the entry. TYPE: `Optional[str]` DEFAULT: `None`
`name`	Optional human-readable name for the entry. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`PrvKeyDataId`	The id of the newly created private key data entry. TYPE: `PrvKeyDataId`

prv_key_data_enumerate ¶

prv_key_data_enumerate() -> list[PrvKeyDataInfo]

Enumerate all private key data entries stored in the open wallet.

RETURNS	DESCRIPTION
`list[PrvKeyDataInfo]`	list[PrvKeyDataInfo]: Metadata for every stored private key data entry.

prv_key_data_get ¶

prv_key_data_get(wallet_secret: str, prv_key_data_id: PrvKeyDataId | str) -> PrvKeyDataInfo

Fetch metadata for a single private key data entry.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`prv_key_data_id`	Id of the entry to fetch. TYPE: `PrvKeyDataId \| str`

RETURNS	DESCRIPTION
`PrvKeyDataInfo`	Metadata for the entry. TYPE: `PrvKeyDataInfo`

RAISES	DESCRIPTION
`Exception`	If no entry exists with the given id.

remove_event_listener ¶

remove_event_listener(event: WalletEventType | str, callback: None | Callable[..., None] = None) -> None

Remove previously registered event listener(s).

PARAMETER	DESCRIPTION
`event`	The WalletEventType (or string) to remove listeners from. Use "all" to operate across every event kind. TYPE: `WalletEventType \| str`
`callback`	Optional specific callback to remove. If None, removes all callbacks for the given event. TYPE: `None \| Callable[..., None]` DEFAULT: `None`

retain_context ¶

retain_context(name: str, data: None | str | bytes | list[int] = None) -> None

Store arbitrary named context data in the wallet runtime.

The data lives in memory for the lifetime of the wallet instance and is not written to disk. Useful for syncing UI state between front-end and back-end processes that share a single wallet instance.

PARAMETER	DESCRIPTION
`name`	A name identifying the context entry. TYPE: `str`
`data`	Optional binary payload to associate with `name`. If None, the entry is cleared. TYPE: `None \| str \| bytes \| list[int]` DEFAULT: `None`

set_network_id ¶

set_network_id(network_id: NetworkId | str) -> None

Set the network id used by the wallet runtime.

PARAMETER	DESCRIPTION
`network_id`	The NetworkId (or string) to bind the wallet to. TYPE: `NetworkId \| str`

RAISES	DESCRIPTION
`Exception`	If the wRPC client is currently connected. Disconnect before changing networks.

start ¶

start() -> None

Start the wallet runtime and event notification task.

Boots the underlying UtxoProcessor, the wRPC client notifier, and the background task that dispatches wallet events to registered Python listeners. Must be called before opening a wallet.

stop ¶

stop() -> None

Stop the wallet runtime and event notification task.

Tears down the background notification task and stops the wallet's UtxoProcessor.

transactions_data_get ¶

transactions_data_get(account_id: AccountId | str, network_id: NetworkId | str, start: int, end: int, filter: None | Sequence[TransactionKind | str] = None) -> dict

Fetch a window of stored transaction history for an account.

PARAMETER	DESCRIPTION
`account_id`	Hex-encoded id of the account. TYPE: `AccountId \| str`
`network_id`	The network the transactions belong to. TYPE: `NetworkId \| str`
`start`	Start index (inclusive) into the transaction history. TYPE: `int`
`end`	End index (exclusive) into the transaction history. TYPE: `int`
`filter`	Optional list of TransactionKind values to filter by. TYPE: `None \| Sequence[TransactionKind \| str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict`	The transaction data response, including the matching transactions. TYPE: `dict`

transactions_replace_metadata ¶

transactions_replace_metadata(account_id: AccountId | str, network_id: NetworkId | str, transaction_id: Hash | str, metadata: Optional[str] = None) -> None

Replace the user-provided metadata attached to a stored transaction.

PARAMETER	DESCRIPTION
`account_id`	Id of the account that owns the transaction. TYPE: `AccountId \| str`
`network_id`	The network the transaction belongs to. TYPE: `NetworkId \| str`
`transaction_id`	Id of the transaction to update. TYPE: `Hash \| str`
`metadata`	New metadata string, or None to clear it. TYPE: `Optional[str]` DEFAULT: `None`

transactions_replace_note ¶

transactions_replace_note(account_id: AccountId | str, network_id: NetworkId | str, transaction_id: Hash | str, note: Optional[str] = None) -> None

Replace the user-provided note attached to a stored transaction.

PARAMETER	DESCRIPTION
`account_id`	Id of the account that owns the transaction. TYPE: `AccountId \| str`
`network_id`	The network the transaction belongs to. TYPE: `NetworkId \| str`
`transaction_id`	Id of the transaction to update. TYPE: `Hash \| str`
`note`	New note text, or None to clear the note. TYPE: `Optional[str]` DEFAULT: `None`

wallet_change_secret ¶

wallet_change_secret(old_wallet_secret: str, new_wallet_secret: str) -> None

Change the password protecting the currently open wallet.

PARAMETER	DESCRIPTION
`old_wallet_secret`	The current wallet password. TYPE: `str`
`new_wallet_secret`	The new password to set. TYPE: `str`

wallet_close ¶

wallet_close() -> None

Close the currently open wallet file.

wallet_create ¶

wallet_create(wallet_secret: str, filename: Optional[str] = None, overwrite_wallet_storage: Optional[bool] = None, title: Optional[str] = None, user_hint: Optional[str] = None) -> dict

Create a new wallet file.

PARAMETER	DESCRIPTION
`wallet_secret`	Password used to encrypt the wallet. TYPE: `str`
`filename`	Optional filename for the new wallet. Defaults to the standard wallet name. TYPE: `Optional[str]` DEFAULT: `None`
`overwrite_wallet_storage`	If True, overwrite an existing wallet at the same path. TYPE: `Optional[bool]` DEFAULT: `None`
`title`	Optional human-readable wallet title. TYPE: `Optional[str]` DEFAULT: `None`
`user_hint`	Optional password hint stored alongside the wallet. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict`	The wallet creation response, including descriptor and storage info. TYPE: `dict`

wallet_enumerate ¶

wallet_enumerate() -> list[WalletDescriptor]

Enumerate all wallet files in the local store.

RETURNS	DESCRIPTION
`list[WalletDescriptor]`	list[WalletDescriptor]: Descriptors for each wallet file found.

wallet_export ¶

wallet_export(wallet_secret: str, include_transactions: bool) -> str

Export the wallet's serialized data as a hex string.

Returns the borsh-serialized wallet payload (private key data remains encrypted with wallet_secret). Suitable for backup or transfer to another instance via wallet_import.

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`include_transactions`	If True, include stored transaction history in the export. TYPE: `bool`

RETURNS	DESCRIPTION
`str`	The wallet payload as a hex-encoded string. TYPE: `str`

wallet_import ¶

wallet_import(wallet_secret: str, wallet_data: str | bytes | list[int]) -> dict

Import a previously exported wallet payload.

PARAMETER	DESCRIPTION
`wallet_secret`	Password used to decrypt the import payload. TYPE: `str`
`wallet_data`	The encrypted wallet bytes produced by `wallet_export`. TYPE: `str \| bytes \| list[int]`

RETURNS	DESCRIPTION
`dict`	The wallet import response, including the resulting descriptor. TYPE: `dict`

wallet_open ¶

wallet_open(wallet_secret: str, account_descriptors: bool, filename: Optional[str] = None) -> dict

Open an existing wallet file.

PARAMETER	DESCRIPTION
`wallet_secret`	Password used to decrypt the wallet. TYPE: `str`
`account_descriptors`	If True, include account descriptors in the response. TYPE: `bool`
`filename`	Optional filename to open. Defaults to the standard wallet name. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict`	The wallet open response, optionally including account descriptors. TYPE: `dict`

wallet_reload ¶

wallet_reload(reactivate: bool) -> None

Reboot the wallet's account runtime without re-reading from disk.

Stops every active account, cleans up the UtxoProcessor, and emits a WalletReload event. The cached wallet data is reused as-is; the store is not re-opened.

PARAMETER	DESCRIPTION
`reactivate`	If True, re-`start()` previously active accounts so they resume UTXO discovery and balance tracking. If False, the caller is responsible for calling `accounts_activate`. TYPE: `bool`

wallet_rename ¶

wallet_rename(wallet_secret: str, title: Optional[str] = None, filename: Optional[str] = None) -> None

Rename the currently open wallet (title and/or on-disk filename).

PARAMETER	DESCRIPTION
`wallet_secret`	Password for the open wallet. TYPE: `str`
`title`	New human-readable title, or None to leave unchanged. TYPE: `Optional[str]` DEFAULT: `None`
`filename`	New on-disk filename, or None to leave unchanged. TYPE: `Optional[str]` DEFAULT: `None`