Creating an embedded wallet

note

To use embedded wallets in your app, please upgrade your @privy-io/react-auth version to at least 1.17.0.

To create an embedded wallet, users 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.

The wallet creation flow

In the process of creating an embedded wallet, users will need to set a 6-digit PIN that secures their wallet. This ensures that the embedded wallet is fully non-custodial for both you (the developer) and Privy, and allows the user to easily recover their wallet if they login to a new device.

Creating an embedded wallet with Privy.

Once a user sets or enters their PIN, they will not have to re-enter their PIN again on that same device.

Triggering the wallet creation flow

You can prompt users to create an embedded wallet either:

1. automatically as part of the login flow
2. manually, using the createWallet function

Automatically triggering wallet creation upon login

To automatically prompt users to create an embedded wallet when they first login to your app, add the optional createPrivyWalletOnLogin flag to the PrivyProvider.

Enabling automatic wallet creation on login

import { PrivyProvider } from '@privy-io/react-auth';

function App({ Component, pageProps }) {
  return (
    <PrivyProvider
      createPrivyWalletOnLogin
      /* Other props ... */
    >
      <Component {...pageProps} />
    </PrivyProvider>
  );
}

If enabled, this option will prompt users to create a wallet immediately after they login, if they do not already have a wallet associated with their account; generally, this means on the user's first login to your app.

For example, if a user chooses to log in with email and this flag is set, they will immediately be prompted to create their embedded wallet after successfully authenticating with your app.

info

If a user refreshes the page or prematurely exits the wallet creation flow before the wallet is successfully created, they may reach an authenticated state 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 method as documented below.

Manually triggering wallet creation via createWallet

Instead of prompting wallet creation during the login flow, you can control when to prompt users 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 want to take your user through wallet creation.

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, createWallet method will return a Promise that resolves with the created Wallet object. Additionally, this new embedded wallet will become the user's active wallet (user.wallet).

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.

Recovering the embedded wallet

note

This section is 🚧 under construction 🚧 and is liable to change as part of our phased rollout. This is simply meant to provide a sense for the interface we plan to support.

When your user attempts to use their embedded wallet on a new device, Privy will prompt the user to recover their wallet on that device, by entering the 6-digit PIN they set when they created their wallet.

Upon successfully entering their PIN, your user can freely use their embedded wallet on the new device. Users will not have to re-enter their PIN on that same device again; they can continue to use their embedded wallet on that device as long as they are authenticated.

info

Behind the scenes, recovery uses Shamir Secret Sharing to reconstruct the private key on the end-users device. No key material is transmitted over networks or exposed to servers. While a recovery "pin" is currently used, Privy is working to expand the options available to end users should they want a more secure recovery mechanism.