Query daily rewards

This example calls GET /v0/gateways/{address}/mobile/rewards/sum with a daily bucket and prints a line per epoch/day. The script aligns the min_time parameter to midnight UTC 30 days ago so the window always starts at a clean boundary, and relies on the API's default max_time (current time).

tip

min_time is inclusive. Records returned by the endpoint start at the timestamp you provide. Review the time-series guide for more detail on window boundaries.

tip

Rewards are recorded for the day the Oracle closes the epoch. When you filter with min_time/max_time, HeliumGeek compares those bounds against each record's endPeriod, not the startPeriod. That way the entire reward is attributed to the date it was issued.

Prerequisites

• Node.js 18 or newer (ships with the Fetch API).
• An API key exported as HELIUMGEEK_API_KEY.
• A gateway address provided either as the GATEWAY_ADDRESS environment variable or as the first CLI argument.

Run the example

1. Download mobile-daily-trend.js and save it locally.

2. Export the environment variables and run:

   export HELIUMGEEK_API_KEY="your-api-key"
   export GATEWAY_ADDRESS="your-gateway-address"
   node mobile-daily-trend.js

   Or pass the address inline:

   HELIUMGEEK_API_KEY="your-api-key" node mobile-daily-trend.js <gateway-address>

Script

mobile-daily-trend.js

#!/usr/bin/env node

const BASE_URL = (process.env.HELIUMGEEK_API_BASE_URL ?? 'https://api.heliumgeek.com/v0').replace(/\/$/, '');
const API_KEY = process.env.HELIUMGEEK_API_KEY;
const GATEWAY_ADDRESS =
  (process.argv[2] ?? process.env.GATEWAY_ADDRESS ?? '').trim();

if (!API_KEY) {
  console.error('Set HELIUMGEEK_API_KEY before running this script.');
  process.exit(1);
}

if (!GATEWAY_ADDRESS) {
  console.error(
    'Provide the gateway address as an argument or set GATEWAY_ADDRESS.'
  );
  process.exit(1);
}

const tokenFormatter = new Intl.NumberFormat('en-US', {
  minimumFractionDigits: 4,
  maximumFractionDigits: 4,
});

async function main() {
  const now = new Date();
  const minDate = startOfUtcDay(now);
  minDate.setUTCDate(minDate.getUTCDate() - 30);

  const response = await fetch(
    buildUrl(`/gateways/${encodeURIComponent(GATEWAY_ADDRESS)}/mobile/rewards/sum`, {
      bucket: 'day',
      min_time: minDate.toISOString(),
    }),
    {
      headers: {
        'x-api-key': API_KEY,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status} ${response.statusText}`);
  }

  const sums = (await response.json()) ?? [];

  if (sums.length === 0) {
    console.log(
      `Gateway ${GATEWAY_ADDRESS} earned no MOBILE rewards between ${minDate.toISOString()} and ${now.toISOString()}.`
    );
    return;
  }

  sums.sort((a, b) => a.startTimestamp - b.startTimestamp);

  console.log(`Daily rewards for ${GATEWAY_ADDRESS}`);
  for (const entry of sums) {
    const label = new Date(entry.startTimestamp * 1000)
      .toISOString()
      .slice(0, 10);
    const unitLabel = entry.unit?.toUpperCase?.() ?? 'MOBILE';
    const pocShare =
      entry.sum > 0
        ? ((Number(entry.pocSum) / Number(entry.sum)) * 100).toFixed(2)
        : '0.00';
    console.log(
      `${label}  total: ${formatTokens(entry.tokenSum)} ${unitLabel}  PoC share: ${pocShare}%`
    );
  }
}

function buildUrl(path, query = {}) {
  const url = new URL(path.replace(/^\//, ''), `${BASE_URL}/`);
  Object.entries(query).forEach(([key, value]) => {
    if (value !== undefined && value !== null && value !== '') {
      url.searchParams.set(key, String(value));
    }
  });
  return url.toString();
}

function startOfUtcDay(referenceDate) {
  return new Date(
    Date.UTC(
      referenceDate.getUTCFullYear(),
      referenceDate.getUTCMonth(),
      referenceDate.getUTCDate()
    )
  );
}

function formatTokens(tokens) {
  return tokenFormatter.format(Number(tokens));
}

main().catch((error) => {
  console.error(error.message);
  process.exit(1);
});