Flutter SDK v7 Migration Guide

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

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 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://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 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

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 for Android and iOS setup.

v7 aligns with Android SDK v10 and iOS SDK v12.

v7 breaking changes

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

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