Upgrade SDK from V4 to V5

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.

Upgrade to V5 to use the latest React SDK APIs and Dynamic’s current embedded wallet infrastructure. V3 embedded wallets use TSS-MPC for stronger key security, sub-second signing, flexible recovery options, and broader chain support. Learn more about V3 embedded wallets.

SDK and wallet version numbers overlap. The React SDK and embedded wallets have independent version histories. In this guide, SDK V5 means React SDK major version 5, while wallet V1/V2/V3 means embedded wallet generations. React SDK V5 creates V3 wallets, while existing V1/V2 wallets are supported only through the migration flow.

Check whether wallet migration is required

Follow the Dynamic CLI getting started guide to install the CLI, authenticate, and select the environment you want to check. Then run:

dyn wallets list-active-embedded-versions --output json | jq '{
  migrationRequired: any(.[]; . == "V1" or . == "V2"),
  legacyVersions: [.[] | select(. == "V1" or . == "V2")],
  legacyVersionCount: ([.[] | select(. == "V1" or . == "V2")] | length)
}'

If migrationRequired is true, add the migration flow described below. legacyVersions lists the legacy version types in use, and legacyVersionCount counts those version types. This endpoint reports which versions are active, not the number of wallets or users on each version. If migrationRequired is false, you can skip the migration section. To inspect an individual user’s wallet versions, open Authenticated Users in the Dynamic dashboard, select the user, and open the Account tab. To see the wallet version configured for new users, open Embedded Wallets.

Upgrade checklist

