@turnkey/react-wallet-kit

@turnkey/react-wallet-kit is the recommended package for integrating Turnkey Embedded Wallets into React applications. It provides a TurnkeyProvider context, a useTurnkey hook exposing all authentication and wallet methods, and a set of pre-built UI components for common flows.

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

Installation

npm install @turnkey/react-wallet-kit

Setup

Wrap your application with TurnkeyProvider and import the package stylesheet. With Next.js App Router, keep app/layout.tsx as a server component and create a separate client wrapper for the provider. This is required if you want to pass callbacks (such as onError), which must be defined in a client component.

Create a providers wrapper

app/providers.tsx

"use client";

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

const turnkeyConfig: TurnkeyProviderConfig = {
  organizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!,
  authProxyConfigId: process.env.NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID!,
};

export function Providers({ children }: { children: React.ReactNode }) {
  return <TurnkeyProvider config={turnkeyConfig}>{children}</TurnkeyProvider>;
}

Add an error callback (optional)

app/providers.tsx

<TurnkeyProvider
  config={turnkeyConfig}
  callbacks={{
    onError: (error) => console.error("Turnkey error:", error),
  }}
>

Import styles and use the provider in your root layout

app/layout.tsx

import "@turnkey/react-wallet-kit/styles.css";
import "./globals.css";
import { Providers } from "./providers";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Configuration

TurnkeyProvider accepts a config prop of type TurnkeyProviderConfig.

Required fields

organizationId

string

required

Your Turnkey parent organization ID.

authProxyConfigId

string

required

The Auth Proxy configuration ID from the Turnkey dashboard.

Authentication options (`config.auth`)

auth.methods

object

Enable or disable individual authentication methods.

Field	Type	Description
`emailOtpAuthEnabled`	`boolean`	Email OTP
`smsOtpAuthEnabled`	`boolean`	SMS OTP
`passkeyAuthEnabled`	`boolean`	Passkey (WebAuthn)
`walletAuthEnabled`	`boolean`	External wallet (MetaMask, Phantom, etc.)
`googleOauthEnabled`	`boolean`	Google OAuth
`appleOauthEnabled`	`boolean`	Apple OAuth
`xOauthEnabled`	`boolean`	X (Twitter) OAuth
`discordOauthEnabled`	`boolean`	Discord OAuth
`facebookOauthEnabled`	`boolean`	Facebook OAuth

auth.methodOrder

Array<'socials' | 'email' | 'sms' | 'passkey' | 'wallet'>

Controls the display order of authentication method groups in the login modal.

auth.oauthOrder

Array<'google' | 'apple' | 'facebook' | 'x' | 'discord'>

Controls the display order of OAuth provider buttons.

auth.oauthConfig

object

OAuth provider configuration.

Field	Type	Description
`oauthRedirectUri`	`string`	Redirect URI for all OAuth flows
`googleClientId`	`string`	Google OAuth client ID
`appleClientId`	`string`	Apple OAuth client ID
`facebookClientId`	`string`	Facebook OAuth client ID
`xClientId`	`string`	X (Twitter) OAuth client ID
`discordClientId`	`string`	Discord OAuth client ID
`openOauthInPage`	`boolean`	Redirect instead of popup (always true on mobile)

auth.sessionExpirationSeconds

string

Session expiration time in seconds. When using the Auth Proxy, configure this in the dashboard instead.

auth.autoRefreshSession

boolean

Automatically refresh sessions before they expire.

UI options (`config.ui`)

ui.logoLight

string

URL of a logo image to display at the top of the login modal in light mode.

ui.logoDark

string

URL of a logo image to display at the top of the login modal in dark mode.

ui.darkMode

boolean

Enable dark mode for all UI components.

ui.colors

object

Theme color overrides for light and dark modes. Accepts light and dark as partial ThemeOverrides objects.

ui.borderRadius

string | number

Border radius for UI elements. Accepts a pixel value or CSS string (e.g., 8 or "1rem").

ui.backgroundBlur

string | number

Background blur for modal overlays.

ui.preferLargeActionButtons

boolean

Use full-width buttons for actions like “Continue”. Defaults to small icon buttons.

Render the modal as a child of TurnkeyProvider instead of appending to the body. Useful for font inheritance and CSS scoping.

Callbacks (`callbacks`)

callbacks.onError

(error: TurnkeyError | TurnkeyNetworkError) => void

Called when any Turnkey error occurs.

callbacks.onAuthenticationSuccess

function

Called after a successful authentication. Receives { session, action, method, identifier }.

callbacks.onOauthRedirect

function

Called after an OAuth redirect flow completes. Receives { idToken, publicKey, sessionKey }.

callbacks.beforeSessionExpiry

(params: { sessionKey: string }) => void

Called before a session expires, allowing you to take action ahead of expiry.

callbacks.onSessionExpired

(params: { sessionKey: string }) => void

Called when a session has expired.

The `useTurnkey` hook

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

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

function LoginButton() {
  const { handleLogin } = useTurnkey();

  return <button onClick={handleLogin}>Login / Sign Up</button>;
}

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
`walletProviders`	`WalletProvider[]`	Connected external wallet providers
`config`	`TurnkeyProviderConfig \| undefined`	The active provider configuration

Authentication methods

