Manage Recovery Methods

Recovery methods are set when a wallet is created, but they are not fixed. You can add a recovery method to an existing wallet — for example a backup phone number or a new server key — and remove one the user no longer controls. Every change is approved by one of the wallet’s existing recovery methods, and that approval is enforced onchain. Adding and removing recovery methods is supported on Solana and Stellar. EVM is coming soon; contact support if you would like early access. See Recovery Methods for the concept, and Configure Wallet Recovery for setting recovery methods at creation time.

Prerequisites

Wallet: An existing Solana or Stellar wallet with at least one recovery method.
API key: An API key with wallets.create and wallets:transactions.create scopes. In staging, all scopes are included by default.

How It Works

Adding or removing a recovery method creates a transaction that one of the wallet’s existing recovery methods must approve. With the SDK, addRecoveryMethod() and removeRecoveryMethod() handle the approval for you: an email or phone method prompts the user for a one-time code, a server method signs with its secret, and an external wallet signs through its onSign callback. Once the transaction confirms, wallet.recoveryMethods reflects the change. With the REST API, you submit the change and then approve the returned transaction yourself.

Rules enforced by the API

A wallet always keeps at least one recovery method: removing the last one is rejected.
A recovery method whose add transaction has not confirmed yet cannot be removed. Adding the same method again returns the in-flight transaction, or starts a new one once it has expired.
Only a recovery method can authorize these changes. Operational signers added with addSigner() cannot.
On Solana, only Crossmint smart wallets support these operations. On Stellar, removing a recovery method requires the wallet to run the latest contract version.

Select the Authorizing Recovery Method

When a wallet has a single recovery method, the SDK uses it to authorize addSigner(), removeSigner(), addRecoveryMethod(), and removeRecoveryMethod(). When a wallet has several, select the one to authorize with first by calling useRecoveryMethod() with one of the entries in wallet.recoveryMethods; otherwise the operation throws SignerRequiredError. Here, the phone recovery method authorizes adding an email signer:

await wallet.useRecoveryMethod({ type: "phone", phone: "+12223334444" });

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

Pass the full config when the method needs it to sign: the secret for a server method, or the onSign callback for an external wallet.

await wallet.useRecoveryMethod({
    type: "server",
    secret: process.env.CROSSMINT_SIGNER_SECRET,
});

Passing a config that does not match any entry in wallet.recoveryMethods throws InvalidRecoveryConfigError.

useRecoveryMethod() is experimental and may change in a future release.

Add a Recovery Method

The new method accepts the same configuration objects as recoveryMethods at wallet creation — email, phone, external-wallet, or server. Phone numbers use E.164 format.

React
Node.js
React Native
REST

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

const { wallet } = useWallet();

const result = await wallet.addRecoveryMethod({
    type: "phone",
    phone: "+12223334444",
});

console.log("Recovery method added:", result.transactionId);
console.log(wallet.recoveryMethods.map((method) => method.type));

For a wallet with a single email recovery method, the user enters the email one-time code to approve the change, and the last line logs ["email", "phone"]. With several recovery methods, call useRecoveryMethod() first.

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(
    "<wallet-address>",
    {
        chain: "solana",
        signer: {
            type: "server",
            secret: process.env.CROSSMINT_SIGNER_SECRET,
        },
    }
);

const result = await wallet.addRecoveryMethod({
    type: "external-wallet",
    address: "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7",
});

console.log("Recovery method added:", result.transactionId);

Here the server signer is the wallet’s recovery method, so it approves the change without user interaction. Only the address is needed to register an external wallet; the onSign callback is required later, when that recovery method is used to authorize an operation.

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

const { wallet } = useWallet();

const result = await wallet.addRecoveryMethod({
    type: "phone",
    phone: "+12223334444",
});

console.log("Recovery method added:", result.transactionId);

When using the REST API, the change must be approved by one of the wallet’s recovery methods. You must approve the transaction to complete it.

Add the recovery method

