Demo Embedded Wallet

Turnkey-based embedded wallet demo built with Next.js. It supports Ethereum, Base, and Solana, on mainnet or testnet. This README is written for developers who want to understand the architecture and fork their own version quickly.

The app is backendless: authentication, wallet management, balances, and transactions all run client-side against Turnkey's Embedded Wallet Kit (@turnkey/react-wallet-kit) and the managed Auth Proxy. Sending is done with Turnkey's transaction management (gas-sponsored), and balances come from Turnkey's Balances API. There are no server actions, no third-party RPC/indexer, and no server API keys.

Table of Contents

• Quickstart
• Configuration
• Architecture Overview
• Key Flows (Sequence Diagrams)
• Feature Tour (What the App Does)
• Co-signing and Policies
• Config Panel
• Turnkey Integration Details
• Troubleshooting
• Networks
• Project Structure
• Scripts

Quickstart

1. Install dependencies

pnpm install

2. Enable the Auth Proxy in the Turnkey dashboard (Embedded Wallets → Configuration), choose the auth methods you want (email OTP, passkey, OAuth, external wallet), set OAuth client IDs + redirect URL there, and copy your Organization ID and Auth Proxy Config ID. To use gas-sponsored sends, also enable Gas Sponsorship for the org.

3. Create .env.local

cp .env.example .env.local

4. Fill the two required variables (see Configuration).
5. Run the app

pnpm dev

Configuration

Environment variables are validated at startup via @t3-oss/env-nextjs in src/env.mjs. Empty values are treated as unset. Set SKIP_ENV_VALIDATION=1 to bypass validation for local builds (pnpm build:local).

Because the app is backendless and the Auth Proxy serves auth configuration (enabled methods, OAuth client IDs, redirect URL, session length, OTP settings) from the dashboard, the app only needs two variables:

Required

Variable	Description
NEXT_PUBLIC_ORGANIZATION_ID	Your Turnkey parent organization ID
NEXT_PUBLIC_AUTH_PROXY_ID	Auth Proxy config ID (dashboard → Embedded Wallets → Configuration)

Optional

Variable	Description
NEXT_PUBLIC_BASE_URL	Turnkey API base URL (defaults to https://api.turnkey.com)
NEXT_PUBLIC_AUTH_PROXY_URL	Auth Proxy endpoint (defaults to https://authproxy.turnkey.com)
NEXT_PUBLIC_OAUTH_REDIRECT_URI	Overrides the dashboard's OAuth redirect URL for every provider. Use it for local dev (e.g. http://localhost:3000/)
NEXT_PUBLIC_POLICY_MANAGER_PUBLIC_KEY	Public key of the Policy Manager API key, used for co-signing. Without it, co-signing setup fails

Policy admin CLI only

These are read only by scripts/policy-admin.ts. Never give them a NEXT_PUBLIC_ prefix and don't add them to the web deployment.

Variable	Description
TURNKEY_POLICY_MANAGER_PRIVATE_KEY	Private half of the Policy Manager key. A root user of every sub-org
TURNKEY_SUBORG_ID	Default sub-org the CLI operates on (override per run with --org <id>)

Everything else — which auth methods appear, OAuth client IDs, OAuth redirect URL, session expiration, OTP length/type, email branding — is configured on the Turnkey dashboard and fetched by the SDK via the Auth Proxy's wallet_kit_config. See Config Panel for overriding the presentation of these at runtime.

Dashboard setting: account lookups

The passkey sign-in flow calls proxyGetAccount to check whether an account already exists for the entered email, so it can route to login vs. sign-up before the user authenticates. For that pre-login lookup to succeed, disable Require token for account lookups in the Auth Proxy configuration (dashboard → Embedded Wallets → Configuration).

With that setting off, account-existence lookups are unauthenticated (an email can be probed for whether it has an account). That is acceptable for a demo; a production app should leave the setting enabled and route login vs. sign-up with an authenticated lookup (e.g. server-side, or after an OTP verification token is obtained).

This is the beginning of the README. Read the rest at the original. Read the full README ↗