Extended API Methods

The Extended API includes a number of “high level” commands to perform tasks such as sending and receiving transfers.

Note

Below you will find the documentation for both the synchronous and asynchronous versions of the Extebded API methods.

It should be made clear, that they do exactly the same IOTA related operations, accept the same arguments and return the same structures. Asynchronous API calls are non-blocking, so your application can do other stuff while waiting for the result from the network.

While synchronous API calls are regular Python methods, their respective asynchronous versions are Python coroutines. You can await their results, schedule them for execution inside and event loop and much more. PyOTA uses the built-in asyncio Python module for asynchronous operation. For an overview of what you can do with it, head over to this article.

broadcast_and_store

Iota.broadcast_and_store(trytes: Iterable[iota.transaction.types.TransactionTrytes]) → dict

Broadcasts and stores a set of transaction trytes.

Parameters

trytes (Iterable[TransactionTrytes]) – Transaction trytes to broadcast and store.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        List of TransactionTrytes that were broadcast.
        Same as the input ``trytes``.
}

References:

async AsyncIota.broadcast_and_store(trytes: Iterable[iota.transaction.types.TransactionTrytes]) → dict

Broadcasts and stores a set of transaction trytes.

Parameters

trytes (Iterable[TransactionTrytes]) – Transaction trytes to broadcast and store.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        List of TransactionTrytes that were broadcast.
        Same as the input ``trytes``.
}

References:

broadcast_bundle

Iota.broadcast_bundle(tail_transaction_hash: iota.transaction.types.TransactionHash) → dict

Re-broadcasts all transactions in a bundle given the tail transaction hash. It might be useful when transactions did not properly propagate, particularly in the case of large bundles.

Parameters

tail_transaction_hash (TransactionHash) – Tail transaction hash of the bundle.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        List of TransactionTrytes that were broadcast.
}

References:

async AsyncIota.broadcast_bundle(tail_transaction_hash: iota.transaction.types.TransactionHash) → dict

Re-broadcasts all transactions in a bundle given the tail transaction hash. It might be useful when transactions did not properly propagate, particularly in the case of large bundles.

Parameters

tail_transaction_hash (TransactionHash) – Tail transaction hash of the bundle.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        List of TransactionTrytes that were broadcast.
}

References:

find_transaction_objects

Iota.find_transaction_objects(bundles: Optional[Iterable[iota.transaction.types.BundleHash]] = None, addresses: Optional[Iterable[iota.types.Address]] = None, tags: Optional[Iterable[iota.types.Tag]] = None, approvees: Optional[Iterable[iota.transaction.types.TransactionHash]] = None) → dict

A more extensive version of find_transactions() that returns transaction objects instead of hashes.

Effectively, this is find_transactions() + get_trytes() + converting the trytes into transaction objects.

It accepts the same parameters as find_transactions().

Find the transactions which match the specified input. All input values are lists, for which a list of return values (transaction hashes), in the same order, is returned for all individual elements. Using multiple of these input fields returns the intersection of the values.

Parameters

  • bundles (Optional[Iterable[BundleHash]]) – List of bundle IDs.

  • addresses (Optional[Iterable[Address]]) – List of addresses.

  • tags (Optional[Iterable[Tag]]) – List of tags.

  • approvees (Optional[Iterable[TransactionHash]]) – List of approvee transaction IDs.

Returns

dict with the following structure:

{
    'transactions': List[Transaction],
        List of Transaction objects that match the input.
}

async AsyncIota.find_transaction_objects(bundles: Optional[Iterable[iota.transaction.types.BundleHash]] = None, addresses: Optional[Iterable[iota.types.Address]] = None, tags: Optional[Iterable[iota.types.Tag]] = None, approvees: Optional[Iterable[iota.transaction.types.TransactionHash]] = None) → dict

A more extensive version of find_transactions() that returns transaction objects instead of hashes.

Effectively, this is find_transactions() + get_trytes() + converting the trytes into transaction objects.

It accepts the same parameters as find_transactions().

Find the transactions which match the specified input. All input values are lists, for which a list of return values (transaction hashes), in the same order, is returned for all individual elements. Using multiple of these input fields returns the intersection of the values.

