useCapxulAccountFund

Mutation hook for faucet-funding the personal Account in test environments — a developer tool, not customer-facing funding.

Funds the signed-in user's personal Account from the test faucet. This is a developer/testing surface for proving balance and money flows in test environments — it is not how customers add money, and it must not ship in a production frontend. See Capability status for what customer-facing funding exists today.

Import

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

Usage

"use client";

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

function DevFundButton() {
  const fund = useCapxulAccountFund();

  // Gate on your own dev/test flag — never render this in production.
  if (process.env.NEXT_PUBLIC_APP_ENV !== "test") return null;

  return (
    <button
      type="button"
      disabled={fund.isPending}
      onClick={() =>
        fund.mutate({ currency: "USD", value: "25", decimals: 6 })
      }
    >
      {fund.isPending ? "Funding…" : "Fund test account"}
    </button>
  );
}

Parameters

The hook itself takes no parameters. The mutation takes a Money — the amount to credit:

Field	Type	Description
`currency`	`string`	Currency code, e.g. `"USD"`.
`value`	`string`	Major-unit decimal string, e.g. `"25"` or `"1.50"`.
`decimals`	`number`	The currency's precision (USD test money uses `6`).

Return type

import { type UseCapxulAccountFundReturn } from "@capxul/sdk-react";
// UseMutationResult<{ txHash: string }, CapxulError, Money>

On success, data is a receipt: { txHash: string }, the identifier of the faucet transfer. Treat it as an opaque proof value for test assertions.

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

Field	Description
`mutate`	Fire the mutation (fire-and-forget; pair with `onSuccess`/`onError` callbacks).
`mutateAsync`	Fire the mutation and get a `Promise` of the result. Rejects with a `CapxulError` on failure.
`data`	The mutation result (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last attempt failed, otherwise `null`.
`isPending`	`true` while the mutation is in flight. Use it to disable submit buttons.
`reset`	Clear the mutation state (`data`, `error`) back to idle.

Mutations do not retry by default. The full field list is in the TanStack Query useMutation reference; see also the TanStack Query integration guide.

Cache behavior

On success this mutation invalidates ["capxul", "accountBalance"], so useCapxulAccountBalance refetches and shows the new balance.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example when the faucet is not available for the key's environment. Faucet funding only exists for test environments.

Client method

This hook wraps the core SDK's dev-only faucet, client._internal.accounts.fund(amount). The faucet is deliberately kept off the public client.accounts surface so it can never leak into production integrations — this hook is the supported way to reach it in a test app.