Password encryption

Add password protection to embedded wallets for enhanced security

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

If the user loses their password, they will lose access to their wallet. There is no way to recover the password or the wallet without it.

Password encryption adds an extra layer of security to embedded wallets by requiring a password to decrypt the user’s key share. This ensures that even if an attacker gains access to the stored key share, they cannot use it without the password.

How it works

When password encryption is enabled, it specifically protects the client-side key share:

1. The user’s client key share is encrypted with their password.
2. This encrypted share is sent through an encryption proxy which adds a second layer of encryption before storing it on Dynamic’s servers. This ensures the share is double-encrypted and accessible from any device.
3. Operations like signing transactions require the password to decrypt this share once per session; after unlocking, the user is not prompted again until the next session.
4. The password is never sent to Dynamic; decryption happens entirely client-side.
5. No single party (Dynamic, encryption provider) can access the key share alone.

Requiring password for wallets

You can require all wallets to have a password in the Dynamic Dashboard:

1. Navigate to Embedded Wallets.
2. Toggle Require Password to enforce that all wallets must be created with a password.

When Require Password is enabled, a password must be provided when creating a wallet. Attempting to create a wallet without a password will return an error. Once the wallet is created and unlocked, it remains unlocked for the rest of the session—the password is not required for every operation.

Wallet creation flows

When password protection is enabled, you can choose between using Dynamic’s built-in UI or building your own.

Using Dynamic’s UI

If you have enabled Automatic Wallet Creation in the dashboard, Dynamic will automatically prompt the user to create a password when they log in. No additional code is required.

Using a custom UI

If you prefer to build your own password entry UI, you must manually create the wallet using createWalletAccount and pass the password.

import { useDynamicWaas } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api-core";

const { createWalletAccount } = useDynamicWaas();

const createSecureWallet = async (password: string) => {
  const wallet = await createWalletAccount(
    [ChainEnum.Evm],
    password
  );

console.log('Password-protected wallet created:', wallet);
};

Password management

• Users set their own password during wallet creation
• They must enter the password to unlock the wallet
• Important: If the user forgets their password, wallet recovery is not possible without a backup.

Unlocking a wallet

If you use Dynamic’s built-in UI, the user is prompted for their password when needed; you do not need to call unlock yourself. The following applies when you build a custom UI.

Custom UI flow

If you are building a custom UI implementation, you must check the wallet lock state and unlock the wallet programmatically before performing any wallet operations. If you skip this step, Dynamic’s default password modal will appear, which defeats the purpose of a custom UI integration.

The required flow for custom UI implementations is:

1. Check wallet state — Call checkWalletLockState to determine if the wallet is password-encrypted and currently locked.
2. Unlock if needed — If the wallet is locked, collect the password in your own UI and call unlockWallet.
3. Proceed with operations — Only after the wallet is unlocked should you perform signing, transactions, or other wallet operations.

import { useWalletPassword } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api-core";

const { unlockWallet, checkWalletLockState } = useWalletPassword();

const ensureWalletUnlocked = async (accountAddress: string, password: string) => {
  // 1. Check if wallet is locked
  const recoveryState = await checkWalletLockState({
    accountAddress,
    chainName: ChainEnum.Evm,
  });

  if (recoveryState?.isPasswordEncrypted) {
    // 2. Unlock with the user's password
    const success = await unlockWallet({
      accountAddress,
      chainName: ChainEnum.Evm,
      password,
    });

    if (!success) {
      throw new Error('Failed to unlock wallet');
    }
  }

  // 3. Wallet is now ready for operations
};

Using unlockWallet directly

Before performing operations with a password-protected wallet in your own flow, unlock it using the useWalletPassword hook:

import { useWalletPassword } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api-core";

const { unlockWallet, state } = useWalletPassword();

const handleUnlock = async (accountAddress: string, password: string) => {
  const success = await unlockWallet({
    accountAddress,
    chainName: ChainEnum.Evm,
    password,
  });

if (success) {
  console.log('Wallet unlocked for this session');
}
};

Once unlocked, the wallet remains unlocked for the rest of the user session (until logout). The user is only asked for the password once per session.

Unlocking one wallet unlocks all wallets associated with the user account. As a result, all wallets for a user must share the same password.

Operations requiring password

Any operation that changes the underlying key shares requires the password to be provided again, even if the wallet is currently unlocked. These operations include:

• Refreshing shares
• Resharing (Cloud backup)
• Delegation

This is because the new shares generated during these processes must be encrypted with the same password before they are stored.

Dynamic’s UI does not automatically prompt for the password during these operations. You must pass the password programmatically to these functions.

Setting a password on an existing account