Parameters

  • bundles (Optional[Iterable[BundleHash]]) – List of bundle IDs.

  • addresses (Optional[Iterable[Address]]) – List of addresses.

  • tags (Optional[Iterable[Tag]]) – List of tags.

  • approvees (Optional[Iterable[TransactionHash]]) – List of approvee transaction IDs.

Returns

dict with the following structure:

{
    'transactions': List[Transaction],
        List of Transaction objects that match the input.
}

get_account_data

Iota.get_account_data(start: int = 0, stop: Optional[int] = None, inclusion_states: bool = False, security_level: Optional[int] = None) → dict

More comprehensive version of get_transfers() that returns addresses and account balance in addition to bundles.

This function is useful in getting all the relevant information of your account.

Parameters

  • start (int) – Starting key index.

  • stop (Optional[int]) –

    Stop before this index.

    Note that this parameter behaves like the stop attribute in a slice object; the stop index is not included in the result.

    If None (default), then this method will check every address until it finds one that is unused.

    Note

    An unused address is an address that has not been spent from and has no transactions referencing it on the Tangle.

    A snapshot removes transactions from the Tangle. As a consequence, after a snapshot, it may happen that this API does not return the correct account data with stop being None.

    As a workaround, you can save your used addresses and their key_index attribute in a local database. Use the start and stop parameters to tell the API from where to start checking and where to stop.

  • inclusion_states (bool) –

    Whether to also fetch the inclusion states of the transfers.

    This requires an additional API call to the node, so it is disabled by default.

  • security_level (Optional[int]) –

    Number of iterations to use when generating new addresses (see get_new_addresses()).

    This value must be between 1 and 3, inclusive.

    If not set, defaults to AddressGenerator.DEFAULT_SECURITY_LEVEL.

Returns

dict with the following structure:

{
    'addresses': List[Address],
        List of generated addresses.

        Note that this list may include unused
        addresses.

    'balance': int,
        Total account balance.  Might be 0.

    'bundles': List[Bundle],
        List of bundles with transactions to/from this
        account.
}

async AsyncIota.get_account_data(start: int = 0, stop: Optional[int] = None, inclusion_states: bool = False, security_level: Optional[int] = None) → dict

More comprehensive version of get_transfers() that returns addresses and account balance in addition to bundles.

This function is useful in getting all the relevant information of your account.

Parameters

  • start (int) – Starting key index.

  • stop (Optional[int]) –

    Stop before this index.

    Note that this parameter behaves like the stop attribute in a slice object; the stop index is not included in the result.

    If None (default), then this method will check every address until it finds one that is unused.

    Note

    An unused address is an address that has not been spent from and has no transactions referencing it on the Tangle.

    A snapshot removes transactions from the Tangle. As a consequence, after a snapshot, it may happen that this API does not return the correct account data with stop being None.

    As a workaround, you can save your used addresses and their key_index attribute in a local database. Use the start and stop parameters to tell the API from where to start checking and where to stop.

  • inclusion_states (bool) –

    Whether to also fetch the inclusion states of the transfers.

    This requires an additional API call to the node, so it is disabled by default.

  • security_level (Optional[int]) –

    Number of iterations to use when generating new addresses (see get_new_addresses()).

    This value must be between 1 and 3, inclusive.

    If not set, defaults to AddressGenerator.DEFAULT_SECURITY_LEVEL.

Returns

dict with the following structure:

{
    'addresses': List[Address],
        List of generated addresses.

        Note that this list may include unused
        addresses.

    'balance': int,
        Total account balance.  Might be 0.

    'bundles': List[Bundle],
        List of bundles with transactions to/from this
        account.
}

get_bundles

Iota.get_bundles(transactions: Iterable[iota.transaction.types.TransactionHash]) → dict

Returns the bundle(s) associated with the specified transaction hashes.

Parameters

transactions (Iterable[TransactionHash]) – Transaction hashes. Must be a tail transaction.

Returns

dict with the following structure:

{
  'bundles': List[Bundle],
       List of matching bundles.  Note that this value is
       always a list, even if only one bundle was found.
}

:raise iota.adapter.BadApiResponse:

  • if any of the bundles fails validation.

  • if any of the bundles is not visible on the Tangle.

References:

async AsyncIota.get_bundles(transactions: Iterable[iota.transaction.types.TransactionHash]) → dict

