Skip to main content
Use Turnkey Embedded Wallet Kit to add authentication and embedded wallets to a Next.js + React app.

​
Prerequisites

Create a Turnkey organization in the Turnkey dashboard, enable Auth Proxy, email OTP, and passkeys. Copy your Organization ID and Auth Proxy Config ID.

​
Step-by-step (Next.js + React)

1

Install the React Wallet Kit

Install the Turnkey React Wallet Kit in your Next.js app.
npm install @turnkey/react-wallet-kit
2

Add environment variables

Store your IDs in .env.local so your app can initialize Turnkey.
NEXT_PUBLIC_ORGANIZATION_ID="your-org-id"
NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID="your-auth-proxy-config-id"
3

Wrap your app with TurnkeyProvider

Initialize Turnkey at the app root and include the wallet kit styles.
Create a client-side provider component, then wrap it in app/layout.tsx.
// 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}
      callbacks={{
        onError: (error) => console.error("Turnkey error:", error),
      }}
    >
      {children}
    </TurnkeyProvider>
  );
}

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

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

Connect a user

Use Turnkey’s modal and show a connected state when login completes.
"use client";

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

export default function ConnectButton() {
  const { handleLogin, authState, clientState } = useTurnkey();

  if (clientState === undefined || clientState === ClientState.Loading) {
    return <p>Loading...</p>;
  }
  if (clientState === ClientState.Error) {
    return <p>Turnkey failed to initialize.</p>;
  }
  if (authState === AuthState.Authenticated) {
    return <p>Connected</p>;
  }

  return <button onClick={handleLogin}>Connect Wallet</button>;
}
5

Theme the Turnkey UI

Use theming to customize the Turnkey UI.
See authentication for custom login flows.