Query reward totals for a period

When you only need aggregate totals for a time window, call GET /v0/gateways/{address}/mobile/rewards/sum without a bucket. The example below aligns min_time to midnight UTC 30 days ago, leaves max_time unset so the API defaults to “now,” and prints the combined, PoC, and data transfer amounts for the window.

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-sum-window.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-sum-window.js

   Or pass the address inline:

   HELIUMGEEK_API_KEY="your-api-key" node mobile-sum-window.js <gateway-address>

Script

mobile-sum-window.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();
const WINDOW_DAYS = 30;

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() - WINDOW_DAYS);

  const response = await fetch(
    buildUrl(`/gateways/${encodeURIComponent(GATEWAY_ADDRESS)}/mobile/rewards/sum`, {
      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;
  }

  console.log(`30-day reward totals for ${GATEWAY_ADDRESS}`);
  for (const entry of sums) {
    const unitLabel = entry.unit?.toUpperCase?.() ?? 'MOBILE';
    const pocShare =
      entry.sum > 0
        ? ((Number(entry.pocSum) / Number(entry.sum)) * 100).toFixed(2)
        : '0.00';
    console.log(
      `${unitLabel}: ${formatTokens(entry.tokenSum)} tokens, 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);
});