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, and a wallet can have more than one recovery method. This guide covers setting recovery methods when the wallet is created.

In the React, React Native, and Node.js SDKs, the recovery wallet-creation property is deprecated. Pass recoveryMethods instead — it takes a list, so a single recovery method is written as recoveryMethods: [{ type: "email" }].

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.

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",
                        recoveryMethods: [{ 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",
    recoveryMethods: [
        {
            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",
        recoveryMethods: [
            {
                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",
                        recoveryMethods: [{ type: "email" }],
                    }}
                >
                    {children}
                </CrossmintWalletProvider>
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

import CrossmintClient

let sdk = CrossmintSDK.shared

let wallet = try await sdk.crossmintWallets.createWallet(
    chain: EVMChain.baseSepolia,
    recoveryMethods: [EVMSigners.email("user@example.com")]
)

import com.crossmint.kotlin.CrossmintSDK
import com.crossmint.kotlin.types.EVMChain
import com.crossmint.kotlin.signers.SignerType

val sdk = CrossmintSDK.shared
val result = sdk.wallets.createWallet(
    chain = EVMChain.BaseSepolia,
    recoveryMethods = listOf(SignerType.Email("user@example.com"))
)
val wallet = result.getOrThrow()

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",
        "owner": "email:user@example.com",
        "config": {
            "recoveryMethods": [
                {
                    "type": "email",
                    "email": "user@example.com"
                }
            ]
        }
    }'

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

const payload = {
    chainType: "evm",
    owner: "email:user@example.com",
    config: {
        recoveryMethods: [
            {
                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",
    "owner": "email:user@example.com",
    "config": {
        "recoveryMethods": [
            {
                "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())

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.

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",
                        recoveryMethods: [
                            {
                                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",
    recoveryMethods: [
        {
            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",
        recoveryMethods: [
            {
                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",
                        recoveryMethods: [
                            {
                                type: "phone",
                                phone: "+1234567890",
                                channel: "whatsapp",
                            },
                        ],
                    }}
                >
                    {children}
                </CrossmintWalletProvider>
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

import CrossmintClient

let sdk = CrossmintSDK.shared

let wallet = try await sdk.crossmintWallets.createWallet(
    chain: EVMChain.baseSepolia,
    recoveryMethods: [EVMSigners.phone("+1234567890", channel: .whatsapp)]
)

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

import com.crossmint.kotlin.CrossmintSDK
import com.crossmint.kotlin.types.EVMChain
import com.crossmint.kotlin.signers.SignerType
import com.crossmint.kotlin.signers.OTPDeliveryChannel

val sdk = CrossmintSDK.shared
val result = sdk.wallets.createWallet(
    chain = EVMChain.BaseSepolia,
    recoveryMethods = listOf(SignerType.Phone("+1234567890", channel = OTPDeliveryChannel.WHATSAPP))
)
val wallet = result.getOrThrow()

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

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",
        "owner": "phone:+1234567890",
        "config": {
            "recoveryMethods": [
                {
                    "type": "phone",
                    "phone": "+1234567890"
                }
            ]
        }
    }'

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

const payload = {
    chainType: "evm",
    owner: "phone:+1234567890",
    config: {
        recoveryMethods: [
            {
                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",
    "owner": "phone:+1234567890",
    "config": {
        "recoveryMethods": [
            {
                "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",
    recoveryMethods: [
        {
            type: "server",
            secret: process.env.CROSSMINT_SIGNER_SECRET,
        },
    ],
});

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

Multiple Recovery Methods

Add more than one entry to recoveryMethods to register several recovery methods on the same wallet. You can combine multiple email and phone recovery methods, and a single one of them is enough to authorize recovery, add or remove signers, and add or remove other recovery methods. See Manage Recovery Methods for changing recovery methods after creation, and for useRecoveryMethod(), which selects the one that authorizes an operation when a wallet has several.

Multiple recovery methods are available on Solana and Stellar. EVM wallets accept a single recovery method today; support for multiple recovery methods on EVM is coming soon.

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: "solana",
                        recoveryMethods: [
                            { type: "email" },
                            {
                                type: "phone",
                                phone: "+1234567890",
                            },
                        ],
                    }}
                >
                    {children}
                </CrossmintWalletProvider>
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

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: "solana",
        owner: "email:user@example.com",
        recoveryMethods: [
            { type: "email", email: "user@example.com" },
            {
                type: "phone",
                phone: "+12223334444", // E.164 format required
            },
        ],
    });

    console.log(wallet.recoveryMethods.map((method) => method.type)); // ["email", "phone"]
} 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: "solana",
                        recoveryMethods: [
                            { type: "email" },
                            {
                                type: "phone",
                                phone: "+1234567890",
                            },
                        ],
                    }}
                >
                    {children}
                </CrossmintWalletProvider>
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

import CrossmintClient

let sdk = CrossmintSDK.shared

let wallet = try await sdk.crossmintWallets.createWallet(
    chain: .solana,
    recoveryMethods: [.email("user@example.com"), .phone("+12223334444")]
)

Only Solana and Stellar accept more than one recovery signer.

import com.crossmint.kotlin.CrossmintSDK
import com.crossmint.kotlin.types.SolanaChain
import com.crossmint.kotlin.signers.SignerType

val sdk = CrossmintSDK.shared
val result = sdk.wallets.createWallet(
    chain = SolanaChain.Solana,
    recoveryMethods = listOf(
        SignerType.Email("user@example.com"),
        SignerType.Phone("+12223334444"),
    )
)
val wallet = result.getOrThrow()

Only Solana and Stellar accept more than one recovery signer.

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": "solana",
        "owner": "email:user@example.com",
        "config": {
            "recoveryMethods": [
                {
                    "type": "email",
                    "email": "user@example.com"
                },
                {
                    "type": "phone",
                    "phone": "+1234567890"
                }
            ]
        }
    }'

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

const payload = {
    chainType: "solana",
    owner: "email:user@example.com",
    config: {
        recoveryMethods: [
            { type: "email", email: "user@example.com" },
            { 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.config.recoveryMethods);

import requests

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

payload = {
    "chainType": "solana",
    "owner": "email:user@example.com",
    "config": {
        "recoveryMethods": [
            {"type": "email", "email": "user@example.com"},
            {"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 Wallets

Server wallets cannot use email or phone recovery methods. Combine a server signer with an external-wallet recovery method instead — for example a key held in your cloud KMS — so that either one can recover the wallet:

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: "solana",
    recoveryMethods: [
        {
            type: "server",
            secret: process.env.CROSSMINT_SIGNER_SECRET,
        },
        {
            type: "external-wallet",
            address: "YOUR_KMS_KEY_ADDRESS",
        },
    ],
});

See Cloud KMS for how to set up a KMS-held key.

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 with the selected recovery method:
- 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

Manage Recovery Methods

Add or remove recovery methods on an existing wallet

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Prerequisites

Email OTP Recovery Method

SMS OTP Recovery Method

Server Recovery Method

Multiple Recovery Methods

Server Wallets

How Recovery Works on a New Device

Choosing a Recovery Method

Next Steps

Device Signer

Server Signer

Manage Recovery Methods

​Prerequisites

​Email OTP Recovery Method

​SMS OTP Recovery Method

​Server Recovery Method

​Multiple Recovery Methods

​Server Wallets

​How Recovery Works on a New Device

​Choosing a Recovery Method

​Next Steps

Device Signer

Server Signer

Manage Recovery Methods

Prerequisites

Email OTP Recovery Method

SMS OTP Recovery Method

Server Recovery Method

Multiple Recovery Methods

Server Wallets

How Recovery Works on a New Device

Choosing a Recovery Method

Next Steps