Getting Balances

Retrieving the current wallet balance is one of the most common operations.

Three methods are available:

WalletConnect: walletBalance.
walletInstance: getBalance().
RPC Provider: getBalance().

Remember

The balance does not update automatically. To retrieve the latest balance, use setTimeout() or setInterval() to call getBalance() periodically. An interval of approximately one minute is recommended for most use cases.

Getting balance from WalletConnect

Use the walletBalance property to retreive the balance. It returns null if disconnected, or a WalletBalance object when connected. The balance reflects the value in bitcoin recorded at connection time or from the most recent update triggered by one of the following:

Connecting to an account.
Switching wallets.
Switching accounts within the same wallet.
Changing networks.

Unlike the walletInstance and RPC provider methods, this property is not refreshed on demand.

The following code shows the definition of the WalletBalance interface:

WalletBalance interfacereact

export interface WalletBalance {
    total: number;
    confirmed: number;
    unconfirmed: number;
    csv75_total: number;
    csv75_unlocked: number;
    csv75_locked: number;
    csv1_total: number;
    csv1_unlocked: number;
    csv1_locked: number;
    p2wda_total_amount: number;
    p2wda_pending_amount: number;
    usd_value: string;
}

The following example demonstrates how to retrieve balance using WalletConnect:

Retrieving balance using WalletConnectreact

const { walletBalance } = useWalletConnect();

return (
    <div>Wallet Balance: { walletBalance?.total }</div>
);

Getting balance from walletInstance

Call the asynchronous getBalance() method on the walletInstance to fetch the current balance in bitcoin. It returns a Balance object.

The following code shows the definition of the Balance interface:

Balance interfacereact

export interface Balance {
    readonly confirmed: number;
    readonly unconfirmed: number;
    readonly total: number;

    readonly csv1_unlocked?: number;
    readonly csv1_locked?: number;
    readonly p2wda_total_amount?: number;
}

The following example demonstrates how to retrieve balance using walletInstance:

Retrieving balance using walletInstancereact

const { walletInstance } = useWalletConnect();
const [balance, setBalance] = useState<number|undefined>(undefined)

useEffect(() => {
    const updateBalance = async () => {
        const balance = walletInstance ? await walletInstance.getBalance() : undefined;
        setBalance(balance?.total);
    };
    void updateBalance();
}, [walletInstance, setBalance]);

Getting balance from RPC Provider

Call the asynchronous getBalance() function of the RPC provider to fetch the current balance. It returns the balance in satoshis as a bigint.

The following example demonstrates how to retrieve balance using RPC Provider:

Retrieving balance using RPC Providertypescript

const { walletAddress, provider } = useWalletConnect();
const [balance, setBalance] = useState<bigint|undefined>(undefined)

useEffect(() => {
    const updateBalance = async () => {
        const balance = walletAddress && await provider?.getBalance(walletAddress);
        setBalance(typeof balance == 'bigint' ? balance : undefined);
    };
    void updateBalance();
}, [provider, walletAddress, setBalance]);