Core API Methods¶
The Core API includes all of the core API calls that are made available by the current IOTA Reference Implementation.
These methods are “low level” and generally do not need to be called directly.
For the full documentation of all the Core API calls, please refer to the official documentation.
Note
Below you will find the documentation for both the synchronous and asynchronous versions of the Core 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.
add_neighbors
¶
-
Iota.
add_neighbors
(uris: Iterable[str]) → dict¶ Add one or more neighbors to the node. Lasts until the node is restarted.
- Parameters
uris (Iterable[str]) –
Use format
<protocol>://<ip address>:<port>
. Example:add_neighbors(['udp://example.com:14265'])
Note
These URIs are for node-to-node communication (e.g., weird things will happen if you specify a node’s HTTP API URI here).
- Returns
dict
with the following structure:{ 'addedNeighbors': int, Total number of added neighbors. 'duration': int, Number of milliseconds it took to complete the request. }
References:
-
async
AsyncIota.
add_neighbors
(uris: Iterable[str]) → dict¶ Add one or more neighbors to the node. Lasts until the node is restarted.
- Parameters
uris (Iterable[str]) –
Use format
<protocol>://<ip address>:<port>
. Example:add_neighbors(['udp://example.com:14265'])
Note
These URIs are for node-to-node communication (e.g., weird things will happen if you specify a node’s HTTP API URI here).
- Returns
dict
with the following structure:{ 'addedNeighbors': int, Total number of added neighbors. 'duration': int, Number of milliseconds it took to complete the request. }
References:
attach_to_tangle
¶
-
Iota.
attach_to_tangle
(trunk_transaction: iota.transaction.types.TransactionHash, branch_transaction: iota.transaction.types.TransactionHash, trytes: Iterable[iota.types.TryteString], min_weight_magnitude: Optional[int] = None) → dict¶ Attaches the specified transactions (trytes) to the Tangle by doing Proof of Work. You need to supply branchTransaction as well as trunkTransaction (basically the tips which you’re going to validate and reference with this transaction) - both of which you’ll get through the
get_transactions_to_approve()
API call.The returned value is a different set of tryte values which you can input into
broadcast_transactions()
andstore_transactions()
.- Parameters
trunk_transaction (TransactionHash) – Trunk transaction hash.
branch_transaction (TransactionHash) – Branch transaction hash.
trytes (Iterable[TransactionTrytes]) – List of transaction trytes in the bundle to be attached.
min_weight_magnitude (Optional[int]) – Minimum weight magnitude to be used for attaching trytes. 14 by default on mainnet, 9 on devnet/devnet.
- Returns
dict
with the following structure:{ 'trytes': List[TransactionTrytes], Transaction trytes that include a valid nonce field. }
References:
-
async
AsyncIota.
attach_to_tangle
(trunk_transaction: iota.transaction.types.TransactionHash, branch_transaction: iota.transaction.types.TransactionHash, trytes: Iterable[iota.types.TryteString], min_weight_magnitude: Optional[int] = None) → dict¶ Attaches the specified transactions (trytes) to the Tangle by doing Proof of Work. You need to supply branchTransaction as well as trunkTransaction (basically the tips which you’re going to validate and reference with this transaction) - both of which you’ll get through the
get_transactions_to_approve()
API call.The returned value is a different set of tryte values which you can input into
broadcast_transactions()
andstore_transactions()
.- Parameters
trunk_transaction (TransactionHash) – Trunk transaction hash.
branch_transaction (TransactionHash) – Branch transaction hash.
trytes (Iterable[TransactionTrytes]) – List of transaction trytes in the bundle to be attached.
min_weight_magnitude (Optional[int]) – Minimum weight magnitude to be used for attaching trytes. 14 by default on mainnet, 9 on devnet/devnet.
- Returns
dict
with the following structure:{ 'trytes': List[TransactionTrytes], Transaction trytes that include a valid nonce field. }
References:
broadcast_transactions
¶
-
Iota.
broadcast_transactions
(trytes: Iterable[iota.types.TryteString]) → dict¶ Broadcast a list of transactions to all neighbors.
The input trytes for this call are provided by
attach_to_tangle()
.- Parameters
trytes (Iterable[TransactionTrytes]) – List of transaction trytes to be broadcast.
- Returns
dict
with the following structure:{ 'duration': int, Number of milliseconds it took to complete the request. }
References:
-
async
AsyncIota.
broadcast_transactions
(trytes: Iterable[iota.types.TryteString]) → dict¶ Broadcast a list of transactions to all neighbors.
The input trytes for this call are provided by
attach_to_tangle()
.- Parameters
trytes (Iterable[TransactionTrytes]) – List of transaction trytes to be broadcast.
- Returns
dict
with the following structure:{ 'duration': int, Number of milliseconds it took to complete the request. }
References:
check_consistency
¶
-
Iota.
check_consistency
(tails: Iterable[iota.transaction.types.TransactionHash]) → dict¶ Used to ensure tail resolves to a consistent ledger which is necessary to validate before attempting promotion. Checks transaction hashes for promotability.
This is called with a pending transaction (or more of them) and it will tell you if it is still possible for this transaction (or all the transactions simultaneously if you give more than one) to be confirmed, or not (because it conflicts with another already confirmed transaction).
- Parameters
tails (Iterable[TransactionHash]) – Transaction hashes. Must be tail transactions.
- Returns
dict
with the following structure:{ 'state': bool, Whether tails resolve to consistent ledger. 'info': str, This field will only exist if 'state' is ``False``. }
References:
-
async
AsyncIota.
check_consistency
(tails: Iterable[iota.transaction.types.TransactionHash]) → dict¶ Used to ensure tail resolves to a consistent ledger which is necessary to validate before attempting promotion. Checks transaction hashes for promotability.
This is called with a pending transaction (or more of them) and it will tell you if it is still possible for this transaction (or all the transactions simultaneously if you give more than one) to be confirmed, or not (because it conflicts with another already confirmed transaction).
- Parameters
tails (Iterable[TransactionHash]) – Transaction hashes. Must be tail transactions.
- Returns
dict
with the following structure:{ 'state': bool, Whether tails resolve to consistent ledger. 'info': str, This field will only exist if 'state' is ``False``. }
References:
find_transactions
¶
-
Iota.
find_transactions
(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¶ Find the transactions which match the specified input and return.
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:{ 'hashes': List[TransationHash], Found transactions. }
References:
-
async
AsyncIota.
find_transactions
(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¶ Find the transactions which match the specified input and return.
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:{ 'hashes': List[TransationHash], Found transactions. }
References:
get_balances
¶
-
Iota.
get_balances
(addresses: Iterable[iota.types.Address], tips: Optional[Iterable[iota.transaction.types.TransactionHash]] = None) → dict¶ Returns the confirmed balance which a list of addresses have at the latest confirmed milestone.
In addition to the balances, it also returns the milestone as well as the index with which the confirmed balance was determined. The balances are returned as a list in the same order as the addresses were provided as input.
- Parameters
addresses (Iterable[Address]) – List of addresses to get the confirmed balance for.
tips (Optional[Iterable[TransactionHash]]) – Tips whose history of transactions to traverse to find the balance.
- Returns
dict
with the following structure:{ 'balances': List[int], List of balances in the same order as the addresses parameters that were passed to the endpoint. 'references': List[TransactionHash], The referencing tips. If no tips parameter was passed to the endpoint, this field contains the hash of the latest milestone that confirmed the balance. 'milestoneIndex': int, The index of the milestone that confirmed the most recent balance. 'duration': int, Number of milliseconds it took to process the request. }
References:
-
async
AsyncIota.
get_balances
(addresses: Iterable[iota.types.Address], tips: Optional[Iterable[iota.transaction.types.TransactionHash]] = None) → dict¶ Returns the confirmed balance which a list of addresses have at the latest confirmed milestone.
In addition to the balances, it also returns the milestone as well as the index with which the confirmed balance was determined. The balances are returned as a list in the same order as the addresses were provided as input.
- Parameters
addresses (Iterable[Address]) – List of addresses to get the confirmed balance for.
tips (Optional[Iterable[TransactionHash]]) – Tips whose history of transactions to traverse to find the balance.
- Returns
dict
with the following structure:{ 'balances': List[int], List of balances in the same order as the addresses parameters that were passed to the endpoint. 'references': List[TransactionHash], The referencing tips. If no tips parameter was passed to the endpoint, this field contains the hash of the latest milestone that confirmed the balance. 'milestoneIndex': int, The index of the milestone that confirmed the most recent balance. 'duration': int, Number of milliseconds it took to process the request. }
References:
get_inclusion_states
¶
-
Iota.
get_inclusion_states
(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.
get_inclusion_states
(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:
get_missing_transactions
¶
-
Iota.
get_missing_transactions
() → dict¶ Returns all transaction hashes that a node is currently requesting from its neighbors.
- Returns
dict
with the following structure:{ 'hashes': List[TransactionHash], Array of missing transaction hashes. 'duration': int, Number of milliseconds it took to process the request. }
References:
-
async
AsyncIota.
get_missing_transactions
() → dict¶ Returns all transaction hashes that a node is currently requesting from its neighbors.
- Returns
dict
with the following structure:{ 'hashes': List[TransactionHash], Array of missing transaction hashes. 'duration': int, Number of milliseconds it took to process the request. }
References:
get_neighbors
¶
-
Iota.
get_neighbors
() → dict¶ Returns the set of neighbors the node is connected with, as well as their activity count.
The activity counter is reset after restarting IRI.
- Returns
dict
with the following structure:{ 'neighbors': List[dict], Array of objects, including the following fields with example values: "address": "/8.8.8.8:14265", "numberOfAllTransactions": 158, "numberOfRandomTransactionRequests": 271, "numberOfNewTransactions": 956, "numberOfInvalidTransactions": 539, "numberOfStaleTransactions": 663, "numberOfSentTransactions": 672, "connectiontype": "TCP" 'duration': int, Number of milliseconds it took to process the request. }
References:
-
async
AsyncIota.
get_neighbors
() → dict¶ Returns the set of neighbors the node is connected with, as well as their activity count.
The activity counter is reset after restarting IRI.
- Returns
dict
with the following structure:{ 'neighbors': List[dict], Array of objects, including the following fields with example values: "address": "/8.8.8.8:14265", "numberOfAllTransactions": 158, "numberOfRandomTransactionRequests": 271, "numberOfNewTransactions": 956, "numberOfInvalidTransactions": 539, "numberOfStaleTransactions": 663, "numberOfSentTransactions": 672, "connectiontype": "TCP" 'duration': int, Number of milliseconds it took to process the request. }
References:
get_node_api_configuration
¶
-
Iota.
get_node_api_configuration
() → dict¶ Returns a node’s API configuration settings.
- Returns
dict
with the following structure:{ '<API-config-settings>': type, Configuration parameters for a node. ... ... ... }
References:
-
async
AsyncIota.
get_node_api_configuration
() → dict¶ Returns a node’s API configuration settings.
- Returns
dict
with the following structure:{ '<API-config-settings>': type, Configuration parameters for a node. ... ... ... }
References:
get_node_info
¶
-
Iota.
get_node_info
() → dict¶ Returns information about the node.
- Returns
dict
with the following structure:{ 'appName': str, Name of the IRI network. 'appVersion': str, Version of the IRI. 'jreAvailableProcessors': int, Available CPU cores on the node. 'jreFreeMemory': int, Amount of free memory in the Java virtual machine. 'jreMaxMemory': int, Maximum amount of memory that the Java virtual machine can use, 'jreTotalMemory': int, Total amount of memory in the Java virtual machine. 'jreVersion': str, The version of the Java runtime environment. 'latestMilestone': TransactionHash Transaction hash of the latest milestone. 'latestMilestoneIndex': int, Index of the latest milestone. 'latestSolidSubtangleMilestone': TransactionHash, Transaction hash of the latest solid milestone. 'latestSolidSubtangleMilestoneIndex': int, Index of the latest solid milestone. 'milestoneStartIndex': int, Start milestone for the current version of the IRI. 'neighbors': int, Total number of connected neighbor nodes. 'packetsQueueSize': int, Size of the packet queue. 'time': int, Current UNIX timestamp. 'tips': int, Number of tips in the network. 'transactionsToRequest': int, Total number of transactions that the node is missing in its ledger. 'features': List[str], Enabled configuration options. 'coordinatorAddress': Address, Address (Merkle root) of the Coordinator. 'duration': int, Number of milliseconds it took to process the request. }
References:
-
async
AsyncIota.
get_node_info
() → dict¶ Returns information about the node.
- Returns
dict
with the following structure:{ 'appName': str, Name of the IRI network. 'appVersion': str, Version of the IRI. 'jreAvailableProcessors': int, Available CPU cores on the node. 'jreFreeMemory': int, Amount of free memory in the Java virtual machine. 'jreMaxMemory': int, Maximum amount of memory that the Java virtual machine can use, 'jreTotalMemory': int, Total amount of memory in the Java virtual machine. 'jreVersion': str, The version of the Java runtime environment. 'latestMilestone': TransactionHash Transaction hash of the latest milestone. 'latestMilestoneIndex': int, Index of the latest milestone. 'latestSolidSubtangleMilestone': TransactionHash, Transaction hash of the latest solid milestone. 'latestSolidSubtangleMilestoneIndex': int, Index of the latest solid milestone. 'milestoneStartIndex': int, Start milestone for the current version of the IRI. 'neighbors': int, Total number of connected neighbor nodes. 'packetsQueueSize': int, Size of the packet queue. 'time': int, Current UNIX timestamp. 'tips': int, Number of tips in the network. 'transactionsToRequest': int, Total number of transactions that the node is missing in its ledger. 'features': List[str], Enabled configuration options. 'coordinatorAddress': Address, Address (Merkle root) of the Coordinator. 'duration': int, Number of milliseconds it took to process the request. }
References:
get_transactions_to_approve
¶
-
Iota.
get_transactions_to_approve
(depth: int, reference: Optional[iota.transaction.types.TransactionHash] = None) → dict¶ Tip selection which returns
trunkTransaction
andbranchTransaction
.- Parameters
depth (int) –
Number of milestones to go back to start the tip selection algorithm.
The higher the depth value, the more “babysitting” the node will perform for the network (as it will confirm more transactions that way).
reference (TransactionHash) – Transaction hash from which to start the weighted random walk. Use this parameter to make sure the returned tip transaction hashes approve a given reference transaction.
- Returns
dict
with the following structure:{ 'trunkTransaction': TransactionHash, Valid trunk transaction hash. 'branchTransaction': TransactionHash, Valid branch transaction hash. 'duration': int, Number of milliseconds it took to complete the request. }
References:
-
async
AsyncIota.
get_transactions_to_approve
(depth: int, reference: Optional[iota.transaction.types.TransactionHash] = None) → dict¶ Tip selection which returns
trunkTransaction
andbranchTransaction
.- Parameters
depth (int) –
Number of milestones to go back to start the tip selection algorithm.
The higher the depth value, the more “babysitting” the node will perform for the network (as it will confirm more transactions that way).
reference (TransactionHash) – Transaction hash from which to start the weighted random walk. Use this parameter to make sure the returned tip transaction hashes approve a given reference transaction.
- Returns
dict
with the following structure:{ 'trunkTransaction': TransactionHash, Valid trunk transaction hash. 'branchTransaction': TransactionHash, Valid branch transaction hash. 'duration': int, Number of milliseconds it took to complete the request. }
References:
get_trytes
¶
-
Iota.
get_trytes
(hashes: Iterable[iota.transaction.types.TransactionHash]) → dict¶ Returns the raw transaction data (trytes) of one or more transactions.
- Returns
dict
with the following structure:{ 'trytes': List[TransactionTrytes], List of transaction trytes for the given transaction hashes (in the same order as the parameters). 'duration': int, Number of milliseconds it took to complete the request. }
Note
If a node doesn’t have the trytes for a given transaction hash in its ledger, the value at the index of that transaction hash is either
null
or a string of 9s.
References:
-
async
AsyncIota.
get_trytes
(hashes: Iterable[iota.transaction.types.TransactionHash]) → dict¶ Returns the raw transaction data (trytes) of one or more transactions.
- Returns
dict
with the following structure:{ 'trytes': List[TransactionTrytes], List of transaction trytes for the given transaction hashes (in the same order as the parameters). 'duration': int, Number of milliseconds it took to complete the request. }
Note
If a node doesn’t have the trytes for a given transaction hash in its ledger, the value at the index of that transaction hash is either
null
or a string of 9s.
References:
interrupt_attaching_to_tangle
¶
-
Iota.
interrupt_attaching_to_tangle
() → dict¶ Interrupts and completely aborts the
attach_to_tangle()
process.- Returns
dict
with the following structure:{ 'duration': int, Number of milliseconds it took to complete the request. }
References:
-
async
AsyncIota.
interrupt_attaching_to_tangle
() → dict¶ Interrupts and completely aborts the
attach_to_tangle()
process.- Returns
dict
with the following structure:{ 'duration': int, Number of milliseconds it took to complete the request. }
References:
remove_neighbors
¶
-
Iota.
remove_neighbors
(uris: Iterable[str]) → dict¶ Removes one or more neighbors from the node. Lasts until the node is restarted.
- Parameters
uris (str) – Use format
<protocol>://<ip address>:<port>
. Example: remove_neighbors([‘udp://example.com:14265’])- Returns
dict
with the following structure:{ 'removedNeighbors': int, Total number of removed neighbors. 'duration': int, Number of milliseconds it took to complete the request. }
References:
-
async
AsyncIota.
remove_neighbors
(uris: Iterable[str]) → dict¶ Removes one or more neighbors from the node. Lasts until the node is restarted.
- Parameters
uris (str) – Use format
<protocol>://<ip address>:<port>
. Example: remove_neighbors([‘udp://example.com:14265’])- Returns
dict
with the following structure:{ 'removedNeighbors': int, Total number of removed neighbors. 'duration': int, Number of milliseconds it took to complete the request. }
References:
store_transactions
¶
-
Iota.
store_transactions
(trytes: Iterable[iota.types.TryteString]) → dict¶ Store transactions into local storage of the node.
The input trytes for this call are provided by
attach_to_tangle()
.- Parameters
trytes (TransactionTrytes) – Valid transaction trytes returned by
attach_to_tangle()
.- Returns
dict
with the following structure:{ 'trytes': TransactionTrytes, Stored trytes. 'duration': int, Number of milliseconds it took to complete the request. }
References:
-
async
AsyncIota.
store_transactions
(trytes: Iterable[iota.types.TryteString]) → dict¶ Store transactions into local storage of the node.
The input trytes for this call are provided by
attach_to_tangle()
.- Parameters
trytes (TransactionTrytes) – Valid transaction trytes returned by
attach_to_tangle()
.- Returns
dict
with the following structure:{ 'trytes': TransactionTrytes, Stored trytes. 'duration': int, Number of milliseconds it took to complete the request. }
References:
were_addresses_spent_from
¶
-
Iota.
were_addresses_spent_from
(addresses: Iterable[iota.types.Address]) → dict¶ Check if a list of addresses was ever spent from, in the current epoch, or in previous epochs.
If an address has a pending transaction, it’s also considered ‘spent’.
- Parameters
addresses (Iterable[Address]) – List of addresses to check.
- Returns
dict
with the following structure:{ 'states': List[bool], States of the specified addresses in the same order as the values in the addresses parameter. A ``True`` value means that the address has been spent from. 'duration': int, Number of milliseconds it took to complete the request. }
References:
-
async
AsyncIota.
were_addresses_spent_from
(addresses: Iterable[iota.types.Address]) → dict¶ Check if a list of addresses was ever spent from, in the current epoch, or in previous epochs.
If an address has a pending transaction, it’s also considered ‘spent’.
- Parameters
addresses (Iterable[Address]) – List of addresses to check.
- Returns
dict
with the following structure:{ 'states': List[bool], States of the specified addresses in the same order as the values in the addresses parameter. A ``True`` value means that the address has been spent from. 'duration': int, Number of milliseconds it took to complete the request. }
References: