> ## Documentation Index
> Fetch the complete documentation index at: https://turnkey-0e7c1f5b-onramp-quick-fix.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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, organization, and API keypair as described in the [Account Setup](/getting-started/quickstart) section.
## Installation
Create a new Next.js app via `npx create-next-app@latest`. Or install into an existing project.
```bash npm
npm install @turnkey/sdk-react
```
```bash pnpm
pnpm add @turnkey/sdk-react
```
```bash yarn
yarn add @turnkey/sdk-react
```
**Technical Requirements**
**Next.js App Router Required**
`@turnkey/sdk-react` requires the Next.js App Router architecture as it leverages React Server Components and Server Actions to handle authentication on your behalf. The SDK automatically manages the "use client" and "use server" directives. The Pages Router is not supported.
**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](https://ui.shadcn.com/docs/react-19).
## Setup
The following environment variables are necessary to use the Turnkey SDK.
```bash .env
NEXT_PUBLIC_ORGANIZATION_ID=
TURNKEY_API_PUBLIC_KEY=
TURNKEY_API_PRIVATE_KEY=
NEXT_PUBLIC_BASE_URL=https://api.turnkey.com
```
**Note**: These environment variable names must be used exactly as shown.
The SDK depends on them internally for server actions and authentication.
Fill in with your Organization ID and API Base URL.
```tsx src/app/layout.tsx
const config = {
apiBaseUrl: "https://api.turnkey.com",
defaultOrganizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID,
};
```
Wrap your layout with the `TurnkeyProvider` component, and import styles from sdk-react.
```tsx src/app/layout.tsx
import "./globals.css";
import { TurnkeyProvider } from "@turnkey/sdk-react";
import "@turnkey/sdk-react/styles"; // required to render auth component styles properly
const config = {
apiBaseUrl: "https://api.turnkey.com",
defaultOrganizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!,
};
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
**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
```
{/* @ts-ignore */} {children}
```
We're actively working towards React 19 compatibility.
## Authenticate
The auth component contains the UI and logic to handle the authentication flow.
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.
```tsx src/app/page.tsx
"use client";
export default function Home() {
// The auth methods to display in the UI
const config = {
authConfig: {
emailEnabled: true,
// Set the rest to false to disable them
passkeyEnabled: false,
phoneEnabled: false,
appleEnabled: false,
facebookEnabled: false,
googleEnabled: false,
walletEnabled: false,
},
// The order of the auth methods to display in the UI
configOrder: ["email" /* "passkey", "phone", "socials" */],
};
return ;
}
```
```
type AuthConfig = {
emailEnabled: boolean;
passkeyEnabled: boolean;
phoneEnabled: boolean;
appleEnabled: boolean;
googleEnabled: boolean;
facebookEnabled: boolean;
walletEnabled: boolean;
};
```
Import the auth component into your app and pass in the config object.
```tsx src/app/page.tsx
"use client";
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,
walletEnabled: false,
},
configOrder: ["email"],
};
return (
);
}
```
Define two functions 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. The `onAuthSuccess` function will route the user to the dashboard after successful authentication.
A new [sub-organization](/concepts/sub-organizations) and [wallet](/concepts/wallets) is created for each new user during the authentication flow.
```tsx 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 router = useRouter();
const onAuthSuccess = async () => {
// We'll add the dashboard route in the next step
router.push("/dashboard");
};
const onError = (errorMessage: string) => {
setErrorMessage(errorMessage);
};
// Add the handlers to the config object
const config = {
// ...
onAuthSuccess: onAuthSuccess,
onError: onError,
};
return (
);
}
```
Add a dashboard route to the app where the user will be able to view their account and sign messages.
```tsx src/app/dashboard/page.tsx
export default function Dashboard() {
return
Dashboard
;
}
```
Since the app is wrapped with the `TurnkeyProvider` component, the `useTurnkey` hook is available to all child components. Calling `turnkey.getSession()` will return the current user's session information from local storage.
Add a state variable to store the user:
```tsx src/app/dashboard/page.tsx
import { useState, useEffect } from "react";
import { useTurnkey } from "@turnkey/sdk-react";
import { Session } from "@turnkey/sdk-types";
export default function Dashboard() {
const { turnkey } = useTurnkey();
const [session, setSession] = useState(null);
useEffect(() => {
if (turnkey) {
turnkey.getSession().then((session) => {
setSession(session ?? null);
});
}
}, [turnkey]);
return
Dashboard
;
}
```
#### User Session
```ts
export type Session = {
sessionType: SessionType;
userId: string;
organizationId: string;
expiry: number; // Unix timestamp representing the expiry of the session set by the server
token: string; // publicKey used to verify stamped requests (lives in IndexedDB); can temporarily be a read bearer token
};
```
## Sign Message
Turnkey supports signing arbitrary messages with the [`signRawPayload`](/api-reference/signing/sign-raw-payload) method.
The `signRawPayload` method requires these parameters:
* `payload`: The raw unsigned payload to sign
* `signWith`: The signing address (wallet account, private key address, or private key ID)
* `encoding`: The message encoding format
* `hashFunction`: The selected hash algorithm
For simplicity, a human readable string, `message`, will be the payload to sign. Add a state variable to store the message and an input field to allow the user to enter the message:
```tsx src/app/dashboard/page.tsx
import { useState, useEffect } from "react";
export default function Dashboard() {
//...
const [message, setMessage] = useState("");
//...
return (
setMessage(e.target.value)}
placeholder="Enter message to sign"
className="w-full px-4 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-indigo-500"
/>
);
}
```
Signing messages requires a signer e.g. a Turnkey wallet address to sign with and a payload or message to sign. A new wallet is created for each user during the authentication flow.
Create a function called `getSignWith`, to get the user's wallet account address which will be used to sign the message.
Use the `getSession` method from the `useTurnkey` hook to get the user's read-write session:
```tsx src/app/dashboard/page.tsx
import { useState, useEffect } from "react";
import { useTurnkey } from "@turnkey/sdk-react";
import { Session } from "@turnkey/sdk-types";
export default function Dashboard() {
const { turnkey, indexedDbClient } = useTurnkey();
const [session, setSession] = useState(null);
const client = indexedDbClient;
if (session) {
// The user's sub-organization id
const organizationId = session?.organizationId;
// Get the user's wallets
const wallets = await client?.getWallets({
organizationId,
});
// Get the first wallet of the user
const walletId = wallets?.wallets[0].walletId ?? '';
// Use the `walletId` to get the accounts associated with the wallet
const accounts = await client?.getWalletAccounts({
organizationId,
walletId,
});
// find an Ethereum account
const matchingAccount = accounts?.accounts.find(
(account) => account.addressFormat === 'ADDRESS_FORMAT_ETHEREUM'
);
const signWith = matchingAccount?.address ?? '';
console.log('signWith:', signWith);
return signWith;
} else {
// log out and clear session
}
useEffect(/* ... */*/);
return (/*
...
*/*/);
}
```
Create a function called `signMessage`. This function will:
* Get the user's wallet account for signing the message
* Compute the keccak256 hash of the message
* Call the `signRawPayload` method
Note: To compute the `keccak256` hash of the message, this example uses the `hashMessage` function from `viem`. However, any other hashing library can be used.
```tsx
const signMessage = async () => {
try {
const payload = hashMessage(message);
const signWith = await getSignWith();
if (!signWith) {
throw new Error('Missing signWith value');
}
const signature = await client?.signRawPayload({
payload,
signWith,
// The message encoding format
encoding: 'PAYLOAD_ENCODING_TEXT_UTF8',
// The hash function used to hash the message
hashFunction: 'HASH_FUNCTION_KECCAK256',
});
if (signature?.r && signature?.s && signature?.v) {
const fullSignature = `0x${signature.v}${signature.r}${signature.s}`;
setSignature(fullSignature);
} else {
setSignature(null);
console.warn('Incomplete signature components');
}
} catch (err) {
console.error('Signing failed:', err);
setSignature('Error signing message');
}
};
```
Add a button to the UI to trigger the `signMessage` function.
```tsx src/app/dashboard/page.tsx
import { useState, useEffect } from "react";
import { useTurnkey } from "@turnkey/sdk-react";
import { hashMessage } from "viem";
export default function Dashboard() {
//...
const [message, setMessage] = useState("");
const signMessage = async () => {
try {
const payload = hashMessage(message);
const signWith = await getSignWith();
if (!signWith) {
throw new Error('Missing signWith value');
}
const signature = await client?.signRawPayload({
payload,
signWith,
// The message encoding format
encoding: 'PAYLOAD_ENCODING_TEXT_UTF8',
// The hash function used to hash the message
hashFunction: 'HASH_FUNCTION_KECCAK256',
});
if (signature?.r && signature?.s && signature?.v) {
const fullSignature = `0x${signature.v}${signature.r}${signature.s}`;
setSignature(fullSignature);
} else {
setSignature(null);
console.warn('Incomplete signature components');
}
} catch (err) {
console.error('Signing failed:', err);
setSignature('Error signing message');
}
};
return (
The auth component contains the UI and logic to handle the authentication flow.