@helium/blockchain-api

TypeScript client and schemas for the Helium Blockchain API.

Installation

npm install @helium/blockchain-api
# or
yarn add @helium/blockchain-api

Quick Start

import { createClient } from "@helium/blockchain-api";

const client = createClient({
  url: "https://api.helium.com",
  transport: "rpc",
});

// Get token balances
const balances = await client.tokens.getBalances({
  walletAddress: "YOUR_WALLET_ADDRESS",
});

// Get hotspots
const hotspots = await client.hotspots.getHotspots({
  walletAddress: "YOUR_WALLET_ADDRESS",
  type: "iot",
  page: 1,
  limit: 20,
});

Authentication

For protected endpoints, provide a context factory:

const client = createClient({
  url: "https://api.helium.com",
  transport: "rpc",
  getContext: () => ({
    userId: currentUser.id,
    walletAddress: connectedWallet?.address ?? null,
    user: privyUser,
  }),
});

Or use an access token:

const client = createClient({
  url: "https://api.helium.com",
  accessToken: "your-access-token",
});

Schema Validation

All Zod schemas are exported for direct use:

import {
  GetBalancesInputSchema,
  TokenBalanceDataSchema,
} from "@helium/blockchain-api";

// Validate input
const input = GetBalancesInputSchema.parse({
  walletAddress: userInput,
});

Error Handling

Typed error definitions are available:

import { createClient, INSUFFICIENT_FUNDS, solanaErrors } from "@helium/blockchain-api";

try {
  await client.tokens.transfer({ ... });
} catch (error) {
  if (error.code === INSUFFICIENT_FUNDS.code) {
    console.error("Not enough SOL:", error.data);
  }
}

Testing with Mock Client

import { createMockClient } from "@helium/blockchain-api";

const mockClient = createMockClient({
  tokens: {
    getBalances: async () => ({
      totalBalanceUsd: 100,
      solBalance: 1,
      solBalanceUsd: 50,
      tokens: [],
    }),
  },
  health: {
    check: async () => ({ ok: true }),
  },
});

// Use in tests
const result = await mockClient.tokens.getBalances({ walletAddress: "..." });

API Reference

Routers

• health - Health check
• tokens - Token balances and transfers
• hotspots - Hotspot management and rewards
• swap - Token swaps via Jupiter
• transactions - Transaction submission and tracking
• welcomePacks - Welcome pack management
• fiat - Fiat offramp and bank accounts
• webhooks - Webhook handlers

License

Apache-2.0