Returns the bundle(s) associated with the specified transaction hashes.

Parameters

transactions (Iterable[TransactionHash]) – Transaction hashes. Must be a tail transaction.

Returns

dict with the following structure:

{
  'bundles': List[Bundle],
       List of matching bundles.  Note that this value is
       always a list, even if only one bundle was found.
}

:raise iota.adapter.BadApiResponse:

  • if any of the bundles fails validation.

  • if any of the bundles is not visible on the Tangle.

References:

get_inputs

Iota.get_inputs(start: int = 0, stop: Optional[int] = None, threshold: Optional[int] = None, security_level: Optional[int] = None) → dict

Gets all possible inputs of a seed and returns them, along with the total balance.

This is either done deterministically (by generating all addresses until find_transactions() returns an empty result), or by providing a key range to search.

Parameters

  • start (int) – Starting key index. Defaults to 0.

  • stop (Optional[int]) –

    Stop before this index.

    Note that this parameter behaves like the stop attribute in a slice object; the stop index is not included in the result.

    If None (default), then this method will not stop until it finds an unused address.

    Note

    An unused address is an address that has not been spent from and has no transactions referencing it on the Tangle.

    A snapshot removes transactions from the Tangle. As a consequence, after a snapshot, it may happen that this API does not return the correct inputs with stop being None.

    As a workaround, you can save your used addresses and their key_index attribute in a local database. Use the start and stop parameters to tell the API from where to start checking for inputs and where to stop.

  • threshold (Optional[int]) –

    If set, determines the minimum threshold for a successful result:

    • As soon as this threshold is reached, iteration will stop.

    • If the command runs out of addresses before the threshold is reached, an exception is raised.

    Note

    This method does not attempt to “optimize” the result (e.g., smallest number of inputs, get as close to threshold as possible, etc.); it simply accumulates inputs in order until the threshold is met.

    If threshold is 0, the first address in the key range with a non-zero balance will be returned (if it exists).

    If threshold is None (default), this method will return all inputs in the specified key range.

  • security_level (Optional[int]) –

    Number of iterations to use when generating new addresses (see get_new_addresses()).

    This value must be between 1 and 3, inclusive.

    If not set, defaults to AddressGenerator.DEFAULT_SECURITY_LEVEL.

Returns

dict with the following structure:

{
    'inputs': List[Address],
        Addresses with nonzero balances that can be used
        as inputs.

    'totalBalance': int,
        Aggregate balance from all matching addresses.
}

Note that each Address in the result has its Address.balance attribute set.

Example:

response = iota.get_inputs(...)

input0 = response['inputs'][0] # type: Address
input0.balance # 42

Raise

  • iota.adapter.BadApiResponse if threshold is not met. Not applicable if threshold is None.

References:

async AsyncIota.get_inputs(start: int = 0, stop: Optional[int] = None, threshold: Optional[int] = None, security_level: Optional[int] = None) → dict

Gets all possible inputs of a seed and returns them, along with the total balance.

This is either done deterministically (by generating all addresses until find_transactions() returns an empty result), or by providing a key range to search.

Parameters

  • start (int) – Starting key index. Defaults to 0.

  • stop (Optional[int]) –

    Stop before this index.

    Note that this parameter behaves like the stop attribute in a slice object; the stop index is not included in the result.

    If None (default), then this method will not stop until it finds an unused address.

    Note

    An unused address is an address that has not been spent from and has no transactions referencing it on the Tangle.

    A snapshot removes transactions from the Tangle. As a consequence, after a snapshot, it may happen that this API does not return the correct inputs with stop being None.

    As a workaround, you can save your used addresses and their key_index attribute in a local database. Use the start and stop parameters to tell the API from where to start checking for inputs and where to stop.

  • threshold (Optional[int]) –

    If set, determines the minimum threshold for a successful result:

    • As soon as this threshold is reached, iteration will stop.

    • If the command runs out of addresses before the threshold is reached, an exception is raised.

    Note

    This method does not attempt to “optimize” the result (e.g., smallest number of inputs, get as close to threshold as possible, etc.); it simply accumulates inputs in order until the threshold is met.

    If threshold is 0, the first address in the key range with a non-zero balance will be returned (if it exists).

    If threshold is None (default), this method will return all inputs in the specified key range.

  • security_level (Optional[int]) –

    Number of iterations to use when generating new addresses (see get_new_addresses()).

    This value must be between 1 and 3, inclusive.

    If not set, defaults to AddressGenerator.DEFAULT_SECURITY_LEVEL.

