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 (latest release: 11.0.2).

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.2.
- Declare the JitPack repository in settings.gradle (dependencyResolutionManagement).
- Remove direct dependencies on org.torusresearch:torus-utils-java or org.torusresearch:fetch-node-details-java; v11 brings in com.github.MetaMask artifacts instead.
- Set compileSdk and targetSdk to 34, and minSdk to at least 26.
- Add mandatory redirectUrl to Web3AuthOptions ({YOUR_APP_PACKAGE_NAME}://auth) and allowlist that exact URL in the dashboard.
- Update AndroidManifest.xml (allowBackup=false, tools:replace, deep link intent filter, singleTop).
- Pass Context to the Web3Auth constructor (Web3Auth(options, context)), not to Web3AuthOptions.
- Replace login() with connectTo() and Provider with AuthConnection.
- Replace Network with Web3AuthNetwork, loginConfig with authConnectionConfig, buildEnv with authBuildEnv, and useCoreKitKey with useSFAKey.
- Update UserInfo fields (verifier -> authConnectionId, verifierId -> userId, aggregateVerifier -> groupedAuthConnectionId, typeOfLogin -> authConnection) and Web3AuthResponse.privKey -> privateKey.
- 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 v8 or earlier patterns).
- Remove MFALevel.DEFAULT; use MFALevel.OPTIONAL, MANDATORY, or NONE.
- Remove any hard-coded /v10 auth or dashboard URLs and /v5 wallet URLs; let the SDK derive them from authBuildEnv.
- Call setResultUrl(intent?.data) in onCreate and in onNewIntent, then call initialize(). Wrap initialize() in try/catch; an error can mean no session, a network failure, or a project config failure.
- For custom JWT (idToken) sign-in: connectTo() opens the Auth flow by default. Use mfaLevel = MFALevel.NONE only if I need silent SFA and my users don't have MFA. Flag that I must verify wallet addresses on a test account before rolling out to existing JWT users.
- 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 settings.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.2'
}

Set compileSdk and targetSdk to 34, and minSdk to at least 26 (required since v9):

android {
    compileSdk 34

    defaultConfig {
        minSdk 26
        targetSdk 34
    }
}

Allowlist your exact redirectUrl (for example, {YOUR_APP_PACKAGE_NAME}://auth) 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. Web3AuthOptions.sessionTime is now Int? instead of Int, so code that reads it as a non-null Int no longer compiles.

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

Dependency coordinates​

v11 changes the coordinates of the libraries it pulls in through JitPack:

v10v11
org.torusresearch:torus-utils-java:4.0.3com.github.MetaMask:torus-utils-java:5.0.0
org.torusresearch:fetch-node-details-java:5.0.0com.github.MetaMask:fetch-node-details-java:6.0.0
com.github.Web3Auth:session-manager-android:3.1.3com.github.MetaMask:session-manager-android:4.0.0

If your app declares the org.torusresearch artifacts directly, remove them to avoid duplicate classes. Package names are unchanged; for example, Web3AuthNetwork is still imported from org.torusresearch.fetchnodedetails.types.

The SDK is now compiled with Kotlin 1.9.24 (v10 used 1.8.22). If you see Kotlin metadata version errors, update your project's Kotlin plugin.

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 or dashboardUrl with /v10 URLs, or walletSdkUrl with a /v5 URL, remove the overrides and let the SDK derive them from authBuildEnv.

v11 also changes which backend hosts the SDK calls. Update any network allowlists or certificate pinning:

  • citadelServerUrl is a new Web3AuthOptions field. It defaults to https://api.web3auth.io/citadel-service.
  • storageServerUrl now defaults to https://api.web3auth.io/session-service.
  • Project configuration is fetched from https://api.web3auth.io/signer-service instead of https://signer.web3auth.io.

BuildEnv.TESTING uses the api-develop.web3auth.io equivalents. Web3AuthOptions also adds optional sessionNamespace and wsEmbedDappClientId fields.

Handle redirects and restore the session​

Pass the redirect intent to setResultUrl() in both onCreate() and onNewIntent(), then call initialize() to restore the session. As in v10, initialize() completes exceptionally when there is no session to restore. It also completes exceptionally when the project configuration can't be fetched, and it can throw synchronously when the device has no network connection. Wrap the call in try/catch and don't assume every error means "no session":

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // ...construct web3Auth...

    web3Auth.setResultUrl(intent?.data)

    try {
        web3Auth.initialize().whenComplete { _, error ->
            if (error == null) {
                // Session restored
            } else {
                // No session, or a network or project config error.
                // Inspect error.message before showing the sign-in screen.
            }
        }
    } catch (e: Exception) {
        // Thrown synchronously, for example when the device is offline
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    web3Auth.setResultUrl(intent?.data)
}

initialize() restores the session from the stored Auth tokens. If none are present, it falls back to the session ID stored by the session service. If the session can't be restored, initialize() clears the stored session data.

note

v11 stores sessions differently from v10. Users might need to sign in again after you upgrade, so test session restore with a v10 session before you release.

Custom JWT sign-in (11.0.2)​

In 11.0.2, connectTo() with an idToken opens the Auth flow in a browser tab by default instead of signing in silently. The result comes back through your redirect URL, so this flow needs the same setup as social sign-in: an allowlisted redirectUrl, the deep link intent filter, and setResultUrl() in onNewIntent().

// Opens the Auth flow (default in 11.0.2)
val loginCompletableFuture = web3Auth.connectTo(
    LoginParams(
        AuthConnection.CUSTOM,
        authConnectionId = "your_auth_connection_id",
        idToken = "your_jwt_token"
    )
)

To keep silent Single Factor Auth (SFA) sign-in, set mfaLevel = MFALevel.NONE:

// Silent SFA; only for users who haven't enabled MFA
val loginCompletableFuture = web3Auth.connectTo(
    LoginParams(
        AuthConnection.CUSTOM,
        authConnectionId = "your_auth_connection_id",
        idToken = "your_jwt_token",
        mfaLevel = MFALevel.NONE
    )
)

With MFALevel.NONE, sign-in fails with USER_ALREADY_ENABLED_MFA ("User has already enabled MFA") for users who already enabled MFA. The JWT can't be reused after this failure, so get a fresh idToken and call connectTo() again without MFALevel.NONE.

caution

The Auth flow and silent SFA produce the key in different ways. getPrivateKey() returns the response's coreKitKey when useSFAKey = true, and its privateKey otherwise. Before rolling out to existing JWT users, sign in with a test account on each flow and confirm the derived wallet address matches the address on v10.

MFA​

In 11.0.2, enableMFA() and manageMFA() are available to users who signed in with an idToken, including SFA sessions (11.0.1 rejected these users with ENABLE_MFA_NOT_ALLOWED).

Both methods now call refreshSession() before opening the MFA flow. If the refresh fails, the stored Auth tokens are cleared. The call then fails with NOUSERFOUND unless the SDK can continue with the user's JWT and a local session.

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. When initialize() succeeds, the SDK fills unset values from your dashboard's Wallet UI settings. If neither your code nor the dashboard sets a confirmation strategy, the SDK uses ConfirmationStrategy.DEFAULT.

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() work for social and custom JWT sign-in in 11.0.2. They aren't available for silent SFA sessions (mfaLevel = MFALevel.NONE). See Get session tokens and Refresh the session.

Other additions​

  • WhiteLabelData adds optional tncLink and privacyPolicy URLs.
  • LoginParams adds optional recordId and loginSource fields. 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 (including custom JWT), 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 ThemeModes.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​

Context moves to the Web3Auth constructor​

Remove context from Web3AuthOptions and pass it as the second argument to Web3Auth:

val web3Auth = Web3Auth(
    Web3AuthOptions(
        context = this,
        clientId = "YOUR_CLIENT_ID",
        network = Network.SAPPHIRE_MAINNET,
        redirectUrl = Uri.parse("your-app://auth"),
    )
)

getSignResponse() removed​

Web3Auth.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")
    }
}

