# Capxul Docs

- [What is Capxul?](https://capxul-sdk-docs.pages.dev/docs): A Stripe-shaped SDK for financial operations — accounts, payments, payroll, and organizations — built for developers and agents.
- [Capability status](https://capxul-sdk-docs.pages.dev/docs/capability-status): What is live, what is SDK-ready but not yet product-proven, and what is roadmap — verified against the published alpha.

- **Learn**
- Getting started
  - [Quickstart](https://capxul-sdk-docs.pages.dev/docs/getting-started): From an empty React app to a working Capxul email OTP sign-in — install the SDK, get a test key, mount the provider, and read the session.
  - [Next.js](https://capxul-sdk-docs.pages.dev/docs/getting-started/nextjs): Wire Capxul email OTP sign-in into a Next.js App Router app — environment variables, route rewrites, provider mounting, and a login page.
  - [Test keys & funds](https://capxul-sdk-docs.pages.dev/docs/getting-started/test-keys): Create a test publishable key and send test funds with the @capxul/sandbox CLI — and know what must never ship to production.
  - [Requirements & signers](https://capxul-sdk-docs.pages.dev/docs/getting-started/requirements-and-signers): The requirement prop declares how much account readiness your app needs at start-up — none, counterfactual, or deployed — and the signer rules that go with it.
- Concepts
  - [Mental model](https://capxul-sdk-docs.pages.dev/docs/concepts/mental-model): How to think about the Capxul SDK — a method-based client over a money substrate, a deliberately narrow public surface, and an explicit result boundary.
  - [Money & accounts](https://capxul-sdk-docs.pages.dev/docs/concepts/money-and-accounts): The domain vocabulary of the platform — Money, Accounts, Transfers, Payments and their kinds, Commitments, payment documents, and the instant-send guardrail.
  - [Identity & organizations](https://capxul-sdk-docs.pages.dev/docs/concepts/identity-and-orgs): Who can hold and move money — Capxul users, organizations and their treasuries, members and roles, handles, acting entities, and typed recipient references.
  - [The account lane](https://capxul-sdk-docs.pages.dev/docs/concepts/account-lane): What happens between sign-in and "ready" — the automatic provisioning ladder, how requirement decides how far it runs, and why apps only read the lifecycle.
  - [Agent-native](https://capxul-sdk-docs.pages.dev/docs/concepts/agent-native): What agent-native means on this platform — agents doing what users and developers can do, through safe structured primitives, and docs built for machine readers.
- Guides
  - [Build the auth flow](https://capxul-sdk-docs.pages.dev/docs/guides/authentication): The complete email OTP journey — send the code, verify, route on session/profile/lifecycle state, complete onboarding, and sign out.
  - [Work with organizations](https://capxul-sdk-docs.pages.dev/docs/guides/organizations): List the orgs a user belongs to, create one, switch the acting entity, read treasury/members/roles, and invite a member with a role.
  - [Send money](https://capxul-sdk-docs.pages.dev/docs/guides/payments): Pay a typed recipient, understand Commitment escrow for unvalidated recipients, list and read payments, cancel, withdraw to an external wallet, and pay out to a saved destination.
  - [TanStack Query integration](https://capxul-sdk-docs.pages.dev/docs/guides/tanstack-query): How the SDK rides TanStack Query — the provider-owned QueryClient, the key namespace, automatic invalidation, manual invalidation, and what clears on sign-out and re-bootstrap.
  - [Handle errors](https://capxul-sdk-docs.pages.dev/docs/guides/error-handling): CapxulError is the single error type across hooks and the raw client — the error shape, where it surfaces, bootstrap retry, and the public error-code catalog.
  - [Drop to the raw client](https://capxul-sdk-docs.pages.dev/docs/guides/raw-client): Call core client methods that don't have first-class hooks yet — useCapxulClientOrNull, gating on bootstrap, unwrapping CapxulResult, and keying under the capxul namespace.

- **Reference**
- Hooks
  - [Hooks](https://capxul-sdk-docs.pages.dev/docs/hooks): Catalog of every @capxul/sdk-react hook — TanStack Query under the hood, one reference page per hook.
  - [CapxulProvider](https://capxul-sdk-docs.pages.dev/docs/hooks/capxul-provider): The root provider that bootstraps the Capxul client and owns the TanStack Query cache for every hook beneath it.
  - [useCapxul](https://capxul-sdk-docs.pages.dev/docs/hooks/use-capxul): Bootstrap-state hook — the surrounding CapxulProvider's status ("bootstrapping" | "ready" | "error"), its error, and a retry function.
  - [useCapxulClientOrNull](https://capxul-sdk-docs.pages.dev/docs/hooks/use-capxul-client-or-null): Advanced escape hatch — returns the bootstrapped CapxulClient, or null while the provider is still bootstrapping.
  - [Actor scopes](https://capxul-sdk-docs.pages.dev/docs/hooks/actor-scopes): The CapxulActorScope argument that points address-book, requests, inbox, and insights hooks at either the personal account or one organization.
  - Auth & session
    - [useCapxulSignIn](https://capxul-sdk-docs.pages.dev/docs/hooks/auth/use-capxul-sign-in): Mutation hook for starting email OTP sign-in — sends the one-time code to the user's email.
    - [useCapxulVerifyOtp](https://capxul-sdk-docs.pages.dev/docs/hooks/auth/use-capxul-verify-otp): Mutation hook for verifying the email OTP code — completes sign-in and returns the session.
    - [useCapxulSignOut](https://capxul-sdk-docs.pages.dev/docs/hooks/auth/use-capxul-sign-out): Mutation hook for ending the current session and clearing cached signed-in state.
    - [useCapxulSession](https://capxul-sdk-docs.pages.dev/docs/hooks/auth/use-capxul-session): Query hook for the signed-in session — Session when signed in, null when signed out.
    - [useCapxulProfile](https://capxul-sdk-docs.pages.dev/docs/hooks/auth/use-capxul-profile): Query hook for the signed-in user's identity profile — null for a fresh identity until onboarding completes.
    - [useCapxulCurrentUser](https://capxul-sdk-docs.pages.dev/docs/hooks/auth/use-capxul-current-user): Query hook for the aggregated current-user context — user, personal account, and organization memberships in one read.
  - Account
    - [useCapxulAccountLifecycle](https://capxul-sdk-docs.pages.dev/docs/hooks/account/use-capxul-account-lifecycle): Query hook for post-sign-in account setup state — loading, settingUp, ready, or failed — with a built-in retry.
    - [useCapxulAccountBalance](https://capxul-sdk-docs.pages.dev/docs/hooks/account/use-capxul-account-balance): Query hook for the signed-in user's personal Account — balance and available balance.
    - [useCapxulAccountFund](https://capxul-sdk-docs.pages.dev/docs/hooks/account/use-capxul-account-fund): Mutation hook for faucet-funding the personal Account in test environments — a developer tool, not customer-facing funding.
  - Sub-accounts
    - [useCapxulSubAccountsList](https://capxul-sdk-docs.pages.dev/docs/hooks/sub-accounts/use-capxul-sub-accounts-list): Query hook for an Account's sub-accounts — the named envelopes that partition its balance.
    - [useCapxulSubAccountCreate](https://capxul-sdk-docs.pages.dev/docs/hooks/sub-accounts/use-capxul-sub-account-create): Mutation hook that creates a named sub-account (envelope) inside an Account.
    - [useCapxulSubAccountRename](https://capxul-sdk-docs.pages.dev/docs/hooks/sub-accounts/use-capxul-sub-account-rename): Mutation hook that renames an existing sub-account (envelope).
    - [useCapxulSubAccountDelete](https://capxul-sdk-docs.pages.dev/docs/hooks/sub-accounts/use-capxul-sub-account-delete): Mutation hook that deletes an empty sub-account (envelope).
    - [useCapxulTransfer](https://capxul-sdk-docs.pages.dev/docs/hooks/sub-accounts/use-capxul-transfer): Mutation hook that moves money within one Account — between the main balance and its sub-account envelopes.
  - Payments
    - [useCapxulPay](https://capxul-sdk-docs.pages.dev/docs/hooks/payments/use-capxul-pay): Mutation hook for sending money to a validated recipient — instant by default, or a scheduled/streaming Commitment.
    - [useCapxulPayout](https://capxul-sdk-docs.pages.dev/docs/hooks/payments/use-capxul-payout): Mutation hook for paying out to a saved destination by id — currently settles wallet destinations only.
    - [useCapxulWithdraw](https://capxul-sdk-docs.pages.dev/docs/hooks/payments/use-capxul-withdraw): Mutation hook for cashing out to an external wallet address, backed by a required Withdrawal document.
    - [useCapxulCancelPayment](https://capxul-sdk-docs.pages.dev/docs/hooks/payments/use-capxul-cancel-payment): Mutation hook for cancelling a payment by id — a published stub that is not yet implemented in the current alpha.
    - [useCapxulPayments](https://capxul-sdk-docs.pages.dev/docs/hooks/payments/use-capxul-payments): Query hook for the signed-in user's payment ledger — the list of Payments, newest state included.
    - [useCapxulPayment](https://capxul-sdk-docs.pages.dev/docs/hooks/payments/use-capxul-payment): Query hook for a single Payment by id — null when no such payment is visible to the signed-in user.
  - Destinations
    - [useCapxulDestinations](https://capxul-sdk-docs.pages.dev/docs/hooks/destinations/use-capxul-destinations): Query hook for saved payout destinations — bank, mobile-money, and wallet metadata scoped to the acting entity.
    - [useCapxulAddDestination](https://capxul-sdk-docs.pages.dev/docs/hooks/destinations/use-capxul-add-destination): Mutation hook for saving a payout destination — masked bank, mobile-money, or wallet details tied to a counterparty.
    - [useCapxulRemoveDestination](https://capxul-sdk-docs.pages.dev/docs/hooks/destinations/use-capxul-remove-destination): Mutation hook for retiring a saved destination by id so it no longer appears in lists or accepts payouts.
  - Activity
    - [useCapxulActivity](https://capxul-sdk-docs.pages.dev/docs/hooks/activity/use-capxul-activity): Query hook for the unified activity feed — a cursor-paged list of payments, payouts, withdrawals, deposits, and claims.
  - Offramp
    - [useCapxulOfframpQuote](https://capxul-sdk-docs.pages.dev/docs/hooks/offramp/use-capxul-offramp-quote): Query hook for pricing a cash-out to a saved destination — fee and received amount, with an expiry.
    - [useCapxulOfframpStatus](https://capxul-sdk-docs.pages.dev/docs/hooks/offramp/use-capxul-offramp-status): Query hook for tracking an offramp by id — its lifecycle status, destination, and linked payment.
  - Address book
    - [useCapxulAddressBook](https://capxul-sdk-docs.pages.dev/docs/hooks/address-book/use-capxul-address-book): Query hook for an actor's address book — every counterparty the person or org has a payment relationship with.
    - [useCapxulAddressBookEntry](https://capxul-sdk-docs.pages.dev/docs/hooks/address-book/use-capxul-address-book-entry): Query hook for one address-book entry of an actor, by entry id — null when no relationship exists.
    - [useCapxulAddAddressBookEntry](https://capxul-sdk-docs.pages.dev/docs/hooks/address-book/use-capxul-add-address-book-entry): Mutation hook that adds a counterparty to an actor's address book from a typed reference.
    - [useCapxulHideAddressBookEntry](https://capxul-sdk-docs.pages.dev/docs/hooks/address-book/use-capxul-hide-address-book-entry): Mutation hook that hides an address-book entry from an actor's contact list without deleting the relationship.
    - [useCapxulUnhideAddressBookEntry](https://capxul-sdk-docs.pages.dev/docs/hooks/address-book/use-capxul-unhide-address-book-entry): Mutation hook that restores a hidden address-book entry to an actor's contact list.
    - [useCapxulLabelAddressBookEntry](https://capxul-sdk-docs.pages.dev/docs/hooks/address-book/use-capxul-label-address-book-entry): Mutation hook that renames an address-book entry in an actor's contact list.
  - Payment requests
    - [useCapxulRequests](https://capxul-sdk-docs.pages.dev/docs/hooks/requests/use-capxul-requests): Query hook for the payment requests an actor has issued — its receivables, with status and expiry.
    - [useCapxulRequest](https://capxul-sdk-docs.pages.dev/docs/hooks/requests/use-capxul-request): Query hook for one payment request an actor has issued, by request id — null when it does not exist.
    - [useCapxulIssueRequest](https://capxul-sdk-docs.pages.dev/docs/hooks/requests/use-capxul-issue-request): Mutation hook that issues a payment request from an actor to a typed payer reference.
    - [useCapxulCancelRequest](https://capxul-sdk-docs.pages.dev/docs/hooks/requests/use-capxul-cancel-request): Mutation hook that cancels a payment request an actor has issued, by request id.
    - [useCapxulReconcileRequests](https://capxul-sdk-docs.pages.dev/docs/hooks/requests/use-capxul-reconcile-requests): Mutation hook that runs a reconciliation pass over an actor's issued payment requests and returns paid / exception entries.
  - Inbox
    - [useCapxulInbox](https://capxul-sdk-docs.pages.dev/docs/hooks/inbox/use-capxul-inbox): Query hook for the payment requests issued to an actor — the requests waiting on the actor to pay or decline.
    - [useCapxulApproveInboxRequest](https://capxul-sdk-docs.pages.dev/docs/hooks/inbox/use-capxul-approve-inbox-request): Mutation hook that approves an inbox payment request — approving pays it, producing a Payment.
    - [useCapxulDeclineInboxRequest](https://capxul-sdk-docs.pages.dev/docs/hooks/inbox/use-capxul-decline-inbox-request): Mutation hook that declines an inbox payment request without paying it.
  - Insights
    - [useCapxulInsightsSummary](https://capxul-sdk-docs.pages.dev/docs/hooks/insights/use-capxul-insights-summary): Query hook for an actor's money-flow summary — pending requests, paid this month, drafts, and reconciliation counters.
    - [useCapxulInsightsHistory](https://capxul-sdk-docs.pages.dev/docs/hooks/insights/use-capxul-insights-history): Query hook for an actor's payment history — the Payment records behind the insights summary.
  - Payroll
    - [useCapxulPayrollRoster](https://capxul-sdk-docs.pages.dev/docs/hooks/payroll/use-capxul-payroll-roster): Query hook for an organization's payroll roster — the employee lines a payroll run pays.
    - [useCapxulAddPayrollRosterLine](https://capxul-sdk-docs.pages.dev/docs/hooks/payroll/use-capxul-add-payroll-roster-line): Mutation hook that adds an employee line to an organization's payroll roster.
    - [useCapxulUpdatePayrollRosterLine](https://capxul-sdk-docs.pages.dev/docs/hooks/payroll/use-capxul-update-payroll-roster-line): Mutation hook that edits an existing payroll roster line — amount, timing, employee ref, or payslip template.
    - [useCapxulRemovePayrollRosterLine](https://capxul-sdk-docs.pages.dev/docs/hooks/payroll/use-capxul-remove-payroll-roster-line): Mutation hook that removes a line from an organization's payroll roster.
    - [useCapxulRunPayroll](https://capxul-sdk-docs.pages.dev/docs/hooks/payroll/use-capxul-run-payroll): Mutation hook that executes a payroll run — one payroll Payment per active roster line, for a given period.
  - Organizations
    - [useCapxulOrgs](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-orgs): Query hook for the list of organizations the signed-in user belongs to.
    - [useCapxulOrg](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-org): Query hook for a single organization you belong to, resolved by org id — null when you are not a member.
    - [useCapxulOrgTreasury](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-org-treasury): Query hook for an organization's treasury Account — the org's balance, scoped by org id.
    - [useCapxulOrganizationAccount](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-organization-account): Query hook for an organization's account summary — balance, available balance, and account address, scoped by org id.
    - [useCapxulOrgMembers](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-org-members): Query hook for an organization's member list — the people who hold authority inside the org, scoped by org id.
    - [useCapxulOrgRoles](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-org-roles): Query hook for the roles defined on an organization — labels, role keys, and spend caps, scoped by org id.
    - [useCapxulInviteMember](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-invite-member): Mutation hook for inviting a member into an organization by email, granting them a role.
    - [useCapxulAssignRole](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-assign-role): Mutation hook for assigning a role to an organization member, keyed by the member's identity address.
    - [useCapxulRemoveMember](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-remove-member): Mutation hook for removing a member from an organization — revokes their role and authority.
    - [useCapxulCreateOrg](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-create-org): Mutation hook for creating an organization — claims a handle, seeds roles from a template, and makes the creator its Owner.
    - [useCapxulOrgDeployRoles](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-org-deploy-roles): Mutation hook that deploys an organization's role set so role grants and spend caps become enforceable.
    - [useCapxulOrganizationAuditLog](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-organization-audit-log): Query hook for an organization's audit log — administrative actions recorded against the org, scoped by org id.
    - [useCapxulSwitchActingEntity](https://capxul-sdk-docs.pages.dev/docs/hooks/organizations/use-capxul-switch-acting-entity): Mutation hook that marks a switch between acting as yourself and acting as an organization — a UI seam with no server call.
  - Onboarding
    - [useCapxulCompletePersonalOnboarding](https://capxul-sdk-docs.pages.dev/docs/hooks/onboarding/use-capxul-complete-personal-onboarding): Mutation hook that completes personal onboarding — saves the identity profile, triggers account setup, and returns the lifecycle snapshot.
    - [useCapxulCompleteOrganizationOnboarding](https://capxul-sdk-docs.pages.dev/docs/hooks/onboarding/use-capxul-complete-organization-onboarding): Mutation hook that completes organization onboarding — saves the founder's profile, creates the org, and returns the org plus lifecycle snapshot.
- Core client
  - [CapxulClient](https://capxul-sdk-docs.pages.dev/docs/client): Reference for the core SDK client — createCapxulClient, the CapxulResult contract, and the method bundles the React hooks wrap.
  - [Node & servers](https://capxul-sdk-docs.pages.dev/docs/client/node-and-servers): Use the core client outside React — in scripts, servers, and agent backends — and hand a pre-built client to CapxulProvider.

- **Platform**
- For agents
  - [MCP server](https://capxul-sdk-docs.pages.dev/docs/agents/mcp): The @capxul/mcp server exposes Capxul financial operations — auth, account readiness, balances, testnet faucet, payments — as MCP tools over Streamable HTTP.
  - [Sandbox CLI](https://capxul-sdk-docs.pages.dev/docs/agents/sandbox): @capxul/sandbox creates test publishable keys and sends testnet faucet funds — the two commands that stand up a working test environment.
  - [Machine-readable docs](https://capxul-sdk-docs.pages.dev/docs/agents/machine-readable-docs): Every page on this site is available as raw markdown — via a per-page content.md URL, llms.txt, and llms-full.txt.
- Contributing
  - [Dev onboarding](https://capxul-sdk-docs.pages.dev/docs/contributors/dev-onboarding): Get productive in the Xelmar-tech/infrastructure monorepo — prerequisites, the vp toolchain, workspace layout, and where the canon lives.
  - [Architecture](https://capxul-sdk-docs.pages.dev/docs/contributors/architecture): The platform shape one layer up — public packages vs the private substrate, the ports-and-adapters seam, and the Convex backend.
  - [Conventions](https://capxul-sdk-docs.pages.dev/docs/contributors/conventions): The load-bearing repo conventions a contributor must know, each with a pointer to its canon file.
  - [Release flow](https://capxul-sdk-docs.pages.dev/docs/contributors/release-flow): How the @capxul/* packages ship — Changesets in pre-release mode on the alpha tag, the Release workflow, and version pinning for consumers.