Returns

dict with the following structure:

{
    'inputs': List[Address],
        Addresses with nonzero balances that can be used
        as inputs.

    'totalBalance': int,
        Aggregate balance from all matching addresses.
}

Note that each Address in the result has its Address.balance attribute set.

Example:

response = iota.get_inputs(...)

input0 = response['inputs'][0] # type: Address
input0.balance # 42

Raise

  • iota.adapter.BadApiResponse if threshold is not met. Not applicable if threshold is None.

References:

get_new_addresses

Iota.get_new_addresses(index: int = 0, count: int = 1, security_level: int = 2, checksum: bool = False)

Generates one or more new addresses from the seed.

Parameters

  • index (int) – The key index of the first new address to generate (must be >= 0).

  • count (int) –

    Number of addresses to generate (must be >= 1).

    Tip

    This is more efficient than calling get_new_addresses() inside a loop.

    If None, this method will progressively generate addresses and scan the Tangle until it finds one that has no transactions referencing it and was never spent from.

    Note

    A snapshot removes transactions from the Tangle. As a consequence, after a snapshot, it may happen that when count is None, this API call returns a “new” address that used to have transactions before the snapshot. As a workaround, you can save your used addresses and their key_index attribute in a local database. Use the index parameter to tell the API from where to start generating and checking new addresses.

  • security_level (int) –

    Number of iterations to use when generating new addresses.

    Larger values take longer, but the resulting signatures are more secure.

    This value must be between 1 and 3, inclusive.

  • checksum (bool) – Specify whether to return the address with the checksum. Defaults to False.

Returns

dict with the following structure:

{
    'addresses': List[Address],
        Always a list, even if only one address was
        generated.
}

References:

async AsyncIota.get_new_addresses(index: int = 0, count: int = 1, security_level: int = 2, checksum: bool = False)

Generates one or more new addresses from the seed.

Parameters

  • index (int) – The key index of the first new address to generate (must be >= 0).

  • count (int) –

    Number of addresses to generate (must be >= 1).

    Tip

    This is more efficient than calling get_new_addresses() inside a loop.

    If None, this method will progressively generate addresses and scan the Tangle until it finds one that has no transactions referencing it and was never spent from.

    Note

    A snapshot removes transactions from the Tangle. As a consequence, after a snapshot, it may happen that when count is None, this API call returns a “new” address that used to have transactions before the snapshot. As a workaround, you can save your used addresses and their key_index attribute in a local database. Use the index parameter to tell the API from where to start generating and checking new addresses.

  • security_level (int) –

    Number of iterations to use when generating new addresses.

    Larger values take longer, but the resulting signatures are more secure.

    This value must be between 1 and 3, inclusive.

  • checksum (bool) – Specify whether to return the address with the checksum. Defaults to False.

Returns

dict with the following structure:

{
    'addresses': List[Address],
        Always a list, even if only one address was
        generated.
}

References:

get_transaction_objects

Iota.get_transaction_objects(hashes: [typing.Iterable[iota.transaction.types.TransactionHash]]) → dict

Fetches transaction objects from the Tangle given their transaction IDs (hashes).

Effectively, this is get_trytes() + converting the trytes into transaction objects.

Similar to find_transaction_objects(), but accepts list of transaction hashes as input.

Parameters

hashes (Iterable[TransactionHash]) – List of transaction IDs (transaction hashes).

Returns

dict with the following structure:

{
    'transactions': List[Transaction],
        List of Transaction objects that match the input.
}

async AsyncIota.get_transaction_objects(hashes: [typing.Iterable[iota.transaction.types.TransactionHash]]) → dict

Fetches transaction objects from the Tangle given their transaction IDs (hashes).

Effectively, this is get_trytes() + converting the trytes into transaction objects.

Similar to find_transaction_objects(), but accepts list of transaction hashes as input.

Parameters

hashes (Iterable[TransactionHash]) – List of transaction IDs (transaction hashes).

Returns

dict with the following structure:

