> For the complete documentation index, see [llms.txt](/llms.txt).

# Web3Auth web SDK v8 to v10 migration guide

This guide will help you upgrade your Web3Auth SDK integration from v8 directly to the **unified Web3Auth Web SDK v10**, focusing on core package and initialization changes.

## Why migrate to v10?[​](#why-migrate-to-v10 "Direct link to Why migrate to v10?")

Web3Auth v10 consolidates functionality into a single powerful SDK that centralizes configuration in the dashboard and eliminates frontend adapter complexity.

Key improvements from v8 to v10:

- **Unified SDK Package:** Single `@web3auth/modal` package replaces multiple adapter packages
- **Dashboard-Centric Configuration:** Chain configurations managed via Web3Auth Developer Dashboard (now the [Embedded Wallets dashboard](https://developer.metamask.io/))
- **Simplified Integration:** No more manual `OpenLoginAdapter` registration
- **Enhanced Developer Experience:** Cleaner API with better TypeScript support

## Installation[​](#installation "Direct link to Installation")

Update to the unified v10 SDK package:

- npm
- Yarn
- pnpm
- Bun

```
npm uninstall @web3auth/modal @web3auth/openlogin-adapter @web3auth/wallet-services-plugin
npm install @web3auth/modal

```

```
yarn remove @web3auth/modal @web3auth/openlogin-adapter @web3auth/wallet-services-plugin
yarn add @web3auth/modal

```

```
pnpm remove @web3auth/modal @web3auth/openlogin-adapter @web3auth/wallet-services-plugin
pnpm add @web3auth/modal

```

```
bun remove @web3auth/modal @web3auth/openlogin-adapter @web3auth/wallet-services-plugin
bun add @web3auth/modal

```

For custom blockchain configurations:

- npm
- Yarn
- pnpm
- Bun

```
npm install @web3auth/ethereum-provider

```

```
yarn add @web3auth/ethereum-provider

```

```
pnpm add @web3auth/ethereum-provider

```

```
bun add @web3auth/ethereum-provider

```

## Breaking changes from v8 to v10[​](#breaking-changes-from-v8-to-v10 "Direct link to Breaking changes from v8 to v10")

### 1. Unified SDK package structure[​](#1-unified-sdk-package-structure "Direct link to 1. Unified SDK package structure")

**v8 used separate packages:**

```
import { Web3Auth } from '@web3auth/modal'
import { OpenloginAdapter } from '@web3auth/openlogin-adapter'
import { WalletServicesPlugin } from '@web3auth/wallet-services-plugin'

```

**v10 uses a single package:**

```
import { Web3Auth } from '@web3auth/modal'
// Most functionality is now built-in - no separate adapters needed for basic use cases

```

### 2. Openloginadapter → authadapter → built-in (v8→v9→v10)[​](#2-openloginadapter--authadapter--built-in-v8v9v10 "Direct link to 2. Openloginadapter → authadapter → built-in (v8→v9→v10)")

In v8, authentication used `OpenloginAdapter`. V9 renamed it to `AuthAdapter`. V10 eliminates the need for separate adapters in most cases.

```
import { OpenloginAdapter } from '@web3auth/openlogin-adapter'

const openloginAdapter = new OpenloginAdapter({
  loginSettings: {
    mfaLevel: 'optional',
  },
  adapterSettings: {
    whiteLabel: {
      name: 'Your App',
      logoLight: 'https://example.com/logo-light.png',
      logoDark: 'https://example.com/logo-dark.png',
    },
  },
})

web3auth.configureAdapter(openloginAdapter)

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

const web3auth = new Web3Auth({
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  // MFA and branding now configured here or via dashboard
  mfaLevel: MFA_LEVELS.OPTIONAL,
})

```

### 3. Chain configuration centralization[​](#3-chain-configuration-centralization "Direct link to 3. Chain configuration centralization")

**v8 required manual chain and provider configuration:**

```
import { EthereumPrivateKeyProvider } from '@web3auth/ethereum-provider'
import { getEvmChainConfig } from '@web3auth/base'

const chainConfig = getEvmChainConfig(1, 'YOUR_CLIENT_ID')

const privateKeyProvider = new EthereumPrivateKeyProvider({
  config: { chainConfig },
})

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

```

**v10 handles standard chains automatically via dashboard:**

```
const web3auth = new Web3Auth({
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  // Chain configuration managed via Web3Auth Developer Dashboard
})

```

Configure your chains on the [Embedded Wallets dashboard](https://developer.metamask.io/) instead of in code.

### 4. Method name changes[​](#4-method-name-changes "Direct link to 4. Method name changes")

```
// Parameter rename
const web3auth = new Web3Auth({
  useCoreKitKey: true,
  useSFAKey: true,
})

// Method rename
const userAuthInfo = await web3auth.authenticateUser()
const userAuthInfo = await web3auth.getIdentityToken()
const idToken = userAuthInfo.idToken

```

**External Wallet Adapters:** If you used external wallet adapters (for example, MetaMask, Phantom, Solflare) in v8, see the 🔌 [External Wallet Adapters Migration Guide](/embedded-wallets/sdk/js/migration-guides/modal/v8-to-v10/external-wallets/) for migrating to the automatic detection system.

**Wallet Services:** If you used the `@web3auth/wallet-services-plugin` in v8, see the 🛠️ [Wallet Services migration guide](/embedded-wallets/sdk/js/migration-guides/modal/v8-to-v10/wallet-services/) for migrating to the built-in integration.

**Whitelabeling and UI customization:** If you had whitelabeling configurations in v8, see the 📋 [whitelabeling migration guide](/embedded-wallets/sdk/js/migration-guides/modal/v8-to-v10/whitelabeling/) for detailed steps.

**Custom authentication:** If you used custom verifiers in v8, see the 🔐 [custom authentication migration guide](/embedded-wallets/sdk/js/migration-guides/modal/v8-to-v10/custom-authentication/) for migrating to the new connections system.

## Complete migration example[​](#complete-migration-example "Direct link to Complete migration example")

Here's a complete before/after example showing the migration from v8 to v10:

- v8 Configuration
- v10 Configuration

```
import { Web3Auth } from '@web3auth/modal'
import { OpenloginAdapter } from '@web3auth/openlogin-adapter'
import { EthereumPrivateKeyProvider } from '@web3auth/ethereum-provider'
import { getEvmChainConfig } from '@web3auth/base'

const clientId = 'YOUR_CLIENT_ID'
const chainConfig = getEvmChainConfig(1, clientId)

const privateKeyProvider = new EthereumPrivateKeyProvider({
  config: { chainConfig },
})

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

const openloginAdapter = new OpenloginAdapter({
  loginSettings: {
    mfaLevel: 'optional',
  },
  adapterSettings: {
    whiteLabel: {
      name: 'Your App',
      logoLight: 'https://example.com/logo-light.png',
    },
  },
})

web3auth.configureAdapter(openloginAdapter)
await web3auth.initModal()

```

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

const web3auth = new Web3Auth({
  clientId: 'YOUR_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  // Chain configuration managed via dashboard
  // Branding configured via dashboard
  // No adapters needed for basic functionality
})

await web3auth.init()

```

## Dashboard configuration required[​](#dashboard-configuration-required "Direct link to Dashboard configuration required")

With v10, configurations that were previously done in code are now managed through the Web3Auth Developer Dashboard:

1. **Chain Configurations:** Add and configure your blockchain networks
2. **Branding and UI:** Set app name, logos, colors, and themes
3. **Login Methods:** Enable/disable social login providers

Configure these settings from the [Web3Auth Developer Dashboard](https://developer.metamask.io).

## Next steps[​](#next-steps "Direct link to Next steps")

- [Web3Auth Documentation - Web SDK v10](https://web3auth.io/embedded-wallets/sdk/js)
- [Web3Auth v10 Examples on GitHub](https://github.com/Web3Auth/web3auth-examples)
- [Join the community](https://web3auth.io/community)