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.

​
The whole flow

mount
  └─ POST /v1/session  →  cookie set, wallet captured
       └─ GET /v1/wallets/:wallet
            ├─ 404 → register
            │         └─ POST /v1/wallets/:wallet → state
            └─ 200 → derive step from kycState + hasAcceptedTos + va
                 ├─ bridge_tos      → POST tos-link, iframe, postMessage
                 ├─ kyc             → POST kyc-link, iframe, poll
                 ├─ review          → status + poll
                 ├─ rejected        → terminal
                 ├─ choose_currency → pick currency + chain
                 │   └─ POST /virtual-account → instructions
                 └─ instructions    → deposit details + onComplete()

​
Steps

​
loading
step
Initial state while session bootstraps and first state read happens. Shows a spinner.
​
register
step
Customer isn’t registered yet (GET /v1/wallets/:address returned 404 customer_not_registered). Shows a form for first_name, last_name, email, country. Submit → POST /v1/wallets/:address.
​
bridge_tos
step
Customer exists but hasAcceptedTos === false. Shows Bridge’s hosted ToS in an iframe. Bridge posts { signedAgreementId } via postMessage on accept; the SDK refreshes state immediately.
​
kyc
step
kycState is not_started or incomplete. Shows Bridge’s hosted KYC in an iframe. SDK polls GET /v1/wallets/:address every 5 seconds to watch the state transition.
​
review
step
kycState === "under_review". Bridge is reviewing the user’s submission. SDK keeps polling.
​
rejected
step
required
kycState === "rejected". Terminal. The user has to start over via support channels — Bridge doesn’t allow programmatic recovery.
​
choose_currency_chain
step
kycState === "active" and no virtual account exists yet. Shows currency (USD/GBP/EUR) and chain (Arbitrum/Base/Ethereum/HyperEVM) pickers. Submit → POST /v1/wallets/:address/virtual-account.
​
creating
step
Brief “provisioning” state while the VA create request is in flight.
​
instructions
step
Virtual account exists. Renders deposit_instructions from Bridge (bank routing + account, sort code + account, IBAN + BIC — varies by currency). Fires onComplete(va) once.
​
error
step
Any unrecoverable error (network failure, bad token, etc.). Shows the error message. Partner-driven retry by remounting the Provider.

​
Derivation rule

deriveStep(walletState, virtualAccount) is a pure function — same inputs always produce the same step. Listed by precedence:
ConditionStep
walletState === null and not in registrationloading
Explicitly forced to registerregister
kycState === "rejected"rejected
!hasAcceptedTosbridge_tos
kycState ∈ {not_started, incomplete}kyc
kycState === "under_review"review
kycState === "active" and va === nullchoose_currency_chain
kycState === "active" and va !== nullinstructions

​
When state refreshes

TriggerEffect
MountOne-shot bootstrap
postMessage from Bridge ToS iframeImmediate refresh
5-second poll while in bridge_tos/kyc/reviewRefresh
Successful register/VA createImmediate refresh
useCalm().refresh()Manual trigger
Polling only runs while the user is actively waiting on an external action. Once you hit instructions or rejected, polling stops.