Configure Wallet Recovery

A recovery method lets users regain access to their wallet when their operational (device) signer is no longer available — for example, when they switch to a new phone or clear their browser data. The recovery method authorizes the enrollment of a new device signer on the new device. You can choose from email OTP, SMS OTP, or a server signer depending on your application’s needs. A wallet can have more than one recovery method, so a user has more than one way to prove ownership. This guide covers setting a recovery method when the wallet is created.

Prerequisites

A Crossmint API key with wallets.create scope
For email OTP: the user’s email address
For SMS OTP: the user’s phone number in E.164 format (e.g., +1234567890)
For server signer: a signer secret stored on your server

Email OTP Recovery Method

The user verifies ownership of their email address via a one-time password sent by Crossmint. This is the most common recovery method for consumer applications.

React
Node.js
React Native
Flutter
REST

Using createOnLogin on the provider (recommended):

import {
    CrossmintProvider,
    CrossmintAuthProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-ui";

function App({ children }) {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintAuthProvider
                loginMethods={["email", "google"]}
            >
                <CrossmintWalletProvider
                    createOnLogin={{
                        chain: "base-sepolia",
                        recovery: { type: "email" },
                    }}
                >
                    {children}
                </CrossmintWalletProvider>
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

Or using createWallet directly:

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

const { createWallet } = useWallet();

const wallet = await createWallet({
    chain: "base-sepolia",
    recovery: {
        type: "email",
        email: "user@example.com", // Omit when using CrossmintAuthProvider (auto-populated)
    },
});

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

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

try {
    const wallet = await crossmintWallets.createWallet({
        chain: "base-sepolia",
        owner: "email:user@example.com",
        recovery: {
            type: "email",
            email: "user@example.com",
        },
    });
} catch (error) {
    console.error("Failed to create wallet:", error);
}

import {
    CrossmintProvider,
    CrossmintAuthProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App({ children }) {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintAuthProvider
                loginMethods={["email", "google"]}
            >
                <CrossmintWalletProvider
                    createOnLogin={{
                        chain: "base-sepolia",
                        recovery: { type: "email" },
                    }}
                >
                    {children}
                </CrossmintWalletProvider>
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

import 'package:flutter/material.dart';
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: CrossmintWalletProvider(
        config: CrossmintWalletProviderConfig(
          clientConfig: const CrossmintClientConfig(
            apiKey: 'YOUR_CLIENT_API_KEY',
            appScheme: 'myapp',
          ),
          walletControllerConfig: const CrossmintWalletControllerConfig(
            createOnLogin: CrossmintCreateOnLoginConfig(
              chain: 'base-sepolia',
              recovery: CrossmintEmailSignerConfig(),
            ),
          ),
          otpPromptBuilder: crossmintDefaultOtpPromptBuilder,
        ),
        child: const HomeScreen(),
      ),
    );
  }
}

When CrossmintEmailSignerConfig() is used with createOnLogin, the email is auto-populated from the authenticated user.

curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
    --data '{
        "chainType": "evm",
        "config": {
            "adminSigner": {
                "type": "email",
                "email": "user@example.com"
            }
        }
    }'

const url =
    "https://staging.crossmint.com/api/2025-06-09/wallets";

const payload = {
    chainType: "evm",
    config: {
        adminSigner: {
            type: "email",
            email: "user@example.com",
        },
    },
};

