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

# Android SDK v10 Migration Guide

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

## 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 Android (web3auth-android-sdk) project to v10.

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/android
3. Detect my current SDK version from build.gradle and list which breaking changes apply.

Then migrate my codebase directly to v10:
- Update the JitPack dependency to com.github.web3auth:web3auth-android-sdk:10.0.1 (or latest v10).
- Set compileSdk and targetSdk to 34.
- 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).
- Update WhiteLabelData fields (appName, mode, buildEnv) if whitelabeling is configured.
- Configure chains in the Embedded Wallets dashboard; v10 reads 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 v10

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:10.0.1'
}

```

Set `compileSdk` and `targetSdk` to **34**:

```groovy
android {
    compileSdk 34

    defaultConfig {
        minSdk 24
        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 v9, focus on the [v10 changes](#v10-changes).

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

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                              |
| -------------------------- | ------------------- | ------------------------ | -------------------------------- |
| Network                    | Mainnet, Cyan, etc. | Sapphire supported       | `Web3AuthNetwork` (Sapphire)     |
| `compileSdk` / `targetSdk` | 33                  | 34                       | 34                               |
| `redirectUrl`              | Optional            | Mandatory (v7.4+)        | Mandatory (`String`)             |
| Whitelabel `name`          | `name`              | `appName`                | `appName`                        |
| Authentication             | N/A                 | `login()` + `Provider`   | `connectTo()` + `AuthConnection` |
| Private key                | N/A                 | `getPrivKey()`           | `getPrivateKey()`                |
| Wallet UI                  | N/A                 | `launchWalletServices()` | `showWalletUI()`                 |
| `request`                  | N/A                 | `chainConfig` + method   | method + `requestParams` only    |
| Sign result                | N/A                 | `getSignResponse()` (v8) | Return value of `request()`      |
| Chain config               | N/A                 | Passed in code           | 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)