Overview

Complete reference for Crossmint’s Wallet SDK, Smart Wallet functionality, UI Components, and NFT integration tools

The Crossmint SDK provides a comprehensive set of tools for building NFT experiences. This reference covers both the UI components and core wallet functionality.

Installation

Smart Wallet SDK

React UI Components

Packages Overview

Smart Wallet SDK

For direct wallet operations:

import { SmartWalletSDK } from "@crossmint/client-sdk-smart-wallet";

const smartWalletSDK = SmartWalletSDK.init({
    clientApiKey: "YOUR_CLIENT_API_KEY",
});

React UI Components

For UI components and hooks:

import {
    // Components (no auth required)
    CrossmintNFTCollectionView,
    CrossmintNFTDetail,
    // Auth-required components and hooks
    CrossmintProvider,
    CrossmintAuthProvider,
    useWallet,
} from "@crossmint/client-sdk-react-ui";

Only wallet-related functionality requires Crossmint Authentication. The NFT display components (CrossmintNFTCollectionView and CrossmintNFTDetail) can be used independently. If you need wallet functionality, wrap your application with both providers:

<CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY}>
    <CrossmintAuthProvider>
        <YourApp />
    </CrossmintAuthProvider>
</CrossmintProvider>

Authentication

The Smart Wallet SDK requires JWT Authentication to be enabled. This ensures that wallet operations are securely tied to authenticated users. For detailed information about setting up authentication, see our JWT Authentication Guide.

Smart Wallet SDK

Initialization

const smartWalletSDK = SmartWalletSDK.init({
    clientApiKey: "YOUR_CLIENT_API_KEY",
});

getOrCreateWallet

function

Retrieves or creates a wallet for an authenticated user. Returns a Promise that resolves to an EVMSmartWallet instance.

function getOrCreateWallet(
    user: { jwt: string },
    chain: SmartWalletChain,
    walletParams?: {
        signer: PassKeySigner | ExternalSigner;
    }
): Promise<EVMSmartWallet>;

Show PassKeySigner Configuration

PassKeys provide a secure, passwordless way to sign transactions:

{
    type: "PASSKEY",
    // Optional name shown during PassKey registration/signing
    passkeyName?: string,
    // Called before PassKey registration starts
    onPrePasskeyRegistration?: () => Promise<void>,
    // Handle registration errors
    onPasskeyRegistrationError?: (error: unknown) => Promise<void>,
    // Called before first transaction signing
    onFirstTimePasskeySigning?: () => Promise<void>,
    // Handle first-time signing errors
    onFirstTimePasskeySigningError?: (error: unknown) => Promise<void>
}

Key Benefits:

• Secure biometric authentication (TouchID, FaceID, Windows Hello)
• No exposed private keys
• Device-based security
• Automatic transaction signing prompts

Example usage:

const wallet = await smartWalletSDK.getOrCreateWallet({ jwt: "USER_JWT" }, "polygon", {
    signer: {
        type: "PASSKEY",
        passkeyName: "My Wallet",
    },
});

Providers and Hooks

The React UI components require Crossmint Authentication to work. This section covers the setup needed for the UI components package.

Provider Setup

<CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY}>
    <CrossmintAuthProvider
        embeddedWallets={{
            createOnLogin: "all-users",
            type: "evm-smart-wallet",
            defaultChain: "polygon",
            showPasskeyHelpers: true,
        }}
        appearance={{
            borderRadius: "16px",
            colors: {
                background: "#FAF5EC",
                textPrimary: "#704130",
                accent: "#602C1B",
            },
        }}
        loginMethods={["email", "google", "farcaster", "twitter"]}
    >
        <YourApp />
    </CrossmintAuthProvider>
</CrossmintProvider>

Wallet Creation Approaches

You have two options for wallet creation:

1. Automatic Creation (Recommended)

   <CrossmintAuthProvider
       embeddedWallets={{
           createOnLogin: "all-users",
           type: "evm-smart-wallet",
           defaultChain: "polygon",
       }}
   >
   

   The wallet is automatically created after user authentication. Use useWallet to access the wallet instance.

2. Manual Creation

   <CrossmintAuthProvider
       embeddedWallets={{
           createOnLogin: "off",
           type: "evm-smart-wallet",
           defaultChain: "polygon",
       }}
   >
   

   You’ll need to call getOrCreateWallet explicitly:

   const { getOrCreateWallet } = useWallet();
   
   // Call when needed
   await getOrCreateWallet({
       type: "evm-smart-wallet",
       signer: { type: "PASSKEY" },
   });
   

When using automatic creation (createOnLogin: "all-users"), you don’t need to call getOrCreateWallet manually. The wallet will be available through useWallet after authentication. Note that getOrCreateWallet will either create a new wallet or retrieve an existing one if it was previously created for the same user credentials and project. This means it’s safe to call multiple times - it won’t create duplicate wallets.

Using Hooks

All wallet-related hooks must be used within the providers above. The main hook you’ll use is useWallet:

