Device Status API

Addresses to burn into firmware

These are the factory defaults. All four live under wellbianlabs.io so the backend can be swapped without touching shipped units. Do not burn a vendor hostname.

Overview

The meter's serial and upload token are written into device settings via BLE provisioning at setup, not compiled into the firmware. With those two values already in settings, the meter can fetch the owner's reward balance and whether the server is receiving data, and show them on screen - no factory reflash per unit.

Quick start

curl "https://api.wellbianlabs.io/v1/device?serial=IARAW2600126&k=<TOKEN>&format=text"

OK 1
NET 1
LASTMIN 1
TODAY 902
SERVER Connected
WITHDRAWABLE 4.878074
CLAIMABLE 4.878074
PENDING 4.868819
CLAIMED 4.887346
TOTAL 14.634240
UNIT WLBN
LINKED 1
ACCRUING 1
NEXTSET 522
HOLDH 24

WITHDRAWABLE  4.878074 WLBN
SERVER        Connected

k is the upload token written into device settings via BLE provisioning at setup - not a value compiled into the firmware image. Legacy v6.04 units instead carry a shared token baked into the AT*ICT*HTTPGET=…/functions/v1/iot/%s?k= string; that path is described separately above. Either way, the end user never sees or enters it.

Auth · request parameters

Response · text format

One KEY SPACE VALUE per line, readable with strtok/sscanf without a JSON parser. Line order is not guaranteed - look up by key. New lines may be added, so ignore keys you do not know.

// ACCRUING 1 · TOTAL 0 · NEXTSET 262
Accruing   1,155 min
Settles in 4h 22m

// After settlement - ACCRUING 1 · TOTAL 4.887346
4.89 WLBN
Connected

Response · JSON format

Omit format to get JSON. Use it on a roomier MCU or in an app.

{
  "ok": true,
  "serial": "IARAW2600126",
  "linked": true,
  "display": { "server": "Connected", "withdrawable": 4.878074, "unit": "WLBN" },
  "reward": {
    "currency": "WLBN",
    "claimable": 4.878074,
    "pending": 4.868819,
    "claimed": 4.887346,
    "total": 14.634240,
    "holdHours": 24
  },
  "network": { "online": true, "lastSeenMin": 1, "todayCount": 902 },
  "accruing": true,
  "nextSettlementInMin": 522,
  "serverTime": "2026-08-28T…Z"
}

Errors

With format=text errors look like this:

OK 0
ERROR BAD_TOKEN

Outdoor air quality

Returns the outdoor air for the unit's neighbourhood. Shown next to the indoor readings, it lets the user decide whether to ventilate.

curl "https://api.wellbianlabs.io/v1/outdoor?serial=IARAW2600126&format=text"

OK 1
PM10 40.3
PM25 28.7
GRADE 2
TEMP 29.5
HUMI 68
AREA Guro 3-dong
AGE 8

Outdoor errors

Test token

A demo token works without an account or a registered unit. It returns fixed sample values without touching the database, so you can build the display, the parser, and the error handling before any hardware is enrolled.

demo

Pick the screen state with serial - no need to wait for a real outage or an unregistered unit.

curl "https://api.wellbianlabs.io/v1/device?serial=DEMO-OFFLINE&k=demo&format=text"

Outdoor takes the same demo token.

curl "https://api.wellbianlabs.io/v1/outdoor?serial=X&k=demo&format=text"

Example · ESP32 / Arduino

// Read from settings (NVS) - written over BLE at provisioning, not compiled in
String serial = "IARAW2600126";   // written via BLE SERIAL command
String token  = "...";             // written via BLE TOKEN command

struct Status {
  bool   ok       = false;
  int    net      = 0;    // 1 = receiving
  int    linked   = 0;    // 0 = no owner yet (not redeemed)
  String server;          // "Connected" / "Disconnected"
  double withdrawable = 0;
  int    lastMin  = -1;
  char   err[24]  = "";
};

bool fetchStatus(Status &st) {
  HTTPClient http;
  String url = "https://api.wellbianlabs.io/v1/device?format=text&serial=" + serial
             + "&k=" + token;

  http.begin(url);                          // see Security below for cert handling
  http.setTimeout(8000);

  int code = http.GET();
  if (code != 200 && code != 401 && code != 404) { http.end(); return false; }

  String body = http.getString();
  http.end();

  // One "KEY VALUE" per line. Order is not guaranteed - match by key.
  int pos = 0;
  while (pos < body.length()) {
    int nl = body.indexOf('\n', pos);
    if (nl < 0) nl = body.length();
    String line = body.substring(pos, nl);
    pos = nl + 1;

    int sp = line.indexOf(' ');
    if (sp < 0) continue;
    String k = line.substring(0, sp);
    String v = line.substring(sp + 1);

    if      (k == "OK")           st.ok = (v.toInt() == 1);
    else if (k == "NET")          st.net = v.toInt();
    else if (k == "LINKED")       st.linked = v.toInt();
    else if (k == "SERVER")       st.server = v;
    else if (k == "WITHDRAWABLE") st.withdrawable = v.toDouble();
    else if (k == "LASTMIN")      st.lastMin = v.toInt();
    else if (k == "ERROR")        v.toCharArray(st.err, sizeof(st.err));
    // unknown keys are ignored on purpose - new ones may appear
  }
  return true;
}

Implementation notes

Polling

Every 5 minutes is plenty for reward status; rewards only change once a day. Outdoor refreshes on a 10-minute cycle, so 5–10 minutes there too. Faster polling returns the same values and only burns power.

Handling failures

On a network failure, keep showing the last good values and mark them stale rather than blanking the screen. BAD_TOKEN will not fix itself - stop retrying and show a settings error. For 5xx, back off and retry.

Security

• These paths are read-only - a leaked token cannot withdraw or transfer anything.
• No wallet address is returned. Only amounts and connection state.
• HTTPS is recommended where the firmware's TLS stack supports it. Units that cannot hold a certificate store can use the fallback connection path provided for them - every endpoint here is read-only, so the exposure is limited to amounts and connection state either way. When TLS is used, sync the clock over NTP (certificate validity depends on it).
• Never print the token to the display or the serial log.

For the end user

There is nothing for them to do. Once the unit is redeemed and WiFi is connected, the reward appears on screen.

1. Register at wellbian.io/redeem with the enclosed redeem code and the unit serial
2. Accept the licence NFT in the wallet (signature)
3. Connect the unit to WiFi → readings start accruing → the reward shows on the device

Before redemption the API returns LINKED 0, so show a "Not registered" prompt to nudge the user through registration.