CalmProvider

<CalmProvider> is the root of a Calm integration. It takes your publishable key and the callbacks Calm uses to reach the connected wallet — the SDK never talks to a wallet vendor itself, so any stack that can produce an address and sign will work.

app/layout.tsx

"use client";
import { CalmProvider } from "@calm-xyz/react";

<CalmProvider
  publishableKey={CALM_PUBLISHABLE_KEY}
  name="Your App"
  address={address}
  chain={1337}
  destinationToken="USDC"
  currency="USD"
  country="US"
  sendTransaction={sendTransaction}
  signTypedData={signTypedData}
  waitForReceipt={waitForReceipt}
>
  {children}
</CalmProvider>

Mount it inside your <QueryClientProvider> and your own wallet stack, and only once a wallet is connected — it reads address at mount and throws without one, as it does for a missing query client, rather than failing silently.

Props

string

required

Your publishable key — calm_public_(live|sandbox)_<32 hex>. Sent as X-Calm-Publishable-Key on every request the SDK makes. Keys are pinned to an origin allowlist; see Authentication.

0x${string}

required

The connected wallet. The provider throws during render without one.

string

required

Your app’s name, as your users know it. Shown beside balances.

number

required

Destination chain id. HyperEVM is 999, HyperCore is 1337.

DestinationToken

required

Which of chain’s payout tokens to deliver — set once here, never shown to the end user. Only Polygon (137) and Monad (143) offer a choice.

Currency

Pins the fiat the buyer is charged in. Omit it and the currency follows country — GB gives GBP, the euro area gives EUR, everywhere else USD — and changes when the buyer picks a different country. Pass one and it is fixed whatever they pick.

string

The buyer’s country, ISO-3166 alpha-2. The card rail’s payment-method catalog is keyed by it and quotes price per (country, method).This is the initial value, not the fixed truth: the buyer can correct it from the control in the flow header, and useCalm() returns setCountry beside country. Omit it and the SDK guesses from the browser’s locale — en-GB gives GB — falling back to US where there is no region to read.

string

default:"https://api.calmtreasury.xyz"

Override the Calm API root. Use https://api.sandbox.calmtreasury.xyz for the sandbox environment.

Wallet callbacks

(input) => Promise<Hex>

required

Broadcast a transaction and return its hash. input carries to and chain, plus optional data, value, gasLimit, maxFeePerGas and maxPriorityFeePerGas as viem-native values — value and the gas fields are bigint. If your wallet vendor is a JSON boundary, convert them here.

(payload) => Promise<Hex>

required

Sign an EIP-712 payload and return the signature. The payload is a viem TypedDataDefinition.

({ chain, hash }) => Promise<TransactionReceipt>

required

Wait for a broadcast transaction to confirm. Read the receipt from an RPC you control rather than through the wallet — a wallet’s own endpoint can stall the confirm step.

​Props

​Wallet callbacks

Props

Wallet callbacks