{
    'transactions': List[Transaction],
        List of Transaction objects that match the input.
}

get_transfers

Iota.get_transfers(start: int = 0, stop: Optional[int] = None, inclusion_states: bool = False) → dict

Returns all transfers associated with the seed.

Parameters

  • start (int) – Starting key index.

  • stop (Optional[int]) –

    Stop before this index.

    Note that this parameter behaves like the stop attribute in a slice object; the stop index is not included in the result.

    If None (default), then this method will check every address until it finds one that is unused.

    Note

    An unused address is an address that has not been spent from and has no transactions referencing it on the Tangle.

    A snapshot removes transactions from the Tangle. As a consequence, after a snapshot, it may happen that this API does not return the expected transfers with stop being None.

    As a workaround, you can save your used addresses and their key_index attribute in a local database. Use the start and stop parameters to tell the API from where to start checking for transfers and where to stop.

  • inclusion_states (bool) –

    Whether to also fetch the inclusion states of the transfers.

    This requires an additional API call to the node, so it is disabled by default.

Returns

dict with the following structure:

{
    'bundles': List[Bundle],
        Matching bundles, sorted by tail transaction
        timestamp.

        This value is always a list, even if only one
        bundle was found.
}

References:

async AsyncIota.get_transfers(start: int = 0, stop: Optional[int] = None, inclusion_states: bool = False) → dict

Returns all transfers associated with the seed.

Parameters

  • start (int) – Starting key index.

  • stop (Optional[int]) –

    Stop before this index.

    Note that this parameter behaves like the stop attribute in a slice object; the stop index is not included in the result.

    If None (default), then this method will check every address until it finds one that is unused.

    Note

    An unused address is an address that has not been spent from and has no transactions referencing it on the Tangle.

    A snapshot removes transactions from the Tangle. As a consequence, after a snapshot, it may happen that this API does not return the expected transfers with stop being None.

    As a workaround, you can save your used addresses and their key_index attribute in a local database. Use the start and stop parameters to tell the API from where to start checking for transfers and where to stop.

  • inclusion_states (bool) –

    Whether to also fetch the inclusion states of the transfers.

    This requires an additional API call to the node, so it is disabled by default.

Returns

dict with the following structure:

{
    'bundles': List[Bundle],
        Matching bundles, sorted by tail transaction
        timestamp.

        This value is always a list, even if only one
        bundle was found.
}

References:

is_confirmed

Iota.is_confirmed(transactions: Iterable[iota.transaction.types.TransactionHash]) → dict

Get the inclusion states of a set of transactions. This is for determining if a transaction was accepted and confirmed by the network or not.

Parameters

transactions (Iterable[TransactionHash]) – List of transactions you want to get the inclusion state for.

Returns

dict with the following structure:

{
    'states': List[bool],
        List of boolean values in the same order as the
        transactions parameters. A ``True`` value means the
        transaction was confirmed.
    'duration': int,
        Number of milliseconds it took to process the request.
}

References:

async AsyncIota.is_confirmed(transactions: Iterable[iota.transaction.types.TransactionHash]) → dict

Get the inclusion states of a set of transactions. This is for determining if a transaction was accepted and confirmed by the network or not.

Parameters

transactions (Iterable[TransactionHash]) – List of transactions you want to get the inclusion state for.

Returns

dict with the following structure:

{
    'states': List[bool],
        List of boolean values in the same order as the
        transactions parameters. A ``True`` value means the
        transaction was confirmed.
    'duration': int,
        Number of milliseconds it took to process the request.
}

References:

is_promotable

Iota.is_promotable(tails: Iterable[iota.transaction.types.TransactionHash]) → dict

Checks if tail transaction(s) is promotable by calling check_consistency() and verifying that attachmentTimestamp is above a lower bound. Lower bound is calculated based on number of milestones issued since transaction attachment.

Parameters

tails (Iterable(TransactionHash)) – List of tail transaction hashes.

Returns

The return type mimics that of check_consistency(). dict with the following structure:

{
    'promotable': bool,
        If ``True``, all tails are promotable. If ``False``, see
        `info` field.

    'info': Optional(List[str])
        If `promotable` is ``False``, this contains info about what
        went wrong.
        Note that when 'promotable' is ``True``, 'info' does not
        exist.

}

