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

# Android SDK v11 Migration Guide

This guide upgrades Embedded Wallets Android SDK integrations from **v4 through v10** directly to **v11**.

If you're already on v10, focus on the [v11 changes](#v11-changes). For older versions, apply the sections below that match your current version, then complete the v11 updates.

## 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](/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 Embedded Wallet SDK for Android (web3auth-android-sdk) project to v11.

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-ew-combined-sdk-doc-52f4ee-consensys-ddffed67.vercel.app/embedded-wallets/migration-guides/android
3. Detect my current SDK version from build.gradle and list which breaking changes apply.

Then migrate my codebase directly to v11:
- Update the JitPack dependency to com.github.web3auth:web3auth-android-sdk:11.0.1 (or latest v11).
- Set compileSdk and targetSdk to 34, and minSdk to at least 26.
- Add mandatory redirectUrl to Web3AuthOptions ({YOUR_APP_PACKAGE_NAME}://auth).
- Update AndroidManifest.xml (allowBackup=false, tools:replace, deep link intent filter, singleTop).
- Replace login() with connectTo() and Provider with AuthConnection.
- Replace Network with Web3AuthNetwork, loginConfig with authConnectionConfig, and buildEnv with authBuildEnv.
- Replace getPrivKey() with getPrivateKey() and getEd25519PrivKey() with getEd25519PrivateKey().
- Replace launchWalletServices() with showWalletUI() and remove ChainConfig parameters.
- Update request() to pass only method and requestParams; remove ChainConfig.
- Replace getSignResponse() with the SignResponse returned from request() (if still on v9 patterns).
- Remove MFALevel.DEFAULT; use MFALevel.OPTIONAL, MANDATORY, or NONE.
- Remove any hard-coded /v10 auth, wallet, or dashboard URLs; let the SDK derive them from authBuildEnv.
- Call initialize() after constructing Web3Auth and passing setResultUrl(), and treat an initialize() error as "no session".
- Use getAccessToken(), getIdentityToken(), getUserInfoAsync(), and refreshSession() where the app needs session tokens.
- Update WhiteLabelData fields (appName, mode) if whitelabeling is configured.
- Configure chains in the Embedded Wallets dashboard; v10 and later read chain config from the dashboard.
- Do not change my Client ID or Sapphire network 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 v11

Add JitPack to your project-level `build.gradle` if it is not already present:

```groovy
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url "https://jitpack.io" }
    }
}

```

Update the dependency in your app-level `build.gradle`:

```groovy
dependencies {
    implementation 'com.github.web3auth:web3auth-android-sdk:11.0.1'
}

```

Set `compileSdk` and `targetSdk` to **34**, and `minSdk` to at least **26**:

```groovy
android {
    compileSdk 34

    defaultConfig {
        minSdk 26
        targetSdk 34
    }
}

```

Allowlist `{SCHEME}://{YOUR_APP_PACKAGE_NAME}` on the [Embedded Wallets dashboard](https://developer.metamask.io).

## Breaking changes

Apply the sections below that match your current version. If you're already on v10, focus on the [v11 changes](#v11-changes). If you're on v9, apply the [v10 changes](#v10-changes) and then the v11 changes.

### v11 changes

v11 moves the SDK to Auth Service v11 and Wallet Services v6. The Auth session is now stored as tokens on the device (session ID, access token, refresh token, and identity token) instead of only in the session service. Most v10 code compiles unchanged; review the items below.

#### `MFALevel.DEFAULT` removed

Replace `MFALevel.DEFAULT` with `MFALevel.OPTIONAL`, `MFALevel.MANDATORY`, or `MFALevel.NONE`, or omit `mfaLevel`:

```kotlin
val loginCompletableFuture = web3Auth.connectTo(
    LoginParams(
        AuthConnection.GOOGLE,
        mfaLevel = MFALevel.MANDATORY // MFALevel.DEFAULT no longer exists
    )
)

```

#### Service URLs

The SDK now uses `/v11` Auth and dashboard URLs and `/v6` Wallet Services URLs for `BuildEnv.PRODUCTION` and `BuildEnv.STAGING`. If you override `sdkUrl`, `walletSdkUrl`, or `dashboardUrl` with `/v10` or `/v5` URLs, remove the overrides and let the SDK derive them from `authBuildEnv`.

#### Initialize and restore the session

Call `initialize()` after constructing `Web3Auth` and passing the launch intent to `setResultUrl()`. `initialize()` restores the session from the stored Auth tokens, falling back to the session service for SFA sessions. If there is no session to restore, `initialize()` completes exceptionally, so show your sign-in screen in the error branch:

```kotlin
web3Auth.setResultUrl(intent?.data)

web3Auth.initialize().whenComplete { _, error ->
    if (error == null) {
        // Session restored
    } else {
        // No session; show the sign-in screen
    }
}

```

#### `sessionTime` uses the dashboard value

The default session time is still 30 days. `Web3AuthOptions.sessionTime` is now nullable: if you leave it unset, `initialize()` uses the session time configured in your dashboard project, which also defaults to 30 days. Set `sessionTime` explicitly only if you need to override the dashboard value.

#### `WalletServicesConfig` defaults

`WalletServicesConfig.confirmationStrategy` now defaults to `null` instead of `ConfirmationStrategy.DEFAULT`, and a new `enableKeyExport` option is available. During `initialize()`, the SDK fills unset values from your dashboard's Wallet UI settings.

#### New APIs

| API                  | Purpose                                                                        |
| -------------------- | ------------------------------------------------------------------------------ |
| `getAccessToken()`   | Returns the Auth access token for the current session.                         |
| `getIdentityToken()` | Returns the identity token (JWT) for the current session.                      |
| `getUserInfoAsync()` | Returns `UserInfo`, filling in `idToken` from the stored session when missing. |
| `refreshSession()`   | Re-authorizes the current session. Clears the stored tokens if it fails.       |

`getAccessToken()` and `getIdentityToken()` aren't available for SFA sessions. See [Get session tokens](/embedded-wallets/sdk/android/usage/session-tokens/) and [Refresh the session](/embedded-wallets/sdk/android/usage/refresh-session/).

#### Other additions

- `WhiteLabelData` adds optional `tncLink` and `privacyPolicy` URLs.
- `LoginParams` adds optional `recordId` and `loginSource` fields for sign-in auditing. The SDK sets them automatically if you don't.
- `WalletUiConfig` adds `enableDefiPositionsDisplay`, and `DefaultPortfolioType` adds `DEFI`.

#### Re-test your integration

After upgrading, re-test sign-in, session restore on app restart, MFA, `showWalletUI()`, `request()`, and `logout()`.

### Network and SDK requirements (from v5)

Use Sapphire networks instead of legacy OpenLogin networks. In v10, `Network` becomes `Web3AuthNetwork`:

```kotlin
import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork

val web3Auth = Web3Auth(
    Web3AuthOptions(
        clientId = getString(R.string.web3auth_project_id),
        web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET
        redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
    ),
    this
)

```

Add `authBuildEnv` when you need a non-production auth environment:

```kotlin
authBuildEnv = BuildEnv.PRODUCTION // PRODUCTION, STAGING, or TESTING

```

### Whitelabel configuration (from v5)

`WhiteLabelData` field names changed:

| v4 and earlier | v5 and later                                            |
| -------------- | ------------------------------------------------------- |
| `name`         | `appName`                                               |
| `dark`         | `mode` (`ThemeModes.LIGHT`, `ThemeModes.DARK`, or auto) |

New optional fields include `appUrl` and `useLogoLoader`. Prefer [dashboard customization](/embedded-wallets/dashboard/customization/) for new projects.

### Mandatory redirect URL (from v7.4)

`redirectUrl` is required in `Web3AuthOptions`. In v10, pass it as a `String` instead of a `Uri`:

```kotlin
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth"

```

### AndroidManifest changes (from v7.1.2)

From v7.1.2, set `android:allowBackup` to `false` and add `tools:replace`:

```xml
<application
        android:allowBackup="false"
        tools:replace="android:fullBackupContent"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher">
</application>

```

Set your main activity `launchMode` to `singleTop` and add the deep link intent filter. See the [Android SDK get started](/embedded-wallets/sdk/android/) for the full manifest setup.

### `launchWalletServices` signature (from v7.2)

From v7.2 through v9, remove `loginParams` and pass only `chainConfig`:

```kotlin
val launchWalletCompletableFuture = web3Auth.launchWalletServices(
    chainConfig = ChainConfig(
        chainId = "0x1",
        rpcTarget = "https://rpc.ethereum.org",
        ticker = "ETH",
        chainNamespace = ChainNamespace.EIP155,
    )
)

```

In v10, replace `launchWalletServices()` with `showWalletUI()` and remove `ChainConfig`. See [v10 changes](#v10-changes).

### `request` signature (from v7.3)

From v7.3 through v9, remove `loginParams` and pass `chainConfig`, method name, and request parameters:

```kotlin
val params = JsonArray().apply {
    add("Hello, World!")
    add(address)
}

val signMsgCompletableFuture = web3Auth.request(
    chainConfig = ChainConfig(
        chainId = "0x1",
        rpcTarget = "https://rpc.ethereum.org",
        ticker = "ETH",
        chainNamespace = ChainNamespace.EIP155,
    ),
    "personal_sign",
    requestParams = params,
)

```

In v10, remove `chainConfig` from `request()`. See [v10 changes](#v10-changes).

### v9 changes

`getSignResponse()` is removed. The `request()` method returns `SignResponse` directly:

```kotlin
signMsgCompletableFuture.whenComplete { signResult, error ->
    if (error == null) {
        Log.d("Sign Result", signResult.toString())
    } else {
        Log.d("MainActivity_Web3Auth", error.message ?: "Something went wrong")
    }
}

```

v9 also adds support for Web3Auth Auth Service v9 and Wallet Services v3 (including swap in the prebuilt wallet UI).

### v10 changes

v10 unifies Plug and Play (PnP) and Single Factor Auth (SFA) in one SDK and renames several APIs.

#### Import changes

**Before (v9.x)**

```kotlin
import com.web3auth.core.Web3Auth
import com.web3auth.core.types.Web3AuthOptions
import com.web3auth.core.types.Network
import com.web3auth.core.types.Provider
import com.web3auth.core.types.LoginConfigItem
import com.web3auth.core.types.TypeOfLogin

```

**After (v10.x)**

```kotlin
import com.web3auth.core.Web3Auth
import com.web3auth.core.types.Web3AuthOptions
import com.web3auth.core.types.AuthConnection
import com.web3auth.core.types.AuthConnectionConfig
import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork

```

#### Enum renames

| v9.x              | v10.x                   |
| ----------------- | ----------------------- |
| `Provider`        | `AuthConnection`        |
| `TypeOfLogin`     | `AuthConnection`        |
| `Network`         | `Web3AuthNetwork`       |
| `LoginConfigItem` | `AuthConnectionConfig`  |
| `Provider.JWT`    | `AuthConnection.CUSTOM` |

#### `Web3AuthOptions` configuration

**Before (v9.x)**

```kotlin
val web3Auth = Web3Auth(
    Web3AuthOptions(
        context = this,
        clientId = "YOUR_CLIENT_ID",
        network = Network.SAPPHIRE_MAINNET,
        redirectUrl = Uri.parse("your-app://auth"),
        loginConfig = hashMapOf("google" to LoginConfigItem(
            verifier = "verifier-name",
            typeOfLogin = TypeOfLogin.GOOGLE,
            clientId = "google-client-id"
        )),
        buildEnv = BuildEnv.PRODUCTION
    )
)

```

**After (v10.x)**

```kotlin
val web3Auth = Web3Auth(
    Web3AuthOptions(
        clientId = "YOUR_CLIENT_ID",
        web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
        redirectUrl = "your-app://auth",
        authConnectionConfig = listOf(AuthConnectionConfig(
            authConnectionId = "verifier-name",
            authConnection = AuthConnection.GOOGLE,
            clientId = "google-client-id"
        )),
        authBuildEnv = BuildEnv.PRODUCTION
    ),
    this
)

```

#### Authentication method

Replace `login()` with `connectTo()`:

**Before (v9.x)**

```kotlin
// Simple social sign-in
val loginCompletableFuture = web3Auth.login(
    LoginParams(Provider.GOOGLE)
)

// Email passwordless
val loginCompletableFuture = web3Auth.login(
    LoginParams(
        Provider.EMAIL_PASSWORDLESS,
        extraLoginOptions = ExtraLoginOptions(login_hint = "user@example.com")
    )
)

// JWT sign-in
val loginCompletableFuture = web3Auth.login(
    LoginParams(
        Provider.JWT,
        extraLoginOptions = ExtraLoginOptions(id_token = "your_jwt_token")
    )
)

```

**After (v10.x)**

```kotlin
// Simple social sign-in (PnP mode)
val loginCompletableFuture = web3Auth.connectTo(
    LoginParams(AuthConnection.GOOGLE)
)

// Email passwordless (PnP mode)
val loginCompletableFuture = web3Auth.connectTo(
    LoginParams(
        AuthConnection.EMAIL_PASSWORDLESS,
        loginHint = "user@example.com"
    )
)

// JWT sign-in (SFA mode)
val loginCompletableFuture = web3Auth.connectTo(
    LoginParams(
        AuthConnection.CUSTOM,
        authConnectionId = "your_auth_connection_id",
        idToken = "your_jwt_token"
    )
)

```

#### Private key methods

| v9.x                  | v10.x                    |
| --------------------- | ------------------------ |
| `getPrivKey()`        | `getPrivateKey()`        |
| `getEd25519PrivKey()` | `getEd25519PrivateKey()` |

#### Wallet Services

**Before (v9.x)**

```kotlin
val chainConfig = ChainConfig(
    chainId = "0x1",
    rpcTarget = "https://rpc.ethereum.org",
    ticker = "ETH",
    chainNamespace = ChainNamespace.EIP155
)

val launchWalletCF = web3Auth.launchWalletServices(chainConfig)

val signCF = web3Auth.request(
    chainConfig = chainConfig,
    method = "personal_sign",
    requestParams = params
)

```

**After (v10.x)**

```kotlin
val launchWalletCF = web3Auth.showWalletUI()

val signCF = web3Auth.request(
    method = "personal_sign",
    requestParams = params
)

```

Configure chains in the [Embedded Wallets dashboard](/embedded-wallets/dashboard/chains-and-networks/). v10 reads chain configuration from your project settings instead of `ChainConfig` in code.

## New APIs (non-breaking)

These APIs were added in intermediate versions. If you're upgrading from an older SDK, adopt the v10 and v11 signatures shown above.

| API                      | Added in | Purpose                                                      |
| ------------------------ | -------- | ------------------------------------------------------------ |
| `enableMFA()`            | v6       | Initiate MFA setup for signed-in users                       |
| `launchWalletServices()` | v6       | Open the prebuilt Wallet Services UI (v10: `showWalletUI()`) |
| `request()`              | v6.1     | Sign transactions with confirmation screens                  |
| SMS Passwordless sign-in | v7.2     | `AuthConnection.SMS_PASSWORDLESS` with `loginHint`           |
| Farcaster sign-in        | v7.2     | `AuthConnection.FARCASTER`                                   |
| SFA with JWT             | v10      | `connectTo()` with `AuthConnection.CUSTOM` and `idToken`     |
| `manageMFA()`            | v9.1     | Open the MFA management flow for signed-in users             |
| `getAccessToken()`       | v11      | Read the Auth access token                                   |
| `getIdentityToken()`     | v11      | Read the identity token (JWT)                                |
| `getUserInfoAsync()`     | v11      | Read `UserInfo` with `idToken` filled from the session       |
| `refreshSession()`       | v11      | Re-authorize the current session                             |

See [Wallet Services](/embedded-wallets/sdk/android/usage/launch-wallet-services/), [Request](/embedded-wallets/sdk/android/usage/request/), and [MFA](/embedded-wallets/sdk/android/advanced/mfa/) for usage details.

## Summary table

| Area                       | Before v5           | v5-v9                    | v10                              | v11                                   |
| -------------------------- | ------------------- | ------------------------ | -------------------------------- | ------------------------------------- |
| Network                    | Mainnet, Cyan, etc. | Sapphire supported       | `Web3AuthNetwork` (Sapphire)     | `Web3AuthNetwork` (Sapphire)          |
| `compileSdk` / `targetSdk` | 33                  | 34                       | 34                               | 34                                    |
| `redirectUrl`              | Optional            | Mandatory (v7.4+)        | Mandatory (`String`)             | Mandatory (`String`)                  |
| Whitelabel `name`          | `name`              | `appName`                | `appName`                        | `appName`                             |
| Authentication             | N/A                 | `login()` + `Provider`   | `connectTo()` + `AuthConnection` | `connectTo()` + `AuthConnection`      |
| Private key                | N/A                 | `getPrivKey()`           | `getPrivateKey()`                | `getPrivateKey()`                     |
| Wallet UI                  | N/A                 | `launchWalletServices()` | `showWalletUI()`                 | `showWalletUI()` (Wallet Services v6) |
| `request`                  | N/A                 | `chainConfig` + method   | method + `requestParams` only    | method + `requestParams` only         |
| Sign result                | N/A                 | `getSignResponse()` (v8) | Return value of `request()`      | Return value of `request()`           |
| Chain config               | N/A                 | Passed in code           | Dashboard-managed                | Dashboard-managed                     |

## Next steps

- [Android SDK get started](/embedded-wallets/sdk/android/)
- [Build with AI](/embedded-wallets/build-with-ai/) for ongoing integration help
- [Release notes](https://github.com/Web3Auth/web3auth-android-sdk/releases)