Flutter SDK v8 Migration Guide

This guide upgrades Embedded Wallets Flutter SDK integrations from v3 through v7 directly to v8.

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 Flutter (web3auth_flutter) project to v8.

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/flutter/
3. Detect my current SDK version from pubspec.yaml and list which breaking changes apply.

Then migrate my codebase directly to v8:
- Update web3auth_flutter to ^8.0.0 in pubspec.yaml.
- Set Android minSdkVersion to 26 and compileSdkVersion to 34.
- Set the iOS platform to 14.0 or later and enable Swift Package Manager
  (flutter config --enable-swift-package-manager); v8 no longer pulls Web3Auth through CocoaPods.
- Replace MFALevel.DEFAULT with MFALevel.OPTIONAL, MFALevel.MANDATORY, or MFALevel.NONE.
- Remove sessionTime from Web3AuthOptions unless I need to override the dashboard value.
- Wrap Web3AuthFlutter.initialize() in try/catch; it throws when no session is active.
- If upgrading from v6 or earlier:
  - Replace Web3AuthFlutter.login() with Web3AuthFlutter.connectTo().
  - Replace Provider with AuthConnection and loginProvider with authConnection.
  - Replace loginConfig with authConnectionConfig and LoginConfigItem with AuthConnectionConfig.
  - Replace Network with Web3AuthNetwork and network: with web3AuthNetwork:.
  - Replace redirectUrl: Uri with redirectUrl: String.
  - Replace getPrivKey() with getPrivateKey() and getEd25519PrivKey() with getEd25519PrivateKey().
  - Replace launchWalletServices(ChainConfig) with showWalletUI() and move chains to Web3AuthOptions.
  - Replace request(ChainConfig, method, params) with request(method, params).
  - Replace useCoreKitKey with useSFAKey and buildEnv with authBuildEnv.
  - For Firebase and other JWT providers, pass idToken on LoginParams instead of extraLoginOptions.id_token.
  - Remove any setResultUrl calls (removed in v4).
- Use Web3AuthFlutter.setCustomTabsClosed() on Android for sign-in cancellation handling.
- Do not change my Client ID, Sapphire network, or auth connection IDs 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 v8

Update pubspec.yaml:

dependencies:
  web3auth_flutter: ^8.0.0

Or run:

flutter pub add web3auth_flutter

Set Android minSdkVersion to 26 and compileSdkVersion to 34:

android {
    compileSdkVersion 34

    defaultConfig {
        minSdkVersion 26
    }
}

Set the iOS platform to 14.0 or later in ios/Podfile, and enable Swift Package Manager:

platform :ios, '14.0'

flutter config --enable-swift-package-manager

Add JitPack to your project-level Gradle file and configure platform redirects. See the Flutter SDK get started for Android and iOS setup.

v8 aligns with Android SDK v11 and iOS SDK v13 (Auth v11 and Wallet Services v6).

v8 breaking changes

iOS requires Swift Package Manager

v8 resolves the native Web3Auth Swift SDK v13 through Swift Package Manager. The plugin's podspec no longer declares a CocoaPods Web3Auth dependency, so iOS builds fail unless Swift Package Manager is enabled for your Flutter project:

flutter config --enable-swift-package-manager

Building the Swift package requires Xcode 15 or later. See the Flutter Swift Package Manager guide.

MFALevel.DEFAULT removed

Auth v11 supports only optional, mandatory, and no MFA prompts. Replace MFALevel.DEFAULT with MFALevel.OPTIONAL, MFALevel.MANDATORY, or MFALevel.NONE:

await Web3AuthFlutter.connectTo(
  LoginParams(
    authConnection: AuthConnection.google,
    // v7: mfaLevel: MFALevel.DEFAULT,
    mfaLevel: MFALevel.OPTIONAL,
  ),
);

sessionTime is now optional

Web3AuthOptions.sessionTime is now nullable and has no default in Dart. When you don't set it, the native SDK uses the session duration from your project configuration in the dashboard (30 days if not configured). Remove sessionTime from your options unless you need to override the dashboard value.

initialize throws without an active session

Web3AuthFlutter.initialize() restores the session managed by the native SDKs. On iOS, initialize now verifies that an authenticated session exists, and throws when it doesn't. Wrap the call in try/catch on both platforms:

await Web3AuthFlutter.init(options);

try {
  await Web3AuthFlutter.initialize();
} catch (e) {
  // No active session. Show your sign-in screen.
}

Service URL versions

The default service URLs moved to Auth v11 and Wallet Services v6. If you override sdkUrl, walletSdkUrl, or dashboardUrl in Web3AuthOptions, update them to the matching versions, or remove the overrides to use the defaults.

New APIs (non-breaking)

API	Description
Web3AuthFlutter.getAccessToken()	Returns the access token for the current auth session.
Web3AuthFlutter.getIdentityToken()	Returns the identity token (ID token) for the current auth session.
Web3AuthFlutter.refreshSession()	Refreshes the session and returns the updated Web3AuthResponse.
Web3AuthFlutter.getUserInfoAsync()	Fetches user info asynchronously, and can backfill idToken from the session.
LoginParams.recordId	Optional audit record ID for the sign-in request. The native SDK generates one when unset.
LoginParams.loginSource	Audit login source. Defaults to web3auth-flutter.
Web3AuthOptions.citadelServerUrl	Custom auth session service URL.
Web3AuthOptions.wsEmbedDappClientId	Optional dapp client ID for the Wallet Services embed.
Web3AuthOptions.useAAWithExternalWallet	Use account abstraction with external wallets. Comes from project configuration when unset.
WhiteLabelData.tncLink, privacyPolicy	Terms and privacy policy URLs (plain String) shown in the consent UI.
WalletServicesConfig.enableKeyExport	Controls private key export in the wallet UI.