Method	Description
`handleLogin(params?)`	Opens the login modal with all enabled authentication methods
`loginWithPasskey(params?)`	Authenticate using a passkey
`signUpWithPasskey(params?)`	Create a new account using a passkey
`loginWithWallet(params)`	Authenticate with a connected external wallet
`signUpWithWallet(params)`	Create a new account with a connected external wallet
`loginOrSignupWithWallet(params)`	Log in or create an account with an external wallet
`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 flow
`handleAppleOauth(params?)`	Initiate Apple OAuth flow
`handleFacebookOauth(params?)`	Initiate Facebook OAuth flow
`handleXOauth(params?)`	Initiate X (Twitter) OAuth flow
`handleDiscordOauth(params?)`	Initiate Discord OAuth flow
`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
`fetchWallets(params?)`	Fetch wallets without updating state
`createWallet(params)`	Create a new embedded wallet
`handleExportWallet(params)`	Open the export wallet modal (iframe-based)
`handleExportPrivateKey(params)`	Open the export private key modal
`handleExportWalletAccount(params)`	Open the export wallet account modal
`handleImportWallet(params?)`	Open the import wallet modal
`handleImportPrivateKey(params?)`	Open the import private key modal
`connectWalletAccount(provider)`	Connect an external wallet account
`handleConnectExternalWallet(params?)`	Open the connect external wallet modal
`handleSignMessage(params)`	Open the sign message modal
`handleSendTransaction(params)`	Open the send transaction modal

User management methods

Method	Description
`refreshUser(params?)`	Fetch the latest user details and update provider state
`handleUpdateUserEmail(params?)`	Open the update email modal with OTP verification
`handleAddEmail(params?)`	Open the add email modal
`handleRemoveUserEmail(params?)`	Open the remove email confirmation modal
`handleUpdateUserPhoneNumber(params?)`	Open the update phone number modal with OTP verification
`handleAddPhoneNumber(params?)`	Open the add phone number modal
`handleRemoveUserPhoneNumber(params?)`	Open the remove phone number confirmation modal
`handleUpdateUserName(params?)`	Open the update username modal
`handleAddPasskey(params?)`	Open the add passkey modal
`handleRemovePasskey(params)`	Open the remove passkey confirmation modal
`handleAddOauthProvider(params)`	Link a new OAuth provider to the user’s account
`handleRemoveOauthProvider(params)`	Remove a linked OAuth provider

Transaction and onramp methods

Method	Description
`handleSendTransaction(params)`	Sign and send an EVM or Solana transaction with a confirmation modal
`handleSendErc20Transfer(params)`	Sign and send an ERC-20 transfer with a confirmation modal
`handleOnRamp(params)`	Open a fiat on-ramp flow (MoonPay or Coinbase) to purchase crypto into an embedded wallet
`handleVerifyAppProofs(params)`	Verify app proofs against their corresponding boot proofs

Pre-built components

The package includes ready-to-use components for common flows. All components are modal-driven and opened via the useTurnkey hook methods above. The underlying component files are organized by category:

Authentication

Email OTP, SMS OTP, passkey, external wallet, and OAuth (Google, Apple, Facebook, X, Discord) login and sign-up flows. Located in src/components/auth/.

Export

Secure export of wallets, wallet accounts, and private keys via an encrypted iframe flow. Located in src/components/export/.

Import

Import wallets and private keys using an encrypted bundle. Located in src/components/import/.

Sign

Message signing modal with support for Ethereum prefix, custom encoding, and hash functions. Located in src/components/sign/.

Send transaction

EVM and Solana transaction sending with a confirmation modal. Located in src/components/send-transaction/.

On-ramp

Fiat on-ramp integration (MoonPay, Coinbase) for purchasing crypto directly into an embedded wallet. Located in src/components/onramp/.

User management

Modals for updating email, phone number, username, passkeys, and OAuth providers. Located in src/components/user/.

Verify

App proof verification flow for wallet-based signups. Located in src/components/verify/.

Get Started

SDK Packages

Blockchain Signers

Authentication & Stampers

Guides

Installation

Setup

Configuration

Required fields

Authentication options (`config.auth`)

UI options (`config.ui`)

Callbacks (`callbacks`)

The `useTurnkey` hook

State

Authentication methods

Wallet methods

User management methods

Transaction and onramp methods

Pre-built components

Authentication

Export

Import

Sign

Send transaction

On-ramp

User management

Verify

Build docs developers (and LLMs) love

Get Started

SDK Packages

Blockchain Signers

Authentication & Stampers

Guides

Documentation Index

​Installation

​Setup

​Configuration

​Required fields

​Authentication options (config.auth)

​UI options (config.ui)

​Callbacks (callbacks)

​The useTurnkey hook

​State

​Authentication methods

​Wallet methods

​User management methods

​Transaction and onramp methods

​Pre-built components

Authentication

Export

Import

Sign

Send transaction

On-ramp

User management

Verify

Build docs developers (and LLMs) love

Installation

Setup

Configuration

Required fields

Authentication options (`config.auth`)

UI options (`config.ui`)

Callbacks (`callbacks`)

The `useTurnkey` hook

State

Authentication methods

Wallet methods

User management methods

Transaction and onramp methods

Pre-built components