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

tip

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

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>
    </>
  );
}

Manual creation on createWallet

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:

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.

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.

Automatic recovery (default)

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.

Password-based recovery

To configure password-based recovery for your user's embedded wallets, simply set the config.embeddedWallets.requireUserPasswordOnCreate property of the PrivyProvider to true:

Configuring manual recovery of embedded wallets

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.

caution

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

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!

No prompt on signatures

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:

Configuring custom UIs for the embedded wallet

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

info

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.