> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Signers to a Wallet

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

Use `addSigner()` to register additional operational signers on an existing wallet. One of the wallet's recovery methods must approve the operation — the SDK handles this automatically. A wallet with several recovery methods needs one selected with `useRecoveryMethod()` first; see [Manage Recovery Methods](https://docs.crossmint.com/wallets/guides/recovery/manage-recovery-methods.md#select-the-authorizing-recovery-method).

## Prerequisites

* An existing wallet with a recovery method 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 method to approve the operation
3. After approval, restores the previously active signer

For client-side wallets with an email or phone recovery method, your user enters a one-time code to approve the new signer. When a server signer is the recovery method, approval happens automatically.

> [!NOTE]
>
> A wallet can have up to 16 signers, counting recovery methods and operational signers together. When a wallet is at the limit, adding a new signer fails with HTTP 400 and the error code `SIGNER_LIMIT_EXCEEDED`. Re-adding a signer that is already on the wallet does not use another slot. [Remove a signer](https://docs.crossmint.com/wallets/guides/signers/remove-signer.md) to free a slot. See [Add and Remove Signers](https://docs.crossmint.com/wallets/concepts/signers.md#add-and-remove-signers) for how the limit is counted.

### Installation Timing

A signer must be installed onchain before it can sign. You can control when this happens. Set the `deployImmediately` option on `addSigner()`:

* Set `deployImmediately: true` to install the signer immediately. The recovery method approves an onchain registration transaction. The signer is ready to sign after that transaction confirms.
* Set `deployImmediately: false` to install the signer later. Registration records a signature request. The signer is installed on its first transaction.

```typescript theme={null}
const signer = await wallet.addSigner(
    { type: "external-wallet", address: "0x1234...abcd" },
    { deployImmediately: false }
);
```

When you use `prepareOnly: true`, the return value shows which approval endpoint to use. Approve a `transactionId` with the [approve transaction](https://docs.crossmint.com/api-reference/wallets/approve-transaction.md) endpoint. Approve a `signatureId` with the [approve signature](https://docs.crossmint.com/api-reference/wallets/approve-signature.md) endpoint.

This option is currently available on EVM through the TypeScript SDK, which installs the signer immediately by default. Solana and Stellar always install signers with an onchain transaction.

If you want to add restrictions to the signer (such as spending limits, recipient whitelists, or an expiry), see [Restrict a Signer with Scopes](https://docs.crossmint.com/wallets/guides/signers/scopes.md).

## 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.

> [!NOTE]
>
> Passkey signers are supported on EVM, Solana, and Stellar. In React Native, configure the `passkeys` prop first; see [Passkey Signer](https://docs.crossmint.com/wallets/guides/signers/passkey.md).

> [tab] React
>
> ```typescript theme={null}
> 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:
>
> ```typescript theme={null}
> wallet.useSigner({ type: "passkey" });
>
> const { hash } = await wallet.send(
>     "0xRecipientAddress",
>     "usdc",
>     "10"
> );
> ```

> [tab] Node.js
>
> ```typescript theme={null}
> 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);
> ```

> [tab] Swift
>
> ```swift theme={null}
> import CrossmintClient
>
> @MainActor
> func addPasskeySigner() async throws {
>     guard let wallet = try await CrossmintSDK.shared.crossmintWallets.getWallet(
>         chain: EVMChain.baseSepolia
>     ) else { return }
>
>     let passkey = SignerConfig.passkey(name: "user@example.com", host: "app.example.com")
>     try await wallet.addSigner(passkey)
>     try await wallet.useSigner(passkey)
> }
> ```
>
> The SDK shows the system prompt to create the passkey. This example needs a configured SDK, a signed-in user and an existing wallet; see the [Swift quickstart](https://docs.crossmint.com/wallets/quickstarts/swift.md). Set up the associated domain first; see [Passkey Signer](https://docs.crossmint.com/wallets/guides/signers/passkey.md).

> [tab] Kotlin
>
> ```kotlin theme={null}
> import android.app.Activity
> import androidx.credentials.CredentialManager
> import com.crossmint.kotlin.CrossmintSDK
> import com.crossmint.kotlin.passkeys.createPasskeyCredential
> import com.crossmint.kotlin.passkeys.useSigner
> import com.crossmint.kotlin.signers.DelegatedSigner
> import com.crossmint.kotlin.types.EVMChain
> import com.crossmint.kotlin.types.getOrThrow
>
> suspend fun addPasskeySigner(activity: Activity) {
>     val wallet = CrossmintSDK.shared.wallets.getWallet(chain = EVMChain.BaseSepolia).getOrThrow()
>     val credentialManager = CredentialManager.create(activity)
>     val credential = createPasskeyCredential(
>         name = "user@example.com",
>         activityProvider = { activity },
>         credentialManager = credentialManager,
>         rpId = "app.example.com",
>         rpName = "Example",
>     ) ?: return
>     val passkey = DelegatedSigner.Passkey(
>         id = credential.id,
>         name = credential.name,
>         publicKeyX = credential.publicKeyX,
>         publicKeyY = credential.publicKeyY,
>     )
>
>     wallet.addSigner(passkey).getOrThrow()
>     wallet.useSigner(passkey, credentialManager, { activity }, rpId = "app.example.com").getOrThrow()
> }
> ```
>
> This example needs a configured SDK, a signed-in user and an existing wallet; see the [Kotlin quickstart](https://docs.crossmint.com/wallets/quickstarts/kotlin.md). Passkey signers also need the `sdk-passkeys` module and an `assetlinks.json` file on the `rpId` domain; see [Passkey Signer](https://docs.crossmint.com/wallets/guides/signers/passkey.md).

> [tab] Flutter
>
> ```dart theme={null}
> 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](https://docs.crossmint.com/sdk-reference/wallets/flutter/controllers.md#wallet-methods)
> for the `CrossmintPasskeySignerConfig` API.

## 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).

> [tab] React
>
> ```typescript theme={null}
> 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`:
>
> ```typescript theme={null}
> wallet.useSigner({
>     type: "external-wallet",
>     address: "0x1234...abcd",
>     onSign: async (payload) => {
>         // Sign the hex payload with your external wallet
>         return await externalWallet.signMessage(payload);
>     },
> });
> ```

> [tab] Flutter
>
> ```dart theme={null}
> 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(...)`.

> [tab] Node.js
>
> ```typescript theme={null}
> 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);
> ```

> [tab] REST
>
> **1. Register the signer**
>
> Call the register signer endpoint with the external wallet address. By default, the EVM endpoint returns a deferred signature. To get an onchain transaction immediately, set `deployImmediately: true` in the request body.
>
> ```bash cURL theme={null}
> 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"
>     }'
> ```
>
> ```js Node.js theme={null}
> const url =
>     "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/signers";
>
> const payload = {
>     chain: "base-sepolia",
>     signer: "external-wallet:0x1234...abcd",
> };
>
> const response = await fetch(url, {
>     method: "POST",
>     headers: {
>         "X-API-KEY": "<x-api-key>",
>         "Content-Type": "application/json",
>     },
>     body: JSON.stringify(payload),
> });
>
> const data = await response.json();
> console.log(data);
> ```
>
> ```python Python theme={null}
> import requests
>
> url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/signers"
>
> payload = {
>     "chain": "base-sepolia",
>     "signer": "external-wallet:0x1234...abcd"
> }
> headers = {
>     "X-API-KEY": "<x-api-key>",
>     "Content-Type": "application/json"
> }
>
> response = requests.post(
>     url, json=payload, headers=headers
> )
> print(response.json())
> ```
>
> See the [API reference](https://docs.crossmint.com/api-reference/wallets/register-delegated-key.md) for more details.
>
> **2. Approve the registration**
>
> Sign the approval message returned in the response using your recovery method, then submit the approval. The EVM endpoint defaults to the deferred signature flow, so use the [approve signature](https://docs.crossmint.com/api-reference/wallets/approve-signature.md) endpoint. If you passed `deployImmediately: true` in the request, the response contains a transaction and you must use the [approve transaction](https://docs.crossmint.com/api-reference/wallets/approve-transaction.md) endpoint. For Solana and Stellar, the response is always a transaction and uses the [approve transaction](https://docs.crossmint.com/api-reference/wallets/approve-transaction.md) 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](https://docs.crossmint.com/wallets/guides/signers/device-signer.md#new-device-recovery). 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:

> [tab] React
>
> ```typescript theme={null}
> import { useWallet } from "@crossmint/client-sdk-react-ui";
>
> const { wallet } = useWallet();
>
> if (wallet.needsRecovery()) {
>     await wallet.recover();
> }
> ```

> [tab] React Native
>
> ```typescript theme={null}
> import { useWallet } from "@crossmint/client-sdk-react-native-ui";
>
> const { wallet } = useWallet();
>
> if (wallet.needsRecovery()) {
>     await wallet.recover();
> }
> ```

> [tab] Flutter
>
> ```dart theme={null}
> 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](https://docs.crossmint.com/wallets/guides/signers/list-signers.md).

## Signer Type Reference

For the full capability matrix, see [Signers](https://docs.crossmint.com/wallets/concepts/signers.md#capability-matrix).

These signers are used for day-to-day transactions and can be listed with [`wallet.signers()`](https://docs.crossmint.com/wallets/guides/signers/list-signers).

| Signer Type | Can Add via `addSigner()` | Chains | Notes |
| - | - | - | - |
| Passkey | Yes | EVM, Solana, Stellar | Biometric WebAuthn prompt |
| External wallet | Yes | EVM, Solana, Stellar | Requires `address`; `onSign` needed for transactions |
| Device | Automatic | EVM, Solana, Stellar | Created during recovery flow on new devices |
| Server | Yes | EVM, Solana, Stellar | Requires `secret` |
| Email | Yes | All | OTP-based |
| Phone | Yes | All | OTP-based |

## Next Steps

> [card] [Device Signer](https://docs.crossmint.com/wallets/guides/signers/device-signer.md)
>
> Understand the default client-side signer

> [card] [Configure Recovery](https://docs.crossmint.com/wallets/guides/recovery/configure-recovery.md)
>
> Set up recovery methods for your wallets

> [card] [Transfer Tokens](https://docs.crossmint.com/wallets/guides/transfer-tokens.md)
>
> Send tokens from your wallet
