Creating an embedded wallet
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
Read our embedded wallets configuration guide to see how to enable either option! Then, make sure to follow the appropriate instructions below, depending on how you've configured your app.
In this guide, you can also check out the user experience of wallet creation.
Creating embedded wallets
- Using automatic creation
- Using manual creation
If you've configured your apps to create embedded wallets for your users automatically when they login
, you do not need to do anything else to create embedded wallets for your users. During login, they will automatically be prompted to create an embedded wallet if they do not already have one.
During login
, if a user refreshes the page or prematurely exits the creation flow before the wallet is successfully created, they may be authenticated
, without an embedded wallet. This can be detected by inspecting the authenticated
) and user.wallet
) properties from the usePrivy
hook.
If this occurs, you can drop your user back into the wallet creation flow, by using the createWallet
.
If you've configured your apps to create embedded wallets for your users manually, when you want to trigger wallet creation in your app, simply call the createWallet
method from usePrivy
hook. See the 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.
User experience
Depending on if you've configured your app to use password-based recovery or not, the user experience for wallet creation and recovery on a new device will differ.
Make sure to follow the appropriate guide below, depending on how you've configured embedded wallets.
Embedded wallets are secured with key splitting to make wallet recovery easy for your users.
- With automatic recovery (default)
- With password-based recovery
Wallet creation
When using automatic recovery of the embedded wallet (the default), your users will not have to complete any additional steps to create an embedded wallet when they login
. The wallet will be created behind-the-scenes.
Wallet recovery on a new device
Your users will not have to complete any additional steps to recover the embedded wallet on a new device. The wallet will be recovered behind-the-scenes.
You can always have users set a password for their wallet later.
Wallet creation
When using password-based recovery of the embedded wallet, your users will be guided through a simple creation flow that explains what an embedded wallet is and how they can use it in your app.
In this process, users will need to set a strong password that secures their wallet recovery materials.

Creating an embedded wallet with password-based recovery.
Wallet recovery on a new device
When your user signs-in on a new device, their embedded wallet must be recovered on that device, and the user must enter their password that they set in the screen above.
Once a wallet is recovered on a given device, the user will not have to recover the wallet on that device again.
Due to how browsers enforce cross-origin restrictions in incognito windows, Privy embedded wallets are not currently available in incognito browser windows. We are working on better support for this use case!