Upgrading legacy embedded wallets to Dynamic WaaS

Prerequisites

Before this page: users who sign in to your app (see Post-login user setup) and a Dynamic environment with WaaS enabled.

What you’ll build

Some users may still hold an earlier, legacy generation of embedded wallet that should be moved onto Dynamic WaaS. Dynamic provides a ready-made upgrade app that performs the upgrade — the wallet keeps the same address. The @dynamic-labs-sdk/legacy-embedded-wallet-upgrade package wraps the whole flow so you only call functions — it derives the environment from your client, builds the app URL, validates the return URL, and handles the completion handshake. Your job is to:

Detect which users need the upgrade.
Route them to the upgrade app — by redirect, by embedding it, or by popup.
React when the upgrade finishes.

This page covers what’s shared across the routes. Each route then has its own page:

Redirect to the app — navigate away and read the outcome on return.
Embed the app (iframe) — render it inline in a sheet or modal.
Popup (new window) — open it in a separate window. The recommended route for React Native, where it runs in the system auth session.

If none of those fit, going lower-level lets you build the URL and own the mounting yourself.

Install

npm install @dynamic-labs-sdk/legacy-embedded-wallet-upgrade

The React entry point (/react) has react and @dynamic-labs-sdk/react-hooks as optional peer dependencies. Non-React apps import the root and never pull React in.

Detect who needs the upgrade

Two synchronous helpers tell you whether the signed-in user has any wallet that needs upgrading. They read the environment and wallets from your client, so single-client apps call them with no arguments.

TypeScript
React / React Native

import {
  hasWalletsRequiringUpgrade,
  getWalletsRequiringUpgrade,
} from '@dynamic-labs-sdk/legacy-embedded-wallet-upgrade';

function maybePromptUpgrade() {
  if (!hasWalletsRequiringUpgrade()) return;

  const wallets = getWalletsRequiringUpgrade();
  // showUpgradeBanner is your implementation.
  showUpgradeBanner(`${wallets.length} wallet(s) can be upgraded.`);
}

import {
  useHasWalletsRequiringUpgrade,
  useWalletsRequiringUpgrade,
} from '@dynamic-labs-sdk/legacy-embedded-wallet-upgrade/react';

function UpgradeBanner() {
  const needsUpgrade = useHasWalletsRequiringUpgrade();
  const wallets = useWalletsRequiringUpgrade();

  if (!needsUpgrade) return null;

  return <p>{wallets.length} wallet(s) can be upgraded.</p>;
}

Choose a route

Route	When to use
Redirect	Simplest — you don’t mind a full-page navigation away and back.
Embed (iframe)	You want the app inline in your own sheet/modal and never leave the page. Web only.
Popup	A redirect is too heavy but you don’t want it inline. Use this for React Native — it runs in the system auth session.

Hosting the app

By default every helper points at Dynamic’s hosted upgrade app. You can run it three ways:

Dynamic-hosted — use the shared Dynamic-hosted deployment as-is (the default; pass nothing).
Your own subdomain — point a CNAME (e.g. upgrade.yourapp.com) at the deployment so it runs on your own domain and branding.
Fork & self-host — clone the upgrade app repo, build, and host it yourself.

For options 2 and 3, tell the package where the app lives with baseUrl — every entry point accepts it:

const baseUrl = 'https://upgrade.yourapp.com';

// Redirect
void startUpgradeRedirect({ baseUrl });

// Embed
const session = openUpgradeIframe({ baseUrl, container });

// Popup
const popupSession = openUpgradePopup({ baseUrl });

// Low-level
const uri = buildUpgradeUrl({ baseUrl });
const unsubscribe = subscribeToUpgradeCompletion({ baseUrl, onComplete });

Required: allowlist the app’s origin (CORS)

Add the origin serving the app to your environment’s allowed origins in the Dynamic dashboard, or the app’s calls will be blocked:

Your own subdomain / self-host → add your origin (e.g. https://upgrade.yourapp.com).
Dynamic-hosted → add https://upgrade-wallet.dynamic.dev.

If the app can’t reach Dynamic, it shows an “add your domain to allowed origins” screen — a signal that the serving origin isn’t allowlisted.

Custom auth domains

If your environment authenticates through a custom domain (e.g. auth.yourapp.com in place of Dynamic’s default API), the Dynamic-hosted upgrade app only authenticates against that domain once it’s on Dynamic’s internal allowlist. Environments that already had a custom domain configured when Dynamic v5 shipped are allowlisted — the flow works out of the box.

Set up a custom domain more recently and the upgrade fails to reach your API? Reach out to Dynamic to have your domain added to the allowlist. (If you fork and self-host the app, you control this list yourself.)

If you serve the app on a subdomain of your app’s domain and your environment uses cookie-based sessions, an already-signed-in user lands in the app already authenticated — no second login. Otherwise the user simply signs in again with the same credential they use in your app.

Tell the just-arrived user to sign in with the same credential they use in your app — that’s how the app finds the wallet to upgrade.

Handling errors

Situation	What to do
Outcome `status` is `error`	The upgrade failed or was cancelled — offer a retry.
App calls blocked	The serving origin isn’t allowlisted — add it to the environment’s allowed origins.

Route-specific errors (blocked/closed popups, etc.) are covered on each route’s page.

Installation & Configuration

Chains & Networks

Authenticate

User & Session Management

Wallets

Flow

Swaps

Funding & Onramp

Events

Building UI

Migrating from React

Extension Development

Upgrading legacy embedded wallets to Dynamic WaaS

Prerequisites

What you’ll build

Install

Detect who needs the upgrade

Choose a route

Hosting the app

Required: allowlist the app’s origin (CORS)

Custom auth domains

Handling errors

See also

​Prerequisites

​What you’ll build

​Install

​Detect who needs the upgrade

​Choose a route

​Hosting the app

​Required: allowlist the app’s origin (CORS)

​Custom auth domains

​Smoother UX: skip the extra login

​Handling errors

​See also

Prerequisites

What you’ll build

Install

Detect who needs the upgrade

Choose a route

Hosting the app

Required: allowlist the app’s origin (CORS)

Custom auth domains

Smoother UX: skip the extra login

Handling errors

See also