Skip to main content

​
Prerequisites

Calm authenticates Privy users via Privy’s identity tokens — short-lived JWTs that carry the user’s sub and linked_accounts (including the wallet and email). They are not the same as Privy access tokens. You only need to flip this once per Privy app.
1

Open the Privy dashboard

Sign in at dashboard.privy.io and pick your app.
2

Navigate to User Management → Authentication → Advanced

Privy User Authentication settings panel, Advanced tab selected
3

Toggle "Return user data in an identity token" ON

Scroll the Advanced tab until you see it. Once enabled, the user’s linked_accounts (including the linked wallet) ride inside the identity token — which is exactly what the SDK forwards to Calm.
Return user data in an identity token toggle, enabled
If this toggle is off, the SDK can’t start a session — the API can’t see the user’s wallet in the JWT claims and returns wallet_not_linked.

​
Installation

To add Calm to your project, install the required packages. 
bun add @calm-xyz/react @privy-io/react-auth@^2.25 @tanstack/react-query@^5
  • Privy is the identity provider the SDK reads the user, wallet, and identity token from.
  • TanStack Query is an async state manager that handles requests, caching, and more.

​
Import the stylesheet

Import the Calm stylesheet once at your app root (Next.js layout.tsx, React main.tsx): 
import "@calm-xyz/react/styles.css";
or @import it from your own CSS file: 
@import "@calm-xyz/react/styles.css";

​
Wrap App in <PrivyCalmProvider>

Place <PrivyCalmProvider> inside <PrivyProvider> and <QueryClientProvider>.
app/layout.tsx
"use client";
import { PrivyProvider } from "@privy-io/react-auth";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { PrivyCalmProvider } from "@calm-xyz/react/privy";

const queryClient = new QueryClient();

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <PrivyProvider appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID!}>
          <QueryClientProvider client={queryClient}>
            {/* <PrivyCalmProvider> must be wrapped in <PrivyProvider>
                and <QueryClientProvider> — it reads the identity token
                from Privy and uses react-query under the hood. */}
            <PrivyCalmProvider
              calmKey={process.env.NEXT_PUBLIC_CALM_KEY!}
              currency="usd"
            >
              {children}
            </PrivyCalmProvider>
          </QueryClientProvider>
        </PrivyProvider>
      </body>
    </html>
  );
}

​
Open the onramp

The provider always renders its children. Wrap any trigger element in <CalmOnramp> to open the deposit modal, and use useReady() to gate the trigger on whether the Calm context is live (i.e. Privy reports a signed-in user with a linked wallet). 
"use client";
import { CalmOnramp } from "@calm-xyz/react";
import { useReady } from "@calm-xyz/react/privy";

function DepositButton() {
  const ready = useReady();
  if (!ready) return <button type="button" disabled>Loading…</button>;
  return (
    <CalmOnramp>
      <button type="button">Deposit funds</button>
    </CalmOnramp>
  );
}

export default function Page() {
  return <DepositButton />;
}

​
Props

​
calmKey
string
required
Your publishable key — calm_public_(live|dev)_<32 hex>. Identifies the Calm tenant. Sent to the API on every session creation via the X-Calm-Publishable-Key header.
​
currency
"usd" | "gbp" | "eur"
required
Source fiat currency for the bank-deposit onramp.
​
initialChain
1 | 8453 | 42161 | 999
default:"999"
Initial destination chain for auto-converted USDC. Optional — defaults to 999 (HyperEVM). Once mounted the SDK owns the chain; switch it at runtime via useCalm().setChain(...).
The destination chain defaults to HyperEVM (999) with mode set to hypercore. It’s independent of the Privy wallet’s current chain — to deliver USDC elsewhere, override initialChain, or call useCalm().setChain(...) at runtime (and setMode(...) when staying on chain 999).
​
initialMode
"hyperevm" | "hypercore"
Initial Hyperliquid execution layer. Optional — defaults to "hypercore" when initialChain is 999. Silently ignored on every other chain because mode only carries meaning on Hyperliquid (the SDK exposes mode: null off 999). Switch at runtime via useCalm().setMode(...), which throws when called with chain !== 999.
​
baseUrl
string
default:"https://api.calmtreasury.xyz"
Override the Calm API root. Use https://api.sandbox.calmtreasury.xyz for the sandbox environment.

​
useReady

import { useReady } from "@calm-xyz/react/privy";

const ready = useReady();
Returns boolean. false until Privy is ready, the user is authenticated, the identity token is issued, and a wallet is linked; true once <PrivyCalmProvider> has a configured Calm context. Safe to call before any provider mounts — defaults to false. Use it to render your own loading UI in place of the silent null the provider used to return.

​
Errors

The provider’s createSession throws on any non-2xx response. The useSession hook surfaces the error in result.error. Common codes:
error.codeMeaning
invalid_tokenPrivy identity token couldn’t be verified — token missing claims, signature invalid, or past exp. Check the Privy dashboard toggle above.
wallet_not_linkedThe wallet on the session URL isn’t in the Privy user’s linked accounts. Usually means the identity-token toggle is off and the wallet didn’t ride inside the JWT.
invalid_publishable_keycalmKey is malformed, unknown, or revoked. Check your Calm dashboard.
publishable_key_missingNo X-Calm-Publishable-Key header reached the API — usually a bundler stripping the env var. Check process.env.NEXT_PUBLIC_CALM_KEY.
origin_not_allowedYour page’s Origin isn’t on the publishable key’s allowlist. Live keys require HTTPS; add the origin in the dashboard.
refresh_wallet_mismatchThe calm_refresh cookie is bound to a different wallet than the one signing in now (common after a Privy account switch). Call useCalm().logout() before mounting the provider for the new wallet.