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

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 Web3Auth by MetaMask, Embedded Wallet SDK 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 Embedded Wallet SDK for 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 deployment target to 14.0 or later and make sure Swift Package Manager is enabled
  (on by default in recent Flutter; otherwise run 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 a duration other than the 30-day default or my dashboard setting.
- 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 deployment target to 14.0 or later (the Runner target in Xcode, and platform :ios in ios/Podfile if your project has one). Make sure Swift Package Manager is enabled; see iOS requires 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 (SPM). The plugin's podspec no longer declares a CocoaPods Web3Auth dependency, so your iOS build must use SPM.

SPM is enabled by default in recent Flutter stable releases, such as Flutter 3.44. If you use an older Flutter version, or you turned SPM off, enable it:

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. The default session is still 30 days. When you don't set sessionTime, the native SDK uses the session time from your dashboard project if you configured one, and 30 days otherwise. Remove sessionTime from your options unless you need a different duration.

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)​

APIDescription
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.recordIdOptional audit record ID for the sign-in request. The native SDK generates one when unset.
LoginParams.loginSourceAudit login source. Defaults to web3auth-flutter.
Web3AuthOptions.citadelServerUrlCustom auth session service URL.
Web3AuthOptions.wsEmbedDappClientIdOptional dapp client ID for the Wallet Services embed.
Web3AuthOptions.useAAWithExternalWalletUse account abstraction with external wallets. Comes from project configuration when unset.
WhiteLabelData.tncLink, privacyPolicyTerms and privacy policy URLs (plain String) shown in the consent UI.
WalletServicesConfig.enableKeyExportControls 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​

v6v7
NetworkWeb3AuthNetwork
network:web3AuthNetwork:
Provider / TypeOfLoginAuthConnection
Provider.jwtAuthConnection.custom
Web3AuthFlutter.login()Web3AuthFlutter.connectTo()
loginProvider:authConnection:
redirectUrl: UriredirectUrl: String
loginConfigauthConnectionConfig
LoginConfigItemAuthConnectionConfig
verifierauthConnectionId
verifierSubIdentifiergroupedAuthConnectionId
verifierIdFielduserIdField
getPrivKey()getPrivateKey()
getEd25519PrivKey()getEd25519PrivateKey()
TorusUserInfoUserInfo
response.privKeyresponse.privateKey
launchWalletServices(ChainConfig)showWalletUI()
request(ChainConfig, method, params)request(method, params)
SDK ChainConfigWeb3AuthOptions(chains: [Chains(...)])
useCoreKitKeyuseSFAKey
buildEnvauthBuildEnv

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 PlatformException catch (e) {
  log(e.message ?? e.toString());
}

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​

Areav3 and earlierv4-v5v6v7v8
setResultUrlUsed on AndroidRemovedRemovedRemovedRemoved
Sign resultN/AgetSignResponse()Return value of request()Return value of request()Return value of request()
Sign inlogin()login()login()connectTo()connectTo()
Private keygetPrivKey()getPrivKey()getPrivKey()getPrivateKey()getPrivateKey()
Wallet UIN/AlaunchWalletServices()launchWalletServices()showWalletUI()showWalletUI()
Chain configN/APer-method ChainConfigPer-method ChainConfigWeb3AuthOptions.chainsWeb3AuthOptions.chains
Session tokensN/AN/AN/AN/AgetAccessToken(), getIdentityToken()
Android minSdk2424262626

Next steps​

On this page