Quick Start

Read a wallet balance from ESP32

Learn how to interact with the IoTeX blockchain from Arduino-based devices.

Post Header Image


Updated: 08/16/2022


Edit on Github


In this geting started guide we will show how you can interact with the IoTeX Blockchain from an embedded device.

Final result

At the end of this guide you will be able to read the IOTX balance of an IoTeX wallet address from an ESP32 board.

Core components

We will use the following core concepts and componnets:

Selecting the board

We will use a development board based on the ESP-WROVER-32 chip. If you have never used an ESP32 board with Arduino before, please see their doc on how to install ESP32 boards in the Arduino IDE.

  1. open the Tools->Board->ESP32 Arduino menu and select ESP32 Wrover Module.
  2. open the Tools->Portmenu and select the serial port of your board (it should look similar to /dev/cu.SLAB_USBtoUART)

Installing the IoTeX SDK for Arduino

In the Arduino IDE, create and save a new sketch, then open the Tools->Manage Libraries... menu item. In the Library Manager dialog, search for IoTeX-blockchain-client and click install.

The full Sketch

Copy-paste the following sketch in the IDE (edit your WiFi network configuration), hit the upload button in the IDE and wait for the software to be flashed into the board (notice that some boards require you to press the one of the available buttons sometimes called boot to allow it to be flashed the software). Once the flash is complete, select Tools->Serial monitorfrom the menu and configure the monitor speed on 115000 baud to see to output. The onboard led should get activated if the address you checked has some balance, or it will stay off if the balance is 0.

#include <Arduino.h>
#include <WiFi.h>
#include "IoTeX-blockchain-client.h"
#define ONBOARD_LED  2
constexpr const char ip[] = "gateway.iotexlab.io";
constexpr const char baseUrl[] = "iotexapi.APIService";
constexpr const int port = 10000;
// Set your Wifi Network name
constexpr const char wifiSsid[] = "<YOUR WIFI NETWORK NAME>";
// Set your WiFi password
constexpr const char wifiPass[] = "<YOUR WIFI PASSWORD>";
// Set the wallet address to check
const char accountStr[] = "io1xkx7y9ygsa3dlmvzzyvv8zm6hd6rmskh4dawyu";
// Create the IoTeX client connection
Connection<Api> connection(ip, port, baseUrl);
void initWiFi()
    WiFi.begin(wifiSsid, wifiPass);
    Serial.print(F("Connecting to WiFi .."));
    while (WiFi.status() != WL_CONNECTED) {
    Serial.print(F("\r\nConnected. IP: "));
void setup() {
    // Connect to the wifi network
    // Configure the LED pin
void loop() {
    // Query the account metadata
    AccountMeta accountMeta;
    ResultCode result = connection.api.wallets.getAccount(accountStr, accountMeta);
    // Print the result
    Serial.print("Result: ");
    // If the query suceeded, print the account metadata
    if (result == ResultCode::SUCCESS)
        Serial.print("Balance: ");
        Serial.print(F("Nonce: "));
        Serial.print(F("PendingNonce: "));
        Serial.print(F("NumActions: "));
        Serial.print(F("IsContract: "));
        Serial.println(accountMeta.isContract ? "\"true\"" : "\"false\"");
    // Enable the onboard led if the balance is > 0.01 IOTX)
    Bignum b = Bignum(accountMeta.balance, NumericBase::Base10);
    Bignum zero = Bignum("0", NumericBase::Base10);
    if (b == zero)
      digitalWrite(ONBOARD_LED, LOW);
    else digitalWrite(ONBOARD_LED, HIGH);
    Serial.println("Program finished");
    while (true) { delay(1000); }

Notes on the IoTeX Gateway

The embedded SDK is based on the Native IoTeX API, which is exposed by any blockchain node through the gRPC protocol. Because implementing a gRPC client on embedded boards is not trivial, the IoTeX library requires a JSON over HTTPs translation of the blockchain API. You can either configure your own IoTeX Blockchain Gateway node using a gRPC-JSON transcoder by [following this tutorial], or you can use a community contributed endpoint for development purposes, like in the code above.


IoTeX Docs

IoTeX Developerslogo