Creating an embedded wallet
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:
- automatically as part of the
login
flow - 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
.
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.
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.
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
).
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.
Recovering the embedded wallet
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
.
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.