Set Up a Wallet

Create a user’s non-custodial wallet with the provider your app ships. Do this first: set up the wallet and read its address before you create the user in the Rain API, since creating the user’s application requires the address. To start, install the SDK and authenticate the wallet with your provider; no Client Session Token needed for this step. The SDK uses a builder: register your RPC endpoints and one or more providers, then build() the SDK. There’s no singleton and no initialize call. Once built, resolve a wallet-bound RainClient for each provider you registered. A RainClient is bound to one provider for its lifetime, but multiple providers can coexist on the same built SDK.

Build the SDK with a provider

Register the provider adapter(s) your app ships: the examples use the managed Turnkey provider with the authenticated TurnkeyContext from the authentication step. build() validates the configuration and throws RainSDKError.invalidConfig / RainError.InvalidConfig if the configuration is incomplete.

import RainCore

let rain = try RainSdk.builder()
    .rpcEndpoints([RainChain.avalancheMainnet: "https://avalanche-c-chain-rpc.publicnode.com"])
    .register(TurnkeyProvider(TurnkeyConfig(turnkey: turnkeyContext)))
    .build()

import com.rain.sdk.RainChain
import com.rain.sdk.RainSdk
import com.rain.sdk.turnkey.TurnkeyConfig
import com.rain.sdk.turnkey.TurnkeyProvider

val rain = RainSdk.builder()
    .rpcEndpoints(mapOf(RainChain.AVALANCHE_MAINNET to "https://avalanche-c-chain-rpc.publicnode.com"))
    .register(TurnkeyProvider(TurnkeyConfig(turnkeyContext)))
    .build()

Optional builder calls:

Method	Purpose
`registerTokens(...)`	Pre-register token metadata so balance calls skip on-chain lookups.
`rainApiEnvironment(...)`	Select the Rain API host (see the built-in Rain API client).
`rainApiCredentials(apiKey, userId)`	Configure the built-in Rain API client at build time.

On iOS, providers are optional: build with endpoints alone for a wallet-agnostic instance that only does transaction building and Rain API calls. rpcEndpoints also accepts [NetworkConfig] when you want to name networks or use CAIP-2 ids. On Android, build() requires at least one registered provider.

Resolve the wallet client

Resolve the RainClient for a registered provider. This suspends on first access: it materializes the vendor wallet. The Turnkey and Privy adapters fail fast here if the provider has no usable account (Portal validates lazily on first use). Resolution runs once per id and is cached; a failed resolution is evicted so you can retry.

let client = try await rain.provider(.turnkey)

import com.rain.sdk.provider.ProviderId

val client = rain.provider(ProviderId.TURNKEY)

You can also resolve by capability instead of id:

let exporter = try await rain.first { $0.capabilities.contains(.export) }

import com.rain.sdk.provider.Capability

val exporter = rain.first { Capability.EXPORT in it.capabilities }

Resolving an unregistered id throws RAIN_102 (RainSDKError.providerNotRegistered / RainError.InvalidConfig). Use client for every wallet operation: balances and transfers, withdrawals, and the calls below.

Get the wallet address

Read the resolved wallet’s address:

let address = try await client.getWalletAddress()
// "0x1234...abcd"

val address = client.getWalletAddress()
// "0x1234...abcd"

Rain records the wallet address against the user, so you never handle key material. Turnkey wallets also hold a Solana account. Pass a Solana chain id to read the base58 address:

let solAddress = try await client.getWalletAddress(chainId: RainChain.solanaDevnet)

val solAddress = client.getWalletAddress(RainChain.SOLANA_DEVNET)

Generate a QR code

Create a QR code image for the wallet address so users can receive funds:

let png = try await client.generateWalletAddressQRCode(dimension: 500, backgroundColor: nil, foregroundColor: nil)
let image = UIImage(data: png)
// Returns PNG image data

val bitmap = client.generateAddressQRCode(width = 500, height = 500)
// Returns an android.graphics.Bitmap of the resolved wallet address

On Android, pass an explicit address to encode a different one.

Your user now has a non-custodial embedded wallet. Query balances, withdraw collateral, or fund a card against it.

Test your integration

Use a testnet chain ID to validate before production:

Build for testnet

Point rpcEndpoints at a testnet, for example Avalanche Fuji (RainChain.avalancheTestnet / RainChain.AVALANCHE_TESTNET, chain id 43113) at https://api.avax-test.network/ext/bc/C/rpc, and resolve the client as above.

Fund your test wallet

Mint rUSD test tokens and deposit them to your user’s collateral contract. See Mint Test Tokens.

Verify each operation

Confirm you get a 0x... address, read a testnet balance, send a small amount, and build a test withdrawal.

What’s next

Create the user & KYC

Onboard the user with the wallet address.

Balances & Transactions

Query balances, fetch history, and send tokens.

Fund the Wallet

Give the card spending power with on-chain collateral.

Withdraw Collateral

Execute collateral withdrawals from your app.

Introduction

Plan & Set Up Your Program

Build Your Program

Run Your Program

Rewards

Embedded Wallets

Set Up a Wallet

Test your integration

What’s next

Create the user & KYC

Balances & Transactions

Fund the Wallet

Withdraw Collateral

​Test your integration

​What’s next

Create the user & KYC

Balances & Transactions

Fund the Wallet

Withdraw Collateral

Test your integration

What’s next