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 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. 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 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 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://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 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:

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

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

android {
    compileSdk 34

    defaultConfig {
        minSdk 26
        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 v10, focus on the v11 changes. If you're on v9, apply the 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:

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:

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​

APIPurpose
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 and Refresh the 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:

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 and v11 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
manageMFA()v9.1Open the MFA management flow for signed-in users
getAccessToken()v11Read the Auth access token
getIdentityToken()v11Read the identity token (JWT)
getUserInfoAsync()v11Read UserInfo with idToken filled from the session
refreshSession()v11Re-authorize the current session

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

Summary table​

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

Next steps​

On this page