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 ​

INFO

Automatic embedded wallet creation is currently not supported if your app uses Privy's whitelabel login interfaces. If this is the case for your app, you must manually create embedded wallets for your users at the desired point in your onboarding flow.

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.

Manual wallet creation ​

To manually create embedded wallets for your users, use the Privy's createWallet method like so:

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

...

const {createWallet} = useCreateWallet();

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 not authenticated, you should prompt them to login first.
  • By default, users can have at most one embedded wallet on EVM networks or Solana. If you need support for additional embedded wallets, your app can create additional hierarchical deterministic (HD) wallets.

Pregeneration ​

Privy also allows you to pregenerate embedded wallets on both EVM networks and Solana for your users, even before they first login to your app. Please see our pregeneration guide for more.