Client API Reference

The Client API is low level client implementation based on RFC: REST Node API, it enables communications with the Node on the Tangle.

Endpoint Setting

struct iota_client_conf_t

Client endpoint configuration.

Public Members

char host[IOTA_ENDPOINT_MAX_LEN]

domain name or IP as string

uint16_t port

prot to connect

bool use_tls

Use TLS or not.

Error Response

struct res_err_t

Node API error response.

Public Members

char *code

an error code from node response

char *msg

a error message from node response

Find Message by Index

int find_message_by_index(iota_client_conf_t const *conf, char const index[], res_find_msg_t *res)

Find message IDs from a given indexation.

Parameters
  • conf[in] The client endpoint configuration

  • index[in] An indexation string

  • res[out] The response object

Returns

int 0 on success

Response

struct res_find_msg_t

API response of find message.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

find_msg_t *msg_ids

Message IDs if is_error is False.

Message IDs from find message API call

struct find_msg_t

Stores message IDs from the response object.

Public Members

uint32_t max_results

The MAX results.

uint32_t count

The number of message IDs in this response.

UT_array *msg_ids

message IDs

Get Balance

int get_balance(iota_client_conf_t const *ctx, char const addr[], res_balance_t *res)

Gets balance from an address.

Parameters
  • ctx[in] IOTA Client conf

  • addr[in] The address

  • res[out] A response object of balance info

Returns

int 0 on success

Response

struct res_balance_t

The response of get balance API call.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

get_balance_t *output_balance

a balance object if is_error is False

Balance object

struct get_balance_t

Stores address string and amount of balance.

Public Members

uint8_t address_type

0 = ED25519 address

uint64_t balance

amount of balance

char address[IOTA_ADDRESS_HEX_BYTES]

hex address string, ex: 7ED3D67FC7B619E72E588F51FEF2379E43E6E9A856635843B3F29AA3A3F1F006

Get Health

int get_health(iota_client_conf_t const *conf, bool *health)

Returns the health of the node.

A node considers itself healthy if its current confirmed milestone is at most two delta away from the latest known milestone, has at least one ongoing gossip stream and the latest known milestone is newer than 5 minutes.

Parameters
  • conf[in] The endpoint configuration

  • health[out] Is node health?

Returns

int 0 on success

Get Message by ID

int get_message_by_id(iota_client_conf_t const *conf, char const msg_id[], res_message_t *res)

Get the message data from a given message ID.

Parameters
  • conf[in] The client endpoint configuration

  • msg_id[in] A message ID to query

  • res[out] The message body of the given ID

Returns

int 0 on success

Response

struct res_message_t

The response of get message.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

message_t *msg

a message object if is_error is False

The Message Object

struct message_t

A message object.

Public Members

char net_id[32]

string of network ID hash

char nonce[32]

string of nonce

UT_array *parent_msg_ids

a list of parent IDs

payload_t type

payload type

void *payload

NULL if no payload.

Get Node Info

int get_node_info(iota_client_conf_t const *conf, res_node_info_t *res)

Gets info API.

Parameters
  • conf[in] The client endpoint configuration

  • res[out] A response object of node info

Returns

int 0 on success

Response

struct res_node_info_t

The response of get node info.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

get_node_info_t *output_node_info

node info if is_error is False

Node Info Object

struct get_node_info_t

The general information about the node.

Public Members

char name[32]

name of this node

char version[32]

version of this node

char network_id[32]

network ID of this node

char bech32hrp[16]

bech32 HRP, atoi for testnet and iota for mainnet

uint64_t min_pow_score

The minimum pow score of the network.

uint64_t latest_milestone_index

The latest known milestone index.

uint64_t confirmed_milestone_index

The current confirmed milestone’s index.

uint64_t pruning_milestone_index

The milestone index at which the last pruning commenced.

uint64_t latest_milestone_timestamp

The timestamp of the latest known milestone.

float msg_pre_sec

The current rate of new messages per second.

float referenced_msg_pre_sec

The current rate of referenced messages per second.

float referenced_rate

The ratio of referenced messages in relation to new messages of the last confirmed milestone.

UT_array *features

The features this node exposes.

bool is_healthy

Whether the node is healthy.

Get Output

int get_output(iota_client_conf_t const *conf, char const output_id[], res_output_t *res)

Get an output from a given output ID.

Parameters
  • conf[in] The client endpoint configuration

  • output_id[in] A hex string of the output ID

  • res[out] The response object from node

