@crossmint/client-sdk-react-native-ui

React Native SDK for integrating Crossmint Wallets into your mobile application. Provides providers, hooks, and built-in UI for wallet creation, signing, and OTP verification.

Prerequisites

Get a client API key from the Crossmint developer console. Ensure your key has the Wallet API scopes enabled, including wallets.fund for stagingFund.

Installation

npx expo install @crossmint/client-sdk-react-native-ui expo-constants expo-device expo-secure-store expo-web-browser react-native-get-random-values react-native-webview

The SDK requires Expo SDK 58 (React Native 0.88, iOS 16.4 or later). The native modules are peer dependencies, and npx expo install picks the versions that match your Expo SDK.

Xcode 27 and iOS 27

Apps built with Xcode 27 (the iOS 27 SDK) must use the UIKit scene lifecycle. If they do not, they stop at launch with "UIScene life cycle is required for apps built with this SDK". Expo SDK 58 generates it: npx expo prebuild adds a SceneDelegate.swift and a scene manifest to Info.plist. No configuration is needed, and the Crossmint config plugin works with it.

After you upgrade to Expo SDK 58, regenerate the native project. If your app generates ios/ and android/ (continuous native generation), run npx expo prebuild --clean. If you maintain those folders by hand, --clean deletes your changes; apply the scene lifecycle changes to your own AppDelegate and Info.plist instead, as described in Expo's iOS scene lifecycle guide.

If your app config still sets ios.enableSceneSupport in expo-build-properties, you can remove it. It has no effect on Expo SDK 58.

Quick Start

1. Setup Providers

With Crossmint Auth (default in staging)

import {
  CrossmintProvider,
  CrossmintAuthProvider,
  CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-native-ui";

export default function App() {
  return (
    <CrossmintProvider apiKey={process.env.EXPO_PUBLIC_CROSSMINT_API_KEY}>
      <CrossmintAuthProvider>
        <CrossmintWalletProvider
          createOnLogin={{
            chain: "base-sepolia",
            recoveryMethods: [{ type: "email" }],
          }}
        >
          <MainApp />
        </CrossmintWalletProvider>
      </CrossmintAuthProvider>
    </CrossmintProvider>
  );
}

Bring Your Own Authentication

Use this when your app already has an auth provider, and in production: connect your provider and configure JWT Authentication in the Crossmint Console (see Move to Production). Then skip CrossmintAuthProvider and pass your provider's JWT to the wallets SDK. See the Custom Auth Guide for full details.

import {
  CrossmintProvider,
  CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-native-ui";

export default function App() {
  return (
    <CrossmintProvider apiKey={process.env.EXPO_PUBLIC_CROSSMINT_API_KEY}>
      <CrossmintWalletProvider
        createOnLogin={{
          chain: "base-sepolia",
          recoveryMethods: [
            {
              type: "email",
              email: "[email protected]",
            },
          ],
        }}
      >
        <MainApp />
      </CrossmintWalletProvider>
    </CrossmintProvider>
  );
}

2. Use Wallets

import { useWallet } from "@crossmint/client-sdk-react-native-ui";
import { View, Text, TouchableOpacity } from "react-native";

function WalletActions() {
  const { wallet, status } = useWallet();

  if (status === "in-progress") return <Text>Loading wallet...</Text>;
  if (!wallet) return <Text>No wallet</Text>;

  // Staging only: mints USDXM, Crossmint's test stablecoin, into the wallet
  const handleFund = async () => {
    await wallet.stagingFund(10);
  };

  const handleSend = async () => {
    const tx = await wallet.send("0xRecipient", "usdxm", "10");
    console.log("Transaction:", tx.explorerLink);
  };

  return (
    <View>
      <Text>Wallet: {wallet.address}</Text>
      <TouchableOpacity onPress={handleFund}>
        <Text>Get 10 USDXM</Text>
      </TouchableOpacity>
      <TouchableOpacity onPress={handleSend}>
        <Text>Send 10 USDXM</Text>
      </TouchableOpacity>
    </View>
  );
}

Providers

CrossmintWalletProvider Props

Hooks

useWallet()

Returns the wallet instance and management functions:

const {
  wallet,              // Wallet | undefined
  status,              // "not-loaded" | "in-progress" | "loaded" | "error"
  getWallet,           // (props: { chain, alias? }) => Promise<Wallet | undefined>
  createWallet,        // (props: ClientSideWalletCreateArgs) => Promise<Wallet | undefined>
  createDeviceSigner,  // () => Promise<DeviceSignerDescriptor> | undefined
  createPasskeySigner, // (name: string) => Promise<RegisterSignerPasskeyParams>
} = useWallet();

useWalletOtpSigner()

For custom OTP UI when using email/phone recovery methods. When showOtpSignerPrompt is set to false, use this hook to handle OTP flows manually:

const { needsAuth, sendOtp, verifyOtp, reject } = useWalletOtpSigner();

useCrossmintAuth()

Authentication state and OAuth login:

const { loginWithOAuth, logout, user } = useCrossmintAuth();

// OAuth providers
loginWithOAuth("google");
loginWithOAuth("twitter");

Components

ExportPrivateKeyButton

Renders a button to export the wallet's private key via TEE. Only renders for email/phone signers.

import { ExportPrivateKeyButton } from "@crossmint/client-sdk-react-native-ui";

<ExportPrivateKeyButton appearance={{ borderRadius: "12px" }} />

Differences from React SDK

Wallets SDK

The wallet object returned by useWallet() is a Wallet instance. For wallet method documentation (send, balances, sign, etc.), see the @crossmint/wallets-sdk README.

Environment Setup

1. Get your API key from Crossmint Console

2. Add to your .env:

EXPO_PUBLIC_CROSSMINT_API_KEY=your_api_key_here

3. Configure deep linking in app.json:

{
  "expo": {
    "scheme": "your-app-scheme"
  }
}

Documentation

• Crossmint Wallets Docs
• SDK Reference
• Wallets Expo Quickstart
• Custom Auth Guide (React Native)

License

Apache-2.0