> ## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.