> For the complete documentation index, see [llms.txt](/llms.txt).

# 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](/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 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://metamask-docs-git-claude-flutter-sdk-ec6fa1-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 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`:

```yaml
dependencies:
  web3auth_flutter: ^8.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
    }
}

```

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](#ios-requires-swift-package-manager).

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.

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](https://github.com/Web3Auth/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:

```sh
flutter config --enable-swift-package-manager

```

Building the Swift package requires Xcode 15 or later. See the [Flutter Swift Package Manager guide](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers).

### `MFALevel.DEFAULT` removed

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

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

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

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

```

See the [Flutter SDK usage reference](/embedded-wallets/sdk/flutter/usage/) 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`

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

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