Returns

int 0 on success

Response

struct res_output_t

The response object of get_output.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

get_output_t output

an output object if is_error is False

Output object

struct get_output_t

An output object.

Public Members

char msg_id[64]

the message IDs that references the output

char tx_id[64]

the transaction ID

char addr[64]

the address in hex string

uint32_t output_type

the output type

uint32_t address_type

the address type

uint64_t amount

the amount of this output

uint16_t output_idx

the index of this output

bool is_spent

is spent or not

Get Outputs From Address

int get_outputs_from_address(iota_client_conf_t const *conf, char const addr[], res_outputs_address_t *res)

Gets output IDs from a given address.

Parameters
  • conf[in] The client endpoint configuration

  • addr[in] An address in hex string format

  • res[out] A response object

Returns

int 0 on successful

Response

struct res_outputs_address_t

The response of get outputs from address.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

get_outputs_address_t *output_ids

an output object if is_error is False

Address Outputs Object

struct get_outputs_address_t

An output object.

Public Members

char address[IOTA_ADDRESS_HEX_BYTES + 1]

hex-encoded string with null terminator.

uint32_t max_results

The number of results it can return at most.

uint32_t count

The actual number of found results.

UT_array *outputs

output IDs

Get Tips

int get_tips(iota_client_conf_t const *conf, res_tips_t *res)

Gets tips.

Returns two non-lazy tips. In case the node can only provide one tip, tip1 and tip2 are identical.

Parameters
  • conf[in] The client endpoint configuration

  • res[out] A response object of tips object

Returns

int 0 on success

Response

struct res_tips_t

The response of get tips.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

get_tips_t *tips

list of tips if is_error is False

Send Message

int send_indexation_msg(iota_client_conf_t const *const conf, char const index[], char const data[], res_send_message_t *res)

Send out an indexation message.

Parameters
  • conf[in] The client endpoint configuration

  • index[in] The string of index

  • data[in] The string of data

  • res[out] The response object

Returns

int 0 on success

int send_core_message(iota_client_conf_t const *const conf, core_message_t *msg, res_send_message_t *res)

Send message thought core message object.

Parameters
  • conf[in] The client endpoint configuration

  • msg[in] A core message

  • res[out] An error or message ID

Returns

int 0 on success

Response

struct res_send_message_t

The response of send message.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

char msg_id[IOTA_MESSAGE_ID_HEX_BYTES + 1]

a message IDs string if is_error is False

Get Message Metadata

int get_message_metadata(iota_client_conf_t const *ctx, char const msg_id[], res_msg_meta_t *res)

Gets message metadata from a given message ID.

Parameters
  • ctx[in] IOTA Client conf

  • msg_id[in] A message ID string for query

  • res[out] A message metadata response

Returns

int 0 on success

Response

struct res_msg_meta_t

The response of get message metadata API call.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

msg_meta_t *meta

a response object if is_error is False

struct msg_meta_t

Stores the message metadata object.

Public Members

char msg_id[IOTA_MESSAGE_ID_HEX_BYTES + 1]

the hex encoded message ID string

UT_array *parents

the parent message IDs

char inclusion_state[32]

the ledger inclusion state of the transaction payload, one of noTransaction, conflicting, included

bool is_solid

whether the message is solid

int8_t should_promote

whether the message should be promoted, optional

int8_t should_reattach

whether the message should be reattached, optional

uint64_t referenced_milestone

The milestone index that references this message, optional.

uint64_t milestone_idx

If this message represents a milestone this is the milestone index, optional.

Get Message Children

int get_message_children(iota_client_conf_t const *ctx, char const msg_id[], res_msg_children_t *res)

Gets message children from a given message ID.

Parameters
  • ctx[in] IOTA Client conf

  • msg_id[in] A message ID string for query

  • res[out] A message children response

Returns

int 0 on success

Response

struct res_msg_children_t

The response of get message children API call.

Public Members

bool is_error

True if got an error from the node.

res_err_t *error

Error message if is_error is True.

msg_children_t *data

a response object if is_error is False

struct msg_children_t

The message children object.

Public Members

uint32_t max_results

The maximum count of results that are returned by the node.

uint32_t count

The actual count of results that are returned.

char msg_id[IOTA_MESSAGE_ID_HEX_BYTES + 1]

the hex encoded message ID string

UT_array *children

the hex encoded message IDs of the children of this message.