References: - https://github.com/iotaledger/iota.js/blob/next/api_reference.md#module_core.isPromotable

async AsyncIota.is_promotable(tails: Iterable[iota.transaction.types.TransactionHash]) → dict

Checks if tail transaction(s) is promotable by calling check_consistency() and verifying that attachmentTimestamp is above a lower bound. Lower bound is calculated based on number of milestones issued since transaction attachment.

Parameters

tails (Iterable(TransactionHash)) – List of tail transaction hashes.

Returns

The return type mimics that of check_consistency(). dict with the following structure:

{
    'promotable': bool,
        If ``True``, all tails are promotable. If ``False``, see
        `info` field.

    'info': Optional(List[str])
        If `promotable` is ``False``, this contains info about what
        went wrong.
        Note that when 'promotable' is ``True``, 'info' does not
        exist.

}

References: - https://github.com/iotaledger/iota.js/blob/next/api_reference.md#module_core.isPromotable

is_reattachable

Iota.is_reattachable(addresses: Iterable[iota.types.Address]) → dict

This API function helps you to determine whether you should replay a transaction or make a new one (either with the same input, or a different one).

This method takes one or more input addresses (i.e. from spent transactions) as input and then checks whether any transactions with a value transferred are confirmed.

If yes, it means that this input address has already been successfully used in a different transaction, and as such you should no longer replay the transaction.

Parameters

addresses (Iterable[Address]) – List of addresses.

Returns

dict with the following structure:

{
  'reattachable': List[bool],
    Always a list, even if only one address was queried.
}

async AsyncIota.is_reattachable(addresses: Iterable[iota.types.Address]) → dict

This API function helps you to determine whether you should replay a transaction or make a new one (either with the same input, or a different one).

This method takes one or more input addresses (i.e. from spent transactions) as input and then checks whether any transactions with a value transferred are confirmed.

If yes, it means that this input address has already been successfully used in a different transaction, and as such you should no longer replay the transaction.

Parameters

addresses (Iterable[Address]) – List of addresses.

Returns

dict with the following structure:

{
  'reattachable': List[bool],
    Always a list, even if only one address was queried.
}

prepare_transfer

Iota.prepare_transfer(transfers: Iterable[iota.transaction.creation.ProposedTransaction], inputs: Optional[Iterable[iota.types.Address]] = None, change_address: Optional[iota.types.Address] = None, security_level: Optional[int] = None) → dict

Prepares transactions to be broadcast to the Tangle, by generating the correct bundle, as well as choosing and signing the inputs (for value transfers).

Parameters

  • transfers (Iterable[ProposedTransaction]) – Transaction objects to prepare.

  • inputs (Optional[Iterable[Address]]) –

    List of addresses used to fund the transfer. Ignored for zero-value transfers.

    If not provided, addresses will be selected automatically by scanning the Tangle for unspent inputs. Depending on how many transfers you’ve already sent with your seed, this process could take awhile.

  • change_address (Optional[Address]) –

    If inputs are provided, any unspent amount will be sent to this address.

    If not specified, a change address will be generated automatically.

  • security_level (Optional[int]) –

    Number of iterations to use when generating new addresses (see get_new_addresses()).

    This value must be between 1 and 3, inclusive.

    If not set, defaults to AddressGenerator.DEFAULT_SECURITY_LEVEL.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        Raw trytes for the transactions in the bundle,
        ready to be provided to :py:meth:`send_trytes`.
}

References:

async AsyncIota.prepare_transfer(transfers: Iterable[iota.transaction.creation.ProposedTransaction], inputs: Optional[Iterable[iota.types.Address]] = None, change_address: Optional[iota.types.Address] = None, security_level: Optional[int] = None) → dict

Prepares transactions to be broadcast to the Tangle, by generating the correct bundle, as well as choosing and signing the inputs (for value transfers).

