Wallet Recovery

​

When You Need This

• Switched devices — you set up a wallet on your laptop and now need to use it on a new computer or phone. The device signer from the original machine cannot be transferred.
• Cleared browser data — you cleared cookies, local storage, or reinstalled the app, which deleted the locally stored device key.
• Lost server signer secret — the secret used to derive your server signer was lost, rotated, or compromised.
• Lost private key — the private key for an external wallet signer is no longer accessible.
• Infrastructure migration — you need to move signing authority to new infrastructure.

​

Prerequisites

• A wallet that was created with a recovery signer (email, phone, or server). If your wallet was not created with a recovery signer, this guide does not apply — see Managed Support Center Recovery below for enterprise options. To configure a recovery signer, see Configure Wallet Recovery.
• A Crossmint client-side API key with wallets.read, wallets:signatures.create, and wallets:transactions.create scopes
• Access to the email address or phone number associated with the recovery signer (for OTP-based recovery)

​

How It Works

1. Wallet fetch — createOnLogin loads the wallet when the user logs in on the new device.
2. Detection — the SDK finds no valid local device key and automatically attempts to add a new device signer.
3. OTP prompt — the pending signer enrollment triggers the recovery flow. For email OTP, the user receives a one-time code and enters it to authorize the new key.
4. New key generation — the SDK generates a new P256 keypair in the device’s secure enclave (or browser credential store).
5. Signer registration — the SDK calls addSigner() to register the new device key onchain, authorized by the recovery signer.
6. Activation — the new device signer becomes the active signer. All subsequent transactions on this device are frictionless.

​

Step 1: Recover on a New Device

​

Automatic Recovery (Recommended)

1. The user logs in on the new device — createOnLogin fetches the wallet
2. The SDK detects no local device key and attempts to add a new device signer
3. The pending signer enrollment triggers the OTP prompt — the user enters the code from their email
4. The new device signer is registered for this device
5. All future transactions on this device are frictionless

​

Preemptive Recovery

"use client";

import { useWallet } from "@crossmint/client-sdk-react-ui";
import { useEffect, useState } from "react";

function WalletRecovery() {
    const { wallet } = useWallet();
    const [recovering, setRecovering] = useState(false);

    useEffect(() => {
        const checkRecovery = async () => {
            if (wallet && wallet.needsRecovery()) {
                setRecovering(true);
                await wallet.recover();
                setRecovering(false);
            }
        };
        checkRecovery();
    }, [wallet]);

    if (recovering) {
        return <p>Verifying your identity to set up this device...</p>;
    }

    return (
        <div>
            <p>Wallet ready: {wallet?.address}</p>
        </div>
    );
}

​

Manual Recovery Flow

"use client";

import { useWallet, useWalletOtpSigner } from "@crossmint/client-sdk-react-ui";
import { useState } from "react";

function ManualRecovery() {
    const { wallet } = useWallet();
    const { needsAuth, verifyOtp, reject } = useWalletOtpSigner();
    const [otpCode, setOtpCode] = useState("");

    if (!wallet || !wallet.needsRecovery()) {
        return <p>Wallet is ready — no recovery needed.</p>;
    }

    if (!needsAuth) {
        return (
            <button onClick={() => wallet.recover()}>
                Start Recovery
            </button>
        );
    }

    return (
        <div>
            <p>Enter the verification code sent to your email:</p>
            <input
                value={otpCode}
                onChange={(e) => setOtpCode(e.target.value)}
                placeholder="Enter OTP code"
            />
            <button onClick={() => verifyOtp(otpCode)}>Verify</button>
            <button onClick={reject}>Cancel</button>
        </div>
    );
}

​

Step 2: Choose a Recovery Action

​

Option A: Add a Different Signer Type

import { useWallet } from "@crossmint/client-sdk-react-ui";

