Upgrade by redirect

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
React

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();
  }
}

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,
  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.

Installation & Configuration

Chains & Networks

Authenticate

User & Session Management

Wallets

Flow

Swaps

Funding & Onramp

Events

Building UI

Migrating from React

Upgrade by redirect

Handling errors

See also

​Handling errors

​See also

Handling errors

See also