For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

Web SDK v11 Migration Guide

This guide upgrades Embedded Wallets Web SDK integrations from v9 or v10 directly to v11 for JavaScript (@web3auth/modal), React (@web3auth/modal/react), and Vue (@web3auth/modal/vue).

AI-assisted migration​

For the best results, install the MetaMask Embedded Wallets skill and MCP server before you migrate. See Build with AI for setup (npx skills add web3auth/skill and MCP at https://mcp.web3auth.io).

Copy the prompt below into your AI coding assistant (Cursor, Claude Code, Codex, Antigravity, or similar):

Migrate my MetaMask Embedded Wallets (@web3auth/modal) project to v11.

Before changing code:
1. Use the web3auth skill and MCP tools (search_docs, get_doc, get_example, get_sdk_reference).
2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/web-v11
3. Detect my framework (JavaScript, React, or Vue) and my current SDK version (v9 or v10).

Then migrate my codebase directly to v11:
- If on v9 modal: apply v9 breaking changes (dashboard chains, connectTo, hooks paths) and v11 changes (connection, Solana kit, polyfills) in one pass.
- If on v9 no-modal: migrate to @web3auth/modal@11, replace Web3AuthNoModal/adapters with connectTo() and dashboard connections, then apply v11 provider/Solana changes.
- If on v10: apply v11 changes only (connection, Solana kit, polyfills, wagmi v3).
- Update package.json dependencies and remove deprecated packages.
- Replace web3auth.provider with connection.ethereumProvider where needed.
- For Solana apps: migrate from @solana/web3.js to @solana/kit and update hook/composable import paths.
- Remove buffer/process/global polyfills added for older SDK versions.
- Do not change my Client ID or Sapphire network unless I ask — that would change wallet addresses.

After migrating, list every file you changed and any manual dashboard steps I still need to do.
tip

Use planning mode (where available) for the initial prompt. Review the plan before generating code; config mistakes can change wallet addresses in production.

Install v11​

npm install @web3auth/modal@11

From v9 no-modal: uninstall legacy packages first, then install the unified SDK:

npm uninstall @web3auth/no-modal @web3auth/auth-adapter @web3auth/wallet-services-plugin
npm install @web3auth/modal@11

Remove other deprecated adapter and plugin packages (see framework tabs below).

For custom blockchain configurations that still need a private key provider in code, you may still install @web3auth/ethereum-provider — but prefer dashboard chain configuration for standard EVM chains.

For Solana apps, also install:

npm install @solana/kit @solana-program/system

React and Vue apps using EVM with Wagmi should upgrade to wagmi v3:

npm install wagmi@3 @tanstack/react-query

For Vue, also register Vue Query in main.ts:

import { VueQueryPlugin } from '@tanstack/vue-query'

createApp(App).use(VueQueryPlugin).mount('#app')

Migrating from v9​

If you're on v9, apply the sections below together with v11 API changes. Version 10 consolidated modal and no-modal flows into @web3auth/modal, moved configuration to the Embedded Wallets dashboard, and integrated Wallet Services and smart accounts into the main SDK — v11 keeps that model and adds the connection API and Solana kit migration described later.

No-modal SDK (v9)​

Recommended: use @web3auth/modal

While @web3auth/no-modal received updates in v9, v11 uses @web3auth/modal for custom UI flows. The modal package supports both the pre-built UI (connect()) and headless custom UI (connectTo()).

Package and class migration​

v9

import { Web3AuthNoModal } from '@web3auth/no-modal'
import { AuthAdapter } from '@web3auth/auth-adapter'

const web3auth = new Web3AuthNoModal({
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  chainConfig,
  privateKeyProvider,
})

v11

import { Web3Auth, WEB3AUTH_NETWORK } from '@web3auth/modal'

const web3auth = new Web3Auth({
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
})

Custom UI: adapters → connectTo​

v9

const authAdapter = new AuthAdapter({
  adapterSettings: {
    loginConfig: {
      google: {
        verifier: 'YOUR_GOOGLE_VERIFIER_NAME',
        typeOfLogin: 'google',
        clientId: 'YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com',
      },
    },
  },
})

web3auth.configureAdapter(authAdapter)
await web3auth.init()

await web3auth.connectTo('auth', {
  loginProvider: 'google',
})

v11

import { AUTH_CONNECTION, WALLET_CONNECTORS, WEB3AUTH_NETWORK, Web3Auth } from '@web3auth/modal'

await web3auth.init()

await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.GOOGLE,
})

// Or with a dashboard connection ID
await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.GOOGLE,
  authConnectionId: 'YOUR_GOOGLE_AUTH_CONNECTION_ID',
})

Verifiers and aggregate verifiers from v9 map to dashboard connections. See Custom authentication.

After sign-in, read the EVM provider from web3auth.connection?.ethereumProvider (see v11 API changes).

Remove packages such as @web3auth/openlogin-adapter and @web3auth/wallet-services-plugin. Wallet Services is built into @web3auth/modal.

If your no-modal init passed chainConfig and EthereumPrivateKeyProvider, remove them and use dashboard chain configuration instead.

General changes (all frameworks)​

Centralized chain configuration​

Remove EthereumPrivateKeyProvider, chainConfig, and privateKeyProvider from Web3AuthOptions for standard EVM chains. Configure chains on the Embedded Wallets dashboard.

import { Web3Auth, WEB3AUTH_NETWORK } from '@web3auth/modal'

const web3auth = new Web3Auth({
  clientId: WEB3AUTH_CLIENT_ID,
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
})

Multi-Factor Authentication (MFA)​

