> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorokit.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# useBalance

> Fetch and normalize balances across Native, Classic, and Soroban assets.

The `useBalance` hook provides a single interface to fetch the balance of any asset on the Stellar network. It automatically detects the asset type and returns a normalized object, so your components do not need to handle different decimal logic for different asset classes.

#### Asset ID Formats

You can pass three types of identifiers to the `assetId` parameter:

* 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

```tsx theme={null}
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

The hook performs the following background tasks:

* **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

The hook returns a query result object where `data` contains:

* `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.