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

# useGetTokenBalance

> Fetches the on-chain token balance for a wallet address.

## Usage

```typescript theme={null}
const {
  data,
  isLoading,
  isError,
  isSuccess,
  error,
  refetch,
  fetchTokenBalance,
} = useGetTokenBalance({
  params: {
    chainToken: ChainToken.USDC,
    chain: Chain.STARKNET,
    walletPublicKey: "0x...",
  },
  getBearerToken: getToken,
});
```

### Input Parameters

| Parameter                | Type                    | Required | Description                                         |
| ------------------------ | ----------------------- | -------- | --------------------------------------------------- |
| `params.chainToken`      | `ChainToken`            | Yes      | Token identifier. Use `ChainToken.USDC`             |
| `params.chain`           | `Chain`                 | Yes      | Blockchain network. Use `Chain.STARKNET`            |
| `params.walletPublicKey` | `string`                | No       | Wallet address to check balance for                 |
| `params.externalUserId`  | `string`                | No       | External user ID (alternative to `walletPublicKey`) |
| `getBearerToken`         | `() => Promise<string>` | Yes      | Function returning the auth token                   |
| `queryOptions`           | `UseQueryOptions`       | No       | React Query options (e.g. `staleTime`, `enabled`)   |

### Return Value

| Property            | Type                                          | Description                                   |
| ------------------- | --------------------------------------------- | --------------------------------------------- |
| `data`              | `GetTokenBalanceResponse \| undefined`        | Balance data                                  |
| `isLoading`         | `boolean`                                     | True while fetching                           |
| `isError`           | `boolean`                                     | True if an error occurred                     |
| `isSuccess`         | `boolean`                                     | True if the query succeeded                   |
| `error`             | `Error \| null`                               | Error when `isError` is true                  |
| `refetch`           | `() => void`                                  | Re-run the query                              |
| `fetchTokenBalance` | `(input) => Promise<GetTokenBalanceResponse>` | Imperatively fetch balance with custom params |

## Example Implementation

```typescript theme={null}
import { useGetTokenBalance, Chain, ChainToken } from "@chipi-stack/chipi-react";
import { useAuth } from "@clerk/nextjs";

export function TokenBalance({ walletPublicKey }: { walletPublicKey: string }) {
  const { getToken } = useAuth();

  const { data, isLoading, error } = useGetTokenBalance({
    params: {
      chainToken: ChainToken.USDC,
      chain: Chain.STARKNET,
      walletPublicKey,
    },
    getBearerToken: getToken,
  });

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

  return (
    <div>
      <p>Balance: {data?.balance} USDC</p>
    </div>
  );
}
```

<Note>
  Either `walletPublicKey` or `externalUserId` must be provided to identify the
  wallet.
</Note>