CrossmintClient

Final Class Top-level facade for the Crossmint SDK.

final class CrossmintClient

CrossmintClient owns every sub-client (auth, wallets, credentials, orders, tokens, users), the shared transport, the auth session store, and the hidden WebView signer bridge. All sub-clients share a closure that reads the live JWT from auth, so token refresh works without rebuilding the dependency graph.

Lifecycle

Construct the client with a CrossmintClientConfig.
await client.initialize() — validates config and auto-resolves the app ID from platform metadata if not supplied.
await client.auth.restoreSession() — restores any persisted JWT.
Use sub-clients or factory helpers (createWalletController, createEvmWallet, etc.) for the rest of your session.
await client.dispose() when tearing down — shuts down the signer bridges and releases the auth client.

Typical bootstrap

final client = CrossmintClient(
  config: const CrossmintClientConfig(
    apiKey: 'YOUR_STAGING_API_KEY',
    appScheme: 'com.your.app',
  ),
);
await client.initialize();
await client.auth.restoreSession();

final walletController = client.createWalletController(
  const CrossmintWalletControllerConfig(showOtpSignerPrompt: true),
);

Named constructor parameters on the factory (auth, wallets, transport, runtimeOverrides, etc.) are injection points primarily used by tests and advanced integrations. Leave them null in production to get the default HTTP transport, secure-storage-backed auth, and platform-resolved app ID.

Constructors

factory CrossmintClient({
  required CrossmintClientConfig config,
  CrossmintAuthClient? auth,
  CrossmintWalletsClient? wallets,
  CrossmintCredentialsClient? credentials,
  CrossmintOrdersClient? orders,
  CrossmintTokensClient? tokens,
  CrossmintUsersClient? users,
  CrossmintTransport? transport,
  CrossmintAuthLauncher? authLauncher,
  CrossmintClientRuntimeOverrides? runtimeOverrides,
})

Creates a CrossmintClient.

Properties

config

final CrossmintClientConfig config

The configuration this client was built with.

auth

final CrossmintAuthClient auth

Authentication sub-client — email OTP, OAuth, wallet sign-in, session persistence, JWT refresh.

wallets

final CrossmintWalletsClient wallets

Wallet sub-client — create, list, and read Crossmint-hosted wallets (EVM, Solana, Stellar) and their signers.

credentials

final CrossmintCredentialsClient credentials

Verifiable credentials sub-client — issue, query, and verify credentials.

orders

final CrossmintOrdersClient orders

Orders sub-client — checkout orders and mint/purchase flows.

tokens

final CrossmintTokensClient tokens

Tokens sub-client — metadata and balances for tokens held by wallets.

users

final CrossmintUsersClient users

Users sub-client — user profile lookups and updates.

appId

String? get appId

The effective app ID — explicit CrossmintClientConfig.appId if set, otherwise the value auto-resolved from platform metadata during initialize. May be null until initialize has completed.

isInitialized

bool get isInitialized

Whether initialize has completed successfully.

isDisposed

bool get isDisposed

Whether dispose has been called. Once disposed, the client cannot be reused — construct a new one.

hiddenSignerBridgeController

HiddenSignerBridgeRuntimeController get hiddenSignerBridgeController

The shared hidden signer bridge controller, lazily constructed on first access. Powers non-custodial email/phone signing inside a hidden WebView.

authStorage

CrossmintAuthStorage get authStorage

The auth storage adapter resolved during construction — either the one passed via CrossmintClientConfig.authStorage or the default flutter_secure_storage-backed implementation.

transport

CrossmintTransport get transport

The HTTP transport resolved during construction. Shared by every sub-client; injects the live JWT via a closure so token refresh works without rebuilding dependencies.

Methods

createWalletController

CrossmintWalletController createWalletController(
  CrossmintWalletControllerConfig config,
)

Creates a CrossmintWalletController bound to this client.

createHiddenSignerBridge

HiddenSignerBridgeRuntimeController createHiddenSignerBridge({
  HiddenSignerBridgeConfig? config,
})

Builds a new HiddenSignerBridgeRuntimeController instance — used internally by hiddenSignerBridgeController. Override the bridge config to point at a custom signer URL (e.g. for testing).

createExportSignerBridge

