Skip to main content

Function.useKeybanAccountBalance

function useKeybanAccountBalance(account: KeybanAccount): ApiResult<string>

Hook to retrieve and subscribe to the balance of a Keyban account.

This React hook allows you to fetch the native balance of a Keyban account and automatically updates when the balance changes. It returns an ApiResult tuple containing the balance or an error if one occurred during retrieval.

Parameters​

ParameterTypeDescription
accountKeybanAccountThe KeybanAccount object representing the user account.

Returns​

ApiResult<string>

An ApiResult<string> tuple containing:

  • First element (balance): A string representing the account's native token balance in the smallest unit (e.g., wei for Ethereum). This value automatically updates when the balance changes.
  • Second element (error): An Error object if an error occurred during retrieval, or null if the balance was fetched successfully.

Return Structure:

[balance: string, error: Error | null]
  • balance: The current balance of the Keyban account as a string.
  • error: An Error object if there was an error fetching the balance, otherwise null.

Example​

import { useKeybanAccount, useKeybanAccountBalance } from "@keyban/sdk-react";

const AccountBalance: React.FC = () => {
  const [account, accountError] = useKeybanAccount();
  if (accountError) throw accountError;

  const [balance, balanceError] = useKeybanAccountBalance(account);
  if (balanceError) throw balanceError;

  return <div>Balance: {balance}</div>;
};

Remarks​

  • Balance Format: The balance is returned as a string representing the amount in the smallest denomination (e.g., wei). You may need to format it to a human-readable format (e.g., Ether) using utility functions.
  • Real-Time Updates: The hook subscribes to balance changes, so your component will re-render automatically when the balance updates.
  • Error Handling: Always check the error element to handle any issues that might occur during balance retrieval.
  • Ensure that your component is wrapped within a KeybanProvider to have access to the Keyban client context.

Throws​

Will throw an error if used outside of a KeybanProvider or if there's an issue retrieving the balance.

See​