Skip to main content
The reads on this page never touch a transaction. Use them whenever your app needs to display balances, browse the catalog, or quote a fiat amount in USD before charging the user.

​
Token balances

getTokenBalance returns the on-chain balance of an ERC-20 token for a wallet. Look the wallet up by your own user identifier, or by the wallet’s public address. 
import { Chain, ChainToken } from "@chipi-stack/backend";

// By externalUserId (the identifier you passed to createWallet)
const usdc = await sdk.getTokenBalance({
  externalUserId: "user-42",
  chainToken: ChainToken.USDC,
  chain: Chain.STARKNET,
});

// Or by raw public key
const eth = await sdk.getTokenBalance({
  walletPublicKey: "0x...",
  chainToken: ChainToken.ETH,
  chain: Chain.STARKNET,
});
The response shape is: 
{
  chain: Chain;             // "STARKNET"
  chainToken: ChainToken;   // "USDC" | "ETH" | "STRK" | ...
  chainTokenAddress: string;
  decimals: number;         // 6 for USDC, 18 for ETH/STRK
  balance: string;          // raw on-chain units, e.g. "1234567" = 1.234567 USDC
}
balance is a string of raw token units (not human-formatted). It’s a string because raw balances exceed JavaScript’s safe-integer range — a single ETH (10^18 wei) is already past Number.MAX_SAFE_INTEGER (2^53 − 1). Parse with BigInt; only convert to Number at display time. 
// For display (acceptable for typical balances; loses precision past ~9 PB of USDC)
const display = Number(BigInt(usdc.balance)) / 10 ** usdc.decimals;
console.log(`USDC balance: ${display}`);

// For ledgers / arithmetic that must stay precise — keep it as BigInt
const balance = BigInt(usdc.balance);
const oneUsdc = 10n ** BigInt(usdc.decimals);
if (balance >= oneUsdc) {
  console.log("User has at least 1 USDC");
}

​
Browse the SKU catalog

getSkuList returns paginated SKUs for the Bill Payments service. See the Bills guide for filtering by category, chipiCategory, carrierName, and provider. 
const result = await sdk.getSkuList({ page: 1, limit: 5 });

console.log(result.total);         // total matching SKUs
console.log(result.data[0].name);  // first SKU's display name
getSku fetches a single SKU by id: 
const sku = await sdk.getSku("sku-MI200");
console.log(sku.name, sku.fixedAmount, sku.currency);

​
Fiat → USD conversion

getUsdAmount converts a local-currency amount to USD using Chipi’s exchange rate. Useful for showing the user “you’ll be charged ~XUSDCforaX USDC for a 200 MXN bill” before they confirm. 
import { Currency } from "@chipi-stack/backend";

const usd = await sdk.getUsdAmount(200, Currency.MXN);
console.log(`200 MXN ≈ $${usd.toFixed(2)} USD`);
Currency values today: "MXN" and "USD".

​
Putting it together

A common dashboard pattern: show the user their USDC balance and quote the cost of a recharge before they tap “buy”. 
import { Chain, ChainToken, Currency } from "@chipi-stack/backend";

async function quotePurchase(sdk, externalUserId, skuId) {
  const [balance, sku] = await Promise.all([
    sdk.getTokenBalance({
      externalUserId,
      chainToken: ChainToken.USDC,
      chain: Chain.STARKNET,
    }),
    sdk.getSku(skuId),
  ]);

  const usdQuote = await sdk.getUsdAmount(sku.fixedAmount, sku.currency as Currency);

  const balanceHuman = Number(BigInt(balance.balance)) / 10 ** balance.decimals;

  return {
    balance: balanceHuman,                              // USDC the user holds
    cost: usdQuote,                                     // approx USDC needed
    canAfford: balanceHuman >= usdQuote,
  };
}
✅ Verified against the live API on 2026-05-11.