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.

tip

In this guide, you can also check out the user experience of wallet creation.

Creating embedded wallets

Using automatic 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.

info

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.

Using manual creation

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:

Example Create Wallet Button

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.

info

Note that:

• Users must be authenticated to create an embedded wallet. If your user is not authenticated, you should prompt them to login before calling createWallet.
• 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.

info

Embedded wallets are secured with key splitting to make wallet recovery easy for your users.

With automatic recovery (default)

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.

tip

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

With password-based recovery

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.

info

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!