function AddPasskeySigner() {
    const { wallet, createPasskeySigner } = useWallet();

    const handleAddPasskey = async () => {
        if (!wallet) return;

        const passkey = await createPasskeySigner("my-wallet-passkey");
        const signer = await wallet.addSigner(passkey);
        console.log("Passkey added:", signer.locator);

        await wallet.useSigner({ type: "passkey" });
    };

    return (
        <button onClick={handleAddPasskey}>
            Add Passkey as New Signer
        </button>
    );
}

import { useWallet } from "@crossmint/client-sdk-react-ui";
import { privateKeyToAccount } from "viem/accounts";

function AddExternalWalletSigner() {
    const { wallet } = useWallet();

    const handleAddExternalWallet = async () => {
        if (!wallet) return;

        const privateKeyEVM = "YOUR_PRIVATE_KEY" as `0x${string}`;
        const account = privateKeyToAccount(privateKeyEVM);

        const signerConfig = {
            type: "external-wallet" as const,
            address: account.address,
            onSign: async (message: string) => {
                return await account.signMessage({
                    message: { raw: message as `0x${string}` },
                });
            },
        };

        const signer = await wallet.addSigner(signerConfig);
        console.log("External wallet added:", signer.locator);

        await wallet.useSigner(signerConfig);
    };

    return (
        <button onClick={handleAddExternalWallet}>
            Add External Wallet as Signer
        </button>
    );
}

import { useWallet } from "@crossmint/client-sdk-react-ui";

function AddServerSigner() {
    const { wallet } = useWallet();

    const handleAddServerSigner = async () => {
        if (!wallet) return;

        const newSigner = await wallet.addSigner({
            type: "server",
            secret: "YOUR_NEW_SERVER_SIGNER_SECRET",
        });

        console.log("New server signer added:", newSigner.locator);
    };

    return (
        <button onClick={handleAddServerSigner}>
            Add Server Signer
        </button>
    );
}

​

Option B: Transfer Funds to a Safe Wallet

import { useWallet } from "@crossmint/client-sdk-react-ui";

function EmergencyTransfer() {
    const { wallet } = useWallet();

    const handleTransfer = async () => {
        if (!wallet) return;

        const result = await wallet.send(
            "YOUR_SAFE_WALLET_ADDRESS",
            "usdc",
            "100"
        );

        console.log("Transfer complete:", result.explorerLink);
    };

    return (
        <button onClick={handleTransfer}>
            Transfer Funds to Safe Wallet
        </button>
    );
}

​

Alternative: Recovery with Phone OTP

​

Alternative: Server-to-Server Recovery

import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({
    apiKey: "YOUR_SERVER_API_KEY",
});
const crossmintWallets = CrossmintWallets.from(crossmint);

const wallet = await crossmintWallets.getWallet(
    "YOUR_WALLET_ADDRESS",
    { chain: "base-sepolia" }
);

// Activate the recovery server signer
await wallet.useSigner({
    type: "server",
    secret: process.env.RECOVERY_SIGNER_SECRET,
});

// Add a new operational server signer
const newSigner = await wallet.addSigner({
    type: "server",
    secret: process.env.NEW_OPERATIONAL_SECRET,
});

console.log("New operational signer added:", newSigner.locator);

​

Best Practices

• Always configure a recovery signer at wallet creation time. Recovery signers cannot be added later via addSigner().
• Use preemptive recovery on app startup to give users a smoother experience — they verify once on load rather than being interrupted mid-transaction.
• Use different secrets for your operational and recovery server signers. Store them in separate secure locations.
• After recovery, the new device signer works automatically. You do not need to manually call addSigner() for device signers — the recover() flow handles this.
• The old device signer remains valid. Each device has its own independent device key. Recovery adds a new key; it does not revoke the old one.
• Consider adding multiple signer types for defense in depth — for example, a device signer for daily use and a passkey as a backup.
• For compromised signers, transfer funds to a safe wallet first, then set up new signers on the original wallet (or create a fresh wallet).

​

Managed Support Center

​

See Also