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() and store_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() and store_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 and branchTransaction.

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 and branchTransaction.

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: