Skip to main content

API Reference - IOTA Client Library - Java binding

Api

The Api enum contains a list of node endpoints we can call. It is used in setting a timeout for a specific api call during the building of a client using withApiTimeout(api, timeout) .

GET_HEALTH GET_INFO GET_PEERS GET_TIPS POST_MESSAGE POST_MESSAGE_WITH_REMOTE_POW GET_OUTPUT GET_MILESTONE GET_MESSAGE GET_BALANCE

ClientBuilder

new(): ClientBuilder

Construct the ClientBuilder instance, with which you can create a Client to connect to nodes

withNode(node): ClientBuilder

Adds an IOTA node to the client pool.

ParamTypeDescription
nodeStringA node URL

withNodes(nodes): ClientBuilder

Adds an array of IOTA nodes to the client pool.

ParamTypeDescription
nodesString[]A node URL

withNodeAuth(node, jwt, username, password): ClientBuilder

Adds an IOTA node by its URL with optional jwt and or basic authentication

ParamTypeDescription
nodesStringA node URL
jwtStringjwt or null
usernameStringusername or null
passwordStringpassword or null

withPrimaryNode(node, jwt, username, password): ClientBuilder

Adds an IOTA node by its URL to be used as primary node, with optional jwt and or basic authentication

ParamTypeDescription
nodeStringA node URL
jwtStringjwt or null
usernameStringusername or null
passwordStringpassword or null

withPrimaryPowNode(node, jwt, username, password): ClientBuilder

Adds an IOTA node by its URL to be used as primary PoW node (for remote PoW), with optional jwt and or basic authentication

ParamTypeDescription
nodeStringA node URL
jwtStringjwt or null
usernameStringusername or null
passwordStringpassword or null

withPermanode(node, jwt, username, password): ClientBuilder

Adds an IOTA permanode by its URL, with optional jwt and or basic authentication

ParamTypeDescription
nodeStringA node URL
jwtStringjwt or null
usernameStringusername or null
passwordStringpassword or null

withNodePoolUrls(nodes): ClientBuilder

Add a list of nodes to use in a node pool

ParamTypeDescription
nodesString[]urls for the node pool

withOfflineMode(): ClientBuilder

Allows creating the client without nodes for offline address generation or signing

withNetwork(network): ClientBuilder

Add a list of nodes to use in a node pool

ParamTypeDescription
networkStringname of the network

withNodeSyncInterval(node_sync_interval): ClientBuilder

Set the node sync interval

ParamTypeDescription
node_sync_intervalfloatthe interval in seconds

withNodeSyncDisabled(): ClientBuilder

Disables the node syncing process. Every node will be considered healthy and ready to use.

withQuorum(quorum): ClientBuilder

Set if quorum should be used or not

ParamTypeDescription
quorumbooleantrue for quorum on, false for off

withQuorumSize(quorum_size): ClientBuilder

Set amount of nodes which should be used for quorum

ParamTypeDescription
quorum_sizelongsize of the quorum

withQuorumThreshold(threshold): ClientBuilder

Set quorum threshold percentage (0-100)

ParamTypeDescription
thresholdlongthreshold for reaching a quorum decision

withMqttBrokerOptions(options): ClientBuilder

Sets the MQTT broker options.

ParamTypeDescription
optionsBrokerOptionsthe options to use in MQTT

withLocalPow(local): ClientBuilder

Sets whether the PoW should be done locally or remotely.

ParamTypeDescription
localbooleantrue for local PoW, false for remote

withTipsInterval(tips): ClientBuilder

Sets after how many seconds new tips will be requested during PoW

ParamTypeDescription
tipslonginterval in seconds

withRequestTimeout(timeout): ClientBuilder

Sets the default request timeout in seconds.

ParamTypeDescription
timeoutfloatthe timeout in seconds

withApiTimeout(api, timeout): ClientBuilder

Sets the request timeout in seconds for a specific API usage.

ParamTypeDescription
apiApiThe api call to set the timeout for
timeoutfloatthe timeout in seconds

withRequestTimeout(timeout): ClientBuilder

Sets the default request timeout in seconds.

ParamTypeDescription
timeoutfloatthe timeout in seconds

finish(): Client

Build the Client instance.

Client

Static methods

Builder(): ClientBuilder

Static method to create a ClientBuilder

generateMnemonic(): String

Generates a new mnemonic.

mnemonicToHexSeed(): String

Returns a hex encoded seed for a mnemonic.

bech32ToHex(bech32): String

Transforms bech32 to hex

isAddressValid(address): boolean

Checks if a String address is valid.

ParamTypeDescription
addressStringThe address to check validity for

parseBech32Address(address): Address

Returns a valid Address parsed from a String.

ParamTypeDescription
addressStringThe address to parse

instance methods

getHealth(): boolean

GET /health endpoint

getNodeHealth(node): boolean

GET /health endpoint for a specific node

ParamTypeDescription
nodeStringnode to call get health on

getInfo(): NodeInfoWrapper

GET /api/v1/info endpoint

getPeers(): PeerDto[]

GET /api/v1/peers endpoint

getTips(): ClientBuilder

GET /api/v1/tips endpoint

getOutput(output_id): OutputResponse

GET /api/v1/outputs/{outputId} endpoint Find an output by its transaction_id and corresponding output_index.

ParamTypeDescription
output_idStringthe id of the output

getAddress(): GetAddressBuilder

GET /api/v1/addresses/{address} endpoint Returns a builder ith which to construct the exact needs.

getAddressBalance(address): BalanceAddressResponse

Return the balance in iota for the given address; No seed or security level needed to do this since we are only checking and already know the address.

ParamTypeDescription
addressStringthe address to look up

getAddressesBalances(addresses): BalanceAddressResponse[]

Return the balance in iota for the given addresses; No seed or security level needed to do this since we are only checking and already know the addresses.

ParamTypeDescription
addressesString[]the addresses to look up

findOutputs(output_ids, addresses): OutputResponse[]

Find all outputs based on the requests criteria. This method will try to query multiple nodes if the request amount exceeds individual node limit.

ParamTypeDescription
output_idsString[]the output ids to look up
addressesString[]the addresses to look up

getMilestone(index): MilestoneResponse

GET /api/v1/milestones/{index} endpoint Get the milestone by the given index.

ParamTypeDescription
indexlongthe milestone index

getMilestoneUtxoChanges(index): MilestoneUtxoChangesResponse

GET /api/v1/milestones/{index}/utxo-changes endpoint Gets the utxo changes by the given milestone index.

ParamTypeDescription
indexlongthe milestone index

getReceipts(): ReceiptDto[]

GET /api/v1/receipts/{migratedAt} endpoint Get the receipts by the given milestone index.

getReceiptsMigratedAt(index): MilestoneUtxoChangesResponse

GET /api/v1/receipts/{migratedAt} endpoint Get the receipts by the given milestone index.

ParamTypeDescription
indexlongthe milestone index

getTreasury(): TreasuryResponse[]

GET /api/v1/treasury endpoint Get the treasury output.

getIncludedMessage(transaction_id): Message

GET /api/v1/transactions/{transactionId}/included-message Returns the included message of the transaction.

ParamTypeDescription
transaction_idTransactionIdthe transaction id (has a fromString constructor)

postMessage(msg): MessageId

POST /api/v1/messages endpoint

ParamTypeDescription
msgMessageThe message to post to the node

reattach(message_id): MessageWrap

Reattaches messages for provided message id. Messages can be reattached only if they are valid and haven't been confirmed for a while.

ParamTypeDescription
message_idMessageIdThe message to re-post to the node

reattachUnchecked(message_id): MessageWrap

Reattach a message without checking if it should be reattached

ParamTypeDescription
message_idMessageIdThe message to re-post to the node

promote(message_id): MessageWrap

Promotes a message. The method should validate if a promotion is necessary through get_message. If not, the method should error out and should not allow unnecessary promotions.