Parameters

  • transfers (Iterable[ProposedTransaction]) – Transaction objects to prepare.

  • inputs (Optional[Iterable[Address]]) –

    List of addresses used to fund the transfer. Ignored for zero-value transfers.

    If not provided, addresses will be selected automatically by scanning the Tangle for unspent inputs. Depending on how many transfers you’ve already sent with your seed, this process could take awhile.

  • change_address (Optional[Address]) –

    If inputs are provided, any unspent amount will be sent to this address.

    If not specified, a change address will be generated automatically.

  • security_level (Optional[int]) –

    Number of iterations to use when generating new addresses (see get_new_addresses()).

    This value must be between 1 and 3, inclusive.

    If not set, defaults to AddressGenerator.DEFAULT_SECURITY_LEVEL.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        Raw trytes for the transactions in the bundle,
        ready to be provided to :py:meth:`send_trytes`.
}

References:

promote_transaction

Iota.promote_transaction(transaction: iota.transaction.types.TransactionHash, depth: int = 3, min_weight_magnitude: Optional[int] = None) → dict

Promotes a transaction by adding spam on top of it.

Parameters

  • transaction (TransactionHash) – Transaction hash. Must be a tail transaction.

  • depth (int) – Depth at which to attach the bundle. Defaults to 3.

  • min_weight_magnitude (Optional[int]) –

    Min weight magnitude, used by the node to calibrate Proof of Work.

    If not provided, a default value will be used.

Returns

dict with the following structure:

{
    'bundle': Bundle,
        The newly-published bundle.
}

async AsyncIota.promote_transaction(transaction: iota.transaction.types.TransactionHash, depth: int = 3, min_weight_magnitude: Optional[int] = None) → dict

Promotes a transaction by adding spam on top of it.

Parameters

  • transaction (TransactionHash) – Transaction hash. Must be a tail transaction.

  • depth (int) – Depth at which to attach the bundle. Defaults to 3.

  • min_weight_magnitude (Optional[int]) –

    Min weight magnitude, used by the node to calibrate Proof of Work.

    If not provided, a default value will be used.

Returns

dict with the following structure:

{
    'bundle': Bundle,
        The newly-published bundle.
}

replay_bundle

Iota.replay_bundle(transaction: iota.transaction.types.TransactionHash, depth: int = 3, min_weight_magnitude: Optional[int] = None) → dict

Takes a tail transaction hash as input, gets the bundle associated with the transaction and then replays the bundle by attaching it to the Tangle.

Parameters

  • transaction (TransactionHash) – Transaction hash. Must be a tail.

  • depth (int) – Depth at which to attach the bundle. Defaults to 3.

  • min_weight_magnitude (Optional[int]) –

    Min weight magnitude, used by the node to calibrate Proof of Work.

    If not provided, a default value will be used.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        Raw trytes that were published to the Tangle.
}

References:

async AsyncIota.replay_bundle(transaction: iota.transaction.types.TransactionHash, depth: int = 3, min_weight_magnitude: Optional[int] = None) → dict

Takes a tail transaction hash as input, gets the bundle associated with the transaction and then replays the bundle by attaching it to the Tangle.

Parameters

  • transaction (TransactionHash) – Transaction hash. Must be a tail.

  • depth (int) – Depth at which to attach the bundle. Defaults to 3.

  • min_weight_magnitude (Optional[int]) –

    Min weight magnitude, used by the node to calibrate Proof of Work.

    If not provided, a default value will be used.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        Raw trytes that were published to the Tangle.
}

References:

send_transfer

Iota.send_transfer(transfers: Iterable[iota.transaction.creation.ProposedTransaction], depth: int = 3, inputs: Optional[Iterable[iota.types.Address]] = None, change_address: Optional[iota.types.Address] = None, min_weight_magnitude: Optional[int] = None, security_level: Optional[int] = None) → dict

Prepares a set of transfers and creates the bundle, then attaches the bundle to the Tangle, and broadcasts and stores the transactions.

Parameters

  • transfers (Iterable[ProposedTransaction]) – Transfers to include in the bundle.

  • depth (int) – Depth at which to attach the bundle. Defaults to 3.

  • inputs (Optional[Iterable[Address]]) – List of inputs used to fund the transfer. Not needed for zero-value transfers.

  • change_address (Optional[Address]) –

    If inputs are provided, any unspent amount will be sent to this address.

    If not specified, a change address will be generated automatically.

  • min_weight_magnitude (Optional[int]) –

    Min weight magnitude, used by the node to calibrate Proof of Work.

    If not provided, a default value will be used.

  • security_level (Optional[int]) –

    Number of iterations to use when generating new addresses (see get_new_addresses()).

    This value must be between 1 and 3, inclusive.

    If not set, defaults to AddressGenerator.DEFAULT_SECURITY_LEVEL.

