> 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[​](#ai-assisted-migration "Direct link to 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):

```
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-dependabot-npmandya-b3f3a6-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[​](#install-v10 "Direct link to Install v10")

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

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

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

```

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

```
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[​](#breaking-changes "Direct link to 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)[​](#network-and-sdk-requirements-from-v5 "Direct link to Network and SDK requirements (from v5)")

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

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

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

```

### Whitelabel configuration (from v5)[​](#whitelabel-configuration-from-v5 "Direct link to 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)[​](#mandatory-redirect-url-from-v74 "Direct link to Mandatory redirect URL (from v7.4)")

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

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

```

### AndroidManifest changes (from v7.1.2)[​](#androidmanifest-changes-from-v712 "Direct link to AndroidManifest changes (from v7.1.2)")

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

```
<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)[​](#launchwalletservices-signature-from-v72 "Direct link to launchwalletservices-signature-from-v72")

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

```
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)[​](#request-signature-from-v73 "Direct link to request-signature-from-v73")

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

```
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[​](#v9-changes "Direct link to v9 changes")

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

```
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-changes "Direct link to v10 changes")

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

#### Import changes[​](#import-changes "Direct link to Import changes")

- Before (v9.x)
- After (v10.x)

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

```

```
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[​](#enum-renames "Direct link to Enum renames")

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

#### `Web3AuthOptions` configuration[​](#web3authoptions-configuration "Direct link to web3authoptions-configuration")

- Before (v9.x)
- After (v10.x)

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

```

```
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[​](#authentication-method "Direct link to Authentication method")

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

- Before (v9.x)
- After (v10.x)

```
// 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")
    )
)

```

```
// 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[​](#private-key-methods "Direct link to Private key methods")

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

#### Wallet Services[​](#wallet-services "Direct link to Wallet Services")

- Before (v9.x)
- After (v10.x)

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

```

```
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)[​](#new-apis-non-breaking "Direct link to 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[​](#summary-table "Direct link to 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[​](#next-steps "Direct link to 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)