useCapxulAccountBalance

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

Reads the signed-in user's personal Account — the owned money container 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>Could not load the balance ({balance.error.code}).</p>;

  const account = balance.data;
  if (account.balance === null || account.available === null) {
    return <p>Valuation unavailable.</p>;
  }
  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 identity = useCapxulIdentity();
const balance = useCapxulAccountBalance({
  enabled: identity.phase === "authenticated" && identity.account.at === "claimed",
});

Return type

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

data is an Account. balances keeps each exact asset quantity. balance and available are fiat valuations. Either value is null when any position has no supplied rate.

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 and cleared on sign-out.

Client method

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