RESTful API Reference#

The RESTful 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#

port 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, bool is_bech32, char const addr[], res_balance_t *res)#

Gets balance from an address.

Parameters

  • ctx – [in] IOTA Client conf

  • is_bech32 – [in] the address type, true for bech32, false for ed25519

  • 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 type, amount of balance, address string, dust allowed status and ledger index.

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

bool dust_allowed#

Dust allowance output to the transaction allowed or not.

uint64_t ledger_idx#

Ledger Index.

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

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 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[65]#

the message IDs that references the output

char tx_id[65]#

the transaction ID

char addr[65]#

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

uint64_t ledger_idx#

The ledger index at which this balance was queried at.

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, bool is_bech32, char const addr[], res_outputs_address_t *res)#

Gets output IDs from a given address.

Parameters

  • conf – [in] The client endpoint configuration

  • is_bech32 – [in] the address type, true for bech32, false for ed25519

  • 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

uint64_t ledger_idx#

The ledger index at which the output was queried at.

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