> For the complete documentation index, see [llms.txt](/llms.txt). # Flutter SDK v7 Migration Guide This guide upgrades Embedded Wallets Flutter SDK integrations from **v3 through v6** directly to **v7**. ## AI-assisted migration[​](#ai-assisted-migration "Direct link to AI-assisted migration") For the best results, install the MetaMask Embedded Wallets **skill** and **MCP server** before you migrate. See [Build with AI](/embedded-wallets/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 v7. 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://metamask-docs-git-flutter-v7-consensys-ddffed67.vercel.app/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 v7: - Update web3auth_flutter to ^7.0.0 in pubspec.yaml. - Set Android minSdkVersion to 26 and compileSdkVersion to 34. - 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 v7[​](#install-v7 "Direct link to Install v7") Update `pubspec.yaml`: ``` dependencies: web3auth_flutter: ^7.0.0 ``` Or run: ``` flutter pub add web3auth_flutter ``` Set Android `minSdkVersion` to **26** and `compileSdkVersion` to **34**: ``` android { compileSdkVersion 34 defaultConfig { minSdkVersion 26 } } ``` Add JitPack to your project-level Gradle file and configure platform redirects. See the [Flutter SDK get started](/embedded-wallets/sdk/flutter/) for Android and iOS setup. v7 aligns with Android SDK v10 and iOS SDK v12. ## v7 breaking changes[​](#v7-changes "Direct link to v7 breaking changes") ### API renames[​](#api-renames "Direct link to 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`[​](#sign-in-with-connectto "Direct link to sign-in-with-connectto") ``` final Web3AuthResponse response = await Web3AuthFlutter.connectTo( LoginParams(authConnection: AuthConnection.google), ); ``` ### Custom JWT and Firebase[​](#custom-jwt-and-firebase "Direct link to 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[​](#wallet-services-and-signing "Direct link to 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/", displayName: "Ethereum Mainnet", ticker: "ETH", ), ], defaultChainId: "0x1", ), ); await Web3AuthFlutter.showWalletUI(); ``` Read signing results from `request()` directly: ``` try { List params = []; params.add("Hello, Web3Auth from Flutter!"); params.add(""); 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[​](#earlier-breaking-changes "Direct link to Earlier breaking changes") Apply the sections below if you are upgrading from versions older than v6. ### `setResultUrl` removed (from v4)[​](#setresulturl-removed-from-v4 "Direct link to 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)[​](#v6-changes-if-upgrading-from-v4-v5 "Direct link to 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[​](#summary-table "Direct link to Summary table") | Area | v3 and earlier | v4-v5 | v6 | v7 | | -------------- | --------------- | ---------------------- | ------------------------- | ------------------------- | | setResultUrl | Used on Android | Removed | Removed | Removed | | Sign result | N/A | getSignResponse() | Return value of request() | Return value of request() | | Sign in | login() | login() | login() | connectTo() | | Private key | getPrivKey() | getPrivKey() | getPrivKey() | getPrivateKey() | | Wallet UI | N/A | launchWalletServices() | launchWalletServices() | showWalletUI() | | Chain config | N/A | Per-method ChainConfig | Per-method ChainConfig | Web3AuthOptions.chains | | Android minSdk | 24 | 24 | 26 | 26 | ## Next steps[​](#next-steps "Direct link to Next steps") - [Flutter SDK get started](/embedded-wallets/sdk/flutter/) - [Build with AI](/embedded-wallets/build-with-ai/) for ongoing integration help - [Release notes](https://github.com/Web3Auth/web3auth-flutter-sdk/releases)