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 aslice
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
beingNone
.As a workaround, you can save your used addresses and their
key_index
attribute in a local database. Use thestart
andstop
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 aslice
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
beingNone
.As a workaround, you can save your used addresses and their
key_index
attribute in a local database. Use thestart
andstop
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 aslice
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
beingNone
.As a workaround, you can save your used addresses and their
key_index
attribute in a local database. Use thestart
andstop
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
isNone
(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 itsAddress.balance
attribute set.Example:
response = iota.get_inputs(...) input0 = response['inputs'][0] # type: Address input0.balance # 42
- Raise
iota.adapter.BadApiResponse
ifthreshold
is not met. Not applicable ifthreshold
isNone
.
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 aslice
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
beingNone
.As a workaround, you can save your used addresses and their
key_index
attribute in a local database. Use thestart
andstop
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
isNone
(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 itsAddress.balance
attribute set.Example:
response = iota.get_inputs(...) input0 = response['inputs'][0] # type: Address input0.balance # 42
- Raise
iota.adapter.BadApiResponse
ifthreshold
is not met. Not applicable ifthreshold
isNone
.
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
isNone
, 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 theirkey_index
attribute in a local database. Use theindex
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
isNone
, 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 theirkey_index
attribute in a local database. Use theindex
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 aslice
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
beingNone
.As a workaround, you can save your used addresses and their
key_index
attribute in a local database. Use thestart
andstop
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 aslice
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
beingNone
.As a workaround, you can save your used addresses and their
key_index
attribute in a local database. Use thestart
andstop
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 thatattachmentTimestamp
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 thatattachmentTimestamp
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. }