Call the add recovery method endpoint. The recoveryMethods field takes one recovery method per request, as a signer object or a signer locator. Set approver to the locator of the recovery method that authorizes the change. Omit chain for Solana and Stellar wallets.

curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: <x-api-key>' \
    --data '{
        "recoveryMethods": {
            "type": "external-wallet",
            "address": "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7"
        },
        "approver": "email:user@example.com"
    }'

const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods';

const payload = {
    recoveryMethods: {
        type: "external-wallet",
        address: "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7"
    },
    approver: "email:user@example.com"
};

const options = {
    method: 'POST',
    headers: {
        'X-API-KEY': '<x-api-key>',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
};

try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}

import requests

url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods"

payload = {
    "recoveryMethods": {
        "type": "external-wallet",
        "address": "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7"
    },
    "approver": "email:user@example.com"
}
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

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

print(response.json())

The response contains the registered method under recoveryMethods and the pending transaction under tx.

Sign and approve the transaction

Sign the approval message returned inside tx.approvals with the recovery method named in approver, then submit the signature to the approve transaction endpoint using the transaction ID from tx.id. Once the transaction succeeds, the new method appears in the wallet’s config.recoveryMethods.

Remove a Recovery Method

Identify the method to remove with the same configuration object you would pass to useRecoveryMethod(). Any of the wallet’s recovery methods can authorize the removal, as long as at least one method remains afterwards. In the React and React Native examples below, the email method authorizes removing the phone method.

React
Node.js
React Native
REST

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

const { wallet } = useWallet();

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

const result = await wallet.removeRecoveryMethod({
    type: "phone",
    phone: "+12223334444",
});

console.log("Recovery method removed:", result.transactionId);

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(
    "<wallet-address>",
    {
        chain: "solana",
        signer: {
            type: "server",
            secret: process.env.CROSSMINT_SIGNER_SECRET,
        },
    }
);

const result = await wallet.removeRecoveryMethod({
    type: "external-wallet",
    address: "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7",
});

console.log("Recovery method removed:", result.transactionId);

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

const { wallet } = useWallet();

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

const result = await wallet.removeRecoveryMethod({
    type: "phone",
    phone: "+12223334444",
});

console.log("Recovery method removed:", result.transactionId);

Remove the recovery method

Call the remove recovery method endpoint with the locator of the method to remove in the path, and the locator of the authorizing method in the approver query parameter. Omit chain for Solana and Stellar wallets.

Recovery method locators (for example phone:+12223334444 or external-wallet:GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7) are listed under config.recoveryMethods when you get the wallet.

curl --request DELETE \
    --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods/external-wallet:GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7?approver=email:user@example.com' \
    --header 'X-API-KEY: <x-api-key>'

const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods/external-wallet:GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7?approver=email:user@example.com';

const options = {
    method: 'DELETE',
    headers: {
        'X-API-KEY': '<x-api-key>'
    }
};

try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}

import requests

url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods/external-wallet:GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7?approver=email:user@example.com"

headers = {"X-API-KEY": "<x-api-key>"}

response = requests.delete(url, headers=headers)

print(response.json())

The response is the pending removal transaction, in the same shape as the get transaction endpoint.

Sign and approve the transaction

Sign the approval message returned inside approvals with the recovery method named in approver, then submit the signature to the approve transaction endpoint. The method is removed from config.recoveryMethods once the transaction succeeds.

Next Steps

Configure Recovery

Set recovery methods when creating a wallet

List Signers

Inspect the wallet’s signers and recovery methods

Recover a Wallet

Regain access from a new device with a recovery method

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Prerequisites

How It Works

Select the Authorizing Recovery Method

Add a Recovery Method

Remove a Recovery Method

Next Steps

Configure Recovery

List Signers

Recover a Wallet

​Prerequisites

​How It Works

​Select the Authorizing Recovery Method

​Add a Recovery Method

​Remove a Recovery Method

​Next Steps

Configure Recovery

List Signers

Recover a Wallet

Prerequisites

How It Works

Select the Authorizing Recovery Method

Add a Recovery Method

Remove a Recovery Method

Next Steps