> 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

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

```txt
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-docs-agent-wallet-s-66054a-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

Update `pubspec.yaml`:

```yaml
dependencies:
  web3auth_flutter: ^7.0.0

```

Or run:

```sh
flutter pub add web3auth_flutter

```

Set Android `minSdkVersion` to **26** and `compileSdkVersion` to **34**:

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

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

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

```

### Custom JWT and Firebase

Pass the JWT on `LoginParams.idToken` with `authConnectionId`:

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

```

Configure the connection during initialization:

```dart
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:

```dart
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:

```dart
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:

```dart
@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](/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)