Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tkhq/sdk/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through integrating Turnkey into a React application using @turnkey/react-wallet-kit. It is the recommended path for most web applications.

​
Prerequisites

  • Node.js 18 or later
  • A Turnkey account with an organization created (sign up at app.turnkey.com)
  • Your Organization ID from the Turnkey dashboard
  • An Auth Proxy Config ID from the Turnkey dashboard
The Auth Proxy Config ID is found in the Turnkey dashboard under Auth Proxy. It enables the SDK to authenticate browser-side requests through Turnkey’s managed proxy without exposing your server API keys to the client.

​
React quickstart

1

Install @turnkey/react-wallet-kit

Add the package to your project using your preferred package manager.
npm install @turnkey/react-wallet-kit
If you are starting from scratch, first create a Next.js app:
terminal
npx create-next-app@latest
2

Set up environment variables

Add your Turnkey credentials to your environment file. In a Next.js project, use .env.local.
.env.local
NEXT_PUBLIC_ORGANIZATION_ID=your-organization-id
NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID=your-auth-proxy-config-id
Both values are available in the Turnkey dashboard.
3

Wrap your app with TurnkeyProvider

With Next.js App Router, keep app/layout.tsx as a server component and create a separate app/providers.tsx client wrapper. This is required to pass callbacks (such as onError), which must be defined in a client component.
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>;
}
You can also add an onError callback to handle errors in one place:
app/providers.tsx
<TurnkeyProvider
  config={turnkeyConfig}
  callbacks={{
    onError: (error) => console.error("Turnkey error:", error),
  }}
>
  {children}
</TurnkeyProvider>
Then import and use your Providers wrapper in app/layout.tsx. Import the SDK styles here too.
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>
  );
}
Keeping layout.tsx as a server component maintains optimal rendering and avoids making your entire app client-side. Centralizing Turnkey setup in providers.tsx keeps configuration, styles, and callbacks in one place.
4

Add a login button

The easiest way to handle authentication is with the handleLogin function from the useTurnkey hook. Calling it opens a modal with all authentication methods you have enabled in your Turnkey dashboard.
components/LoginButton.tsx
"use client";

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

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

  return <button onClick={handleLogin}>Login / Sign Up</button>;
}
The handleLogin function supports passkeys, email OTP, SMS OTP, and OAuth providers (Google, Apple, Facebook, X, Discord) — whichever you have enabled in your Auth Proxy Config.
5

Access the wallet after login

After authentication, the useTurnkey hook exposes the current session, user, and wallets state. You can use these to show wallet addresses or trigger signing operations.
components/WalletDisplay.tsx
"use client";

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

export function WalletDisplay() {
  const { session, user, wallets } = useTurnkey();

  if (!session) {
    return <p>Not logged in.</p>;
  }

  return (
    <div>
      <p>Logged in as: {user?.username}</p>
      <ul>
        {wallets.map((wallet) => (
          <li key={wallet.walletId}>{wallet.walletName}</li>
        ))}
      </ul>
    </div>
  );
}

​
Server-side quickstart

To interact with the Turnkey API from a Node.js backend, use @turnkey/sdk-server. 
npm install @turnkey/sdk-server
Instantiate the server client and set up a proxy handler:
server.js
const { Turnkey } = require("@turnkey/sdk-server");
const fs = require("fs");

// Load config containing API credentials, base URL, and org ID
const turnkeyConfig = JSON.parse(fs.readFileSync("./turnkey.json", "utf8"));

const turnkeyServerClient = new Turnkey(turnkeyConfig);

// Attach a proxy endpoint to forward authenticated requests from the browser
const turnkeyProxyHandler = turnkeyServerClient.expressProxyHandler({});

app.post("/apiProxy", turnkeyProxyHandler);

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

​
Next steps

Core concepts

Learn about organizations, sub-organizations, wallets, stampers, and how Turnkey’s auth model works.

@turnkey/react-wallet-kit

Full reference for the React Wallet Kit package, including all config options and hook methods.

Authentication guide

Deep dive into authentication flows: passkeys, OTP, OAuth, and wallet-based login.

Blockchain signers

Connect a Turnkey wallet to ethers.js, viem, Solana, or CosmJS.