CrossmintExportSignerBridgeRuntimeController createExportSignerBridge({
  HiddenSignerBridgeConfig? config,
})

Builds a new CrossmintExportSignerBridgeRuntimeController instance. Used internally by exportSignerBridgeController.

createEvmNonCustodialSigner

CrossmintEvmNonCustodialSigner createEvmNonCustodialSigner({
  required HiddenSignerBridge bridge,
  required String signerType,
  required String signerLocator,
  String? address,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})

Builds a non-custodial EVM signer bound to an existing HiddenSignerBridge. Produces secp256k1 signatures inside the WebView without exposing keys to Dart.

createSolanaNonCustodialSigner

CrossmintSolanaNonCustodialSigner createSolanaNonCustodialSigner({
  required HiddenSignerBridge bridge,
  required String signerType,
  required String signerLocator,
  String? address,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})

Builds a non-custodial Solana signer bound to an existing HiddenSignerBridge. Produces ed25519 signatures inside the WebView.

createStellarNonCustodialSigner

CrossmintStellarNonCustodialSigner createStellarNonCustodialSigner({
  required HiddenSignerBridge bridge,
  required String signerType,
  required String signerLocator,
  String? address,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})

Builds a non-custodial Stellar signer bound to an existing HiddenSignerBridge. Produces ed25519 signatures inside the WebView.

createEvmWallet

CrossmintEvmWallet createEvmWallet({
  required CrossmintWallet wallet,
  CrossmintSignerConfig? recoverySigner,
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
  DeviceSignerKeyStorage? deviceSignerKeyStorage,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})

Wraps a server-issued CrossmintWallet in a runtime CrossmintEvmWallet.

createSolanaWallet

CrossmintSolanaWallet createSolanaWallet({
  required CrossmintWallet wallet,
  CrossmintSignerConfig? recoverySigner,
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
  DeviceSignerKeyStorage? deviceSignerKeyStorage,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})

Wraps a server-issued CrossmintWallet in a runtime CrossmintSolanaWallet.

createStellarWallet

CrossmintStellarWallet createStellarWallet({
  required CrossmintWallet wallet,
  CrossmintSignerConfig? recoverySigner,
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
  DeviceSignerKeyStorage? deviceSignerKeyStorage,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})

Wraps a server-issued CrossmintWallet in a runtime CrossmintStellarWallet.

createDeviceWalletSigner

CrossmintDeviceWalletSigner createDeviceWalletSigner({
  required String signerLocator,
  required String address,
  DeviceSignerKeyStorage? storage,
})

Builds a hardware-backed device signer for an existing server signer.

createEvmExternalWalletSigner

CrossmintEvmExternalWalletSigner createEvmExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})

Builds an external-wallet EVM signer that delegates to a user-supplied CrossmintExternalWalletSignCallback. Use for wallets owned by the user (e.g. MetaMask, Rainbow) where the SDK only needs to request signatures.

createSolanaExternalWalletSigner

CrossmintSolanaExternalWalletSigner createSolanaExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})

Builds an external-wallet Solana signer that delegates to a user-supplied CrossmintExternalWalletSignCallback.

createStellarExternalWalletSigner

CrossmintStellarExternalWalletSigner createStellarExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})

Builds an external-wallet Stellar signer that delegates to a user-supplied CrossmintExternalWalletSignCallback.

createPasskeyApprovalSigner

CrossmintPasskeyApprovalSigner createPasskeyApprovalSigner({
  required String credentialId,
  required String signerLocator,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})

Builds a passkey approval signer. The caller provides onSign — a callback that performs the WebAuthn / platform-native passkey assertion and returns a CrossmintPasskeySignResult. Native platform passkey support is pending (Stage 2); today every passkey signer requires an explicit callback or CrossmintSignerException(code: passkeyCallbackMissing) is thrown during signing.

dispose

Future<void> dispose()

Releases the signer bridges and auth client, then marks the client as disposed. Safe to call multiple times. After disposal, construct a new CrossmintClient rather than reusing this one.

initialize

Future<void> initialize()

Validates configuration and prepares the client for use.

Introduction

Quickstarts ⚡️

Concepts

Guides

API Reference

Documentation Index

​Lifecycle

​Typical bootstrap

​Constructors