Appearance

Migrating existing users to Privy ​

Privy makes it easy for you to migrate existing user accounts from your existing auth setup.

At a high-level, your migration workflow involves two key components: importing existing user accounts and ensuring users have continuous ownership over any assets stored in their wallets, including embedded wallets. From these two pieces, you can easily switch over from a custom provider or add Privy to your existing auth flow.

Importing user data ​

You can easily import users and their accounts to Privy and can even pre-generate Privy embedded wallets for them.

Privy supports both:

  • just-in-time migration so you can map your existing users to Privy users as they log in
  • proactive migration to import user data into Privy all at once

Just-in-time migration ​

The simplest option is to "lazily" transfer your existing users to Privy. When an existing user logs in to your app via Privy for the first time, add their Privy DID to your internal users database to create a mapping between your existing user entry and their Privy user object.

Namely, we suggest:

  1. In your internal users database, add a PrivyDID column.
  2. In the onComplete callback from Privy's useLogin hook, if the isNewUser flag is true, make a request to your backend with the user's Privy DID (user.id) and any account data you need to identify that user from your existing DB.

For example, the request to your backend for a new user might include a body like:

json
{
  "address": user.wallet?.address,
  "email": user.email?.address,
  "privyDID": user.id
}
  1. When your backend receives the request from step (2), find the corresponding entry in your internal user database, matching on their wallet address, email address, or any other relevant account data.
  • If entry does not have a PrivyDID, add the Privy DID from your request to the PrivyDID column in your database.
  • If the entry already has a "Privy DID" in your database, it should match the Privy DID included in your request. There is nothing more to do.
  • If there is no user matching the account information in the request, you can assume it is a new user in your internal database, and create an entry for them with their PrivyDID.

In this way, you can maintain a mapping between your existing user data and the corresponding Privy user object.

Your user data will be updated as your users login to your app using Privy.

Proactive migration ​

If your existing users database associates multiple linked accounts (e.g. email, wallet, Discord, etc.) to a single user, we recommend that you proactively migrate them to Privy using the import users endpoint. This ensures you can migrate your users and preserve the links between their different accounts in Privy.

Please see the instructions here for more.

Ensuring continuous asset ownership ​

Once you've migrated your user data to Privy, you should next migrate user assets if necessary to ensure the transition is seamless for your users. This can be done by transferring over user addresses to Privy (migrating the wallet) or having them transfer assets to their new accounts (migrating the assets).

The best path depends on your current setup and whether you need users to keep their existing wallets. We generally recommend transferring assets if you can.

TIP

In most cases, migrating assets and/or wallets is only necessary if you are coming from another embedded wallet provider. If your users currently use external wallets to store their assets, you can simply import their address to Privy.

If you are able to transfer assets ​

  • Migrating from a custodial system
    • If you are able to submit transactions on behalf of your users, you can set up batch transactions on your backend, sponsoring gas on behalf of your users to transfer their assets into pregenerated Privy wallets.
  • Migrating from a non-custodial system
    • When they next log in, prompt your users to run a one-time transfer to migrate their assets over to their new account.

If you need to transfer wallets instead of transferring assets ​

  • Migrating from a custodial system
    • Reach out to discuss whether Privy can help you import your existing user wallets. This would enable you to move your users' keys so they are managed by Privy's non-custodial system.
  • Migrating from a non-custodial system
    • We recommend you prompt your user to export their keys so they can use them with an external wallet (like MetaMask).

TIP

Privy's system is non-custodial. This means neither you nor Privy will have any access to your user's private keys after the migration.