Add Signers to a Wallet

Add signers to an existing wallet — passkeys, external wallets, and device signers.

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:

1. Submits the new signer registration request
2. Temporarily activates the recovery signer to approve the operation
3. 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

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

const { wallet } = useWallet();

const signer = await wallet.addSigner({ 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"
);

Flutter

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

final controller = CrossmintWalletContext.of(context).requireWalletController;
final wallet = controller.createEvmWallet();

// The SDK has no built-in passkey implementation — bridge to the passkey
// plugin of your choice (for example `passkeys` or a native platform
// channel). The SDK invokes your callback whenever a signature is needed.
final passkeyConfig = CrossmintPasskeySignerConfig(
  name: 'My device passkey',
  onCreatePasskey: (name) async {
    // Register a new passkey credential with your plugin and return it
    // as a `CrossmintPasskeyCredential`. Called once when the signer is
    // registered.
    return await YourPasskeyPlugin.create(name);
  },
  onSignWithPasskey: (message) async {
    // Sign `message` with the passkey and return the result as a
    // `CrossmintPasskeySignResult`. Called on every signing operation.
    return await YourPasskeyPlugin.sign(message);
  },
);
final result = await wallet.addSigner(passkeyConfig);
print('Passkey added: ${result.signer.locator}');

Passkey signers require onCreatePasskey and onSignWithPasskey callbacks that bridge to your native passkey plugin. See the Flutter SDK reference for the CrossmintPasskeySignerConfig API. (The EVM-only restriction above applies to all SDKs — passkey signers rely on WebAuthn, which is not supported on Solana or Stellar.)

Node.js

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

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

const signer = await wallet.addSigner({ 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

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

const { wallet } = useWallet();

const signer = await wallet.addSigner({
    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);
    },
});

Flutter

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

final controller = CrossmintWalletContext.of(context).requireWalletController;
final wallet = controller.createEvmWallet();

final result = await wallet.addSigner(
  const CrossmintExternalWalletSignerConfig(address: '0x1234...abcd'),
);
print('External wallet added: ${result.signer.locator}');

To use the external wallet for signing, wrap it with a sign callback via controller.createEvmWalletWithExternalWalletSigner(...).

Node.js

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

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

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

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

REST

1. Register the signer

   Call the register signer endpoint with the external wallet address.

   cURL

   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.

2. 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:

React

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

const { wallet } = useWallet();

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

React Native

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

const { wallet } = useWallet();

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

Flutter

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

final controller = CrossmintWalletContext.of(context).requireWalletController;
final wallet = controller.createEvmWallet();

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

List Signers

To list all signers registered on a wallet, see List Wallet Signers.

Signer Type Reference

Operational Signers

These signers are used for day-to-day transactions and can be listed with wallet.signers().

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

Recovery Signers

Recovery signers approve high-privilege operations (adding new signers, recovery). They cannot be added via addSigner() — they are configured at wallet creation time. Access the recovery signer via wallet.recovery. See Configure Wallet Recovery.

Signer Type	Chains	Notes
Email	All	OTP-based approval
Phone	All	OTP-based approval

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