If a wallet was created without a password, you can add password protection later using setPassword. This is useful when you want to enable password encryption for users who initially created their wallet without one.

import { useWalletPassword } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api-core";

const { setPassword } = useWalletPassword();

const addPasswordToWallet = async (
  accountAddress: string,
  newPassword: string
) => {
  const success = await setPassword({
    accountAddress,
    chainName: ChainEnum.Evm,
    password: newPassword,
  });

  if (success) {
    console.log('Password added to existing wallet');
  }
};

Migrating existing wallets

Enabling Require Password in the dashboard only enforces password protection for new wallets. Existing wallets created before this setting was enabled remain unprotected.

To migrate an existing wallet to password protection:

1. Check if the wallet is already password-protected.
2. If it is not encrypted, prompt the user for a password and set it.

import { useWalletPassword } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api-core";

const MigrateWallet = () => {
  const { setPassword, checkWalletLockState } = useWalletPassword();

  const migrate = async (accountAddress: string, newPassword: string) => {
    // 1. Check if already encrypted
    const { isPasswordEncrypted } = await checkWalletLockState({
      accountAddress,
      chainName: ChainEnum.Evm,
    });

    if (isPasswordEncrypted) {
      console.log('Wallet is already password protected');
      return;
    }

    // 2. Set password
    const success = await setPassword({
      accountAddress,
      chainName: ChainEnum.Evm,
      password: newPassword,
    });

    if (success) {
      console.log('Wallet migrated to password protection');
    }
  };

  return (
    // Your UI implementation
    <></>
  );
};

Updating the password

Change an existing password using updatePassword. This will update the password for all wallets associated with the user account.

import { useWalletPassword } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api-core";

const { updatePassword } = useWalletPassword();

const changePassword = async (
  accountAddress: string,
  currentPassword: string,
  newPassword: string
) => {
  const success = await updatePassword({
    accountAddress,
    chainName: ChainEnum.Evm,
    existingPassword: currentPassword,
    newPassword,
  });

  if (success) {
    console.log('Password updated');
  }
};

Checking wallet lock state

Check if a wallet requires unlocking:

import { useWalletPassword } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api-core";

const { checkWalletLockState } = useWalletPassword();

const checkState = async (accountAddress: string) => {
  const recoveryState = await checkWalletLockState({
    accountAddress,
    chainName: ChainEnum.Evm,
  });

  console.log('Wallet recovery state:', recoveryState);
};

Complete example

This example demonstrates how to check the wallet state, unlock it if necessary, and then sign a message — the recommended pattern for custom UI implementations.

import { useState } from 'react';
import { useDynamicWaas, useWalletPassword } from "@dynamic-labs/sdk-react-core";
import { ChainEnum } from "@dynamic-labs/sdk-api-core";

const PasswordProtectedWallet = () => {
  const [password, setPassword] = useState('');
  const { createWalletAccount, getWaasWallets } = useDynamicWaas();
  const { unlockWallet, checkWalletLockState, state } = useWalletPassword();

  const createWallet = async () => {
    const wallet = await createWalletAccount([ChainEnum.Evm], password);
    console.log('Wallet created:', wallet);
  };

  const unlock = async () => {
    const wallets = await getWaasWallets();
    if (wallets.length === 0) return;

    // 1. Check if wallet is locked
    const recoveryState = await checkWalletLockState({
      accountAddress: wallets[0].address,
      chainName: ChainEnum.Evm,
    });

    if (recoveryState?.isPasswordEncrypted) {
      // 2. Unlock with the user's password
      await unlockWallet({
        accountAddress: wallets[0].address,
        chainName: ChainEnum.Evm,
        password,
      });
    }

    // 3. Wallet is now ready for signing, transactions, etc.
    console.log('Wallet ready');
  };

  return (
    <div>
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Enter password"
      />
      <button onClick={createWallet}>
        Create Password-Protected Wallet
      </button>
      <button onClick={unlock} disabled={state.isLoading}>
        Unlock Wallet
      </button>
      {state.error && <p>Error: {state.error}</p>}
    </div>
  );
};

Security considerations

Password-protected wallets are only as secure as the password itself. Enforce strong password requirements and educate users about password security.

• Password strength: Require minimum length and complexity
• No password recovery: If using user-provided passwords, there’s no way to recover a forgotten password without a backup.
• Session-based unlock: Wallets remain unlocked for the session, reducing friction while maintaining security
• Combine with backups: Consider enabling Google Drive backup for additional recovery options

Related

• useWalletPassword - API reference
• Creating Embedded Wallets - Wallet creation options
• Recovery - Recovery flow with password protection
• Password encryption (JavaScript) - Vanilla JS SDK guide
• Password encryption (React Native) - React Native guide