ParamTypeDescription
message_idMessageIdThe message to promote to the node

promoteUnchecked(message_id): MessageWrap

Promote a message without checking if it should be promoted

ParamTypeDescription
message_idMessageIdThe message to promote to the node

getBalance(seed): GetBalanceBuilderApi

Return the balance for a provided seed and its wallet chain account index. Addresses with balance must be consecutive, so this method will return once it encounters a zero balance address.

ParamTypeDescription
seedStringthe seed we use to generate addresses

message(): ClientMessageBuilder

A generic send function for easily sending transaction or indexation messages.

getMessage(): GetMessageBuilder

GET /api/v1/messages/{messageId} endpoint

getAddresses(seed): GetAddressesBuilder

Return a list of addresses from the seed regardless of their validity.

ParamTypeDescription
seedStringthe seed we use to generate addresses

retryUntilIncluded(message_id, interval, max_attempts): MessageWrap[]

Retries (promotes or reattaches) a message for provided message id until it's included (referenced by a milestone). Default interval is 5 seconds and max attempts is 10. Returns reattached messages. Set to -1 for defaults.

ParamTypeDescription
message_idMessageIdthe id of the message we wish to have included
intervallongdelay in between retries in seconds
max_attemptslongmaximum amount of retries before we error out

findInputs(addresses, amount): UtxoInput[]

Function to find inputs from addresses for a provided amount (useful for offline signing)

ParamTypeDescription
addressesString[]A list of addresses to check for inputs
amountlongThe value we need these inputs to contain in total

ClientMessageBuilder

withSeed(seed): ClientMessageBuilder

Sets the seed.

ParamTypeDescription
seedStringthe seed we use to sign messages

withAccountIndex(account_index): ClientMessageBuilder

Sets the account index.

ParamTypeDescription
account_indexlongThe account index we use

withInitialAddressIndex(initial_address_index): ClientMessageBuilder

Sets the index of the address to start looking for balance.

ParamTypeDescription
initial_address_indexlongThe starting index

withInput(initial_address_index): ClientMessageBuilder

Set a custom input(transaction output)

ParamTypeDescription
inputUtxoInputcustom input

withInputRange(low, high): ClientMessageBuilder

Set a custom range in which to search for addresses for custom inputs. Default: 0..100

ParamTypeDescription
lowlonglower end of the range (must be 0 or higher)
highlonghigher end of the range (must be higher than low)

withOutput(address, amount): ClientMessageBuilder

Set a transfer to the builder, tries to parse address

ParamTypeDescription
addressStringThe address we transfer the amount to
amountlongthe amount of iota to send to the address

withOutputHex(address, amount): ClientMessageBuilder

Set a transfer to the builder, address needs to be hex encoded

ParamTypeDescription
addressStringThe address we transfer the amount to
amountlongthe amount of iota to send to the address

withDustAllowanceOutput(address, amount): ClientMessageBuilder

Set a dust allowance transfer to the builder, address needs to be Bech32 encoded

ParamTypeDescription
addressStringThe address we transfer the dust amount to
amountlongthe amount of iota to send to the address. Must be more than 1.000.000

withIndexVec(index): ClientMessageBuilder

Set indexation to the builder

ParamTypeDescription
indexbyte[]index in bytes

withIndexString(index): ClientMessageBuilder

Set indexation to the builder

ParamTypeDescription
indexStringThe index

withData(data): ClientMessageBuilder

Set the data part of a message to the builder

ParamTypeDescription
databyte[]data in bytes

withDataString(data): ClientMessageBuilder

Set the data part of a message to the builder

ParamTypeDescription
dataStringThe data

prepareTransaction(): PreparedTransactionData

Prepare a transaction. This consumes the builder.

signTransaction(prepared_transaction_data, seed, inputs_range_low, inputs_range_high): MessagePayload

Sign the transaction. Set inputsRangeLow and high to 0 for not using an input range. This consumes the builder.

