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:
- when the embedded wallet is created
- how the embedded wallet is secured and recovered
- whether embedded wallets prompt the user for signatures
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
By default, Privy will not automatically create embedded wallets for your users, but you can easily change that, per the instructions below!
- Automatic creation on login
- Manual creation on createWallet
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 notlogin
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>
</>
);
}
Instead of triggering wallet creation during the login
flow, you can control when to create a wallet using the createWallet
function exposed via the usePrivy
hook. This allows you to build custom flows and choose specifically when to create a wallet for your user.
To create embedded wallets manually, only when you call createWallet
, just omit the config.embeddedWallets.createOnLogin
property of the PrivyProvider
or set it to 'off'
. This is the default for all Privy apps.
Then, when you want to trigger wallet creation in your app, simply call the createWallet
method from usePrivy
hook, like in the button example below:
import { usePrivy } from '@privy-io/react-auth';
function CreateWalletButton() {
const { ready, authenticated, createWallet } = usePrivy();
// Users must be `authenticated` in order to create an embedded wallet
return <button disabled={!(ready && authenticated)} onClick={createWallet}>Create a wallet</button>;
}
When invoked, the createWallet
method will return a Promise that resolves with the created Wallet
object.
Note that:
- Users must be
authenticated
to create an embedded wallet. If your user is notauthenticated
, you should prompt them tologin
before callingcreateWallet
. - Users can have at most one embedded wallet. If your user already has an embedded wallet, and you call
createWallet
, the method will fail.
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.
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.
- Automatic recovery (default)
- Password-based recovery
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.
You can always have users set a password for their wallet later.
To configure password-based recovery for your user's embedded wallets, simply set the config.embeddedWallets.requireUserPasswordOnCreate
property of the PrivyProvider
to true
:
function MyApp({Component, pageProps}: AppProps) {
return (
<>
<PrivyProvider
appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
config={{
embeddedWallets: {
requireUserPasswordOnCreate: true // defaults false
}
}}
>
<Component {...pageProps} />
</PrivyProvider>
</>
);
}
With this option, when your app triggers embedded wallet creation for a user, the user will be guided through a simple creation flow in the Privy modal, which explains to your user what an embedded wallet is and how they can use it in your app.

Creating an embedded wallet with password-based recovery.
As part of this process, the user will be required to set a password to secure the recovery material for their embedded wallet. They will not have to re-enter their password again to use the embedded wallet on that same device, but they will have to enter their password to use the embedded wallet on a new device.
When using recovery with a password, if a user loses their password and the device on which the embedded wallet was created, their embedded wallet will be irrecoverable. Privy cannot help them with recovery in this scenario.
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.
- Prompt on signatures
- No prompt on signatures
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.
You can check out the user experience for these prompts here!
To configure your app's embedded wallets to not prompt your users for signatures, set the config.embeddedWallets.noPromptOnSignature
property of the PrivyProvider
to true
:
import { PrivyProvider } from '@privy-io/react-auth';
function App({ Component, pageProps }) {
return (
<PrivyProvider
config={{
embeddedWallets: {
noPromptOnSignature: true // defaults to false
}
}}
>
<Component {...pageProps} />
</PrivyProvider>
);
}
When true
, this option will configure Privy's signMessage
and sendTransaction
methods in your app to simply compute a signature or send a transaction, without showing Privy's prompts to your users.
With this option enabled, you can then choose whether:
- to attach your own UI prompts to embedded wallet signature and transaction requests, or
- to have embedded wallets be completely behind-the-scenes in your user experience
If you have both the noPromptOnSignatures
option and the requireUserPasswordOnCreate
option enabled in your app, your user:
- will see a Privy UI when their wallet is created or recovered
- will not see a Privy UI when their wallet is used for signatures and transactions
This can be a confusing experience for users. In kind, we suggest only using the noPromptOnSignatures
option if you do not have the requireUserPasswordOnCreate
option enabled.