Appearance
Creating embedded wallets ​
If your app uses embedded wallets, you can configure Privy to create wallets automatically for your users as part of their login
flow, or you can manually create wallets for your users when required.
Automatic wallet creation ​
When automatic wallet creation is enabled, Privy will create wallets for users when they login to your app––specifically, as part of Privy's login
method.
To configure Privy to automatically create embedded wallets for your user when they login, set the config.embeddedWallets.createOnLogin
property of your PrivyProvider
:
tsx
<PrivyProvider
appId='your-privy-app-id'
config={{
embeddedWallets: {
createOnLogin: 'users-without-wallets' // defaults to 'off'
}
...insertTheRestOfYourPrivyProviderConfig
}}
>
{children}
</PrivyProvider>
The possible values for config.embeddedWallets.createOnLogin
are 'off'
, 'users-without-wallets'
, and 'all-users'
:
- When
'off'
, Privy will not automatically create embedded wallets for your users, but you can always manually create wallets for them later. This is the default setting. - When set to
'users-without-wallets'
, Privy will automatically create an embedded wallet for users that do not already have another external wallet linked to their account. - When set to
'all-users'
, Privy will automatically create an embedded wallet for all users, including those that do have another external wallet linked to their account.
INFO
With automatic wallet creation, there may be edge cases where a user is able to successfully login
, but Privy is not able to create an embedded wallet for them.
This most commonly occurs when a user logs in and closes your app before embedded wallet creation has finished, allowing them to become authenticated
without having an embedded wallet.
To handle these cases, we strongly recommend that your app provide a fallback UI to allow users to manually create an embedded wallet on demand using manual creation. This ensures users always have a fallback option to create wallets.
Additionally, the next time the user logs in to your app, if they still do not have an embedded wallet, Privy will re-attempt automatic wallet creation for them.
WARNING
On whitelabel login, the config.embeddedWallets.createOnLogin
is not honored. If you use custom components in your login flow and would like to create embedded wallets for your users, please use the createWallet
method once they are authenticated.
Manual wallet creation ​
To manually create embedded wallets for your users, use the the createWallet
method from usePrivy
hook:
tsx
const {createWallet} = usePrivy();
When invoked, this method will create an embedded wallet for the user, and return a Promise that resolves to the Wallet
if creation was successful, or rejects if there was an error during creation.
Please note that
- Users must be
authenticated
to create an embedded wallet. If your user is notauthenticated
, you should prompt them tologin
first. - Users can have at most one embedded wallet. If your user already has an embedded wallet, and you call
createWallet
, the method will throw an error.
See the example below:
tsx
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>
);
}
Pregeneration ​
Privy also allows you to pregenerate embedded wallets for your users, even before they first login to your app. Please see our pregeneration guide for more.