Core API¶
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.
Extended API¶
The Extended API includes a number of “high level” commands to perform tasks such as sending and receiving transfers.
broadcast_and_store
¶
Broadcasts and stores a set of transaction trytes.
Parameters¶
trytes: Iterable[TransactionTrytes]
: Transaction trytes.
Return¶
This method returns a dict
with the following items:
trytes: List[TransactionTrytes]
: Transaction trytes that were broadcast/stored. Should be the same as the value of thetrytes
parameter.
find_transaction_objects
¶
A more extensive version of the core API 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.param: Optional[Iterable[TransactionHash]]
: List of approvee transaction IDs.
Return¶
This method returns a dict
with the following items:
transactions: List[Transaction]
: List of Transaction objects that match the input
get_account_data
¶
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 thestop
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 without any transfers. 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.
Return¶
This method returns a dict with the following items:
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[Bundles]
: List of bundles with transactions to/from this account.
get_bundles
¶
Given a TransactionHash
, returns the bundle(s) associated with it.
Parameters¶
transaction: TransactionHash
: Hash of a tail transaction.
Return¶
This method returns a dict
with the following items:
bundles: List[Bundle]
: List of matching bundles. Note that this value is always a list, even if only one bundle was found.
get_inputs
¶
Gets all possible inputs of a seed and returns them 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. 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.
- 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.
Note that 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.
Return¶
This method returns a dict
with the following items:
inputs: List[Address]
: Addresses with nonzero balances that can be used as inputs.totalBalance: int
: Aggregate balance of all inputs found.
get_latest_inclusion
¶
Fetches the inclusion state for the specified transaction hashes, as of the latest milestone that the node has processed.
Parameters¶
hashes: Iterable[TransactionHash]
: Iterable of transaction hashes.
Return¶
This method returns a dict
with the following items:
<TransactionHash>: bool
: Inclusion state for a single transaction.
There will be one item per transaction hash in the hashes
parameter.
get_new_addresses
¶
Generates one or more new addresses from the seed.
Parameters¶
index: int
: Specify the index of the new address (must be >= 1).count: Optional[int]
: Number of addresses to generate (must be >= 1).- If
None
, this method will scan the Tangle to find the next available unused address and return that. security_level: int
: Number of iterations to use when generating new addresses. Lower values generate addresses faster, higher values result in more secure signatures in transactions.
Return¶
This method returns a dict
with the following items:
addresses: List[Address]
: The generated address(es). Note that this value is always a list, even if only one address was generated.
get_transaction_objects
¶
Returns a list of transaction objects given a list of transaction hashes.
This is effectively calling get_trytes
and converting the trytes to
transaction objects.
Similar to find_transaction_objects
, but input is list of hashes.
Parameters¶
hashes
: List of transaction hashes that should be fetched.
Return¶
Returns a dict
with the following items:
transactions: List[Transaction]
: List of transaction objects.
get_transfers
¶
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 without any transfers.
Return¶
This method returns a dict
with the following items:
bundles: List[Bundle]
: Matching bundles, sorted by tail transaction timestamp.
is_reattachable
¶
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¶
address: Iterable[Address]
: List of addresses.
Return¶
This method returns a dict
with the following items:
reattachable: List[Bool]
: Always a list, even if only one address was queried.
prepare_transfer
¶
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.
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.
Return¶
This method returns a dict
with the following items:
trytes: List[TransactionTrytes]
: Raw trytes for the transactions in the bundle, ready to be provided tosend_trytes
.
promote_transaction
¶
Promotes a transaction by adding spam on top of it.
transaction: TransactionHash
: Transaction hash. Must be a tail.depth: int
: Depth at which to attach the bundle.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.
Return¶
This method returns a dict
with the following items:
bundle: Bundle
: The newly-published bundle.
replay_bundle
¶
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.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.
Return¶
This method returns a dict
with the following items:
trytes: List[TransactionTrytes]
: Raw trytes that were published to the Tangle.
send_transfer
¶
Prepares a set of transfers and creates the bundle, then attaches the bundle to the Tangle, and broadcasts and stores the transactions.
Parameters¶
depth: int
: Depth at which to attach the bundle.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.
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.
Return¶
This method returns a dict
with the following items:
bundle: Bundle
: The newly-published bundle.
send_trytes
¶
Attaches transaction trytes to the Tangle, then broadcasts and stores them.
Parameters¶
trytes: Iterable[TransactionTrytes]
: Transaction trytes to publish.depth: int
: Depth at which to attach the bundle.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.
Return¶
This method returns a dict
with the following items:
trytes: List[TransactionTrytes]
: Raw trytes that were published to the Tangle.