Update every @dynamic-labs/* package to the latest V5 version.
Replace removed APIs (see Removed APIs).
If the environment includes V1/V2 wallets, add a migration path (see Migrate existing embedded wallets).

Update your packages

Update all Dynamic packages to V5 at the same time. Mixing V4 and V5 packages is not supported. See the latest version on npm.

Breaking changes

Embedded wallets require V3

V5 does not use V1/V2 wallets for normal wallet operations. Users can still access a legacy wallet through the migration flow, where they export its private key and import it into V3. Importing the same key preserves the wallet address and access to its funds. In React, after the SDK detects a V1/V2 wallet without a migration UI, it throws this developer-facing Error:

A legacy embedded wallet (V1/V2) was detected, but `LegacyWalletMigrationProvider` from `@dynamic-labs/legacy-embedded-wallet-migration` is not mounted. Legacy wallets are no longer supported natively by `@dynamic-labs/sdk-react-core` — mount the migration provider so the user can complete the migration to a V3 WaaS wallet before performing any further actions.

Mounting LegacyWalletMigrationProvider satisfies this check. See Migrate existing embedded wallets.

Legacy embedded wallet connectors removed from chain aggregators

EthereumWalletConnectors and SolanaWalletConnectors no longer bundle the legacy embedded wallet connectors. New embedded wallets don’t need them. If you need to support migration from legacy embedded wallets, import the legacy connectors separately and add them alongside your other connectors:

import { LegacyEVMEmbeddedWalletConnectors } from '@dynamic-labs/embedded-wallet-evm';
import { EthereumWalletConnectors } from '@dynamic-labs/ethereum';
import { LegacySolanaEmbeddedWalletConnectors } from '@dynamic-labs/embedded-wallet-solana';
import { SolanaWalletConnectors } from '@dynamic-labs/solana';

const walletConnectors = [
  EthereumWalletConnectors,
  LegacyEVMEmbeddedWalletConnectors,
  SolanaWalletConnectors,
  LegacySolanaEmbeddedWalletConnectors,
];

Add only the connectors for the chains you support. Pair them with LegacyWalletMigrationProvider so users can upgrade — see Migrate existing embedded wallets.

`@dynamic-labs/eclipse` removed

The @dynamic-labs/eclipse package has been removed. Use @dynamic-labs/solana for Eclipse and other Solana-based chains.

Removed APIs

Removed	Replacement
`useUpgradeEmbeddedWallet`	Use the migration flow from `@dynamic-labs/legacy-embedded-wallet-migration`
`useUpgradeToDynamicWaasFlow`	Use the migration flow from `@dynamic-labs/legacy-embedded-wallet-migration`
`useEmbeddedWallet().revealWalletKey`	`useLegacyWalletExport().revealWalletKey` (from the migration package)
`useFunding`	`useOnramp` (was already deprecated in V4)
`handleUnlinkWallet` (from `useDynamicContext`)	`removeWallet` (from `useDynamicContext`)

Migrate existing embedded wallets

This section only applies if you have users on legacy (V1/V2) embedded wallets. If you don’t, there is nothing to do here — you can skip it.

Users on legacy V1/V2 embedded wallets must upgrade to a V3 wallet. The upgrade always follows the same shape: the user exports the legacy wallet’s private key, and that key is imported into a new V3 wallet. The private key is only ever handled client-side.

If you use Account Abstraction, the migration flow automatically resolves the legacy EOA signer behind an ERC-4337 smart wallet or ERC-7702 account. Importing the same key preserves the signer’s address, so no separate smart wallet migration is required.

Choose one of two paths:

With the built-in UI — Dynamic renders a migration modal that walks the user through export and upgrade. This is the simplest option and the default.
Without the UI (headless) — you build your own UI and drive the upgrade programmatically. Use this when you need full control over the experience.

All migration APIs live in the @dynamic-labs/legacy-embedded-wallet-migration package:

npm install @dynamic-labs/legacy-embedded-wallet-migration

With the built-in UI

React
React Native

Mount LegacyWalletMigrationProvider inside your DynamicContextProvider. When a legacy wallet is detected, the migration modal opens automatically and handles the export and upgrade end-to-end.

import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core';
import { LegacyWalletMigrationProvider } from '@dynamic-labs/legacy-embedded-wallet-migration';

const App = () => (
  <DynamicContextProvider settings={{ environmentId: 'YOUR_ENVIRONMENT_ID' }}>
    <LegacyWalletMigrationProvider>
      <YourApp />
    </LegacyWalletMigrationProvider>
  </DynamicContextProvider>
);

To open the flow manually (for example, from a “Migrate wallet” button) instead of relying on auto-open, use useLegacyWalletMigration:

import { LegacyWalletMigrationProvider, useLegacyWalletMigration } from '@dynamic-labs/legacy-embedded-wallet-migration';

const MigrateButton = () => {
  const { startUpgrade } = useLegacyWalletMigration();
  return <button onClick={() => startUpgrade()}>Migrate wallet</button>;
};

The migration modal is built into the SDK and opens automatically when a legacy wallet is detected. No extra components are required — auto-open is on by default:

import { createClient } from '@dynamic-labs/client';
import { ReactNativeExtension } from '@dynamic-labs/react-native-extension';

export const dynamicClient = createClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  // legacyWalletMigrationModal: { autoOpen: true } is the default
}).extend(ReactNativeExtension());

The modal renders inside the SDK’s webview and walks the user through exporting the key and upgrading to V3.

Without the UI (headless)

Disable the built-in modal, then drive the upgrade with your own UI. Choose this option when you need to integrate migration into an existing flow, match custom UI or accessibility requirements, or control when each step appears. You must build and maintain the loading, error, and completion states yourself, so use the built-in UI unless you need that control. The steps are the same on both platforms:

Detect the legacy wallets that need migration.
Trigger the private key export for the user.
Pass the exported key to the upgrade call.

The export UI displays the private key inside a cross-origin iframe. Application code cannot read the key while it remains in the iframe. In a headless flow, the user copies the key into an application-controlled input, so your application can access it at that point. Keep the value in memory only long enough to call the upgrade API. Do not log it, persist it, send it to your backend, or include it in analytics or error reports. Clear the input and application state after each upgrade attempt.

React
React Native

Mount LegacyWalletMigrationProvider with autoOpen={false} (this still satisfies the legacy-wallet enforcement check), then use the migration hooks to build your own UI.

import {
  LegacyWalletMigrationProvider,
  useLegacyWalletsToMigrate,
  useLegacyWalletExport,
  useUpgradeToDynamicWaas,
} from '@dynamic-labs/legacy-embedded-wallet-migration';

const MigrationUI = () => {
  const walletsToMigrate = useLegacyWalletsToMigrate();
  const { revealWalletKey } = useLegacyWalletExport();
  const { upgradeToDynamicWaas } = useUpgradeToDynamicWaas();

  return (
    <>
      {walletsToMigrate.map((wallet, index) => (
        <div key={wallet.id}>
          {/* Step 1: export the legacy key into a container you own */}
          <button
            onClick={() =>
              revealWalletKey({
                wallet,
                type: 'privateKey',
                htmlContainerId: `export-container-${index}`,
              })
            }
          >
            Export key
          </button>
          <div id={`export-container-${index}`} />

          {/* Step 2: pass the exported key back to upgrade the wallet */}
          <button
            onClick={() => upgradeToDynamicWaas({ privateKey: 'PASTED_KEY', wallet })}
          >
            Upgrade to Dynamic WaaS
          </button>
        </div>
      ))}
    </>
  );
};

