Skip to main content

Embedded Wallets Quickstart

Turnkey's Embedded Wallets enable you to integrate secure, custom wallet experiences directly into your product. With features like advanced security, seamless authentication, and flexible UX options, you can focus on building great products while we handle the complexities of private key management.

Prerequisites​

This guide assumes you've completed the steps to create an account and organization as described in the Getting Started section.

Installation​

Create a new Next.js app via npx create-next-app@latest. Or install into an existing project.

npm install @turnkey/sdk-react
note

React 19 Users

If you're using Next.js 15 with React 19 you may encounter an installation error with @turnkey/sdk-react. Consider:

  • Downgrading React to 18.x.x
  • Using npm install --force or --legacy-peer-deps

You may learn more about this here.

Add Turnkey to your app​

Configure

Fill in with your Organization ID and API Base URL.

src/app/layout.tsx
const config = {
  apiBaseUrl: "https://api.turnkey.com",
  defaultOrganizationId: process.env.NEXT_PUBLIC_TURNKEY_ORGANIZATION_ID,
};

Provider

Wrap your layout with the TurnkeyProvider component.

src/app/layout.tsx
import { TurnkeyProvider } from "@turnkey/sdk-react";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <TurnkeyProvider config={config}>{children}</TurnkeyProvider>
      </body>
    </html>
  );
}
note

React 19 Users

@turnkey/sdk-react is built with React 18. If you're using React 19 you'll find a type mismatch on the children type.

To fix this, you can use the @ts-ignore directive to suppress the error.

src/app/layout.tsx
<TurnkeyProvider config={config}>
  {/* @ts-ignore */}
  {children}
</TurnkeyProvider>

We're actively working towards React 19 compatibility.

Auth Component​

Auth Component

The auth component contains the UI and logic to handle the authentication flow.

Configure

For simplicity, this app will only support email authentication. We have other guides on additional authentication methods. Additionally, you can customize the order in which the auth methods are displayed.

src/app/page.tsx
export default function Home() {
  // The auth methods to display in the UI
  const config = {
    authConfig: {
      emailEnabled: true,
      passkeyEnabled: false,
      phoneEnabled: false,
      appleEnabled: false,
      facebookEnabled: false,
      googleEnabled: false,
    },
    // The order of the auth methods to display in the UI
    configOrder: ["email" /* "passkey", "phone", "socials" */],
  };

  return <div></div>;
}
Auth Config Options
type AuthConfig = {
  emailEnabled: boolean;
  passkeyEnabled: boolean;
  phoneEnabled: boolean;
  appleEnabled: boolean;
  googleEnabled: boolean;
  facebookEnabled: boolean;
};

Import

Import the auth component into your app and pass in the config object.

src/app/page.tsx
import { Auth } from "@turnkey/sdk-react";

export default function Home() {
  const config = {
    authConfig: {
      emailEnabled: true,
      passkeyEnabled: false,
      phoneEnabled: false,
      appleEnabled: false,
      facebookEnabled: false,
      googleEnabled: false,
    },
    configOrder: ["email"],
  };

  return (
    <div>
      <Auth {...config} />
    </div>
  );
}

Handlers

Define two function to handle the "success" and "error" states. Initially, the onError function will set an errorMessage state variable which will be used to display an error message to the user.

src/app/page.tsx
"use client";

import { useState } from "react";
import { Auth } from "@turnkey/sdk-react";

export default function Home() {
  const [errorMessage, setErrorMessage] = useState("");

  const onAuthSuccess = async () => {};

  const onError = (errorMessage: string) => {
    setErrorMessage(errorMessage);
  };

  // Add the handlers to the config object
  const config = {
    // ...
    onAuthSuccess: onAuthSuccess,
    onError: onError,
  };

  return (
    <div>
      <Auth {...config} />
    </div>
  );
}