Skip to main content

Adding a password to the embedded wallet

By default, Privy will create embedded wallets for your users secured by automatic recovery. If you'd like to modify existing wallets to use password-based recovery, you can easily prompt users to set a password for their wallet. These modes trade off user friction (setting a password) for adding a second factor to recover embedded wallets on a new device.

Users may have different requirements throughout the app-lifecycle so Privy enables you to change the user recovery mode for each user. If you'd like to modify existing wallets to use password-based recovery, you can easily prompt users to set a password for their wallet.

Importantly, this allows you to secure the embedded wallet's recovery share with user-provided entropy, while enabling you to control when users are required to set a password to recover their embedded wallet. As an example, you might:

  • at first, create wallets for your users secured by automatic recovery, to minimize onboarding friction
  • later, prompt the user to set a password to secure their wallet (e.g. when their balance crosses a threshold)
tip

We strongly recommend you prompt users to set a password if their embedded wallets reach a certain usage or asset threshold. This is especially important if you are enabling SMS-based authentication for US users, where SIM swapping is common. With password-based recovery, even if a user's phone number (or authentication method generally) is compromised, their embedded wallet cannot be accessed on a new device without knowledge of the password.

caution

If a user sets a password for their wallet and loses both their password and their device, their embedded wallet will be unrecoverable even if they still have access to their auth method. This is a key aspect of self-custodial recovery.

In kind, if you plan to have users set passwords for their wallets, we recommend that you make it expressly clear in your app's language that passwords must be securely stored lest wallets become unrecoverable.

To prompt users to add a password to their wallet, use the setWalletPassword method from the usePrivy hook. This method will open a modal where the user can set a password for their embedded wallet:

Setting a password for the embedded wallet

Setting a password for the embedded wallet.

When invoked, setWalletPassword will return a Promise for the embedded wallet's updated Wallet object, that will resolve once the user has successfully set a password for their wallet.

The method will reject with an error if the user does not have an embedded wallet, or if the user has already set a password for their wallet. To determine if a user's embedded wallet is already secured by a password, check if the embedded wallet's entry in the user.linkedAccounts array has a recoveryMethod of 'user-passcode'.

Verifying if the user already has a password
const {user} = usePrivy();
const embeddedWallet = user.linkedAccounts.find((account) => (account.type === 'wallet' && account.walletClientType === 'privy'));
const alreadyHasPassword = embeddedWallet.recoveryMethod === 'user-passcode';

As an example, you might add setWalletPassword as an event handler for a set password button in your app:

Example Add Password Button
import { usePrivy } from '@privy-io/react-auth';

// This example assumes you have already checked that Privy is `ready` and the user is `authenticated`
function AddPasswordButton() {
  const { user, setWalletPassword } = usePrivy();
  // This is taken from the code snippet above
  const embeddedWallet = user.linkedAccounts.find(
    (account) => (account.type === 'wallet' && account.walletClientType === 'privy'));
  const alreadyHasPassword = embeddedWallet.recoveryMethod === 'user-passcode';

  return (
      <button
        // Only users who have an embedded wallet and have not already set a password can click
        disabled={!embeddedWallet || !alreadyHasPassword}
        onClick={setWalletPassword}
      >
        Add a password to your wallet
      </button>
    );
}

Once a user has set a password for their wallet, they will only be prompted to re-enter that password when using the wallet on a new device or browser. Once the wallet is recovered on a given device, the user will not need to re-enter their password on that same device.

info

Once a password has been set for a wallet, it is not currently possible to reset the password. We are actively building support for this flow.