Upgrade by redirect

Navigate the user to the Dynamic upgrade app and read the outcome when they return, using detectUpgradeRedirect and completeUpgradeRedirect.

Navigate the user to the upgrade app, then handle the outcome when they return. This is the simplest route — see the overview for detection, hosting, and the shared CORS requirements.

The return leg is two functions, matching how social sign-in and device registration consume their redirects:

• detectUpgradeRedirect({ url }) — a pure, synchronous check for whether the URL is a return from the upgrade app.
• completeUpgradeRedirect({ url }, client?) — reads the outcome, refreshes the session on success, and returns it (null when there’s nothing to consume). The refresh is best-effort: the upgrade already succeeded on the backend, so a failed refresh still reports success and reconciles on the next auth refresh.

You always pass the URL yourself — window.location.href.

TypeScript

import {
  startUpgradeRedirect,
  detectUpgradeRedirect,
  completeUpgradeRedirect,
} from '@dynamic-labs-sdk/legacy-embedded-wallet-upgrade';

// On your "Upgrade wallet" button. redirectUrl defaults to the current page.
function startUpgrade() {
  void startUpgradeRedirect();
}

// Run once on the page the user returns to.
async function handleUpgradeReturn() {
  if (!detectUpgradeRedirect({ url: window.location.href })) return;

  const outcome = await completeUpgradeRedirect({ url: window.location.href });
  if (outcome?.status === 'success') {
    // The session was already refreshed for you. refreshUi is your implementation.
    refreshUi();
  } else {
    // offerRetry is your implementation — the upgrade failed or was cancelled.
    offerRetry();
  }
}

React

useUpgradeRedirectResult runs the detect + complete steps once on mount and strips the result parameter from the URL for you. Drive your UI off result (the outcome once the user returns, undefined until then) and error (set if consuming the return fails). onComplete / onError callbacks are also available if you prefer.

import { startUpgradeRedirect } from '@dynamic-labs-sdk/legacy-embedded-wallet-upgrade';
import { useUpgradeRedirectResult } from '@dynamic-labs-sdk/legacy-embedded-wallet-upgrade/react';

function UpgradeButton() {
  const { result, error } = useUpgradeRedirectResult();

  if (result?.status === 'success') {
    // The session was already refreshed for you.
    return <p>Wallet upgraded.</p>;
  }

  const failed = error !== undefined || result?.status === 'error';

  return (
    <>
      <button type="button" onClick={() => void startUpgradeRedirect()}>
        Upgrade wallet
      </button>
      {failed && <p>Upgrade failed — try again.</p>}
    </>
  );
}

Handling errors

Situation	What to do
Outcome status is error	The upgrade failed or was cancelled — offer a retry.

See also

• Upgrade overview — detection, hosting, and shared requirements
• Embed the app (iframe)
• Popup (new window)
• Going lower-level