Skip to main content

Configuring embedded wallets in your app

Depending on your target user base, you may want to adjust the role that embedded wallets play in your app's user experience. Privy allows you to configure multiple properties of the embedded wallet, including:

all via the config.embeddedWallets property of the PrivyProvider. Read below for more instructions!

When the wallet is created

You can configure Privy to create embedded wallets for your users:

  • automatically, as a part of their first login to your app
  • manually, when you call Privy's createWallet
tip

By default, Privy will not automatically create embedded wallets for your users, but you can easily change that, per the instructions below!

To create embedded wallets automatically, when a user first logs in to your app, just set the config.embeddedWallets.createOnLogin property of your PrivyProvider to either:

  • 'users-without-wallets', which will create an embedded wallet for all users who did not login with an external wallet and do not already have a wallet, or
  • 'all-users', which will create an embedded wallet for all users, including users who have an external wallet linked

With this option enabled, if a user chooses to log in with email and this flag is set, an embedded wallet will be automatically created for them after they successfully authenticate with your app.

An example config for automatically creating embedded wallets for users without wallets is below.

function MyApp({Component, pageProps}: AppProps) {
return (
<>
<PrivyProvider
appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
config={{
embeddedWallets: {
createOnLogin: 'users-without-wallets'
}
}}
>
<Component {...pageProps} />
</PrivyProvider>
</>
);
}

How the wallet is recovered

With Privy's embedded wallets, user keys are never stored anywhere. They are split up and reconstitued as needed to enable user signatures. Privy's embedded wallets can be recovered in two modes:

  • Automatic (default): In this mode, Privy secures the cryptographic material needed to help your user recover their wallet across devices. This means wallets can be created behind the scenes, without requiring any user action.
  • Password-based: In this mode, your users secure their wallet's recovery material with their own password, rather than one generated by Privy. Crucially, this means they will need to provide this password to recover their wallet when they log in to a new device.
info

Choosing what mode to use with Privy embedded wallets depends on your trust assumptions, the value of assets controlled by your user's embedded wallets, and your threat model.

Security tradeoffs deserve careful consideration. Please reach out if you have any questions: we would love to help you pick the right solution for your use case.

To configure automatic recovery for your user's embedded wallets, you do not need to do anything. This is the default for all Privy apps with embedded wallets enabled.

With this option, your user's recovery material is secured by a strong, random password generated by Privy. When logging into a new device, your user will not have to complete any additional steps to be use their embedded wallet.

tip

You can always have users set a password for their wallet later.

Whether the wallet prompts on signatures

When your app needs to request signatures for a message or a transaction from your users, you can choose whether the embedded wallet prompts your user for a signature or not.

If your app is configured to have the embedded wallet prompt users on signature requests, your user will be shown a Privy modal with information and guidance about the action they are about to take. You can customize this explanatory text to give the appropriate context to your user.

You do not need to do anything to configure this option; this is the default for all Privy apps.

tip

You can check out the user experience for these prompts here!