@turnkey/react-native-wallet-kit

Embedded wallet integration for React Native applications

@turnkey/react-native-wallet-kit is the recommended package for integrating Turnkey Embedded Wallets into React Native applications. It works with both Expo and bare React Native projects and provides the same TurnkeyProvider and useTurnkey hook pattern as the web SDK.

This package supersedes @turnkey/sdk-react-native. New projects should use @turnkey/react-native-wallet-kit directly.

Installation

npm install @turnkey/react-native-wallet-kit

Peer dependencies

Install all required peer dependencies:

npm install react react-native react-native-passkey react-native-inappbrowser-reborn react-native-gesture-handler react-native-safe-area-context react-native-svg @react-native-async-storage/async-storage react-native-get-random-values react-native-url-polyfill buffer

Setup

Expo polyfills

If you are using Expo, import the required polyfills early in your root layout file and ensure Buffer is available globally:

import "react-native-get-random-values";
import "react-native-url-polyfill/auto";
import { Buffer } from "buffer";
(global as any).Buffer = (global as any).Buffer || Buffer;

Provider

Wrap your application with TurnkeyProvider:

import { TurnkeyProvider } from "@turnkey/react-native-wallet-kit";

export default function App() {
  return (
    <TurnkeyProvider
      config={{
        organizationId: "your-organization-id",
        authProxyConfigId: "your-auth-proxy-config-id",
      }}
    >
      {/* Your app content */}
    </TurnkeyProvider>
  );
}

Configuration

TurnkeyProvider accepts a config prop with the following required fields:

organizationId · string · required

Your Turnkey parent organization ID.

authProxyConfigId · string · required

The Auth Proxy configuration ID from the Turnkey dashboard.

The useTurnkey hook

Import useTurnkey inside any component that is a descendant of TurnkeyProvider.

import { useTurnkey, AuthState } from "@turnkey/react-native-wallet-kit";

function LoginButton() {
  const { loginWithPasskey, loginWithOtp, handleGoogleOauth } = useTurnkey();

  return (
    <>
      <Button title="Login with Passkey" onPress={() => loginWithPasskey()} />
      <Button
        title="Login with Email OTP"
        onPress={async () => {
          // initialize + verify OTP as needed, then:
          await loginWithOtp({ email: "[e-mail]", otp: "123456" });
        }}
      />
      <Button title="Login with Google" onPress={() => handleGoogleOauth()} />
    </>
  );
}

State

Property	Type	Description
authState	AuthState	"authenticated" or "unauthenticated"
clientState	ClientState	"loading", "ready", or "error"
session	Session | undefined	The active session object
user	v1User | undefined	The authenticated user
wallets	Wallet[]	The user’s embedded wallets

Authentication methods

Method	Description
loginWithPasskey(params?)	Authenticate using a device passkey
signUpWithPasskey(params?)	Create a new account using a passkey
initOtp(params)	Send an OTP to the user’s email or phone
verifyOtp(params)	Verify the OTP code
loginWithOtp(params)	Log in using an OTP verification token
signUpWithOtp(params)	Sign up using an OTP verification token
handleGoogleOauth(params?)	Initiate Google OAuth via in-app browser
handleAppleOauth(params?)	Initiate Apple OAuth via in-app browser
handleFacebookOauth(params?)	Initiate Facebook OAuth via in-app browser
handleXOauth(params?)	Initiate X (Twitter) OAuth via in-app browser
handleDiscordOauth(params?)	Initiate Discord OAuth via in-app browser
logout(params?)	Log out from the active or specified session

Wallet methods

Method	Description
refreshWallets(params?)	Fetch the latest list of wallets and update provider state
createWallet(params)	Create a new embedded wallet
exportWallet(params)	Export a wallet; decrypts and returns the mnemonic by default
exportPrivateKey(params)	Export a private key; returns raw key material by default
exportWalletAccount(params)	Export a wallet account; returns raw key material by default
importWallet(params)	Import a wallet by mnemonic
importPrivateKey(params)	Import a private key

User management methods

Method	Description
refreshUser(params?)	Fetch the latest user details and update provider state

OAuth flows on React Native

All OAuth flows on React Native use the in-app browser (react-native-inappbrowser-reborn) and deep-link back to the app on completion. The openInPage option available in the web SDK is not applicable on React Native — the in-app browser is always used.

const { handleGoogleOauth } = useTurnkey();

// Open Google OAuth in the in-app browser
await handleGoogleOauth({
  clientId: "your-google-client-id",
  onOauthSuccess: ({ oidcToken, providerName, publicKey }) => {
    console.log("OAuth success:", providerName);
  },
});

Export and import without iframes

Unlike the web SDK, key export and import on React Native do not use iframes. The provider handles decryption natively using a generated P-256 key pair:

const { exportWallet } = useTurnkey();

// Returns the decrypted mnemonic string by default
const mnemonic = await exportWallet({ walletId: "wallet-id" });

// Set decrypt: false to receive the raw encrypted bundle
const bundle = await exportWallet({ walletId: "wallet-id", decrypt: false });