Recover a wallet

Portal-Managed Recovery (default)

When using Portal-Managed Backups, you can simply call the portal.recoverWallet() function passing an empty string for the cipherText parameter. Portal will then fetch the cipherText from our backend and complete the recovery process.

// With Password backup
await portal.recoverWallet('', BackupMethods.password, {
  passwordStorage: {
    password: "${USER_PROVIDED_PASSWORD}"
  }
})

// With GDrive backup
await portal.recoverWallet('', BackupMethods.gdrive)

// With PasskeyBackups
await portal.recoverWallet('', BackupMethods.passkey)

// With Firebase Auth Backup (configure Firebase storage and ensure user is signed in)
await portal.recoverWallet('', BackupMethods.firebase)

WARNING: To recover a wallet with the Portal SDK, your device must be configured to use passcode authentication. Please note that if you disable your passcode authentication after executing the recover function, you will need to run the recover function again.

Self-Managed Recovery

By default, Portal manages storing both the encrypted client backup share and the custodian backup share for you. If you prefer to store and manage the backup shares in your own infrastructure instead of using Portal-Managed Backups, see our Self-Managed Backups guide. Before recovering, you will need to retrieve the encrypted client backup share from your API. You will then provide the encrypted client backup share to portal.recoverWallet. Here’s an example of how that might look in your code:

// Fetch the encrypted client backup share from your API.
const cipherText = await axios.get('/users/[userId]/user-backup-share?backupMethod=GDRIVE')

// Recover replaces your current signing shares (if there are any) with new ones.
await portal.recoverWallet(cipherText, BackupMethods.gdrive)

Passkey Recovery

To recover a wallet that was backed up with a passkey:

Portal-Managed Recovery
Self-Managed Recovery

import React from 'react'

const RecoveryButton: React.FC = () => {
  const handleRecovery = async () => {
    // Portal fetches the cipherText automatically
    const address = await portal.recoverWallet(
      '',
      BackupMethods.passkey,
      {},
      (status) => console.log('Recovery progress:', status)
    )

    console.log('Recovered wallet address:', address)
  }

  return (
    <button onClick={handleRecovery}>Recover wallet</button>
  )
}

export default RecoveryButton

import axios from 'axios'
import React from 'react'

const RecoveryButton: React.FC = () => {
  const handleRecovery = async () => {
    // Fetch the cipherText from your backend
    const response = await axios.get('{your_server}/users/[userId]/user-backup-share')
    const cipherText = response.data.cipherText

    const address = await portal.recoverWallet(
      cipherText,
      BackupMethods.passkey,
      {},
      (status) => console.log('Recovery progress:', status)
    )

    console.log('Recovered wallet address:', address)
  }

  return (
    <button onClick={handleRecovery}>Recover wallet</button>
  )
}

export default RecoveryButton

Custom Domain Passkeys Recovery

If you configured a custom domain for passkeys (see Custom Domain Passkeys), use the following recovery flow:

Portal-Managed Recovery
Self-Managed Recovery

import React from 'react'
import { PasskeyOptions } from '@portal-hq/web/types'

const passkeyOptions: PasskeyOptions = {
  customDomain: 'https://passkeys.yourapp.com',  // Your configured subdomain. This will be the same across all environments, even local.
  relyingPartyId: 'yourapp.com',                 // Your root domain. For local dev set this to `localhost`
  relyingPartyName: 'Your App Name',             // Displayed in passkey prompts
  usePopup: false,                               // Direct WebAuthn calls
}

const RecoveryButton: React.FC = () => {
  const handleRecovery = async () => {
    try {
      // Step 1: Authenticate with passkey to get encryption key
      const encryptionKey = await portal.authenticatePasskeyAndRetrieveKey(passkeyOptions)

      // Step 2: Recover wallet - Portal fetches cipherText automatically
      const address = await portal.recoverWallet(
        '',
        BackupMethods.custom,
        { customStorage: { encryptionKey } },
        (status) => console.log('Recovery progress:', status)
      )

      console.log('Recovered wallet address:', address)
    } catch (error) {
      console.error('Recovery failed:', error)
    }
  }

  return (
    <button onClick={handleRecovery}>Recover with Passkey</button>
  )
}

import axios from 'axios'
import React from 'react'
import { PasskeyOptions } from '@portal-hq/web/types'

const passkeyOptions: PasskeyOptions = {
  customDomain: 'https://passkeys.yourapp.com',  // Your configured subdomain. This will be the same across all environments, even local.
  relyingPartyId: 'yourapp.com',                 // Your root domain. For local dev set this to `localhost`
  relyingPartyName: 'Your App Name',             // Displayed in passkey prompts
  usePopup: false,                               // Direct WebAuthn calls
}

