Skip to main content
Integrate Rain embedded wallets end to end. This page maps each step to its guide. Create the wallet first: you need its address to create the user’s application. Here’s the full path:
WalletCreate the wallet
UserOnboard & complete KYC
FundingFund the wallet
CardIssue the card
SpendSpend & check balances

​
Backend API key vs. Client Session Token

Rain accepts two kinds of caller. Be deliberate about which you use:

Backend, with your primary API key

The established, default path for calling Rain. Use your primary API key (Api-Key header) for everything server-side: creating and managing users, applications, contracts, cards, and payments.

App, with a Client Session Token (CST)

A newer, optional capability. A CST is a short-lived (about 1 hour) token scoped to a single, already-created user: your backend mints it from your API key, or the SDK’s built-in Rain API client mints one automatically. Your app then sends it as Authorization: Bearer cst_… to call that user’s endpoints directly, without shipping your primary API key to the device. A CST can’t create users or mint other tokens.

​
Backend or CST: which to use

Default to the backend API-key flow, since it’s proven and covers every server-side operation. The main reason to reach for a CST is fetching a withdrawal signature on-device; everything else can stay on the backend.

​
What runs where

Here’s exactly which calls go where:

​
Backend vs. app, in short

Creating and managing things is a backend API-key job; the app handles the wallet (through its provider) and on-chain actions, and, only if you opt into a CST, can make user-scoped Rain calls directly.

​
The end-to-end flow

Each step maps to its own guide.
1

Authenticate the wallet

AppAuthenticate the user’s wallet with your provider (Turnkey, Portal, or Privy), outside Rain. See Authentication.
2

Set up the wallet

AppBuild the SDK, resolve the wallet, and read its address. The address is required for the next step. See Set up a wallet.
3

Create the user & complete KYC

BackendCreate the user’s application with the wallet address and complete KYC, using your API key. See Create the user & KYC.
4

Fund the wallet

AppBack the user’s card spend with collateral: the user deposits tokens into their collateral contract, or, with Real Time Funding, keeps funds in the wallet to be pulled at authorization. See Fund the wallet and Managing Collateral.
5

Issue a card

BackendIssue a card for the approved user with your API key. See Card Issuance.
6

Spend & check balances

AppThe card draws on the user’s funded spending power. Read wallet balances and send tokens with the SDK. See Balances & Transactions.
7

Withdraw

App or Backend + AppFetch the admin withdrawal signature from Rain (in-app with the SDK’s built-in Rain API client, or from your backend), then execute withdrawCollateral in the app. See Withdraw Collateral.
Want the app to call user-scoped Rain endpoints directly, for example to fetch the withdrawal signature on-device? Mint a Client Session Token. It’s optional; the backend API-key flow covers these calls too.

​
FAQ

Creating the application is backend-only: it creates the user, and a CST can’t create users or mint other tokens. Completing KYC runs on your backend by default (the standard flow), but can optionally run from the app with a CST. When the app calls user-scoped Rain endpoints, the SDK’s built-in Rain API client mints and caches the required CST automatically. The app’s other jobs are the wallet and on-chain funding.
Almost, but not quite. The on-chain part is a single call: withdrawCollateral builds the transaction, signs it through the wallet, and submits it. But it needs an admin withdrawal signature from the Rain API first, so a withdrawal is always two steps:
  1. Fetch the signature: in-app with the SDK’s fetchAdminSignature (the built-in Rain API client), or GET /v1/issuing/users/:userId/signatures/withdrawals from your backend (API key).
  2. Withdraw: pass the signature to withdrawCollateral, one SDK call. On Android, autoSend = false returns the raw transaction data if you’d rather submit it yourself.
It can’t collapse to a single call, because the admin signature must come from Rain’s signing service. See Withdraw Collateral.

​
What’s next

Set Up a Wallet

Build the SDK and create a wallet.

Create the user & KYC

Onboard the user with the wallet address.

Fund the Wallet

Put funds behind the card.