useCapxulCompletePersonalOnboarding

Mutation hook that completes personal onboarding — saves the identity profile, triggers account setup, and returns the lifecycle snapshot.

Completes personal onboarding after the first sign-in: persists the user's identity profile (display name, country, optional withdrawal address), triggers account setup, and returns a lifecycle snapshot to route on. For founders creating a company, use useCapxulCompleteOrganizationOnboarding instead.

Import

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

Usage

"use client";

import { useState } from "react";
import { useCapxulCompletePersonalOnboarding } from "@capxul/sdk-react";
import { useRouter } from "next/navigation";

function PersonalOnboardingForm() {
  const router = useRouter();
  const completePersonal = useCapxulCompletePersonalOnboarding();
  const [displayName, setDisplayName] = useState("");
  const [country, setCountry] = useState("");

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault();
        const { lifecycle } = await completePersonal.mutateAsync({
          displayName: displayName.trim(),
          country: country.trim(),
        });
        router.push(lifecycle.status === "ready" ? "/dashboard" : "/signup/provisioning");
      }}
    >
      <input required value={displayName} onChange={(e) => setDisplayName(e.target.value)} />
      <input required placeholder="GH" value={country} onChange={(e) => setCountry(e.target.value)} />
      <button type="submit" disabled={completePersonal.isPending}>
        {completePersonal.isPending ? "Setting up…" : "Continue"}
      </button>
      {completePersonal.error ? <p>{completePersonal.error.message}</p> : null}
    </form>
  );
}

Call it from a submit handler and route on lifecycle.status — "ready" goes straight to the app, anything else goes to a provisioning screen driven by useCapxulAccountLifecycle (which self-polls until setup settles). Onboarding is a one-time step: before it completes, useCapxulProfile reads null for the fresh identity.

Parameters

The hook itself takes no parameters. The mutation takes a CompletePersonalOnboardingInput:

Field	Type	Description
`displayName`	`string`	The user's display name. Required.
`country`	`string`	ISO-3166 country code (e.g. `"GH"`). Required.
`withdrawalAddress`	`string \| undefined`	Optional cash-out destination — a `0x`-prefixed address string, validated and normalized at the boundary.

Return type

import { type UseCapxulCompletePersonalOnboardingReturn } from "@capxul/sdk-react";
// UseMutationResult<CompletePersonalOnboardingResult, CapxulError, CompletePersonalOnboardingInput>

On success, data is { lifecycle: AccountLifecycle } — the post-onboarding account-setup snapshot. lifecycle.status is the single routing source of truth; its values are documented on the useCapxulAccountLifecycle page.

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", "profile"] (useCapxulProfile) — the profile is no longer null.
["capxul", "accountLifecycle"] (useCapxulAccountLifecycle) — the provisioning screen reflects the new state.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example an invalid country code or withdrawal address, or calling it without a signed-in session.

Client method

This hook wraps client.onboarding.completePersonal(input) on the core SDK.