Upgrading embedded wallets

The React SDK ran the wallet upgrade inside its widget. In the JavaScript SDK you detect who needs upgrading and route them to the ready-made upgrade app with the legacy-embedded-wallet-upgrade package.

Some users may still hold an earlier generation of embedded wallet that must be moved onto Dynamic WaaS, and the wallet keeps the same address. This upgrade is required, not optional: the JavaScript SDK does not support legacy wallets, so no chain extension registers a provider for them and those users cannot sign until they upgrade.

The React SDK ran this upgrade automatically inside its widget. In the JavaScript SDK there’s no widget, so the two things the widget did for you (detecting who needs the upgrade and running the flow) are now steps you trigger yourself with the @dynamic-labs-sdk/legacy-embedded-wallet-upgrade package.

The build itself (detect, then upgrade by redirect / embed / popup, plus hosting and CORS) is identical in any JavaScript SDK app, so it lives in one place: Upgrading legacy embedded wallets to Dynamic WaaS (Building UI). This page only covers what changes when you migrate off the React widget.

If any of your users use passkeys for sign-in or MFA, the upgrade app must run on the domain your passkeys were registered on, because passkeys only work on that domain or its subdomains. See Passkey users require your own domain.

What maps to what

React SDK (widget did this for you)	JavaScript SDK (you do it with the package)
detected the upgradeable wallet	hasWalletsRequiringUpgrade() / getWalletsRequiringUpgrade()
ran the in-app upgrade flow	route to the upgrade app: startUpgradeRedirect() or openUpgradeIframe()
showed completion in the widget	react to the returned outcome, { status: 'success' | 'error' }

React hooks (useHasWalletsRequiringUpgrade, useUpgradeRedirectResult, useUpgradeIframe) live in the package’s /react entry. See the Building UI guide for the full code, the embed/popup paths, and the required origin allowlist.

See also

• Upgrading legacy embedded wallets to Dynamic WaaS: the full build
• Post-login user setup: detect upgrade needs alongside other post-login steps
• Embedded wallets: setup & creation: creating new WaaS wallets