const App = () => (
  <LegacyWalletMigrationProvider autoOpen={false}>
    <MigrationUI />
  </LegacyWalletMigrationProvider>
);

Mounting LegacyWalletMigrationProvider with autoOpen={false} satisfies the legacy-wallet enforcement check for you, and the migration hooks work whether or not you render the built-in modal.

Set legacyWalletMigrationModal: { autoOpen: false } when creating the client, then read the legacy wallets from the client and drive the upgrade yourself.

import { createClient } from '@dynamic-labs/client';
import { ReactNativeExtension } from '@dynamic-labs/react-native-extension';

export const dynamicClient = createClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  legacyWalletMigrationModal: { autoOpen: false },
}).extend(ReactNativeExtension());

import { useReactiveClient } from '@dynamic-labs/react-hooks';
import { dynamicClient } from './client';

const MigrationScreen = () => {
  const client = useReactiveClient(dynamicClient);
  const walletsToMigrate = client.wallets.embedded.legacyWalletsToMigrate;

  // Step 1: export the legacy key. This opens a sheet where the user copies
  // their private key.
  const exportKey = () =>
    client.ui.wallets.revealEmbeddedWalletKey({ type: 'private-key' });

  // Step 2: pass the exported key back to upgrade the wallet.
  const upgrade = (privateKey: string) =>
    client.wallets.embedded.upgradeToDynamicWaas({ privateKey });

  return null; // render your own UI using walletsToMigrate, exportKey, upgrade
};

Each entry in legacyWalletsToMigrate has id, address, and chain, so you can list the wallets that still need migration.

New features

Legacy embedded wallet migration package

@dynamic-labs/legacy-embedded-wallet-migration is a new package that owns the entire legacy-to-V3 upgrade flow. It provides the built-in migration modal (LegacyWalletMigrationProvider) and the headless building blocks (useLegacyWalletsToMigrate, useHasLegacyWalletsToMigrate, useLegacyWalletExport, useUpgradeToDynamicWaas) so you can offer either experience.

Implementation Guides

SDK Reference

Upgrade SDK from V4 to V5

Recommended: JavaScript SDK with React Hooks

Check whether wallet migration is required

Upgrade checklist

Update your packages

Breaking changes

Embedded wallets require V3

Legacy embedded wallet connectors removed from chain aggregators

`@dynamic-labs/eclipse` removed

Removed APIs

Migrate existing embedded wallets

With the built-in UI

Without the UI (headless)

New features

Legacy embedded wallet migration package

Recommended: JavaScript SDK with React Hooks

​Check whether wallet migration is required

​Upgrade checklist

​Update your packages

​Breaking changes

​Embedded wallets require V3

​Legacy embedded wallet connectors removed from chain aggregators

​@dynamic-labs/eclipse removed

​Removed APIs

​Migrate existing embedded wallets

​With the built-in UI

​Without the UI (headless)

​New features

​Legacy embedded wallet migration package

Check whether wallet migration is required

Upgrade checklist

Update your packages

Breaking changes

Embedded wallets require V3

Legacy embedded wallet connectors removed from chain aggregators

`@dynamic-labs/eclipse` removed

Removed APIs

Migrate existing embedded wallets

With the built-in UI

Without the UI (headless)

New features

Legacy embedded wallet migration package