Tokens

Every amount the SDK takes or returns is a bigint in the token's smallest unit. This page shows where a token's decimals come from, how to format and parse amounts, and how to give tokens names and logos.

The running example is USDC, which has 6 decimals. 25 USDC is 25_000_000n.

The tokens a cluster listsCopy Anchor Link

sdk.mints lists the tokens the mainnet preset names, 57 of them. Each NimbusMint has:

• mint, the token's mint address.
• tokenProgram, the program that owns the mint: SPL Token or Token-2022.
• decimals, how many decimal places its smallest unit has.

for (const { mint, decimals, tokenProgram } of sdk.mints) {
  console.log(mint, decimals, tokenProgram);
}

Offer only these tokens in your token picker. The SDK names a token in a balance, a held payment or a history item only when it is in this list.

Format an amountCopy Anchor Link

Divide by the token's decimals to show an amount. This formatter keeps the full precision of a bigint, drops trailing zeros and groups thousands:

function formatAmount(value: bigint, decimals: number): string {
  const negative = value < 0n;
  const digits = (negative ? -value : value)
    .toString()
    .padStart(decimals + 1, "0");
  const whole = digits.slice(0, digits.length - decimals);
  const fraction = digits.slice(digits.length - decimals).replace(/0+$/u, "");
  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/gu, ",");
  const sign = negative ? "-" : "";
  return fraction === "" ? `${sign}${grouped}` : `${sign}${grouped}.${fraction}`;
}

formatAmount(25_000_000n, 6); // "25"
formatAmount(1_234_567_890n, 6); // "1,234.56789"

Avoid Number for amounts. A large balance in a token with 9 decimals loses precision as a Number.

Parse what the user typesCopy Anchor Link

Turn what Alice types into the smallest unit the same way, in reverse:

function parseAmount(text: string, decimals: number): bigint | undefined {
  const match = /^(\d+)(?:\.(\d*))?$/u.exec(text.trim().replace(/,/gu, ""));
  if (match?.[1] === undefined) return undefined;
  const fraction = match[2] ?? "";
  if (fraction.length > decimals) return undefined;
  return BigInt(match[1] + fraction.padEnd(decimals, "0"));
}

parseAmount("25", 6); // 25_000_000n
parseAmount("12.5", 6); // 12_500_000n

It refuses more decimal places than the token has. Tell the user why, as the example app does.

Names and logosCopy Anchor Link

The SDK carries no token names, symbols or logos. Take them from a token list you trust.

The example app writes its list ahead of time with a script, apps/nimbus-example/scripts/fetch-tokens.ts, which it runs as pnpm tokens:

Serving logos from your own site matters. A cross-origin isolated page shows an image from another site only when that site allows it, and many logo hosts do not.

For a token the list lacks, show its shortened address, and draw its initials in place of a logo.

Unsupported tokensCopy Anchor Link

A deposit of an address that is not a token mint throws a NimbusSolanaFlowError with reason mint-unsupported. That covers an address with no account, an account another program owns, and data that is not a mint.

A Token-2022 token whose transfer fee changes at the next epoch throws fee-changing instead. Try again once the epoch turns.

NextCopy Anchor Link