ParamTypeDescription
prepared_transaction_dataPreparedTransactionDataThe prepared data (from prepareTransaction)
seedStringThe seed we use for address finding and signing
inputs_range_lowlongThe 1 lower range (minimum 0)
inputs_range_highlongThe the inputs higher range (minimum lower + 1)

finish(payload): Message

Consume the builder and return the message made with the generic message payload

ParamTypeDescription
payloadMessagePayloadThe data

finishTransaction(payload): Message

Consume the builder and return the message made with a TransactionPayload

ParamTypeDescription
payloadTransactionPayloadThe data

finishMilestone(payload): Message

Consume the builder and return the message made with a MilestonePayload

ParamTypeDescription
payloadMilestonePayloadThe data

finishIndex(payload): Message

Consume the builder and return the message made with an IndexationPayload | Param | Type | Description | | ----- | ---------- | ----------- | | payload | IndexationPayload | The data |

finishReceipt(payload): Message

Consume the builder and return the message made with a ReceiptPayload

ParamTypeDescription
payloadReceiptPayloadThe data

finishTreasury(payload): Message

Consume the builder and return the message made with a TreasuryPayload

ParamTypeDescription
payloadTreasuryPayloadThe data

finish(): Message

Consume the builder and return the message

GetMessageBuilder

indexString(index): MessageId[]

GET /api/v1/messages?index={Index} endpoint Consume the builder and search for messages matching the index

ParamTypeDescription
indexbyte[]index in bytes

indexVec(index): MessageId[]

GET /api/v1/messages?index={Index} endpoint Consume the builder and search for messages matching the index

ParamTypeDescription
indexStringThe index

data(message_id): Message

GET /api/v1/messages/{messageID} endpoint Consume the builder and find a message by its identifier. This method returns the given message object if it exists.

ParamTypeDescription
message_idMessageIdThe id of the message

metadata(message_id): MessageMetadata

GET /api/v1/messages/{messageID}/metadata endpoint Consume the builder and find a message by its identifier. This method returns the given message metadata if it exists.

ParamTypeDescription
message_idMessageIdThe id of the message

raw(message_id): String

GET /api/v1/messages/{messageID}/raw endpoint Consume the builder and find a message by its identifier. This method returns the given message raw data if it exists.

ParamTypeDescription
message_idMessageIdThe id of the message

children(message_id): MessageId []

GET /api/v1/messages/{messageID}/children endpoint Consume the builder and returns the list of message IDs that reference a message by its identifier if it exists.

ParamTypeDescription
message_idMessageIdThe id of the message

GetAddressesBuilder

balance(address): BalanceAddressResponse

Consume the builder and get the balance of a given Bech32 encoded address. If count equals maxResults, then there might be more outputs available but those were skipped for performance reasons. User should sweep the address to reduce the amount of outputs.

ParamTypeDescription
addressStringThe address were looking up the balance for

outputs(address, options): BalanceAddressResponse

Consume the builder and get all outputs that use a given address. If count equals maxResults, then there might be more outputs available but those were skipped for performance reasons. User should sweep the address to reduce the amount of outputs.

ParamTypeDescription
addressStringThe address were looking up the balance for
optionsOutputsOptionsThe options for which outputs to show

OutputsOptions

includeSpent(include_spent): void

Whether the query should include spent outputs or not.

ParamTypeDescription
include_spentbooleantrue for including spent addresses, false for excluding

outputType(output_type): void

On what type of output are we filtering. can be SIGNATURE_LOCKED_SINGLE, SIGNATURE_LOCKED_DUST_ALLOWANCE or TREASURY

ParamTypeDescription
output_typeOutputKindThe output type filter.

Message

Represent the object that nodes gossip around the network.

builder(): MessageBuilder

Creates a new MessageBuilder to construct an instance of a Message.

networkId(): long

Returns the network id of a Message.

nonce(): long

Returns the nonce of a Message.

parents(): MessageId []

Returns the parents of a Message.

payload(): Optional<MessagePayload>