Move MFA settings from AuthAdapter to Web3AuthOptions:

import { MFA_FACTOR, MFA_LEVELS, WEB3AUTH_NETWORK, type Web3AuthOptions } from '@web3auth/modal'

const web3AuthOptions: Web3AuthOptions = {
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  mfaLevel: MFA_LEVELS.MANDATORY,
  mfaSettings: {
    [MFA_FACTOR.DEVICE]: { enable: true, priority: 1, mandatory: true },
    [MFA_FACTOR.BACKUP_SHARE]: { enable: true, priority: 2, mandatory: true },
  },
}

Method renames​

v9v11
useCoreKitKey: trueuseSFAKey: true
web3auth.authenticateUser()web3auth.getIdentityToken()

Wallet Services, whitelabeling, smart accounts, custom auth​

v9 approachv11 approach
@web3auth/wallet-services-pluginBuilt into @web3auth/modal — see Wallet Services
uiConfig / adapter whitelabelDashboard customization — see Whitelabel
@web3auth/account-abstraction-providerDashboard-managed smart accounts — see Smart accounts
Verifiers / aggregate verifiersDashboard connections — see Custom authentication

Framework-specific changes​

Use @web3auth/modal for both modal and custom UI flows.

Modal UI (v9):

import { Web3Auth, WEB3AUTH_NETWORK } from '@web3auth/modal'

const web3auth = new Web3Auth({
  clientId: WEB3AUTH_CLIENT_ID,
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
})

await web3auth.init()
await web3auth.connect()

const provider = web3auth.provider

v11 (modal UI):

await web3auth.init()
await web3auth.connect()

const provider = web3auth.connection?.ethereumProvider ?? null

Custom UI (v9 no-modal): see No-modal SDK (v9) for connectTo() and connection ID migration. After connectTo(), use web3auth.connection?.ethereumProvider.

v11 API changes​

Version 11 introduces the connection object for wallet access, migrates Solana integrations to @solana/kit, and removes the need for browser polyfills. If you're already on v10, this section is the main code update; if you're on v9, apply it together with Migrating from v9.

Provider API changes (all frameworks)​

useWeb3Auth() no longer returns provider​

v10

const { provider } = useWeb3Auth()
const accounts = await provider.request({ method: 'eth_accounts' })

v11

const { connection } = useWeb3Auth()
// connection: { ethereumProvider, solanaWallet, connectorName }

For EVM work in React and Vue, prefer Wagmi hooks (useAccount, useBalance, useSendTransaction). They receive the provider through the Web3Auth connector.

Web3Auth class: provider is write-only​

v10

const provider = web3auth.provider

v11

const provider = web3auth.connection?.ethereumProvider ?? null

When you still need connection.ethereumProvider​

Use it only for JSON-RPC edge cases Wagmi does not cover:

  • private_key for non-EVM chain derivation
  • public_key for social-login server verification
  • Custom JSON-RPC methods

For external wallets, use Wagmi useAccount().address instead of eth_accounts.

const pubKey = await connection?.ethereumProvider?.request({ method: 'public_key' })

Solana migration (all frameworks)​

Remove @solana/web3.js as the primary dependency. Add @solana/kit and @solana-program/system.

v10

import { useSolanaWallet } from '@web3auth/modal/react'

v11

import { useSolanaWallet, useSignTransaction } from '@web3auth/modal/react/solana'

For Vue, import from @web3auth/modal/vue/solana.

v11 useSolanaWallet() return shape:

{
  accounts: string[] | null
  solanaWallet: Wallet | null
  rpc: Rpc<SolanaRpcApi> | null
  getPrivateKey: () => Promise<string>
}

Fetch balance with @solana/kit:

import { address } from '@solana/kit'
import { useSolanaWallet } from '@web3auth/modal/react/solana'

const { accounts, rpc } = useSolanaWallet()
const { value } = await rpc!.getBalance(address(accounts![0])).send()
const sol = Number(value) / 1e9

In Vue, unwrap refs with .value (rpc.value, accounts.value).

See React Solana hooks or Vue Solana composables for transaction examples.

For Vanilla JS, read connection.solanaWallet from web3auth.connection after sign-in. See the JavaScript SDK Solana integration snippets.

Polyfill removal​

Remove these when upgrading to v11:

  • Vite define: { global: 'globalThis' } and browserify aliases
  • devDependencies: buffer, process, crypto-browserify, and related polyfill packages
  • Angular polyfills.ts global / Buffer / process hacks (keep only zone.js)

Framework-specific v11 changes​

After connect(), read the EVM provider from connection:

await web3auth.connect()
const provider = web3auth.connection?.ethereumProvider ?? null

For Solana, use web3auth.connection?.solanaWallet instead of wrapping web3auth.provider in SolanaWallet.

Summary table​

Areav9v10v11
Package@web3auth/modal or no-modal + adapters@web3auth/modal@web3auth/modal@11
Custom UI loginconnectTo('auth', { loginProvider }) + adaptersconnectTo(WALLET_CONNECTORS.AUTH, { authConnection })Same as v10
Chain configCode (chainConfig)DashboardDashboard
Provider from hookproviderproviderconnection or Wagmi
Provider from classweb3auth.providerweb3auth.providerweb3auth.connection?.ethereumProvider
Identity tokenauthenticateUser()getIdentityToken()getIdentityToken()
Solana RPC@solana/web3.js Connection@solana/web3.js Connectionrpc from useSolanaWallet()
Solana hooks path@web3auth/modal/react@web3auth/modal/react@web3auth/modal/react/solana
PolyfillsOften requiredOften requiredNot required

Next steps​

On this page