useCapxulAddAddressBookEntry
Mutation hook that adds a counterparty to an actor's address book from a typed reference.
Adds a counterparty to an actor scope's address
book by hand — most entries appear automatically from payment history, this
hook is for saving someone before any money has moved. List entries with
useCapxulAddressBook;
rename with
useCapxulLabelAddressBookEntry.
Import
import { capxulOrgScope, useCapxulAddAddressBookEntry } from "@capxul/sdk-react";Usage
"use client";
import {
capxulOrgScope,
useCapxulAddAddressBookEntry,
useCapxulOrgs,
} from "@capxul/sdk-react";
function AddSupplierButton({ email }: { email: string }) {
const orgs = useCapxulOrgs();
const orgId = orgs.data?.[0]?.orgId;
const addEntry = useCapxulAddAddressBookEntry(capxulOrgScope(orgId));
return (
<button
type="button"
disabled={orgId === undefined || addEntry.isPending}
onClick={() =>
addEntry.mutate({
ref: { kind: "email", email },
label: "Supplier",
})
}
>
{addEntry.isPending ? "Adding…" : "Add to org address book"}
</button>
);
}For the personal address book, call the hook with capxulAccountScope (or no
argument at all — that is the default).
Parameters
actor
CapxulActorScope | undefined — defaults to capxulAccountScope
Which actor's address book to write to. An explicit undefined also falls
back to the personal scope, so when scoping to an org keep the control
disabled until the org id has loaded (as in the example above). See
Actor scopes.
Mutation input
The mutation takes an AddressBookAddInput:
Prop
Type
ref must be a typed reference — a handle, email, org handle, payee id, or
Capxul user id. Bare EVM addresses are rejected by design. label is the
display name; when omitted, the entry falls back to a label derived from the
reference itself.
Return type
import { type UseCapxulAddAddressBookEntryReturn } from "@capxul/sdk-react";
// UseMutationResult<AddressBookEntry, CapxulError, AddressBookAddInput>On success, data is the created AddressBookEntry — its id is what the
other address-book hooks take as entryId.
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, for the acting scope only, the address book list and the new entry's detail query. Org additions never refetch the personal address book, and vice versa.
Errors
Failures surface as a CapxulError on
error / thrown from mutateAsync — for example an empty reference value or
a raw 0x… address passed where a typed reference is required.
Client method
This hook wraps client.account.addressBook.add(input) for
the personal scope, or
client.org(orgId).addressBook.add(input) for an org scope.