Returns the optional payload of a Message.

MessageBuilder

A builder to build a Message.

new(): MessageBuilder

A builder to build a Message.

networkId(network_id): MessageBuilder

Adds a network id to a MessageBuilder.

ParamTypeDescription
network_idlongThe network id of the message

parents(parents): MessageBuilder

Adds parents to a MessageBuilder.

ParamTypeDescription
parentsMessageId[]The parents of this message

payload(payload): MessageBuilder

Adds a payload to a MessageBuilder.

ParamTypeDescription
payloadMessagePayloadThe payload of the message

MessagePayload

deserialize(serialised_data): MessagePayload

Turns a serialized message payload string back into its class

ParamTypeDescription
serialised_dataStringThe serialised Json MessagePayload string

serialize(): String

Serializes the message payload into a json string.

payloadType(): MessagePayloadType

Get the type of message this contains (used to select the correct getter). Possible types are TRANSACTION, MILESTONE, INDEXATION, RECEIPT and TREASURY_TRANSACTION.

getAsIndexation(): Optional<IndexationPayload>

Get this Payload as a Indexation payload type

getAsTransaction(): Optional<TransactionPayload>

Get this Payload as a TransactionPayload type

getAsTreasury(): Optional<TreasuryPayload>

Get this Payload as a TreasuryPayload type

getAsMilestone(): Optional<MilestonePayload>

Get this Payload as a MilestonePayload type

getAsReceipt(): Optional<ReceiptPayload>

Get this Payload as a ReceiptPayload type

IndexationPayload

fromBytes(index, data): void

Creates a new IndexationPayload.

ParamTypeDescription
indexbyte []index bytes
databyte []data bytes

fromStrings(index, data): void

Creates a new IndexationPayload from strings

ParamTypeDescription
indexStringindex string
dataStringdata string

index(): byte []

Returns the index of an IndexationPayload.

data(): byte []

Returns the data of an IndexationPayload.

TransactionPayload

builder(): TransactionPayloadBuilder

Return a new TransactionPayloadBuilder to build a TransactionPayload.

essence(): Essence

Return the essence of a TransactionPayload.

unlockBlocks(): UnlockBlock []

Return unlock blocks of a TransactionPayload.

id(): TransactionId

Computes the identifier of a TransactionPayload.

TransactionPayloadBuilder

new(): TransactionPayloadBuilder

Creates a new TransactionPayloadBuilder.

withEssence(essence): TransactionPayloadBuilder

Adds an essence to a TransactionPayloadBuilder.

ParamTypeDescription
essenceEssenceindex bytes

withUnlockBlocks(unlock_blocks): TransactionPayloadBuilder

Adds unlock blocks to a TransactionPayloadBuilder.

ParamTypeDescription
unlock_blocksUnlockBlocksindex bytes

finish(): TransactionPayload

Finishes a TransactionPayloadBuilder into a TransactionPayload.

TreasuryPayload

new(input, output): TreasuryPayload

Creates a new TreasuryPayload.

ParamTypeDescription
inputTreasuryInputThe input information of this payload
outputTreasuryOutputthe output information of this payload

input(): TreasuryInput

Return the TreasuryInput

output(): TreasuryOutput

Returns the TreasuryOutput

MilestonePayload

essence(): MilestonePayloadEssence

Returns the essence of a MilestonePayload.

signatures(): MilestoneSignature[]

Returns the signatures of a MilestonePayload.

id(): long

Computes the identifier of a MilestonePayload.

validate(applicable_public_keys, min_threshold): void

Semantically validate a MilestonePayload. Throws an error if the milestone is considered invalid.

ParamTypeDescription
applicable_public_keysString[]hex encoded list of public keys used by the milestone
min_thresholdlongMinimum amount of signatures we need to verify on either side

ReceiptPayload

from(migrated_at, last, funds, transaction): void

Creates a new ReceiptPayload.

