useBalance

​

Asset ID Formats

• native: Fetches the XLM balance.
• CODE:ISSUER: Fetches a classic Stellar asset (e.g., USDC:GA5Z...).
• C…: Fetches the balance from a Soroban token contract.

​

Usage

import { useBalance } from "@sorokit/hooks";

function AccountBalance({ address }) {
  const { data, isLoading, error } = useBalance(address, "native");

  if (isLoading) return <span>Loading...</span>;
  if (error) return <span>Error: {error.message}</span>;

  return (
    <div>
      <p>Raw Amount: {data.raw.toString()}</p>
      <p>Display: {data.formatted} XLM</p>
    </div>
  );
}

​

Normalization Logic

• Decimal Handling: Classic assets are always treated as 7 decimals. Soroban assets are queried for their specific decimal count at runtime.
• BigInt Safety: The raw balance is always returned as a bigint to prevent precision loss during mathematical operations.
• Smart Caching: Uses TanStack Query to ensure multiple components requesting the same balance do not trigger redundant network calls.

​

Parameters

• address: The G... or C... address whose balance you want to check.
• assetId: The identifier for the asset.
• options: Standard query options, including enabled to defer the fetch.

​

Return Value

• raw: The balance in the smallest unit (stroops or bits) as a bigint.
• formatted: A human-readable string with the decimal point in the correct place.
• decimals: The number of decimal places used by the asset.