useCapxulSubAccountCreate

Creates a sub-account — a named envelope inside an Account. Creating an envelope only names it; it holds no money until you fund it with useCapxulTransfer. The new envelope appears in useCapxulSubAccountsList.

Import

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

Usage

"use client";

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

function NewEnvelopeForm() {
  const account = useCapxulAccountBalance();
  const createSubAccount = useCapxulSubAccountCreate();
  const [name, setName] = useState("");
  const accountId = account.data?.id;

  if (accountId === undefined) return null;

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault();
        await createSubAccount.mutateAsync({ accountId, name });
        setName("");
      }}
    >
      <input
        required
        maxLength={64}
        value={name}
        onChange={(event) => setName(event.target.value)}
        placeholder="Rent"
      />
      <button type="submit" disabled={createSubAccount.isPending}>
        {createSubAccount.isPending ? "Creating…" : "Create envelope"}
      </button>
      {createSubAccount.error ? <p>{createSubAccount.error.message}</p> : null}
    </form>
  );
}

Parameters

The hook itself takes no parameters. The mutation input is an object with two fields:

Field	Type	Description
`accountId`	`AccountId`	The Account to create the envelope in.
`name`	`string`	Display name for the new sub-account. Must be non-empty, at most 64 characters.

Return type

import { type UseCapxulSubAccountCreateReturn } from "@capxul/sdk-react";
// UseMutationResult<SubAccount, CapxulError, { accountId: AccountId; name: string }>

On success, data is the created SubAccount — its id, accountId, name, balance (a Money), and createdAt.

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 the Account's sub-account list (["capxul", "subAccounts", accountId]) and the personal balance (["capxul", "accountBalance"]), so envelope lists and available-balance reads refetch together.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example when the name is empty or longer than 64 characters, or when the mutation fires while <CapxulProvider> is still bootstrapping.

Client method

This hook wraps client.subAccounts.create(accountId, { name }) on the core SDK.