ParamTypeDescription
migrated_atlongThe milestone index at which the funds of a ReceiptPayload were migrated
lastbooleanwhether a ReceiptPayload is the final one for a given migrated at index.
fundsMigratedFundsEntry[]The funds which are migrated
transactionMessagePayloadThe TreasuryTransaction used to fund the funds. Must be a Treasury type

migratedAt(): long

Returns the milestone index at which the funds of a ReceiptPayload were migrated at in the legacy network.

last(): boolean

Returns whether a ReceiptPayload is the final one for a given migrated at index.

funds(): MigratedFundsEntry[]

The funds which were migrated with a ReceiptPayload.

amount(): long

Returns the sum of all MigratedFundsEntry items within a ReceiptPayload.

transaction(): TreasuryPayload

The TreasuryTransaction used to fund the funds of a ReceiptPayload.

Essence

getAsRegular(): Optional<RegularEssence>

Get this Essence as a RegularEssence type

RegularEssence

inputs(): Input[]

Gets the transaction inputs.

outputs(): Output[]

Gets the transaction outputs.

payload(): Optional<MessagePayload>

Gets the optional payload attached to this transaction

MilestonePayloadEssence

index(): long

Returns the index of a MilestonePayloadEssence.

timestamp(): long

Returns the timestamp of a MilestonePayloadEssence.

parents(): MessageId[]

Returns the parents of a MilestonePayloadEssence.

merkleProof(): byte[]

Returns the merkle proof of a MilestonePayloadEssence.

nextPowScore(): long

Returns the next proof of work score of a MilestonePayloadEssence.

nextPowScoreMilestone(): long

Returns the next proof of work index of a MilestonePayloadEssence.

publicKeys(): PublicKey[]

Returns the public keys of a MilestonePayloadEssence.

receipt(): Optional<ReceiptPayload>

Returns the optional receipt of a MilestonePayloadEssence.

hash(): byte[]

Hashes the MilestonePayloadEssence to be signed.

UnlockBocks

from(unlock_blocks): UnlockBocks

Constructs an UnlockBlocks type from an array of blocks

ParamTypeDescription
unlock_blocksUnlockBock[]The UnlockBocks to add

get(index) Optional<UnlockBlock>

Gets a clone of an UnlockBlock from UnlockBlocks. Returns the referenced unlock block if the requested unlock block was a reference.

ParamTypeDescription
indexlongThe UnlockBock to get

UnlockBock

kind(): UnlockBlockKind

Get the type of message this contains (used to select the correct getter). Possible types are ED25519 and REFERENCE.

getAsReference(): Optional<ReferenceUnlock>

Get this UnlockBock as a Reference Unlock type

getAsSignature(): Optional<SignatureUnlock>

Get this UnlockBock as a SignatureUnlock type

ReferenceUnlock

from(index): ReferenceUnlock

Creates a new ReferenceUnlock by index

ParamTypeDescription
indexintThe index this Reference is actually using

index(): long

Return the index of a ReferenceUnlock.

SignatureUnlock

new(public_key, signature): SignatureUnlock

Create a new SignatureUnlock

ParamTypeDescription
public_keybyte[]The public_key associated with the signature
signaturebyte[]The signature of this block

MigratedFundsEntry

from(hash, output): MigratedFundsEntry

Creates a new MigratedFundsEntry.

ParamTypeDescription
hashStringThe tail transaction hash of the entry
outputSignatureLockedSingleOutputThe output used in this entry

tailTransactionHash(): String

Returns the tail transaction hash of a MigratedFundsEntry.

output(): SignatureLockedSingleOutput

Returns the output of a MigratedFundsEntry.

SignatureLockedSingleOutput

Describes a deposit to a single address which is unlocked via a signature.

from(address, amount): SignatureLockedSingleOutput

Creates a new SignatureLockedSingleOutput.

ParamTypeDescription
addressAddressThe address of the output
amountlongThe amount of the output

address(): Address

Returns the address of a SignatureLockedSingleOutput.

amount(): long

Returns the amount of a SignatureLockedDustAllowanceOutput.