const RecoveryButton: React.FC = () => {
  const handleRecovery = async () => {
    try {
      // Step 1: Retrieve cipherText from your backend
      const response = await axios.get('{your_server}/users/[userId]/user-backup-share')
      const cipherText = response.data.cipherText

      if (!cipherText) {
        throw new Error('No backup found')
      }

      // Step 2: Authenticate with passkey to get encryption key
      const encryptionKey = await portal.authenticatePasskeyAndRetrieveKey(passkeyOptions)

      // Step 3: Recover wallet with the encryption key
      const address = await portal.recoverWallet(
        cipherText,
        BackupMethods.custom,
        { customStorage: { encryptionKey } },
        (status) => console.log('Recovery progress:', status)
      )

      console.log('Recovered wallet address:', address)
    } catch (error) {
      console.error('Recovery failed:', error)
    }
  }

  return (
    <button onClick={handleRecovery}>Recover with Passkey</button>
  )
}

Important: You must have called portal.storedClientBackupShare(true, BackupMethods.custom) after successfully storing the cipherText during backup. If this was not called, recovery will fail with the error “Cannot run recovery, backup was not completed successfully”.

Firebase Auth recovery

Firebase recovery uses the same TBS-backed encryption key flow as backup. Call configureFirebaseStorage with the same getToken implementation you use for backup, and ensure the user is signed in to Firebase before calling recoverWallet. The tab examples below assume a configured portal instance (same pattern as other recovery snippets in this guide).

Portal-Managed Recovery
Self-Managed Recovery

import React from 'react'
import { BackupMethods } from '@portal-hq/web'
import { getAuth } from 'firebase/auth'

const FirebaseRecoveryButton: React.FC = () => {
  const handleRecovery = async () => {
    const auth = getAuth()

    portal.configureFirebaseStorage({
      getToken: async (options?: { forceRefresh?: boolean }) => {
        const user = auth.currentUser
        if (!user) {
          return null
        }
        return user.getIdToken(Boolean(options?.forceRefresh))
      },
    })

    const address = await portal.recoverWallet(
      '',
      BackupMethods.firebase,
      {},
      (status) => console.log('Recovery progress:', status),
    )

    console.log('Recovered wallet address:', address)
  }

  return (
    <button onClick={handleRecovery}>Recover with Firebase</button>
  )
}

export default FirebaseRecoveryButton

import axios from 'axios'
import React from 'react'
import { BackupMethods } from '@portal-hq/web'
import { getAuth } from 'firebase/auth'

const FirebaseRecoveryButton: React.FC = () => {
  const handleRecovery = async () => {
    const auth = getAuth()

    portal.configureFirebaseStorage({
      getToken: async (options?: { forceRefresh?: boolean }) => {
        const user = auth.currentUser
        if (!user) {
          return null
        }
        return user.getIdToken(Boolean(options?.forceRefresh))
      },
    })

    const response = await axios.get(
      '{your_server}/users/[userId]/user-backup-share?backupMethod=FIREBASE',
    )
    const cipherText = response.data.cipherText

    const address = await portal.recoverWallet(
      cipherText,
      BackupMethods.firebase,
      {},
      (status) => console.log('Recovery progress:', status),
    )

    console.log('Recovered wallet address:', address)
  }

  return (
    <button onClick={handleRecovery}>Recover with Firebase</button>
  )
}

export default FirebaseRecoveryButton

See Back up a wallet — Firebase Auth backup for setup prerequisites and the Firebase Auth Backup resource.

Progress Callbacks

You can learn how to handle the progress callbacks for portal.recoverWallet here.

Next steps

Amazing! Your users can now have multiple backups and can easily recover their wallet. Next let’s dive into handling sessions across multiple devices for your users.

Getting Started

SDKs

APIs

Integrations

Resources

Recover a wallet

Portal-Managed Recovery (default)

Self-Managed Recovery

Passkey Recovery

Custom Domain Passkeys Recovery

Firebase Auth recovery

Progress Callbacks

Next steps

​Portal-Managed Recovery (default)

​Self-Managed Recovery

​Passkey Recovery

​Custom Domain Passkeys Recovery

​Firebase Auth recovery

​Progress Callbacks

​Next steps

Portal-Managed Recovery (default)

Self-Managed Recovery

Passkey Recovery

Custom Domain Passkeys Recovery

Firebase Auth recovery

Progress Callbacks

Next steps