Returns

dict with the following structure:

{
    'bundle': Bundle,
        The newly-published bundle.
}

References:

async AsyncIota.send_transfer(transfers: Iterable[iota.transaction.creation.ProposedTransaction], depth: int = 3, inputs: Optional[Iterable[iota.types.Address]] = None, change_address: Optional[iota.types.Address] = None, min_weight_magnitude: Optional[int] = None, security_level: Optional[int] = None) → dict

Prepares a set of transfers and creates the bundle, then attaches the bundle to the Tangle, and broadcasts and stores the transactions.

Parameters

  • transfers (Iterable[ProposedTransaction]) – Transfers to include in the bundle.

  • depth (int) – Depth at which to attach the bundle. Defaults to 3.

  • inputs (Optional[Iterable[Address]]) – List of inputs used to fund the transfer. Not needed for zero-value transfers.

  • change_address (Optional[Address]) –

    If inputs are provided, any unspent amount will be sent to this address.

    If not specified, a change address will be generated automatically.

  • min_weight_magnitude (Optional[int]) –

    Min weight magnitude, used by the node to calibrate Proof of Work.

    If not provided, a default value will be used.

  • security_level (Optional[int]) –

    Number of iterations to use when generating new addresses (see get_new_addresses()).

    This value must be between 1 and 3, inclusive.

    If not set, defaults to AddressGenerator.DEFAULT_SECURITY_LEVEL.

Returns

dict with the following structure:

{
    'bundle': Bundle,
        The newly-published bundle.
}

References:

send_trytes

Iota.send_trytes(trytes: Iterable[iota.transaction.types.TransactionTrytes], depth: int = 3, min_weight_magnitude: Optional[int] = None) → dict

Attaches transaction trytes to the Tangle, then broadcasts and stores them.

Parameters

  • trytes (Iterable[TransactionTrytes]) – Transaction encoded as a tryte sequence.

  • depth (int) – Depth at which to attach the bundle. Defaults to 3.

  • min_weight_magnitude (Optional[int]) –

    Min weight magnitude, used by the node to calibrate Proof of Work.

    If not provided, a default value will be used.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        Raw trytes that were published to the Tangle.
}

References:

async AsyncIota.send_trytes(trytes: Iterable[iota.transaction.types.TransactionTrytes], depth: int = 3, min_weight_magnitude: Optional[int] = None) → dict

Attaches transaction trytes to the Tangle, then broadcasts and stores them.

Parameters

  • trytes (Iterable[TransactionTrytes]) – Transaction encoded as a tryte sequence.

  • depth (int) – Depth at which to attach the bundle. Defaults to 3.

  • min_weight_magnitude (Optional[int]) –

    Min weight magnitude, used by the node to calibrate Proof of Work.

    If not provided, a default value will be used.

Returns

dict with the following structure:

{
    'trytes': List[TransactionTrytes],
        Raw trytes that were published to the Tangle.
}

References:

traverse_bundle

Iota.traverse_bundle(tail_hash: iota.transaction.types.TransactionHash) → dict

Fetches and traverses a bundle from the Tangle given a tail transaction hash. Recursively traverse the Tangle, collecting transactions until we hit a new bundle.

This method is (usually) faster than find_transactions(), and it ensures we don’t collect transactions from replayed bundles.

Parameters

tail_hash (TransactionHash) – Tail transaction hash of the bundle.

Returns

dict with the following structure:

{
  'bundle': List[Bundle],
        List of matching bundles.  Note that this value is
        always a list, even if only one bundle was found.
}

async AsyncIota.traverse_bundle(tail_hash: iota.transaction.types.TransactionHash) → dict

Fetches and traverses a bundle from the Tangle given a tail transaction hash. Recursively traverse the Tangle, collecting transactions until we hit a new bundle.

This method is (usually) faster than find_transactions(), and it ensures we don’t collect transactions from replayed bundles.

Parameters

tail_hash (TransactionHash) – Tail transaction hash of the bundle.

Returns

dict with the following structure:

{
  'bundle': List[Bundle],
        List of matching bundles.  Note that this value is
        always a list, even if only one bundle was found.
}