Skip to content

WaaS docs #613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MasterHW wants to merge 3 commits into
base: main
Choose a base branch
from
Open

WaaS docs #613

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
26830be
initial commit
MasterHW Mar 27, 2026
af9b358
partial selma copy edits
MasterHW Mar 30, 2026
8cb9d90
more copy edits
MasterHW Mar 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 32 additions & 2 deletions category/code-examples.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,40 @@ mode: wide
---

<CardGroup>
<Card title="Create a sub-org with a passkey user" href="/embedded-wallets/code-examples/create-sub-org-passkey" icon="file-lines" iconType="solid" horizontal>
Create a sub-org with a passkey user
<Card title="Embedded Consumer Wallet" href="/embedded-wallets/code-examples/embedded-consumer-wallet" icon="file-lines" iconType="solid" horizontal>
Embedded Consumer Wallet
</Card>

<Card
title="Embedded Business Wallet"
href="/products/embedded-business-wallets/overview"
icon="file-lines"
iconType="solid"
horizontal
>
Embedded Business Wallet
</Card>

<Card
title="Embedded Wallet-as-a-Service"
href="/embedded-wallets/embedded-waas"
icon="file-lines"
iconType="solid"
horizontal
>
Embedded Wallet-as-a-Service
</Card>

<Card
title="Create a sub-org with a passkey user"
href="/embedded-wallets/code-examples/create-sub-org-passkey"
icon="file-lines"
iconType="solid"
horizontal
>
Create a sub-org with a passkey user
</Card>

<Card
title="Authenticate a user with a passkey credential"
href="/embedded-wallets/code-examples/authenticate-user-passkey"
Expand Down
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,7 @@
"category/code-examples",
"embedded-wallets/code-examples/embedded-consumer-wallet",
"products/embedded-business-wallets/overview",
"embedded-wallets/embedded-waas",
"embedded-wallets/code-examples/create-sub-org-passkey",
"embedded-wallets/code-examples/authenticate-user-passkey",
"embedded-wallets/code-examples/create-passkey-session",
Expand Down
115 changes: 90 additions & 25 deletions embedded-wallets/code-examples/embedded-consumer-wallet.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,34 @@
---
title: "Embedded Consumer Wallet"
description: "Turnkey provides wallet infrastructure with flexible authentication, programmable transaction flows, and granular access controls, while keys remain in hardware-backed enclaves. Start with the Embedded Wallet Kit and drop down to low-level primitives when you need to customize. "
description:
"Turnkey provides wallet infrastructure with flexible authentication, programmable transaction
flows, and granular access controls, while keys remain in hardware-backed enclaves. Start with the
Embedded Wallet Kit and drop down to low-level primitives when you need to customize. "
---

**Why Turnkey for Embedded Consumer Wallets**\
Turnkey delivers a secure, flexible solution for embedding end-user wallets directly into your application. Users sign in with familiar methods (passkeys, email, OAuth), without seed phrases, browser extensions, or external wallets. Turnkey lets you compose your app's core experiences (onboarding, wallet flows, and transactions) with full control, without restricting critical product decisions to pre-built flows. Keys stay inside hardware-backed Trusted Execution Environments [(TEEs)](/security/secure-enclaves), ensuring private keys are never exposed to your developers or to Turnkey.

