For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

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 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://docs.metamask.io/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:

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.

Breaking changes​

Apply the sections below that match your current version. If you're already on v9, focus on the v10 changes.

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

WhiteLabelData field names changed:

v4 and earlierv5 and later
nameappName
darkmode (ThemeModes.LIGHT, ThemeModes.DARK, or auto)

New optional fields include appUrl and useLogoLoader. Prefer 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:

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:

<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 for the full manifest setup.

launchWalletServices signature (from v7.2)​

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.

request signature (from v7.3)​

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.

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 unifies Plug and Play (PnP) and Single Factor Auth (SFA) in one SDK and renames several APIs.

Import changes​

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

Enum renames​

v9.xv10.x
ProviderAuthConnection
TypeOfLoginAuthConnection
NetworkWeb3AuthNetwork
LoginConfigItemAuthConnectionConfig
Provider.JWTAuthConnection.CUSTOM

Web3AuthOptions configuration​

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

Authentication method​

Replace login() with connectTo():

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

Private key methods​

v9.xv10.x
getPrivKey()getPrivateKey()
getEd25519PrivKey()getEd25519PrivateKey()

Wallet Services​

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
)

Configure chains in the Embedded Wallets dashboard. 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.

APIAdded inPurpose
enableMFA()v6Initiate MFA setup for signed-in users
launchWalletServices()v6Open the prebuilt Wallet Services UI (v10: showWalletUI())
request()v6.1Sign transactions with confirmation screens
SMS Passwordless sign-inv7.2AuthConnection.SMS_PASSWORDLESS with loginHint
Farcaster sign-inv7.2AuthConnection.FARCASTER
SFA with JWTv10connectTo() with AuthConnection.CUSTOM and idToken

See Wallet Services, Request, and MFA for usage details.

Summary table​

AreaBefore v5v5-v9v10
NetworkMainnet, Cyan, etc.Sapphire supportedWeb3AuthNetwork (Sapphire)
compileSdk / targetSdk333434
redirectUrlOptionalMandatory (v7.4+)Mandatory (String)
Whitelabel namenameappNameappName
AuthenticationN/Alogin() + ProviderconnectTo() + AuthConnection
Private keyN/AgetPrivKey()getPrivateKey()
Wallet UIN/AlaunchWalletServices()showWalletUI()
requestN/AchainConfig + methodmethod + requestParams only
Sign resultN/AgetSignResponse() (v8)Return value of request()
Chain configN/APassed in codeDashboard-managed

Next steps​

On this page