Skip to main content

API Reference

info

The following APIs will throw an exception if an error occurs. For all the optional values, the default values are the same as the ones in the Rust API.

init_logger(config)

ParamTypeDefaultDescription
configstrundefinedThe logger configuration

The config is the dumped string from the JSON, which key:value pairs are from the bee logger.

Please check the example/logger_example.py to see how to use it.

AccountManager

constructor(storage_path (optional), password (optional), polling_interval (optional), automatic_output_consolidation(optional), output_consolidation_threshold(optional), sync_spent_outputs(optional), persist_events(optional)): AccountManager

Creates a new instance of the AccountManager.

ParamTypeDefaultDescription
[storage_path]str./storageThe path where the database file will be saved
[storage_password]strundefinedThe storage password to encrypt/decrypt accounts
[polling_interval]int30000The polling interval in seconds
[automatic_output_consolidation]booltrueDisables the automatic output consolidation process
[output_consolidation_threshold]int100Sets the number of outputs an address must have to trigger the automatic consolidation process
[sync_spent_outputs]booleanfalseEnables fetching spent output history on account sync
[persist_events]booleanfalseEnables event persistence
[allow_create_multiple_empty_accounts]booleanfalseEnables creating accounts with latest account being empty
info

If the storage_path is set, then the storage needs to be set too. An exception will be thrown when errors happened.

Returns the constructed AccountManager.

start_background_sync(polling_interval, automatic_output_consolidation): void

Starts the background polling and MQTT monitoring.

ParamTypeDefaultDescription
polling_intervalnumberundefinedThe polling interval in seconds
automatic_output_consolidationbooleanundefinedIf outputs should get consolidated automatically

stop_background_sync(): void

Stops the background polling and MQTT monitoring.

set_storage_password(password): void

Sets the password used for encrypting the storage.

ParamTypeDefaultDescription
passwordstrundefinedThe storage password

set_stronghold_password(password): void

Sets the Stronghold password.

ParamTypeDefaultDescription
passwordstrundefinedThe storage password

is_latest_address_unused(): bool

Determines whether all accounts have the latest address unused.

Returns true if the latest address is unused.

store_mnemonic(signer_type, mnemonic (optional)): bool

Stores a mnemonic for the given signer type. If the mnemonic is not provided, we'll generate one.

ParamTypeDefaultDescription
signer_typestrundefinedShould be Stronghold , LedgerNano , or LedgerNanoSimulator
mnemonicstrrandomly generatedThe provided mnemonic or the randomly generated one

generate_mnemonic(): str

Generates a new mnemonic.

Returns the generated mnemonic string.

verify_mnemonic(mnemonic): void

Checks is the mnemonic is valid. If a mnemonic was generated with generate_mnemonic() , the mnemonic here should match the generated.

ParamTypeDefaultDescription
mnemonicstrundefinedThe provided mnemonic

create_account(client_options): AccountInitialiser

Creat a new account.

