iOS Quickstart

Authenticate a user, create an embedded wallet, and send your first transaction using the Rain iOS SDK.

This guide walks you through a wallet integration in Swift, from initializing the SDK and authenticating a user to retrieving their wallet address and sending tokens on Base Sepolia.

Before you begin

Install the Rain SDK and configure a Base Sepolia RPC endpoint.

All wallet operations in this quickstart run directly in your iOS application. You do not need a Rain API key.

1. Create the provider

   RainProvider is the Rain wallet: it owns login, wallet creation, and sessions. The wallet backend’s identity is embedded in the SDK, so the default configuration is the product. Create one provider per app and keep it for the app’s lifetime.

   import RainWallet
   
   let wallet = RainProvider()
   

   To react to a session that dies and can’t be refreshed, or to enable passkeys, pass a RainWalletConfig:

   let wallet = RainProvider(RainWalletConfig(
       passkeyDomain: "example.com",              // nil (default) leaves passkeys off
       onSessionExpired: {                        // fires once per session death; not on logout
           Task { @MainActor in showLoginScreen() }
       }
   ))
   
2. Log in: restore a session or start a login

   On launch, wait for the SDK to restore a persisted session. A returning user skips the code entirely.

   await wallet.awaitSessionRestore()
   
   if wallet.hasActiveSession() {
       // Returning user: go straight to the wallet.
   } else {
       // New device or logged out: run the one-time-code flow below.
   }
   

   wallet.authState publishes .loading, .authenticated, or .unauthenticated on every change, and wallet.currentAuthState() is its snapshot, so a login screen can bind to it instead of polling.

3. Send a one-time code

   Send a login code to the user’s email address or phone number. The contact is the account’s identity: a first login with it signs the user up, and later logins with the same contact find the same account.

   try await wallet.sendLoginCode(to: .email("[e-mail]"))
   // or by SMS:
   // try await wallet.sendLoginCode(to: .phone("[phone]"))
   

   Calling sendLoginCode again for the same contact issues a new code and replaces the pending one, which is how you implement Resend code. A blank email or a phone number that isn’t a valid international number throws RainError.invalidConfig before anything leaves the device.

4. Confirm the code and create the wallet

   Pass the code the user typed. On a first login the SDK signs the user up and creates one wallet holding an Ethereum account and a Solana account, from a single seed, in the same request. On a returning login it finds the existing account.

   do {
       try await wallet.confirmLoginCode(code)
   } catch let error as RainError where error == .invalidLoginCode {
       // RAIN_203: wrong, expired, or already-used code. Keep the screen up and let the user retype it.
   }
   

   A wrong code keeps the pending challenge, so the user can retype it without requesting a new one. Codes expire after 5 minutes and lock after 3 wrong attempts.

   The user is logged in and their wallet exists. A successful login also ends the user’s sessions on other devices; the signed-out device’s onSessionExpired fires on its next call.

5. Build the SDK and resolve the wallet

   Register the provider with the chains you want to use and build the SDK. Then resolve the wallet-bound RainClient. Resolution suspends once, while the SDK materializes the wallet, and is cached afterwards.

   let rain = try RainSdk.builder()
       .rpcEndpoints([
           RainChain.baseSepolia: "https://sepolia.base.org",
           RainChain.solanaDevnet: "https://api.devnet.solana.com",
       ])
       .register(wallet)
       .build()
   
   let client = try await rain.provider(.rain)
   
   let evmAddress = try await client.getWalletAddress()                              // "0x…"
   let solanaAddress = try await client.getWalletAddress(chainId: RainChain.solanaDevnet) // base58
   

   Resolving before a session is live throws RainError.tokenExpired (RAIN_201). Send the EVM address (and the Solana address, if you use Solana) to your backend: creating the user’s Rain application requires it. See Wallet creation.

6. Send a transaction

   Fund the wallet with testnet USDC first (the Circle faucet supports Base Sepolia), then send some of it to another address you control. Amounts are Decimal in human units; the SDK resolves the token’s decimals and converts exactly.

   let usdc = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"   // Base Sepolia USDC
   let recipient = "0x..."                                     // an address you control
   
   let balance = try await client.getBalance(
       chainId: RainChain.baseSepolia,
       token: .contract(address: usdc)
   )
   print(balance.formatted, balance.symbol ?? "")   // "10" "USDC"
   
   let result = try await client.sendToken(
       chainId: RainChain.baseSepolia,
       contractAddress: usdc,
       to: recipient,
       amount: 1.5
   )
   print(result.transactionHash)
   

   Gas is sponsored by default, so the wallet doesn’t need ETH to send. Native sends use client.sendNative(chainId:to:amount:).

   You’ve logged in, created a wallet, and sent a token. Everything else on RainClient follows the same shape: balances and history, receiving funds, and card funding.

Log in with a passkey instead

Users can log in with an existing passkey or add a passkey to their account for future authentication.

Configure passkeyDomain during SDK setup. The anchor parameter specifies the window used to display the system passkey prompt.

// Returning user with a passkey on this account:
try await wallet.loginWithPasskey(anchor: window)

// Logged in with a code? Register a passkey for next time:
try await wallet.addPasskey(anchor: window)

Use signUpWithPasskey(anchor:) only when creating a new account. Returning users should use loginWithPasskey(anchor:) to access their existing wallet.

See Authentication options for additional configuration and recovery guidance.

Log out and clean up

Use logout() to end the user’s session and close() to release SDK resources.

try await wallet.logout()   // clears the stored session; safe when none exists
rain.close()                // tears down resolved clients and stops the provider's session watcher

Calling rain.close() permanently closes the SDK instance. Create a new RainSdk instance before the next login. Use rain.reset() instead if you only need to clear resolved clients while keeping the provider active.

Using an existing wallet provider

If your application already uses Portal, Privy, or your own Turnkey organization, register the corresponding provider adapter instead of RainProvider. Authentication and session management remain with your existing provider. Subsequent wallet operations use the same RainClient interface.

import RainPortal   // re-exports RainCore, like RainWallet does

let rain = try RainSdk.builder()
    .rpcEndpoints([RainChain.baseSepolia: "https://sepolia.base.org"])
    .register(PortalProvider(PortalConfig(sessionToken: portalSessionToken)))
    .build()

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

For setup instructions and supported capabilities, see Third party wallet providers.

What’s next

Features

What each platform and chain supports.

Testing

Testnets, test tokens, and the pre-go-live checklist.

Error reference

Every RAIN_* code and how to handle it.