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.

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 not authenticated, you should prompt them to login 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.