consumer embedded wallet doc

embedded-wallets/code-examples/consumer-embeddedwallet.mdx

@@ -0,0 +1,107 @@
+---
+title: "Consumer Embedded Wallets"
+description: "Consumer embedded wallets: custody model, authentication, session management, and architecture. Turnkey provides secure key infrastructure in TEEs while you control UX, policies, and transaction flows. Use Embedded Wallet Kit for fast integration or SDKs and APIs for more customization."
+mode: wide
+---
+
+## Why consumer embedded wallets?
+
+An embedded wallet gives your users in-app crypto without seed phrases, browser extensions, or external wallets. Users sign in with familiar methods (passkeys, email, OAuth); Turnkey handles key management and signing in the background. Keys stay inside hardware-backed [Trusted Execution Environments (TEEs)](https://docs.turnkey.com/security/secure-enclaves). Private keys are never exposed to your developers or to Turnkey.
+
+You can use the [Embedded Wallet Kit](https://docs.turnkey.com/reference/embedded-wallet-kit) for fast integration, or [Turnkey SDKs](https://docs.turnkey.com/sdks/introduction) and the [API](https://docs.turnkey.com/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 consumer embedded wallets in production.
+
+## Key implementation decisions
+
+For a full map of embedded wallet capabilities, see the [Features overview](https://docs.turnkey.com/embedded-wallets/features/overview).
+
+| Decision | Summary | Learn more |
+| :---- | :---- | :---- |
+| **Custody model** | User-controlled, app-controlled, or delegated/hybrid. Configure via policies and sub-organization settings. | [Sub-organizations as wallets](https://docs.turnkey.com/embedded-wallets/sub-organizations-as-wallets), [Delegated Access](https://docs.turnkey.com/concepts/policies/delegated-access-frontend) |
+| **Authentication** | Passkeys, OAuth/email, or SMS. You can use the [Auth Proxy](https://docs.turnkey.com/reference/auth-proxy) for backend-signed OTP/OAuth/signup without your own backend, or wire auth to your app. | [Authentication Overview](https://docs.turnkey.com/authentication/overview), [Auth Proxy](https://docs.turnkey.com/reference/auth-proxy), [Quickstart](https://docs.turnkey.com/getting-started/embedded-wallet-quickstart), [Sub-organization auth](https://docs.turnkey.com/embedded-wallets/sub-organization-auth) |
+| **Session management** | Read-write vs read-only; where credentials live (IndexedDB, SecureStorage, or LocalStorage); default 15 minutes (configurable). | [Sessions](https://docs.turnkey.com/authentication/sessions), [Quickstart](https://docs.turnkey.com/getting-started/embedded-wallet-quickstart) |
+| **Wallet architecture** | Key-based (HD) or smart contract wallets. Turnkey supports both. | [Wallets Concept](https://docs.turnkey.com/concepts/wallets), [Transaction Management](https://docs.turnkey.com/concepts/transaction-management) |
+| **Transaction management** | Gasless UX via sponsored transactions. Covers who pays gas and how transactions are sent and broadcast. | [Transaction Management](https://docs.turnkey.com/concepts/transaction-management), [Sending sponsored transactions](https://docs.turnkey.com/embedded-wallets/code-examples/sending-sponsored-transactions) |
+| **Key portability** | Whether users can import or export keys. Enabling export can support user sovereignty. | [Export](https://docs.turnkey.com/embedded-wallets/code-examples/export), [Import](https://docs.turnkey.com/embedded-wallets/code-examples/import) |
+
+### Custody model
+
+Choose how much control users and your app have over signing:
+
+| Model | Description |
+| :---- | :---- |
+| **User-controlled** | Only the user can authorize actions (self-custody). |
+| **App-controlled** | Your backend can authorize actions (automation, trading, subscriptions). |
+| **Delegated / hybrid** | Scoped permissions shared between user and backend. |
+
+Configure via [policies](https://docs.turnkey.com/concepts/policies/quickstart) and sub-organization settings. See [Sub-organizations as wallets](https://docs.turnkey.com/embedded-wallets/sub-organizations-as-wallets) and [Delegated Access](https://docs.turnkey.com/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](https://docs.turnkey.com/authentication/overview).
+* **OAuth / email:** Familiar, low-friction. See [Authentication Overview](https://docs.turnkey.com/authentication/overview).
+* **SMS:** Market-dependent; consider risk and compliance.
+
+Turnkey authentication plugs into your onboarding flow. You can use the [Auth Proxy](https://docs.turnkey.com/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](https://docs.turnkey.com/getting-started/embedded-wallet-quickstart) and [Sub-organization auth](https://docs.turnkey.com/embedded-wallets/sub-organization-auth).
+
+### 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).
+* **Session duration:** Default: 15 minutes (configurable via `expirationSeconds`).
+
+See [Sessions](https://docs.turnkey.com/authentication/sessions) for mechanisms, refresh, and FAQ, and the [Embedded Wallets Quickstart](https://docs.turnkey.com/getting-started/embedded-wallet-quickstart) for configuration.
+
+### Wallet architecture
+
+| Approach | Pros | Considerations |
+| :---- | :---- | :---- |
+| **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](https://docs.turnkey.com/concepts/wallets) and [Transaction Management](https://docs.turnkey.com/concepts/transaction-management) for derivation and gas sponsorship.
+
+### Transaction management
+
+You can offer 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](https://docs.turnkey.com/concepts/transaction-management) for nonce handling, construction, signing, and broadcast, and [Sending sponsored transactions](https://docs.turnkey.com/embedded-wallets/code-examples/sending-sponsored-transactions) for relay providers, gas policies, and error handling.
+
+### Key portability
+
+Decide whether users can import or export keys. Enabling export can support user sovereignty and long-term trust. See [Export](https://docs.turnkey.com/embedded-wallets/code-examples/export) and [Import](https://docs.turnkey.com/embedded-wallets/code-examples/import).
+
+## Core security principles
+
+Turnkey’s consumer embedded wallet solution is built on:
+
+* **Keys never leave the enclave:** Private keys live in [Trusted Execution Environments (TEEs)](https://docs.turnkey.com/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](https://docs.turnkey.com/authentication/overview) for supported methods and [Enclave to end-user secure channel](https://docs.turnkey.com/security/enclave-secure-channels) for how requests are verified.
+* **Scoped, programmable control:** Choose non-custodial, hybrid, or app-controlled custody. [Policies](https://docs.turnkey.com/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.
+
+## Example: Neobank-style embedded wallet
+
+Typical requirements and how Turnkey addresses them:
+
+| Requirement | Turnkey capability |
+| :---- | :---- |
+| Seamless onboarding | Automated provisioning via [Quickstart](https://docs.turnkey.com/getting-started/embedded-wallet-quickstart) and [SDKs](https://docs.turnkey.com/sdks/introduction) |
+| User custody without key exposure | Keys remain in [secure enclaves](https://docs.turnkey.com/security/secure-enclaves); only signatures are returned |
+| Gasless UX | [Sponsored transactions](https://docs.turnkey.com/concepts/transaction-management) and [sending sponsored transactions](https://docs.turnkey.com/embedded-wallets/code-examples/sending-sponsored-transactions) |
+| Email-based auth and recovery | [Sub-organization auth](https://docs.turnkey.com/embedded-wallets/sub-organization-auth) and [Sub-organization recovery](https://docs.turnkey.com/embedded-wallets/sub-organization-recovery) |
+| Send without wallet setup | [Claim links](https://docs.turnkey.com/wallets/claim-links#claim-links): send via URL; recipient claims with email |
+| Backend automation | [Delegated access](https://docs.turnkey.com/concepts/policies/delegated-access-backend) and scoped signing policies |
+| Multichain support | Chain-agnostic derivation and signing; [Networks](https://docs.turnkey.com/networks/overview) and [Wallets Concept](https://docs.turnkey.com/concepts/wallets) |
+| Fast integration | [Code Examples Hub](https://docs.turnkey.com/category/code-examples) and [SDKs](https://docs.turnkey.com/sdks/introduction) |
+
+## Architecture at a glance
+
+User authentication flows into a signed request to Turnkey. Inside the enclave, the [policy engine](https://docs.turnkey.com/concepts/policies/overview) evaluates the request; key derivation and signing follow, and only the signature is returned. Your app can then broadcast the transaction or use Turnkey’s broadcast. For data flow and infrastructure details, see [Embedded Wallets overview](https://docs.turnkey.com/embedded-wallets/overview) and [Secure enclaves](https://docs.turnkey.com/security/secure-enclaves).
+
+## Next steps
+
+Ready to build? You can start with the [Embedded Wallets Quickstart](https://docs.turnkey.com/getting-started/embedded-wallet-quickstart), explore the [Features overview](https://docs.turnkey.com/embedded-wallets/features/overview), or browse the [Code Examples Hub](https://docs.turnkey.com/category/code-examples). For signing flows, see [Signing Transactions](https://docs.turnkey.com/embedded-wallets/code-examples/signing-transactions) and the [React SDK signing reference](https://docs.turnkey.com/sdks/react/signing).