Add Signers to a Wallet

This page has been updated for Wallets SDK V1. If you are using the previous version, see the previous version docs or the V1 migration guide.

Use addSigner() to register additional signers on an existing wallet. The wallet’s recovery signer must approve the operation — the SDK handles this automatically.

Email and phone signers cannot be added via addSigner(). They can only be configured as recovery signers at wallet creation time. See Configure Wallet Recovery.

Prerequisites

An existing wallet with a recovery signer configured
API key with wallets:signatures.create and wallets:transactions.create scopes

How It Works

When you call addSigner(), the SDK:

Submits the new signer registration request
Temporarily activates the recovery signer to approve the operation
After approval, restores the previously active signer

For client-side wallets with an email or phone recovery signer, the user is prompted with an OTP to approve adding the new signer. For server signer recovery, approval happens automatically.

Add a Passkey Signer

Passkey signers use the WebAuthn/FIDO2 standard for biometric authentication. The user registers a passkey via a browser or platform authenticator prompt.

Passkey signers are EVM-only. They are not supported on Solana or Stellar.

React
Node.js

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

const { wallet } = useWallet();

const signer = await wallet.addSigner({
    signer: { type: "passkey" },
});

console.log("Passkey added:", signer.locator);

After adding, activate the passkey for signing:

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

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

const signer = await wallet.addSigner({
    signer: { type: "passkey" },
});

console.log("Passkey added:", signer.locator);

Add an External Wallet Signer

An external wallet signer connects an existing blockchain wallet or keypair — such as MetaMask, Phantom, or a raw keypair — as a signer. When adding an external wallet via addSigner(), only the address is needed (no onSign callback required for registration).

React
Node.js
REST

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

const { wallet } = useWallet();

const signer = await wallet.addSigner({
    signer: {
        type: "external-wallet",
        address: "0x1234...abcd",
    },
});

console.log("External wallet added:", signer.locator);

To use the external wallet for signing, activate it with the full config including onSign:

wallet.useSigner({
    type: "external-wallet",
    address: "0x1234...abcd",
    onSign: async (payload) => {
        // Sign the hex payload with your external wallet
        return await externalWallet.signMessage(payload);
    },
});

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: "base-sepolia",
        signer: {
            type: "server",
            secret: process.env.CROSSMINT_SIGNER_SECRET,
        },
    }
);

const signer = await wallet.addSigner({
    signer: {
        type: "external-wallet",
        address: "0x1234...abcd",
    },
});

console.log("External wallet added:", signer.locator);

Call the register signer endpoint with the external wallet address.

curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/signers \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: <x-api-key>' \
    --data '{
        "chain": "base-sepolia",
        "signer": "external-wallet:0x1234...abcd"
    }'

See the API reference for more details.

Approve the registration

Sign the approval message returned in the response using your recovery signer, then submit the approval. For EVM wallets, use the approve signature endpoint. For Solana and Stellar, use the approve transaction endpoint.

External Wallet `onSign` by Chain

When using an external wallet signer for transactions (via useSigner), the onSign callback receives chain-specific payloads:

Chain	`onSign` Signature	Payload	Expected Return
EVM	`(payload: string) => Promise<string>`	Hex-encoded message	Hex-encoded signature
Solana	`(tx: VersionedTransaction) => Promise<VersionedTransaction>`	Unsigned transaction	Signed transaction
Stellar	`(payload: string) => Promise<string>`	String payload	Signed string

Add a Device Signer on a New Device

When a user accesses their wallet from a new device, the SDK automatically handles device signer creation through the recovery flow. You do not need to call addSigner() manually for this — it happens as part of the recovery process. If you want to trigger recovery before the first transaction:

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

const { wallet } = useWallet();

if (wallet.needsRecovery()) {
    await wallet.recover();
}

List Signers

Retrieve all signers registered on a wallet:

React
Node.js
REST

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

const { wallet } = useWallet();

const signerList = await wallet.signers();
console.log(signerList);

const signerList = await wallet.signers();

for (const s of signerList) {
    console.log(s.type, s.locator, s.status);
}

Fetch the wallet details — signers are included in the response:

curl --request GET \
    --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress> \
    --header 'X-API-KEY: <x-api-key>'

Signer Type Reference

Signer Type	Can Add via `addSigner()`	Chains	Notes
Passkey	Yes	EVM only	Biometric WebAuthn prompt
External wallet	Yes	EVM, Solana, Stellar	Requires `address`; `onSign` needed for transactions
Device	Automatic	EVM, Stellar	Created during recovery flow on new devices
Server	Yes	EVM, Solana, Stellar	Requires `secret`
Email	No	All	Recovery signer only — set at wallet creation
Phone	No	All	Recovery signer only — set at wallet creation

Next Steps

Device Signer

Understand the default client-side signer

Configure Recovery

Set up recovery signers for your wallets

Transfer Tokens

Send tokens from your wallet

Introduction

Quickstarts ⚡️

Concepts

Guides

API Reference

Prerequisites

How It Works

Add a Passkey Signer

Add an External Wallet Signer

External Wallet `onSign` by Chain

Add a Device Signer on a New Device

List Signers

Signer Type Reference

Next Steps

Device Signer

Configure Recovery

Transfer Tokens

Introduction

Quickstarts ⚡️

Concepts

Guides

API Reference

​Prerequisites

​How It Works

​Add a Passkey Signer

​Add an External Wallet Signer

​External Wallet onSign by Chain

​Add a Device Signer on a New Device

​List Signers

​Signer Type Reference

​Next Steps

Device Signer

Configure Recovery

Transfer Tokens

Prerequisites

How It Works

Add a Passkey Signer

Add an External Wallet Signer

External Wallet `onSign` by Chain

Add a Device Signer on a New Device

List Signers

Signer Type Reference

Next Steps