Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.calmtreasury.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Install

bun add @calm-xyz/react
Peer dep: react@^18 || ^19 (only if you use the widget).

​
Drop in the widget

1

Wrap your app in PrivyProvider

The SDK relies on Privy’s identity tokens. If you’re already using Privy, skip this step.
import { PrivyProvider } from "@privy-io/react-auth";

export default function App() {
  return (
    <PrivyProvider appId="<your_privy_app_id>">
      {/* ... */}
    </PrivyProvider>
  );
}
2

Mount CalmProvider + DepositFlow

The Provider bootstraps a session on mount. <DepositFlow /> renders the multi-step onboarding flow.
import { usePrivy } from "@privy-io/react-auth";
import { CalmProvider, DepositFlow } from "@calm-xyz/react";

function CalmGateway() {
  const { ready, authenticated, getIdentityToken, user } = usePrivy();
  if (!ready || !authenticated) return null;

  return (
    <CalmProvider
      getAccessToken={getIdentityToken}
      defaults={{
        email: user?.email?.address,
        country: "US",
      }}
    >
      <DepositFlow onComplete={(va) => console.log("VA ready", va.id)} />
    </CalmProvider>
  );
}
3

That's it

On first render the SDK fires POST /v1/session, sets a cookie, and walks the user through register → ToS → KYC → currency choice → deposit details.

​
Anatomy of a session

The cookie is HttpOnly, Secure, SameSite=None, and Partitioned. It lasts an hour. The SDK uses credentials: "include" on every request, so the cookie attaches automatically — you never see it.

​
Next

State machine

Every step the widget can be in, and how it advances.

Composing your own flow

Bring your own UI with useCalm() and the individual step components.