Migrating from Privy to WaaP

A step-by-step guide for migrating your application from Privy embedded wallets to WaaP. Covers all three Privy wallet types, with account pregeneration for zero-friction user migration.

Before You Start

Contact our team  to get started with migration. We’ll set you up with:

• An API key for account pregeneration (bulk wallet creation for your users)
• A dedicated migration support channel
• Revenue share terms for your integration

Identify your Privy wallet types. Your application may use one or more of these:

Step 1: Pre-Generate WaaP Accounts

Before changing anything in your application, pre-generate WaaP wallets for your existing users. This means every user will have a wallet waiting for them when they first log in through WaaP.

Our team will provide you with an API key for the Account Pregeneration API. For each user:

curl -X POST https://auth.waap.xyz/pregen-account \
  -H "X-Pregen-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Response:

{
  "address": "0x1234...abcd"
}

Store the email → WaaP address mapping. You’ll need it for asset transfers and on-chain reference updates.

Don’t have an API key yet? Get in touch → 

Step 2: Integrate the WaaP SDK

WaaP’s SDK is EIP-1193 compliant. If your app uses wagmi, ethers.js, or viem, the swap is straightforward.

Install

npm install @human.tech/waap-sdk

Initialize

import { initWaaP } from '@human.tech/waap-sdk';
 
initWaaP({
  config: {
    // Configure auth methods — match what your Privy integration used
    authenticationMethods: ['email', 'social'],
    allowedSocials: ['google', 'discord'],
    styles: { darkMode: true }
  }
});

Connect with wagmi

import { usePrivy } from '@privy-io/react-auth';
const { login } = usePrivy();

// window.waap is an EIP-1193 provider
// wagmi picks it up automatically
// Standard useAccount(), useConnect(), etc.

The WaaP SDK provides window.waap as an EIP-1193 provider. Any library that works with MetaMask works with WaaP — no code changes beyond initialization.

Use the Playground to visually configure auth methods, styling, and social providers, then copy the generated config.

Step 3: Migrate Wallets by Type

Client-Side EOA Wallets

These require user participation — the user must transfer assets from their old Privy wallet to their new WaaP wallet.

What to build:

1. A migration prompt in your app UI that shows the user their new WaaP wallet address.
2. An asset transfer flow — either manual (user sends assets themselves) or assisted (you build a transfer helper using Privy’s exportWallet() and a signing flow).

User experience:

1. User logs into your app → WaaP authentication matches them to their pre-generated account via email.
2. Your app shows: “Your new wallet address is 0x1234.... Transfer your assets from your previous wallet.”
3. User transfers tokens, NFTs, and positions from old Privy address to new WaaP address.
4. Done — user continues using your app with WaaP.

Developer checklist:

• Map Privy user IDs → WaaP user IDs in your backend
• Update any on-chain references to user addresses (allow-lists, vesting schedules, etc.)
• Build migration UI with clear instructions and address display
• Send migration emails/notifications to users who haven’t migrated after N days

Server-Side EOA Wallets

These are fully automatable. The user never held the key directly, so you can orchestrate the entire migration programmatically.

Migration script (pseudocode):

for (const user of serverSideWalletUsers) {
  // 1. Get user's new WaaP address (already pre-generated in Step 1)
  const waapAddress = addressMap[user.email];
 
  // 2. Export key from Privy (server-side API)
  const privyKey = await privy.exportWallet(user.privyWalletId);
 
  // 3. Transfer all assets from old address to new address
  await transferAllAssets(privyKey, waapAddress);
 
  // 4. Securely dispose of the exported key
  privyKey.destroy(); // Never persist to disk or logs
}

Developer checklist:

• Script batch export → transfer flow
• Handle multi-chain assets (run transfers on each chain where user has balances)
• Notify users that their wallet address has changed
• Update backend references and any dependent integrations

Smart Wallets (ERC-4337)

Smart wallets are on-chain contracts — the address doesn’t change. Instead of transferring assets, you transfer ownership of the smart contract to the new WaaP wallet.

// Interface depends on your smart account implementation
// SimpleAccount / Kernel / Safe each have different functions
 
// Example: SimpleAccount-style
function transferOwnership(address newOwner) external onlyOwner;

Developer checklist:

• Identify which smart account implementation you use (SimpleAccount, Kernel, Safe, Biconomy, etc.)
• Execute ownership transfer for each smart wallet
• Update bundler/paymaster to accept WaaP-signed UserOperations
• Test signing, gas sponsorship, and all smart account features end-to-end

Step 4: Migrate Agent Wallets (If Applicable)

If you’re using Privy server wallets for AI agent operations, the migration path is:

1. Pre-generate agent wallets via the Account Pregeneration API (same as Step 1).
2. Install waap-cli in your agent’s runtime:

   npm install -g @human.tech/waap-cli@latest

3. Transfer agent funds from Privy server wallet addresses to new WaaP addresses.
4. Replace Privy SDK calls with waap-cli commands:

   # Sign and send a transaction
   waap-cli send-tx --to 0x... --value 0.01 --chain-id 1
    
   # Sign EIP-712 typed data (e.g., Polymarket orders)
   waap-cli sign-typed-data --data '{...}'
    
   # Check balance
   waap-cli request eth_getBalance '["0x...","latest"]' --chain-id 1

5. Configure security policies:

   # Set daily spend limit
   waap-cli policy set --daily-spend-limit 500
    
   # Enable 2FA via Telegram for high-risk operations
   waap-cli 2fa enable --telegram <chat_id>

6. Set up Permission Tokens for routine agent operations that should bypass 2FA (max 2 hours, scoped to specific actions).

For full CLI documentation, see WaaP for Agents.

Migration Summary

Recommended Timeline

Need Help?

• Get in touch  — Migration support, API key setup, and custom timeline planning.
• Documentation — Full SDK and CLI reference throughout this site.
• Live examples — See working integration recipes.