Turnkey

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)

Install the React Wallet Kit

Install the Turnkey React Wallet Kit in your Next.js app.

Install dependencies

npm install @turnkey/react-wallet-kit

Add environment variables

Store your IDs in .env.local so your app can initialize Turnkey.

Create .env.local

NEXT_PUBLIC_ORGANIZATION_ID="your-org-id"
NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID="your-auth-proxy-config-id"

Wrap your app with TurnkeyProvider

Initialize Turnkey at the app root and include the wallet kit styles.

App Router
Pages Router

Create a client-side provider component, then wrap it in app/layout.tsx.

app/providers.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

// 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>
  );
}

Wrap your app in pages/_app.tsx.

pages/_app.tsx

// pages/_app.tsx
import type { AppProps } from "next/app";
import "@turnkey/react-wallet-kit/styles.css";
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 default function App({ Component, pageProps }: AppProps) {
  return (
    <TurnkeyProvider
      config={turnkeyConfig}
      callbacks={{
        onError: (error) => console.error("Turnkey error:", error),
      }}
    >
      <Component {...pageProps} />
    </TurnkeyProvider>
  );
}

Connect a user

Use Turnkey’s modal and show a connected state when login completes.

Connect button

"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>;
}

Theme the Turnkey UI

Use theming to customize the Turnkey UI.

See authentication for custom login flows.

Privy

⌘I

Troubleshooting

Trading API

Wallets

Prerequisites

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

​Prerequisites

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

Prerequisites

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