final String accessToken = await Web3AuthFlutter.getAccessToken();
final String idToken = await Web3AuthFlutter.getIdentityToken();
final Web3AuthResponse refreshed = await Web3AuthFlutter.refreshSession();

See the Flutter SDK usage reference for details.

v7 breaking changes

Apply this section if you are upgrading from v6 or earlier. v7 aligned with Android SDK v10 and iOS SDK v12.

API renames

v6	v7
Network	Web3AuthNetwork
network:	web3AuthNetwork:
Provider / TypeOfLogin	AuthConnection
Provider.jwt	AuthConnection.custom
Web3AuthFlutter.login()	Web3AuthFlutter.connectTo()
loginProvider:	authConnection:
redirectUrl: Uri	redirectUrl: String
loginConfig	authConnectionConfig
LoginConfigItem	AuthConnectionConfig
verifier	authConnectionId
verifierSubIdentifier	groupedAuthConnectionId
verifierIdField	userIdField
getPrivKey()	getPrivateKey()
getEd25519PrivKey()	getEd25519PrivateKey()
TorusUserInfo	UserInfo
response.privKey	response.privateKey
launchWalletServices(ChainConfig)	showWalletUI()
request(ChainConfig, method, params)	request(method, params)
SDK ChainConfig	Web3AuthOptions(chains: [Chains(...)])
useCoreKitKey	useSFAKey
buildEnv	authBuildEnv

Sign in with connectTo

final Web3AuthResponse response = await Web3AuthFlutter.connectTo(
  LoginParams(authConnection: AuthConnection.google),
);

Custom JWT and Firebase

Pass the JWT on LoginParams.idToken with authConnectionId:

final Web3AuthResponse response = await Web3AuthFlutter.connectTo(
  LoginParams(
    authConnection: AuthConnection.custom,
    authConnectionId: "w3a-firebase-demo",
    idToken: firebaseIdToken,
  ),
);

Configure the connection during initialization:

authConnectionConfig: [
  AuthConnectionConfig(
    authConnection: AuthConnection.custom,
    authConnectionId: "w3a-firebase-demo",
    clientId: "WEB3AUTH_CLIENT_ID",
  ),
],

Wallet Services and signing

Configure chains in Web3AuthOptions, then call Wallet Services without a chain argument:

await Web3AuthFlutter.init(
  Web3AuthOptions(
    clientId: "WEB3AUTH_CLIENT_ID",
    web3AuthNetwork: Web3AuthNetwork.sapphire_mainnet,
    redirectUrl: redirectUrl,
    chains: [
      Chains(
        chainId: "0x1",
        rpcTarget: "https://mainnet.infura.io/v3/<YOUR_KEY>",
        displayName: "Ethereum Mainnet",
        ticker: "ETH",
      ),
    ],
    defaultChainId: "0x1",
  ),
);

await Web3AuthFlutter.showWalletUI();

Read signing results from request() directly:

try {
  List<dynamic> params = [];
  params.add("Hello, Web3Auth from Flutter!");
  params.add("<User Address in Hex>");

  final response = await Web3AuthFlutter.request(
    "personal_sign",
    params,
  );

  log(response.toString());
} on UserCancelledException {
  log("User cancelled.");
} catch (e) {
  log("Unknown exception occurred");
}

Earlier breaking changes

Apply the sections below if you are upgrading from versions older than v6.

setResultUrl removed (from v4)

v4 removes setResultUrl. On Android, use Web3AuthFlutter.setCustomTabsClosed() in your app lifecycle observer to detect when the user closes the custom tab:

@override
void didChangeAppLifecycleState(final AppLifecycleState state) {
  if (state == AppLifecycleState.resumed) {
    Web3AuthFlutter.setCustomTabsClosed();
  }
}

Register the observer in initState with WidgetsBinding.instance.addObserver(this).

v6 changes (if upgrading from v4-v5)

• getSignResponse() removed: use the return value of request().
• Minimum Android SDK 26: update minSdkVersion in your app-level Gradle file.

Summary table

Area	v3 and earlier	v4-v5	v6	v7	v8
setResultUrl	Used on Android	Removed	Removed	Removed	Removed
Sign result	N/A	getSignResponse()	Return value of request()	Return value of request()	Return value of request()
Sign in	login()	login()	login()	connectTo()	connectTo()
Private key	getPrivKey()	getPrivKey()	getPrivKey()	getPrivateKey()	getPrivateKey()
Wallet UI	N/A	launchWalletServices()	launchWalletServices()	showWalletUI()	showWalletUI()
Chain config	N/A	Per-method ChainConfig	Per-method ChainConfig	Web3AuthOptions.chains	Web3AuthOptions.chains
Session tokens	N/A	N/A	N/A	N/A	getAccessToken(), getIdentityToken()
Android minSdk	24	24	26	26	26

Next steps

• Flutter SDK get started
• Build with AI for ongoing integration help
• Release notes