minSdk 26​

v9 raises the minimum minSdk from 24 to 26.

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

Field renames​

v9.xv10.x
Web3AuthOptions.networkWeb3AuthOptions.web3AuthNetwork
Web3AuthOptions.buildEnvWeb3AuthOptions.authBuildEnv
Web3AuthOptions.loginConfig (HashMap)Web3AuthOptions.authConnectionConfig (List)
Web3AuthOptions.useCoreKitKeyWeb3AuthOptions.useSFAKey
Web3AuthOptions.chainNamespaceRemoved
LoginParams.loginProviderLoginParams.authConnection
LoginParams.redirectUrlRemoved
UserInfo.verifierUserInfo.authConnectionId
UserInfo.verifierIdUserInfo.userId
UserInfo.aggregateVerifierUserInfo.groupedAuthConnectionId
UserInfo.typeOfLoginUserInfo.authConnection
Web3AuthResponse.privKeyWeb3AuthResponse.privateKey

Web3AuthOptions configuration​

val web3Auth = Web3Auth(
    Web3AuthOptions(
        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
    ),
    this
)

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

See Custom JWT sign-in (11.0.2) for the v11 behavior.

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 (11.0.2: add mfaLevel = MFALevel.NONE)
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 (11.0.2)
NetworkMainnet, Cyan, etc.Sapphire supportedWeb3AuthNetwork (Sapphire)Web3AuthNetwork (Sapphire)
compileSdk / targetSdk33343434
minSdk2424 (26 from v9)2626
ContextIn Web3AuthOptionsIn Web3AuthOptions (constructor from v9)Web3Auth constructorWeb3Auth constructor
redirectUrlOptionalMandatory (v7.4+)Mandatory (String)Mandatory (String)
Whitelabel namenameappNameappNameappName
AuthenticationN/Alogin() + ProviderconnectTo() + AuthConnectionconnectTo() + AuthConnection
Custom JWT sign-inN/AProvider.JWTSilent SFAAuth flow by default; silent SFA with MFALevel.NONE
Private keyN/AgetPrivkey()getPrivateKey()getPrivateKey()
Wallet UIN/AlaunchWalletServices()showWalletUI()showWalletUI() (Wallet Services v6)
requestN/AchainConfig + methodmethod + requestParams onlymethod + requestParams only
Sign resultN/AgetSignResponse() (v6.1-v8)Return value of request()Return value of request()
Chain configN/APassed in codeDashboard-managedDashboard-managed

Next steps​

On this page