External Wallet Signer

Configure an external wallet or keypair as a signer at wallet creation.

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

Use an external wallet signer to connect an existing blockchain wallet or raw keypair — such as MetaMask, Phantom, or a backend keypair — as an operational signer on a Crossmint smart wallet. This is the right choice when your users already have a wallet they want to use to control a Crossmint smart wallet.

Supported on EVM, Solana, and Stellar.

Configuration

Configure the wallet with an external wallet as the operational signer at creation time. The address is the public address of the external wallet.

React

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"]}>
                <CrossmintWalletProvider
                    createOnLogin={{
                        chain: "base-sepolia",
                        recovery: { type: "email" },
                        signers: [{
                            type: "external-wallet",
                            address: "0x1234...abcd",
                        }],
                    }}
                >
                    {children}
                </CrossmintWalletProvider>
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}

Or create the wallet explicitly:

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

const { createWallet } = useWallet();

const wallet = await createWallet({
    chain: "base-sepolia",
    recovery: { type: "email", email: "[e-mail]" },
    signers: [{
        type: "external-wallet",
        address: "0x1234...abcd",
    }],
});

Node.js

import { CrossmintWallets, createCrossmint } 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",
    recovery: { type: "email", email: "[e-mail]" },
    signers: [{
        type: "external-wallet",
        address: "0x1234...abcd",
    }],
});

Signing Transactions

External wallet signing requires an onSign callback. Before sending transactions, activate the signer with the full config:

wallet.useSigner({
    type: "external-wallet",
    address: "0x1234...abcd",
    onSign: async (payload) => {
        // EVM: payload is a hex-encoded message; return a hex-encoded signature
        // Solana: payload is a VersionedTransaction; return the signed transaction
        // Stellar: payload is a string; return a signed string
        return await externalWallet.signMessage(payload);
    },
});

const { hash } = await wallet.send(
    "0xRecipientAddress",
    "usdc",
    "10"
);

See Add Signers — External Wallet onSign by Chain for chain-specific onSign signatures and return values.

Adding an External Wallet to an Existing Wallet

If the wallet already exists with a different signer, you can register an external wallet via wallet.addSigner({ type: "external-wallet", address }). See Add Signers for the full flow.

Next Steps

Add Signers

Register additional signers on an existing wallet

Configure Recovery

Set up email or phone recovery

Device Signer

The default client-side signer