useCapxulActivity
Query hook for the unified activity feed — a cursor-paged list of payments, payouts, withdrawals, deposits, and claims.
Reads the activity feed — one cursor-paged timeline across payments,
payouts, withdrawals, deposits, and claims, scoped to the acting entity. For
the raw payment ledger use
useCapxulPayments.
Published contract, no live read yet
In the published alpha, client.activity.list is a stub: every fetch
fails with a NOT_IMPLEMENTED CapxulError
("activity.list is not yet implemented"). The hook, parameters, types, and
query keys are published so a feed UI can be typed and wired today, but the
query will sit in the error state until a later release. See
Capability status.
Import
import { useCapxulActivity } from "@capxul/sdk-react";Usage
"use client";
import { useCapxulActivity } from "@capxul/sdk-react";
function ActivityFeed() {
const activity = useCapxulActivity({ limit: 20 });
if (activity.isLoading) return <p>Loading activity…</p>;
if (activity.error) return <p>{activity.error.message}</p>;
return (
<ul>
{activity.data.items.map((item) => (
<li key={item.id}>
{item.title} — {item.amount.value} {item.amount.currency} (
{item.direction})
</li>
))}
</ul>
);
}Parameters
params
ActivityListParams | undefined
Optional filters and paging. Omit it entirely for the default feed.
Prop
Type
actor scopes the feed to the personal account (default) or an organization.
cursor pages through results — pass the previous page's nextCursor.
paymentType and timing filter by payment classification and timing kind.
options
{ enabled?: boolean } | undefined
Pass enabled: false to skip the read until your UI is ready for it.
Return type
import { type UseCapxulActivityReturn } from "@capxul/sdk-react";
// UseQueryResult<ActivityPage, CapxulError>data is an ActivityPage: items (a read-only array of ActivityItem) and
nextCursor (null on the last page). Each ActivityItem carries its kind
(payment, payout, withdrawal, deposit, or claim), a direction
(in, out, or internal), the payment status and amount, a display
title and subtitle, the counterparty target when known, and the linked
paymentId when the item maps to a ledger row.
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", "activity", <serialized params>] — one cache entry per
actor / cursor / limit / filter combination. No mutation invalidates activity
keys automatically today; call refetch (or change params) to reload the
feed after a money mutation.
Errors
Every fetch currently fails with NOT_IMPLEMENTED (see the callout above).
Failures surface as a CapxulError on error.
Client method
This hook wraps client.activity.list(params) on the core SDK.