You can use the [Embedded Wallet Kit](/reference/embedded-wallet-kit) for fast integration, or [Turnkey SDKs](/sdks/introduction) and the [API](/api-reference/overview) for more customization. Leading apps like [Moonshot](https://www.turnkey.com/customers/how-moonshot-powers-millions-of-self-custodial-wallets-using-turnkey), [Infinex](https://www.turnkey.com/customers/making-onchain-ux-seamless-with-infinex-and-turnkey), and [Axiom](https://www.turnkey.com/customers/axiom-global-defi-trading-platform) use Turnkey for embedded consumer wallets in production.
Turnkey delivers a secure, flexible solution for embedding end-user wallets directly into your
application. Users sign in with familiar methods (passkeys, email, OAuth), without seed phrases,
browser extensions, or external wallets. Turnkey lets you compose your app's core experiences
(onboarding, wallet flows, and transactions) with full control, without restricting critical product
decisions to pre-built flows. Keys stay inside hardware-backed Trusted Execution Environments
[(TEEs)](/security/secure-enclaves), ensuring private keys are never exposed to your developers or
to Turnkey.

You can use the [Embedded Wallet Kit](/reference/embedded-wallet-kit) for fast integration, or
[Turnkey SDKs](/sdks/introduction) and the [API](/api-reference/overview) for more customization.
Leading apps like
[Moonshot](https://www.turnkey.com/customers/how-moonshot-powers-millions-of-self-custodial-wallets-using-turnkey),
[Infinex](https://www.turnkey.com/customers/making-onchain-ux-seamless-with-infinex-and-turnkey),
and [Axiom](https://www.turnkey.com/customers/axiom-global-defi-trading-platform) use Turnkey for
embedded consumer wallets in production.

## Key implementation decisions

Turnkey enables developers to tailor non-custodial, embedded user wallets across dimensions such as custody model, authentication, and more. See the key implementation decisions below to curate the exact user experience you need. For a full map of embedded wallet capabilities, see the [Features overview](/embedded-wallets/features/overview).
Turnkey enables developers to tailor non-custodial, embedded user wallets across dimensions such as
custody model, authentication, and more. See the key implementation decisions below to curate the
exact user experience you need. For a full map of embedded wallet capabilities, see the
[Features overview](/embedded-wallets/features/overview).

| Decision | Explanation | Learn more |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -31,27 +49,40 @@ Choose how much control users and your app have over signing:
| **App-controlled** | Your backend can authorize actions (automation, trading, subscriptions). | **Seamless Automation:** Ideal for custodial products like trading bots or subscriptions that require acting on a user's behalf without manual approval. |
| **Delegated / hybrid** | Scoped permissions shared between user and backend. | **Frictionless UX:** Enables background actions (e.g., gas sponsorship or scheduled ops) while keeping the user in final control of asset transfers. |

Configure via [policies](/concepts/policies/quickstart) and[ sub-organization settings](/sdks/react/sub-organization-customization). See [Delegated Access](/concepts/policies/delegated-access-frontend) for non-custodial, hybrid, and app-controlled options.
Configure via [policies](/concepts/policies/quickstart)
and[ sub-organization settings](/sdks/react/sub-organization-customization). See
[Delegated Access](/concepts/policies/delegated-access-frontend) for non-custodial, hybrid, and
app-controlled options.

### Authentication

Balance security and friction for your audience:

- **Passkeys:** Phishing-resistant, biometric. See [passkey authentication](/authentication/overview).
- **OAuth / email:** Familiar, low-friction. See [Authentication Overview](/authentication/overview).
- **Passkeys:** Phishing-resistant, biometric. See
[passkey authentication](/authentication/overview).
- **OAuth / email:** Familiar, low-friction. See
[Authentication Overview](/authentication/overview).
- **SMS:** Market-dependent; consider risk and compliance.

Turnkey authentication plugs into your onboarding flow. You can use the [Auth Proxy](/reference/auth-proxy) when you want backend-signed OTP/OAuth/signup with origin enforcement and central config without hosting your own backend; your frontend calls Auth Proxy endpoints directly. Alternatively, wire auth to your app. Get started with the [Embedded Wallets Quickstart](/sdks/react/index).
Turnkey authentication plugs into your onboarding flow. You can use the
[Auth Proxy](/reference/auth-proxy) when you want backend-signed OTP/OAuth/signup with origin
enforcement and central config without hosting your own backend; your frontend calls Auth Proxy
endpoints directly. Alternatively, wire auth to your app. Get started with the
[Embedded Wallets Quickstart](/sdks/react/index).

### Session management

Choose how users stay authorized and where session credentials live:

- **Read-write vs read-only:** Read-write sessions (OTP, OAuth, passkey sessions) let users perform multiple signed actions in a time window. Read-only sessions suit low-touch apps where you mainly need to read data (e.g., via parent-org access or a read-only session token).
- **Storage:** IndexedDB (web) for persistent, client-held sessions without exposing keys to your JavaScript; SecureStorage (mobile); or LocalStorage (keys in app-accessible storage).
- **Read-write vs read-only:** Read-write sessions (OTP, OAuth, passkey sessions) let users perform
multiple signed actions in a time window. Read-only sessions suit low-touch apps where you mainly
need to read data (e.g., via parent-org access or a read-only session token).
- **Storage:** IndexedDB (web) for persistent, client-held sessions without exposing keys to your
JavaScript; SecureStorage (mobile); or LocalStorage (keys in app-accessible storage).
- **Session duration:** Default: 15 minutes (configurable via `expirationSeconds`).

See [Sessions](/authentication/sessions) for mechanisms, refresh, and FAQ, and the [Embedded Wallets Quickstart](/sdks/react/index) for configuration.
See [Sessions](/authentication/sessions) for mechanisms, refresh, and FAQ, and the
[Embedded Wallets Quickstart](/sdks/react/index) for configuration.

### Wallet architecture

Expand All @@ -62,33 +93,58 @@ Choose where keys are generated and how wallets interact with the blockchain.
| **Key-based (HD wallets)** | Chain-agnostic, no on-chain deployment, broad compatibility. | Standard derivation and signing. |
| **Smart contract wallets** | Gas sponsorship, batching, advanced permissions. | Requires on-chain deployment and infrastructure. |

Turnkey supports both. See [Wallets Concept](/concepts/wallets) and [Transaction Management](/concepts/transaction-management) for derivation and gas sponsorship.
Turnkey supports both. See [Wallets Concept](/concepts/wallets) and
[Transaction Management](/concepts/transaction-management) for derivation and gas sponsorship.

### Gas sponsorship

Provide gasless UX by sponsoring gas for your users. Turnkey supports sponsored transactions and relay integration so users can sign and send without holding native tokens.
Provide gasless UX by sponsoring gas for your users. Turnkey supports sponsored transactions and
relay integration so users can sign and send without holding native tokens.

See [Transaction Management](/concepts/transaction-management) for gas sponsorship, transaction construction, broadcast, nonce management and monitoring capabilities.
See [Transaction Management](/concepts/transaction-management) for gas sponsorship, transaction
construction, broadcast, nonce management and monitoring capabilities.

### Key portability

Enable key portability and define whether users can import or export private keys. Enabling export can support user sovereignty and long-term trust. See [Import/Export wallets](https://docs.turnkey.com/sdks/react/using-embedded-wallets#importing-and-exporting-wallets).
Enable key portability and define whether users can import or export private keys. Enabling export
can support user sovereignty and long-term trust. See
[Import/Export wallets](https://docs.turnkey.com/sdks/react/using-embedded-wallets#importing-and-exporting-wallets).

## Core security principles

Embedded consumer wallet with Turnkey is built on these key principles:

- **Keys never leave the enclave:** Private keys live in [Trusted Execution Environments (TEEs)](/security/secure-enclaves). All derivation and signing happen inside verifiable infrastructure; only signatures are returned. [Remote attestation](https://whitepaper.turnkey.com/architecture) lets you verify enclave integrity. Raw keys are never exposed to your app or to Turnkey.
- **Authenticator-bound requests:** Every sensitive operation is signed by a user-held authenticator (passkey, email, etc.). The enclave verifies the signature and then performs the operation. No request, no signing; a compromise outside the enclave cannot move funds. See [Authentication Overview](/authentication/overview) for supported methods and [Enclave to end-user secure channel](/security/enclave-secure-channels) for how requests are verified.
- **Scoped, programmable control:** Choose non-custodial, hybrid, or app-controlled custody. [Policies](/concepts/policies/quickstart) and sub-organization isolation limit who can sign what.
- **Trusted vs. untrusted separation:** Verification and execution run only inside secure enclaves. Trusted and untrusted infrastructure are strictly separated so that a breach of your app or backend does not expose keys or signing capability.
- **Keys never leave the enclave:** Private keys live in
[Trusted Execution Environments (TEEs)](/security/secure-enclaves). All derivation and signing
happen inside verifiable infrastructure; only signatures are returned.
[Remote attestation](https://whitepaper.turnkey.com/architecture) lets you verify enclave
integrity. Raw keys are never exposed to your app or to Turnkey.
- **Authenticator-bound requests:** Every sensitive operation is signed by a user-held authenticator
(passkey, email, etc.). The enclave verifies the signature and then performs the operation. No
request, no signing; a compromise outside the enclave cannot move funds. See
[Authentication Overview](/authentication/overview) for supported methods and
[Enclave to end-user secure channel](/security/enclave-secure-channels) for how requests are
verified.
- **Scoped, programmable control:** Choose non-custodial, hybrid, or app-controlled custody.
[Policies](/concepts/policies/quickstart) and sub-organization isolation limit who can sign what.
- **Trusted vs. untrusted separation:** Verification and execution run only inside secure enclaves.
Trusted and untrusted infrastructure are strictly separated so that a breach of your app or
backend does not expose keys or signing capability.

## Architecture at a glance

User authentication flows into a signed request to Turnkey. Inside the enclave, the [policy engine](/concepts/policies/overview) evaluates the request; key derivation and signing follow, and only the signature is returned. Your app can then broadcast the transaction through another provider or with [Turnkey Transaction Management](https://docs.turnkey.com/concepts/transaction-management#construction-and-broadcast). For data flow and infrastructure details, see [Embedded Wallets overview](/embedded-wallets/overview) and [Secure enclaves](/security/secure-enclaves).
User authentication flows into a signed request to Turnkey. Inside the enclave, the
[policy engine](/concepts/policies/overview) evaluates the request; key derivation and signing
follow, and only the signature is returned. Your app can then broadcast the transaction through
another provider or with
[Turnkey Transaction Management](https://docs.turnkey.com/concepts/transaction-management#construction-and-broadcast).
For data flow and infrastructure details, see
[Embedded Wallets overview](/embedded-wallets/overview) and
[Secure enclaves](/security/secure-enclaves).

<Frame>
![Embedded Consumer Wallets architecture: user/service, wallets, policy engine, authenticators, secure enclave infrastructure](/assets/files/Consumer_Wallets.png)
![Embedded Consumer Wallets architecture: user/service, wallets, policy engine, authenticators,
secure enclave infrastructure](/assets/files/Consumer_Wallets.png)
</Frame>

## Example: Neobank-style embedded consumer wallet
Expand Down Expand Up @@ -120,6 +176,7 @@ Follow these steps to launch an embedded consumer wallet experience inside your
- [Auth Proxy overview](https://docs.turnkey.com/reference/auth-proxy)
- [Email authentication (OTP)](https://docs.turnkey.com/authentication/email)
- [Passkeys integration](https://docs.turnkey.com/authentication/passkeys/integration)

</Step>
<Step title="Add Turnkey to Your Client App">
Install and initialize the Turnkey SDK at app startup so sessions and wallet operations are ready immediately.
Expand All @@ -128,6 +185,7 @@ Follow these steps to launch an embedded consumer wallet experience inside your

- [Embedded Wallet Kit (React)](https://docs.turnkey.com/sdks/react/getting-started)
- [Embedded Wallet Kit (React Native)](https://docs.turnkey.com/sdks/react-native/getting-started)

</Step>
<Step title="Implement Login, Signup & Session Handling">
Build your login/signup flow and gate wallet actions until:
Expand All @@ -139,6 +197,7 @@ Follow these steps to launch an embedded consumer wallet experience inside your

- [Wallet authentication guide](/sdks/react/auth)
- [OAuth signup helper](https://docs.turnkey.com/generated-docs/react-wallet-kit/client-context-type-add-oauth-provider)

</Step>
<Step title="Create a Sub-Organization & Wallet Per User">
**On first login:**
Expand All @@ -152,6 +211,7 @@ Follow these steps to launch an embedded consumer wallet experience inside your
- [Sub-organization customization](/sdks/react/sub-organization-customization)
- [Create wallet](https://docs.turnkey.com/sdks/react/using-embedded-wallets#creating-an-embedded-wallet)
- [Create wallet accounts](https://docs.turnkey.com/sdks/react/using-embedded-wallets#creating-wallet-accounts)

</Step>
<Step title="Enable Core Wallet Actions in the UI">
Expose wallet functionality directly inside your app.
Expand All @@ -165,13 +225,18 @@ Follow these steps to launch an embedded consumer wallet experience inside your
**Import / Export / Recovery (Optional) Docs**

- [Import & Export wallets](https://docs.turnkey.com/wallets/export-wallets)

</Step>
</Steps>

## Next steps

Ready to build? You can start with the [Embedded Wallets Quickstart](/getting-started/embedded-wallet-quickstart), explore the [Features overview](/embedded-wallets/features/overview), or browse the [Code Examples Hub](/category/code-examples).
Ready to build? You can start with the
[Embedded Wallets Quickstart](/getting-started/embedded-wallet-quickstart), explore the
[Features overview](/embedded-wallets/features/overview), or browse the
[Code Examples Hub](/category/code-examples).

<Frame>
![Turnkey in action: Moonshot onboarding — email sign-in, verification, portfolio, and asset view](/assets/files/moonshot_consumerwallet.png)
</Frame>
![Turnkey in action: Moonshot onboarding — email sign-in, verification, portfolio, and asset
view](/assets/files/moonshot_consumerwallet.png)
</Frame>
Loading