Manage wallet lifecycle states

After initializing Portal for your user, it’s crucial to determine their wallet’s lifecycle state to ensure a healthy wallet state. We provide several helper methods to easily derive the state of your users’ wallets:

// Checks if the user has created a wallet on any device.
portal.doesWalletExistOrThrow()

// Checks if the user's wallet share is on their current device.
portal.isWalletOnDeviceOrThrow()

// Checks if the user has backed up their wallet.
portal.isWalletBackedUpOrThrow()

// Checks if the user can recover their wallet.
portal.isWalletRecoverableOrThrow()

// Returns a list of available recovery methods based on the user's backups.
portal.availableRecoveryMethods()

The previous methods doesWalletExist(), isWalletOnDevice(), isWalletBackedUp(), and isWalletRecoverable() are deprecated. These methods silently return false when an error occurs, which can mask underlying issues. Use the OrThrow variants above instead — they propagate errors so you can handle them explicitly.

As of 9.1.0, isWalletOnDeviceOrThrow() returns false when the user has no usable wallet share on the current device, rather than throwing. Having no wallet on this device is a normal lifecycle state, not an error, so it no longer surfaces as one.If you wrapped the call in a try/catch to treat the throw as “no wallet on device”, that catch block no longer runs for this case. Branch on the returned Boolean instead:

// Before 9.1.0
val walletExistsOnDevice = try {
    portal.isWalletOnDeviceOrThrow()
} catch (e: Exception) {
    false
}

// 9.1.0 and later
val walletExistsOnDevice = portal.isWalletOnDeviceOrThrow()

Keep your try/catch for genuine failures — the method still throws when the client isn’t set, when the chainId is malformed, or when a share left over from an older SDK version can’t be parsed. Just don’t rely on it to signal “no wallet on device”. See absent shares versus unreadable shares for the underlying change.

These methods can be used together to understand the user’s wallet state and determine the next steps. For example:

suspend fun manageWalletState(portal: Portal) {
    try {
        // Determine the wallet's state.
        val walletExists = portal.doesWalletExistOrThrow()
        val walletExistsOnDevice = portal.isWalletOnDeviceOrThrow()
        val walletIsRecoverable = portal.isWalletRecoverableOrThrow()

        if (!walletExists) {
            // Create and back up the wallet using portal.createWallet() and portal.backup().
        } else if (!walletExistsOnDevice) {
            if (walletIsRecoverable) {
                // Recover the wallet using portal.recover().
            } else {
                // Inform the user to back up the wallet on the original device.
            }
        } else {
            // The wallet is ready to use.
        }
    } catch(e: Exception) {
        // Handle any errors that occur.
    }
}

Each method also accepts an optional chainId parameter (e.g., "eip155:1") or a PortalNamespace to check the state for a specific chain instead of globally. Starting from SDK version 10.1.0, this includes "stellar:pubnet", "tron:mainnet", and "xrpl:0" (or PortalNamespace.STELLAR, TRON, and XRPL), which resolve to the wallet that holds that address: Tron and XRP Ledger to the SECP256K1 wallet, Stellar to the ED25519 wallet. To read the addresses themselves, see Get wallet addresses. And that’s it! You’re now helping your users maintain a safe and secure experience with their wallets while using your apps.

Getting Started

SDKs

APIs

Integrations

Resources

Manage wallet lifecycle states