Skip to main content
Version: IOTA

Python API Reference

info

The following APIs will throw an exception if an error occurs. For all optional values, the default values are the same as 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 fern 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

TransferOutput​

ParamTypeDefaultDescription
amountintundefinedThe amount to transfer
addressstrundefinedThe address to send
output_kindstrnullShould be SignatureLockedSingle or SignatureLockedDustAllowance

TransferWithOutputs​

constructor(outputs: list[TransferOutput], indexation (optional), remainder_value_strategy (optional): str, skip_sync (optional)): TransferWithOutputs​

The Transfer object used in SyncedAccount

ParamTypeDefaultDescription
outputslist[TransferOutput]undefinedThe amount to transfer
indexation[Indexation](#indexation)nullThe indexation payload
remainder_value_strategystr_ChangeAddress_Should be ReuseAddress or ChangeAddress
skip_syncboolFalseWhether to skip the sync process

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.

transfer_with_outputs(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 (optional),
    'disabled': bool,
}

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
}