ParamTypeDefaultDescription
client_options[ClientOptions](#clientoptions)undefinedThe client options

Returns a constructed AccountInitialiser.

remove_account(account_id): void

Deletes an account.

ParamTypeDefaultDescription
account_idstrundefinedThe account with this id to be deleted

sync_accounts(): AccountsSynchronizer

Returns the AccountsSynchronizer to setup the process to synchronize the accounts with the Tangle.

internal_transfer(from_account_id, to_account_id, amount): WalletMessage

Transfers an amount from an account to another.

ParamTypeDefaultDescription
from_account_idstrundefinedThe source of account id in the transfering
to_account_idstrundefinedThe destination of account id in the transfering
amountintundefinedThe transfer amount

Returns the transfer's WalletMessage.

backup(destination, Stronghold_password): str

Backups the storage to the given destination.

ParamTypeDefaultDescription
destinationstrundefinedThe path to the backup file
Stronghold_passwordstrundefinedThe backup Stronghold password

Returns the full path to the backup file.

import_accounts(source, Stronghold_password): void

Imports a database file.

ParamTypeDefaultDescription
sourcestrundefinedThe path to the backup file
Stronghold_passwordstrundefinedThe backup Stronghold password

get_account(account_id): AccountHandle

Gets the account with the given identifier or index.

ParamTypeDefaultDescription
account_idstrundefinedThe account id, alias, index or one of its addresses

Returns the associated AccountHandle object or undefined if the account wasn't found.

get_accounts(): list[AccountHandle]

Gets all stored accounts.

Returns a list of AccountHandle.

retry(account_id, message_id): WalletMessage

Retries (promotes or reattaches) the given message.

ParamTypeDefaultDescription
account_idstrundefinedThe account id, alias, index or one of its addresses
message_idstrundefinedThe message's identifier

Returns the retried WalletMessage.

reattach(account_id, message_id): WalletMessage

Reattach the given message.

ParamTypeDefaultDescription
account_idstrundefinedThe account id, alias, index or one of its addresses
message_idstrundefinedThe message's identifier

Returns the reattached WalletMessage.

promote(account_id, message_id): WalletMessage

Promote the given message.

ParamTypeDefaultDescription
account_idstrundefinedThe account id, alias, index or one of its addresses
message_idstrundefinedThe message's identifier

Returns the promoted WalletMessage.

get_balance_change_events(count (optional), skip (optional), from_timestamp (optional))

Gets the persisted balance change events.

ParamTypeDefaultDescription
countnumber0The number of events to return (0 to return all)
skipnumber0The number of events to skip
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

Event object: { accountId: string, address: string, balanceChange: { spent: number, received: number } }

get_balance_change_event_count(from_timestamp (optional))

Gets the number of persisted balance change events.

ParamTypeDefaultDescription
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

get_transaction_confirmation_events(count (optional), skip (optional), from_timestamp (optional))

Gets the persisted transaction confirmation change events.

ParamTypeDefaultDescription
countnumber0The number of events to return (0 to return all)
skipnumber0The number of events to skip
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

Event object: { accountId: string, message: Message, confirmed: boolean }

get_transaction_confirmation_event_count(from_timestamp (optional))

Gets the number of persisted transaction confirmation change events.

ParamTypeDefaultDescription
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

get_new_transaction_events(count (optional), skip (optional), from_timestamp (optional))

Gets the persisted new transaction events.

ParamTypeDefaultDescription
countnumber0The number of events to return (0 to return all)
skipnumber0The number of events to skip
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

Event object: { accountId: string, message: Message }

get_new_transaction_event_count(from_timestamp (optional))

Gets the number of persisted new transaction events.

ParamTypeDefaultDescription
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

get_reattachment_events(count (optional), skip (optional), from_timestamp (optional))

Gets the persisted transaction reattachment events.

ParamTypeDefaultDescription
countnumber0The number of events to return (0 to return all)
skipnumber0The number of events to skip
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

Event object: { accountId: string, message: Message }

get_reattachment_event_count(from_timestamp (optional))

Gets the number of persisted transaction reattachment events.

ParamTypeDefaultDescription
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

get_broadcast_events(count (optional), skip (optional), from_timestamp (optional))

Gets the persisted transaction broadcast events.

ParamTypeDefaultDescription
countnumber0The number of events to return (0 to return all)
skipnumber0The number of events to skip
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

Event object: { accountId: string, message: Message }

get_broadcast_event_count(from_timestamp (optional))

Gets the number of persisted transaction broadcast events.

ParamTypeDefaultDescription
from_timestampnumbernullFilter events that were stored after the given UTC timestamp

AccountSynchronizer

gap_limit(limit): void

Set the number of address indexes that are generated.

ParamTypeDefaultDescription
limitintundefinedThe number of address indexes that are generated

skip_persistence(): void

Skip saving new messages and addresses on the account object. The found SyncedAccount is returned on the execute call but won't be persisted on the database.

address_index(address_index): void

Set the initial address index to start syncing.

ParamTypeDefaultDescription
address_indexintundefinedThe initial address index to start syncing

execute(): SyncedAccount

Syncs account with the tangle. The account syncing process ensures that the latest metadata (balance, transactions) associated with an account is fetched from the tangle and is stored locally.

AccountsSynchronizer

gap_limit(limit): void

Set the number of address indexes that are generated on each account.

ParamTypeDefaultDescription
limitintundefinedThe number of address indexes that are generated on each account

address_index(address_index): void

Set the initial address index to start syncing on each account.

ParamTypeDefaultDescription
address_indexintundefinedThe initial address index to start syncing on each account

execute(): listSyncedAccount

Syncs the accounts with the tangle.

Transfer

constructor(amount, address, indexation (optional), remainder_value_strategy (optional): str, skip_sync (optional), output_kind (optional)): Transfer

The Transfer object used in SyncedAccount

ParamTypeDefaultDescription
amountintundefinedThe amount to transfer
addressstrundefinedThe address to send
indexation[Indexation](#indexation)nullThe indexation payload
remainder_value_strategystr_ChangeAddress_Should be ReuseAddress or ChangeAddress
skip_syncboolFalseWhether to skip the sync process
output_kindstrnullShould be SignatureLockedSingle or SignatureLockedDustAllowance

SyncedAccount

The result of a sync operation on an Account.

account_handle(): AccountHandle

Get the AccountHandle of this account

Returns the AccountHandle.

deposit_address(): Address

Get the deposit_address of this account.

Returns the Address.

messages(): WalletMessage

Get the messages of this account.

Returns the WalletMessage.

addresses()

Get the addresses of this account.

Returns the list of WalletMessage.

AccountHandle

id(): str

Returns the account ID.

signer_type(): str

Returns the signer type of this account.

index(): int

Returns the account index.

alias(): str

Returns the account alias.

created_at(): int

Returns the created UNIX timestamp.

last_synced_at(): int or None (it did not be synced before)

Returns the last synced UNIX timestamp.

client_options(): ClientOptions

Returns the client options of this account.

bech32_hrp(): str

Returns the Bech32 HRP string.

sync(): AccountSynchronizer

Returns the AccountSynchronizer to setup the process to synchronize this account with the Tangle.

transfer(transfer_obj): WalletMessage

Transfer tokens.

ParamTypeDefaultDescription
transfer_obj[Transfer](#transfer)undefinedThe transfer we want to make

Returns the WalletMessage which makes the transfering.

retry(message_id): WalletMessage

Retries (promotes or reattaches) the given message.

ParamTypeDefaultDescription
message_idstrundefinedThe message's identifier

Returns the retried WalletMessage.

reattach(message_id): WalletMessage

Reattach the given message.

ParamTypeDefaultDescription
message_idstrundefinedThe message's identifier

Returns the reattached WalletMessage.

promote(message_id): WalletMessage

Promote the given message.

ParamTypeDefaultDescription
message_idstrundefinedThe message's identifier

Returns the promoted WalletMessage.

consolidate_outputs(): listWalletMessage

Consolidates the account addresses outputs.

Returns the list of generated WalletMessage.

generate_address(): list[Address]

Returns a new unused address and links it to this account.

get_unused_address(): Address

Synchronizes the account addresses with the Tangle and returns the latest address in the account, which is an address without balance.

Returns the latest address in the account.

is_latest_address_unused(): bool

Syncs the latest address with the Tangle and determines whether it's unused or not. An unused address is an address without balance and associated message history. Note that such address might have been used in the past, because the message history might have been pruned by the node.

Returns true if the latest address in the account is unused.

latest_address(): Address

Returns the most recent address of the account.

addresses(): list[Address]

Returns a list of Address in the account.

balance(): AccountBalance

Gets the account balance information.

Returns the AccountBalance in this account.

get_node_info(url (optional), auth (optional)): NodeInfoWrapper

Gets information about the node.

ParamTypeDefaultDescription
urlstrundefinedThe node url
authlist[str]undefinedThe node auth options

Returns the NodeInfoWrapper

set_alias(alias): void

Updates the account alias.

ParamTypeDefaultDescription
aliasstrundefinedThe account alias to set

set_client_options(options): void

Updates the account's client options.

ParamTypeDefaultDescription
options[ClientOptions](#clientoptions)undefinedThe client options to set

message_count(message_type (optional)): int

Returns the number of messages associated with the account.

ParamTypeDefaultDescription
message_typestrundefinedShould be Received , Sent , Failed , Unconfirmed , or Value

list_messages(count, from, message_type (optional)): list(WalletMessage)

Get the list of messages of this account.

ParamTypeDefaultDescription
countintundefinedThe count of the messages to get
fromintundefinedThe iniital address index
message_typestrundefinedShould be Received , Sent , Failed , Unconfirmed , or Value

list_spent_addresses(): list[Address]

Returns the list of spent Address in the account.

get_message(message_id): WalletMessage](#walletmessage) (optional)

Get the WalletMessage by the message identifier in the account if it exists.

AccountInitialiser

signer_type(signer_type): void

Sets the account type.

ParamTypeDefaultDescription
signer_typestrsigner_typeShould be Stronghold , LedgerNano , or LedgerNanoSimulator

alias(alias): void

Defines the account alias. If not defined, we'll generate one.

ParamTypeDefaultDescription
aliasstrundefinedThe account alias

created_at(created_at): void

Time of account creation.

ParamTypeDefaultDescription
created_atu64undefinedThe account creation time

messages(messages): void

Messages associated with the seed. The account can be initialised with locally stored messages.

ParamTypeDefaultDescription
messageslist([WalletMessage](#walletmessage))undefinedThe locally stored messages

addresses(addresses): list(WalletAddress)

Address history associated with the seed. The account can be initialised with locally stored address history.

ParamTypeDefaultDescription
addresseslist([WalletAddress](#walletaddress))undefinedThe historical addresses

skip_persistence(): void

Skips storing the account to the database.

initialise(): AccountHandle

Initialises the account.

Returns the initilized AccountHandle

Event Listeners

on_balance_change(callback): list[int]

Listen to balance changes.

ParamTypeDefaultDescription
[callback]functionundefinedThe callback function

Returns the event id as list[int].

remove_balance_change_listener(list[int]): void

Removes the balance change listener associated with the given identifier.

ParamTypeDefaultDescription
[id]list[int]undefinedThe event id

on_new_transaction(callback): list[int]

Listen to new messages.

ParamTypeDefaultDescription
[callback]functionundefinedThe callback function

Returns the event id as list[int].

remove_new_transaction_listener(list[int]): void

Removes the new transaction listener associated with the given identifier.

ParamTypeDefaultDescription
[id]list[int]undefinedThe event id

on_confirmation_state_change(callback): list[int]

Listen to transaction confirmation state change.

ParamTypeDefaultDescription
[callback]functionundefinedThe callback function

Returns the event id as list[int].

remove_confirmation_state_change_listener(list[int]): void

Removes the new transaction listener associated with the given identifier.

ParamTypeDefaultDescription
[id]list[int]undefinedThe event id

on_reattachment(callback): list[int]

Listen to transaction reattachment.

ParamTypeDefaultDescription
[callback]functionundefinedThe callback function

Returns the event id as list[int].

remove_reattachment_listener(list[int]): void

Removes the reattachment listener associated with the given identifier.

ParamTypeDefaultDescription
[id]list[int]undefinedThe event id

on_broadcast(callback): list[int]

Listen to transaction broadcast.

ParamTypeDefaultDescription
[callback]functionundefinedThe callback function

Returns the event id as list[int].

remove_broadcast_listener(list[int]): void

Removes the broadcast listener associated with the given identifier.

ParamTypeDefaultDescription
[id]list[int]undefinedThe event id

on_error(callback): list[int]

Listen to errors.

ParamTypeDefaultDescription
[callback]functionundefinedThe callback function

Returns the event id as list[int].

remove_error_listener(list[int]): void

Removes the error listener associated with the given identifier.

ParamTypeDefaultDescription
[id]list[int]undefinedThe event id

on_stronghold_status_change(callback): list[int]

Listen to Stronghold status change events.

ParamTypeDefaultDescription
[callback]functionundefinedThe callback function

Returns the event id as list[int].

remove_stronghold_status_change_listener(list[int]): void

Removes the Stronghold status change listener associated with the given identifier.

ParamTypeDefaultDescription
[id]list[int]undefinedThe event id

on_transfer_progress(callback): list[int]

Listen to transfer progress events.

ParamTypeDefaultDescription
[callback]functionundefinedThe callback function

Returns the event id as list[int].

remove_transfer_progress_listener(list[int]): void

Removes the transfer progress listener associated with the given identifier.

ParamTypeDefaultDescription
[id]list[int]undefinedThe event id

on_migration_progress(callback): list[int]

Listen to migration progress events.

ParamTypeDefaultDescription
[callback]functionundefinedThe callback function

Returns the event id as list[int].

remove_migration_progress_listener(list[int]): void

Removes the migration progress listener associated with the given identifier.

ParamTypeDefaultDescription
[id]list[int]undefinedThe event id

WalletAddress

A dict with the following key:value pairs.

wallet_address = {
'address': str,
'balance': int,
'key_index': int,
'internal': bool,
'outputs': dict[(string, WalletAddressOutput)],
}

Please refer to WalletAddressOutput for the details of this type.

WalletAddressOutput

A dict with the following key:value pairs.

wallet_address_output = {
'transaction_id': str,
'message_id': str,
'index': int,
'amount': int,
'is_spent': bool,
'address': str,
'kind': str,
}
}

Address

A dict with the following key:value pairs.

address = {
'address': AddressWrapper,
'balance': int,
'key_index': int,
'internal': bool,
'outputs': list[AddressOutput],
}

Please refer to AddressWrapper and AddressOutput for the details of this type.

AddressWrapper

A dict with the following key:value pairs.

address_wrapper = {
'inner': str
}

AddressOutput

A dict with the following key:value pairs.

address_output = {
'transaction_id': str,
'message_id': str,
'index': int,
'amount': int,
'is_spent': bool,
'address': AddressWrapper,
}

Please refer to AddressWrapper for the details of this type.

AccountBalance

A dict with the following key:value pairs.

account_balance = {
'total': int,
'available': int,
'incoming': int,
'outgoing': int,
}

ClientOptions

A dict with the following key:value pairs.

client_options = {
'nodes': list[[Node](#node)] (optional),
'primary_node': [Node](#node)] (optional),
'primary_pow_node': [Node](#node)] (optional),
'node_pool_urls': list[str] (optional),
'network': str (optional),
'mqtt_enabled': bool (optional),
'mqtt_broker_options': [BrokerOptions](#brokeroptions) (optional),
'local_pow': bool (optional),
'node_sync_interval': int (optional), # in milliseconds
'node_sync_enabled': bool (optional),
'request_timeout': int (optional), # in milliseconds
'api_timeout': {
'GetTips': int (optional) # in milliseconds
'PostMessage': int (optional) # in milliseconds
'GetOutput': int (optional) # in milliseconds
} (optional)
}

Note that this message object in wallet.rs is not the same as the message object in iota.rs.

Node

A dict with the following key:value pairs.

node = {
'url': string,
'auth': [NodeAuth](#nodeauth) (optional),
}

NodeAuth

A dict with the following key:value pairs.

node = {
'username': string,
'password': string,
}

BrokerOptions

A dict with the following key:value pairs.

broker_options = {
'automatic_disconnect': bool (optional),
'timeout': int (optional),
'use_ws': bool (optional),
'port': u16 (optional),
'max_reconnection_attempts': u64 (optional),
}

WalletMessage

A dict with the following key:value pairs.

wallet_message = {
'id': str,
'version': u64,
'parents': list[str],
'payload_length': int,
'payload': Payload,
'timestamp': int,
'nonce': int,
'confirmed': bool (optional),
'broadcasted': bool
}

Please refer to Payload for the details of this type.

Payload

A dict with the following key:value pairs.

payload = {
'transaction': list[Transaction] (optional),
'milestone': list[Milestone] (optional),
'indexation': list[Indexation] (optional),
}

Please refer to Transaction, Milestone, and Indexation for the details of these types.

Transaction

A dict with the following key:value pairs.

transaction = {
'essence': {
regular: RegularEssence
},
'unlock_blocks': list[UnlockBlock],
}

Please refer to RegularEssence and UnlockBlock for the details of these types.

Milestone

A dict with the following key:value pairs.

milestone = {
'essence': MilestonePayloadEssence,
'signatures': list[bytes],
}

Please refer to MilestonePayloadEssence for the details of this type.

MilestonePayloadEssence

A dict with the following key:value pairs.

milestone_payload_essence = {
'index': int,
'timestamp': int,
'parents': list[str],
'merkle_proof': bytes,
'public_keys': bytes
}

Indexation

A dict with the following key:value pairs.

indexation = {
'index': bytes,
'data': bytes
}

RegularEssenceEssence

A dict with the following key:value pairs.

transaction_regular_essence = {
'inputs': list[Input],
'outputs': list[Output],
'payload': Payload (optional),
'internal': bool,
'incoming': bool,
'value': int,
'remainder_value': int,
}

Please refer to Input, Output, and Payload for the details of these types.

Output

A dict with the following key:value pairs.

output = {
'address': str,
'amount': int
}

Input

A dict with the following key:value pairs.

input = {
'transaction_id': str,
'index': int
}

UnlockBlock

A dict with the following key:value pairs.

unlock_block = {
'signature': Ed25519Signature (optional),
'reference': int (optional)
}

Please refer to Ed25519Signature for the details of this type.

Ed25519Signature

A dict with the following key:value pairs.

ed25519_signature = {
'public_key': bytes,
'public_key': bytes
}