function WalletStatus() {
    const {
        status, // "not-loaded" | "in-progress" | "loaded"
        wallet, // EVMSmartWallet instance when loaded
        error, // Error information if status is "loading-error"
        getOrCreateWallet,
        clearWallet,
    } = useWallet();

    useEffect(() => {
        if (status === "not-loaded") {
            getOrCreateWallet({
                type: "evm-smart-wallet",
                signer: { type: "PASSKEY" },
            });
        }
    }, [status]);

    if (status === "in-progress") {
        return <div>Loading wallet...</div>;
    }

    if (error) {
        return <div>Error: {error.message}</div>;
    }

    if (!wallet) {
        return <div>No wallet found</div>;
    }

    return (
        <div>
            <p>Wallet Address: {wallet.address}</p>
            <p>Chain: {wallet.chain}</p>
        </div>
    );
}

The useWallet hook must be used within both CrossmintProvider and CrossmintAuthProvider. Components using this hook will only have access to wallets after successful authentication.

UI Components

NFT Collection View

The CrossmintNFTCollectionView component displays NFTs from any wallet or collection in a responsive grid layout.

wallets

Wallet[]

required

List of wallets to display NFTs from:

{
  chain: "ethereum" | "polygon" | "solana",
  publicKey: string
}

uiConfig

UIConfig

Customize the component’s appearance:

{
  colors?: {
      background?: string;
      backgroundSecondary?: string;
      backgroundTertiary?: string;
      textPrimary?: string;
      textSecondary?: string;
      accent?: string;
      border?: string;
      danger?: string;
      textLink?: string;
  };
  fonts?: Array<{
      family: string;
      src?: string;
      cssSrc?: string;
      display?: "auto" | "block" | "swap" | "fallback" | "optional";
      style?: "normal" | "italic" | "oblique";
      weight?: string;
  }>;
  fontSizeBase?: string;
  spacingUnit?: string;
  borderRadius?: string;
  fontWeightPrimary?: string;
  fontWeightSecondary?: string;
}

environment

string

"production" (default) or "staging"

NFT Detail View

The CrossmintNFTDetail component shows detailed information about a specific NFT.

nft

NFTOrNFTLocator

required

NFT identifier as a locator string (recommended) or object:

Example usage with locator:

<CrossmintNFTDetail nft="ethereum:0x123...abc:1" />

uiConfig

UIConfig

Same configuration options as CrossmintNFTCollectionView

environment

string

"production" (default) or "staging"

Smart Wallet

The EVMSmartWallet class provides core blockchain functionality:

address

string

The wallet’s blockchain address

chain

SmartWalletChain

The blockchain network:

type SmartWalletChain =
  // Mainnets
  | "ethereum"
  | "polygon"
  | "optimism"
  | "arbitrum"
  | "base"
  // Testnets
  | "polygon-amoy"
  | "base-sepolia"
  | "optimism-sepolia"
  | "arbitrum-sepolia"

transferToken

function

async function transferToken(
    toAddress: string,
    config: {
        type: "native" | "erc20" | "erc721" | "erc1155";
        amount?: string;
        tokenId?: string;
        contractAddress?: string;
    }
): Promise<string>;

executeContract

function

Executes a smart contract function call. Returns a Promise that resolves to the transaction hash.

async function executeContract({
    address: string,
    abi: Abi,
    functionName: string,
    args: any[],
    value?: bigint,
    config?: SendTransactionOptions
}): Promise<string>;

Example usage:

const abi = [
    {
        inputs: [
            {
                name: "recipient",
                type: "address",
            },
        ],
        name: "mintNFT",
        outputs: [],
        stateMutability: "nonpayable",
        type: "function",
    },
];

await wallet.executeContract({
    address: contractAddress,
    abi,
    functionName: "mintNFT",
    args: [recipientAddress],
});

clearWallet

function

Resets the wallet state and cleans up any associated resources. typescript function clearWallet(): void;

nfts

function

Retrieves all NFTs owned by the wallet on the current chain.

async function nfts(): Promise<NFT[]>;

Show Response Format

The response format varies by chain:

Example usage:

const { wallet } = useWallet();

if (wallet) {
    const nfts = await wallet.nfts();
    console.log(`Found ${nfts.length} NFTs`);

    // Access NFT metadata
    nfts.forEach(nft => {
        console.log(
            `NFT: ${nft.metadata.name}`,
            `Image: ${nft.metadata.image}`
        );
    });
}

Common Patterns

Custom Grid Layout

<div className="grid grid-cols-3 gap-4">
    <CrossmintNFTCollectionView
        wallets={[
            {
                chain: "ethereum",
                publicKey: "0x...",
            },
        ]}
        uiConfig={{
            colors: {
                background: "transparent",
            },
        }}
    />
</div>

Connecting a Wallet

function WalletConnect() {
    const { status, getOrCreateWallet } = useWallet();

    return (
        <button onClick={getOrCreateWallet} disabled={status === "in-progress"}>
            {status === "in-progress" ? "Connecting..." : "Connect Wallet"}
        </button>
    );
}

Transferring NFTs

async function transferNFT(toAddress: string, nft: NFT) {
    const { wallet } = useWallet();

    if (!wallet) return;

    const hash = await wallet.transferToken(toAddress, {
        type: "erc721",
        contractAddress: nft.contractAddress,
        tokenId: nft.tokenId,
    });

    return hash;
}

---

Next Steps

UI Components

Learn about our pre-built UI components for displaying NFTs and wallet information

Client Quickstart

Get started with client-side wallet integration

Server Integration

Learn about server-side wallet management

Talk to an expert

Contact our sales team for support.