const response = await fetch(url, {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_SERVER_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.crossmint.com/api/2025-06-09/wallets"

payload = {
    "chainType": "evm",
    "config": {
        "adminSigner": {
            "type": "email",
            "email": "user@example.com"
        }
    }
}
headers = {
    "X-API-KEY": "YOUR_SERVER_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

The REST API uses the legacy field name adminSigner for the recovery method. The SDK uses recovery.

SMS OTP Recovery Method

The user verifies ownership of their phone number via a one-time password delivered by SMS (or optionally WhatsApp). This is ideal for mobile-first applications. By default, OTPs are sent via SMS. Set channel: "whatsapp" in the phone signer config to deliver the OTP through WhatsApp instead.

WhatsApp delivery is not supported in Brazil, Mexico, India, or Indonesia. Phone numbers in those countries receive the OTP over SMS even when channel: "whatsapp" is set.

React
Node.js
React Native
Flutter
REST

Using createOnLogin on the provider:

import {
    CrossmintProvider,
    CrossmintAuthProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-ui";

function App({ children }) {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintAuthProvider
                loginMethods={["email", "google"]}
            >
                <CrossmintWalletProvider
                    createOnLogin={{
                        chain: "base-sepolia",
                        recovery: {
                            type: "phone",
                            phone: "+1234567890",
                            channel: "whatsapp",
                        },
                    }}
                >
                    {children}
                </CrossmintWalletProvider>
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

Or using createWallet directly:

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

const { createWallet } = useWallet();

const wallet = await createWallet({
    chain: "base-sepolia",
    recovery: {
        type: "phone",
        phone: "+1234567890", // E.164 format required
        channel: "whatsapp",
    },
});

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

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

try {
    const wallet = await crossmintWallets.createWallet({
        chain: "base-sepolia",
        owner: "phone:+12223334444",
        recovery: {
            type: "phone",
            phone: "+12223334444", // E.164 format required
            channel: "whatsapp",
        },
    });
} catch (error) {
    console.error("Failed to create wallet:", error);
}

import {
    CrossmintProvider,
    CrossmintAuthProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App({ children }) {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintAuthProvider
                loginMethods={["email", "google"]}
            >
                <CrossmintWalletProvider
                    createOnLogin={{
                        chain: "base-sepolia",
                        recovery: {
                            type: "phone",
                            phone: "+1234567890",
                            channel: "whatsapp",
                        },
                    }}
                >
                    {children}
                </CrossmintWalletProvider>
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

CrossmintWalletProvider(
  config: CrossmintWalletProviderConfig(
    clientConfig: const CrossmintClientConfig(
      apiKey: 'YOUR_CLIENT_API_KEY',
      appScheme: 'myapp',
    ),
    walletControllerConfig: const CrossmintWalletControllerConfig(
      createOnLogin: CrossmintCreateOnLoginConfig(
        chain: 'base-sepolia',
        recovery: CrossmintPhoneSignerConfig(phone: 'YOUR_E164_PHONE_NUMBER'),
      ),
    ),
    otpPromptBuilder: crossmintDefaultOtpPromptBuilder,
  ),
  child: const HomeScreen(),
)

Phone numbers must be in E.164 format (e.g. +1234567890).

curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
    --data '{
        "chainType": "evm",
        "config": {
            "adminSigner": {
                "type": "phone",
                "phone": "+1234567890"
            }
        }
    }'

const url =
    "https://staging.crossmint.com/api/2025-06-09/wallets";

const payload = {
    chainType: "evm",
    config: {
        adminSigner: {
            type: "phone",
            phone: "+1234567890",
        },
    },
};

const response = await fetch(url, {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_SERVER_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
});

const data = await response.json();
console.log(data);

import requests

url = "https://staging.crossmint.com/api/2025-06-09/wallets"

payload = {
    "chainType": "evm",
    "config": {
        "adminSigner": {
            "type": "phone",
            "phone": "+1234567890"
        }
    }
}
headers = {
    "X-API-KEY": "YOUR_SERVER_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Server Recovery Method

Use a server signer as the recovery method when your backend should manage recovery without a user-facing OTP flow. This fits company wallets, agents, backend automation, and hybrid architectures.

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

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

const wallet = await crossmintWallets.createWallet({
    chain: "base-sepolia",
    recovery: {
        type: "server",
        secret: process.env.CROSSMINT_SIGNER_SECRET,
    },
});

For more on generating and managing server signer secrets, see the Server Signer guide.

How Recovery Works on a New Device

When a user accesses their wallet from a new device where no device signer exists:

The user authenticates via your app — the SDK retrieves the wallet
The SDK detects no local device signer on this device
On the first transaction (or when recover() is called), the SDK triggers the recovery flow:
- Email OTP: Crossmint sends a one-time code to the user’s email
- SMS OTP: Crossmint sends a one-time code to the user’s phone
- Server signer: your backend signs the recovery approval automatically
The recovery method authorizes a new device signer for this device
All subsequent transactions on the new device are frictionless

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

const { wallet } = useWallet();

// Check if recovery is needed on this device
if (wallet.needsRecovery()) {
    // Trigger recovery proactively (optional)
    await wallet.recover();
}

The previous device’s signer remains valid. Each device maintains its own independent device signer.

Choosing a Recovery Method

Method	Best For	User Friction	Server Required
Email OTP	Consumer apps with email-based auth	Medium (OTP prompt)	No
SMS OTP	Mobile-first apps	Medium (OTP prompt)	No
Server signer	AI agents, backend automation, hybrid apps	None (automatic)	Yes

Advanced: recovery methods can also send transactions

A recovery method is an onchain signer, so it can authorize transactions and not only signer changes. For an email or phone recovery method, the one-time code prompt is the familiar experience users already expect when they recover an account, which is why it works well for recovery. That same prompt appears on every operation, so it is a poor fit for day-to-day approvals — an operational signer approves those without interrupting the user.To sign with a recovery method, select it explicitly: activate it in the SDK, or set the signer field to its locator in the REST API.

React
Node.js
REST

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

const { wallet } = useWallet();

await wallet.useSigner({ type: "email", email: "user@example.com" });

const { hash } = await wallet.send("0xRecipientAddress", "usdc", "10");

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",
});

await wallet.useSigner({ type: "email", email: "user@example.com" });

const { hash } = await wallet.send("0xRecipientAddress", "usdc", "10");

curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/transactions \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
    --data '{
        "params": {
            "chain": "base-sepolia",
            "signer": "email:user@example.com",
            "calls": [{
                "to": "0xRecipientAddress",
                "value": "0",
                "data": "0x"
            }]
        }
    }'

const walletAddress = "YOUR_WALLET_ADDRESS";

const response = await fetch(
    `https://staging.crossmint.com/api/2025-06-09/wallets/${walletAddress}/transactions`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": "YOUR_SERVER_API_KEY",
        },
        body: JSON.stringify({
            params: {
                chain: "base-sepolia",
                signer: "email:user@example.com",
                calls: [{ to: "0xRecipientAddress", value: "0", data: "0x" }],
            },
        }),
    }
);

const { id } = await response.json();

import requests

wallet_address = "YOUR_WALLET_ADDRESS"

response = requests.post(
    f"https://staging.crossmint.com/api/2025-06-09/wallets/{wallet_address}/transactions",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "YOUR_SERVER_API_KEY",
    },
    json={
        "params": {
            "chain": "base-sepolia",
            "signer": "email:user@example.com",
            "calls": [{"to": "0xRecipientAddress", "value": "0", "data": "0x"}],
        }
    },
)

transaction_id = response.json()["id"]

The transaction is created in awaiting-approval status. Approve it with the recovery method through the approve transaction endpoint. When submitting a signed approval, approvals[].signer must be the locator of the recovery method that produced the signature.

Next Steps

Device Signer

Understand how the default client-side signer works

Server Signer

Set up server-side signing with key derivation

Add Signers

Add passkeys or external wallets to an existing wallet

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Prerequisites

Email OTP Recovery Method

SMS OTP Recovery Method

Server Recovery Method

How Recovery Works on a New Device

Choosing a Recovery Method

Next Steps

Device Signer

Server Signer

Add Signers

​Prerequisites

​Email OTP Recovery Method

​SMS OTP Recovery Method

​Server Recovery Method

​How Recovery Works on a New Device

​Choosing a Recovery Method

​Next Steps

Device Signer

Server Signer

Add Signers

Prerequisites

Email OTP Recovery Method

SMS OTP Recovery Method

Server Recovery Method

How Recovery Works on a New Device

Choosing a Recovery Method

Next Steps