This guide walks through migrating your app and users’ embedded wallets from Alchemy Account Kit to Privy. The migration SDK handles re-authenticating users with Alchemy, securely exporting their private keys, and importing them into Privy. After migration, users log in with Privy while keeping the same wallet addresses and assets. Transactions and sponsorship continue through Alchemy infrastructure.Documentation Index
Fetch the complete documentation index at: https://docs.privy.io/llms.txt
Use this file to discover all available pages before exploring further.
Overview
- Set up Privy and replace Alchemy auth by swapping
@account-kit/reactfor@privy-io/react-auth. - Reconnect sending and gas sponsorship by wiring Privy wallets to Alchemy transaction infrastructure.
- Install the migration SDK to migrate wallet keys when users log in.
- Deploy the updated app, export users from Alchemy, and import users into Privy.
Step 1: Set up Privy and replace Alchemy auth
Replace Alchemy auth SDKs with Privy to support login and signup.- Set up your organization in Privy.
- Follow React SDK setup instructions.
- Enable the same login methods your users used with Alchemy, such as email, Google, and passkeys.
Step 1a: Install Privy and remove Alchemy auth packages
Step 1b: Replace the Alchemy provider with PrivyProvider
Remove AlchemyAccountProvider (and cookieToInitialState for SSR), then wrap your app with PrivyProvider.
Step 1c: Replace Alchemy hooks with Privy equivalents
Update all imports from@account-kit/react.
| Before (Alchemy) | After (Privy) |
|---|---|
useSignerStatus().isConnected | usePrivy().authenticated |
useAuthModal().openAuthModal() | usePrivy().login() |
useLogout() | usePrivy().logout (function, not hook) |
useUser() | usePrivy().user (email is at user.email?.address) |
useSmartAccountClient() | Use @alchemy/wallet-apis in step 2 |
useSendUserOperation() | client.sendCalls() in step 2 |
cookieToInitialState (SSR) | Remove |
Step 2: Reconnect sending and gas sponsorship
Wire Privy wallets to Alchemy transaction infrastructure so gasless transactions, batching, and existing send flows continue to work. This will now use Alchemy SDK v5 with Wallet APIs. Full guide for Privy + Alchemy: More on Alchemy SDK v5: Notes:- The client defaults to EIP-7702 and delegates the Privy wallet at send time.
- For ERC-4337 mode, request an account before sending and include the account address in
sendCalls. - If your app previously used ERC-4337 (with assets directly in smart accounts), follow the EIP-7702 guide for non-7702 mode. Add an extra call to
wallet_requestAccountbefore sending.
Prerequisites
- Alchemy API key: From the Alchemy Dashboard. This must be the same app that has your Smart Wallets configuration and gas policy linked.
- Gas sponsorship policy ID: From the Gas Manager dashboard.
Step 2a: Install transaction SDK
Step 2b: Get the Privy signer
UsetoViemAccount to convert a Privy embedded wallet into a viem LocalAccount.
useWallets() returns the user’s Privy wallets. toViemAccount converts the Privy wallet into a standard viem LocalAccount, which is what the Alchemy wallet client needs as a signer. The signer is undefined until the wallet is ready, so your UI should handle that loading state.
Step 2c: Send gasless transactions
Step 3: Install the React Migration SDK
The migration SDK is a drop-in React component that detects users who need wallet migration, prompts re-authentication through Alchemy, and transfers key material from Alchemy TEE to Privy TEE with end-to-end encryption.How it works
When a user logs in, the SDK:- Detects migration need by checking Alchemy migration metadata and missing embedded wallets.
- Shows a migration modal that prompts re-authentication with the original Alchemy method.
- Migrates wallets by exporting keys from Alchemy TEE and importing into Privy TEE.
- Confirms completion with a success view and auto-close.
Supported authentication methods
- Email (OTP)
- Twitter/X
- GitHub
- Discord
- Passkey (non-anonymous, for example passkeys linked to email)
Step 3a: Install migration packages
Step 3b: Import migration styles
Step 3c: Create the Alchemy config
UsecreateMigrationConfig and include all auth methods your users used with Alchemy.
The auth.sections field should include all login methods originally used with Alchemy. The SDK automatically detects which method each user needs and shows the right sign-in flow.
This remains true even if your app used custom UI with useAuthenticate. Use the same config pattern below and include all auth methods your users used. Only pre-built components are supported for the migration flow.
Step 3d: Set up MigrationProvider
Wrap MigrationProvider inside PrivyProvider.
MigrationProvider props
| Prop | Type | Required | Description |
|---|---|---|---|
alchemyConfig | AlchemyAccountsConfigWithUI | Yes | Config created with createMigrationConfig |
privyAppId | string | Yes | Privy app ID |
privyClientId | string | Yes | Privy app client ID |
showDebugButton | boolean | No | Show debug buttons for testing (dev only) |
skipOrgVerification | boolean | No | Skip Alchemy org ID verification (dev only) |
After migration is complete
After users have migrated wallets (for example, after at least one login):- Remove
@privy-io/alchemy-migration,@account-kit/react, and@account-kit/infra. - Keep
createOnLogin: 'users-without-wallets'for standard new-user wallet creation. - Remove
MigrationProvider.
Step 4: Deploy the updated app, export users, and import into Privy
To detect users who need key migration, Privy needs imported user data and linked auth methods from Alchemy. This import does not move keys. Recommended sequence: Deploy → Export → Import.- Pause new signups briefly.
- Deploy your updated app with Privy auth.
- Immediately export users from Alchemy.
- Import users into Privy.
- Resume normal operations.
Step 4a: Export users from Alchemy
- Open the Alchemy dashboard and choose your app.
- Go to Wallets → Export.
- Select Export users and download the JSON file.
Step 4b: Import users into Privy
- Open the Privy dashboard and choose your target app.
- Go to User management → Users → Import users.
- Upload the JSON exported from Alchemy.
FAQ
Do users need to do anything?
Users only need to sign in once with their original Alchemy login method.Will wallet addresses change?
No. Wallet addresses remain the same.Are private keys ever exposed?
No. Keys move from Alchemy TEE to Privy TEE through end-to-end encryption.What if a user has both Ethereum and Solana wallets?
Both are migrated automatically and independently.What if a user already has a Privy wallet?
Only missing wallets are migrated. If a user already has an ETH wallet but not SOL, only SOL is migrated.Can migration be tested before launch?
Yes. SetshowDebugButton: true on MigrationProvider and validate with a test Alchemy app.
What if deployment and export cannot happen at exactly the same time?
Deploy first, then export. Once your app is on Privy, no new users are being created in Alchemy, so the export captures everyone. If export happens before deploy and there is a gap, run a second export after deploying to capture users who signed up in between.The migration modal never appears
Common causes:- Users were not imported from Alchemy before first Privy login.
- Wallet auto-creation ran before migration checks.
- The user already has all required wallets in Privy.

