useCapxulAccountBalance

Query hook for the signed-in user's personal Account — balance and available balance.

Reads the signed-in user's personal Account — the logical pot of money with its balance and available balance.

Import

import { useCapxulAccountBalance } from "@capxul/sdk-react";

Usage

"use client";

import { useCapxulAccountBalance } from "@capxul/sdk-react";

function BalanceCard() {
  const balance = useCapxulAccountBalance();

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

  const account = balance.data;
  return (
    <div>
      <p>
        {account.balance.value} {account.balance.currency}
      </p>
      <p>
        Available: {account.available.value} {account.available.currency}
      </p>
    </div>
  );
}

Parameters

options

UseCapxulAccountBalanceOptions | undefined

Prop

Type

Pass enabled: false to skip the balance read until your UI is ready for it — for example, while the account lane is still provisioning:

const lifecycle = useCapxulAccountLifecycle();
const balance = useCapxulAccountBalance({
  enabled: lifecycle.data?.phase === "ready",
});

Return type

import { type UseCapxulAccountBalanceReturn } from "@capxul/sdk-react";
// UseQueryResult<Account, CapxulError>

data is an Account: the opaque account id, its balance, and its available balance (both are Money — a currency, a decimal value, and a precision; never a raw token integer).

The hook returns TanStack Query's UseQueryResult. The most-used fields:

Field	Description
`data`	The query data (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last fetch failed, otherwise `null`.
`status`	`'pending'` \| `'error'` \| `'success'`.
`isLoading`	`true` during the first fetch (no data yet).
`isFetching`	`true` whenever a fetch is in flight, including background refetches.
`refetch`	Manually refetch the query.

Capxul query hooks stay pending until the provider finishes bootstrapping — you do not need to gate them on useCapxul() yourself. The full field list is in the TanStack Query useQuery reference; see also the TanStack Query integration guide.

Query key

["capxul", "accountBalance"] — invalidated automatically by money mutations (useCapxulPay, useCapxulTransfer, …) and cleared on sign-out.

Client method

This hook wraps client.accounts.read() on the core SDK.