Controllers

Flutter controllers for the Flutter SDK reference for Crossmint wallets

The Flutter SDK uses ChangeNotifier-based controllers instead of React hooks. Controllers can be used directly (headless) or accessed through the widget tree via providers.

---

CrossmintClient

The top-level facade for the Crossmint SDK. Provides access to auth, wallets, and all sub-clients.

Properties

config · CrossmintClientConfig

The configuration this client was built with.

Show properties

authStorage · CrossmintAuthStorage?

Custom session / token store. When null, the SDK uses FlutterSecureStorage under the hood.

logger · CrossmintLogger?

Custom logger sink. When null, the SDK writes no logs.

refreshRoute · Uri?

Optional custom server endpoint for token refresh.

logoutRoute · Uri?

Optional custom server endpoint for logout.

auth · CrossmintAuthClient

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

wallets · CrossmintWalletsClient

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

credentials · CrossmintCredentialsClient

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

orders · CrossmintOrdersClient

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

tokens · CrossmintTokensClient

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

users · CrossmintUsersClient

Users sub-client — user profile lookups and updates.

appId · String?

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

Whether [initialize] has completed successfully.

isDisposed · bool

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

hiddenSignerBridgeController · HiddenSignerBridgeRuntimeController

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

Show properties

config · HiddenSignerBridgeConfig · required

Show properties

uri · Uri · required

javaScriptChannelName · String

dispatchScriptBuilder · HiddenSignerDispatchScriptBuilder

handshakeSignal · String

handshakeTimeout · Duration

requestTimeout · Duration

allowedOrigins · Set<String>

authStorage · CrossmintAuthStorage

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

transport · CrossmintTransport

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(config) · CrossmintWalletController

Creates a [CrossmintWalletController] bound to this client.

Show parameters

config · CrossmintWalletControllerConfig · required

createHiddenSignerBridge(config) · HiddenSignerBridgeRuntimeController

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

Show parameters

config · HiddenSignerBridgeConfig?

createExportSignerBridge(config) · CrossmintExportSignerBridgeRuntimeController

Builds a new [CrossmintExportSignerBridgeRuntimeController] instance. Used internally by [exportSignerBridgeController].

Show parameters

config · HiddenSignerBridgeConfig?

createEvmNonCustodialSigner(bridge, signerType, signerLocator, address, onAuthRequired, channel) · CrossmintEvmNonCustodialSigner

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

Show parameters

bridge · HiddenSignerBridge · required

signerType · String · required

signerLocator · String · required

address · String?

onAuthRequired · CrossmintSignerAuthRequiredCallback?

channel · CrossmintOtpDeliveryChannel?

createSolanaNonCustodialSigner(bridge, signerType, signerLocator, address, onAuthRequired, channel) · CrossmintSolanaNonCustodialSigner

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

Show parameters

bridge · HiddenSignerBridge · required

signerType · String · required

signerLocator · String · required

address · String?

onAuthRequired · CrossmintSignerAuthRequiredCallback?

channel · CrossmintOtpDeliveryChannel?

createStellarNonCustodialSigner(bridge, signerType, signerLocator, address, onAuthRequired, channel) · CrossmintStellarNonCustodialSigner

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

Show parameters

bridge · HiddenSignerBridge · required

signerType · String · required

signerLocator · String · required

address · String?

onAuthRequired · CrossmintSignerAuthRequiredCallback?

channel · CrossmintOtpDeliveryChannel?

createEvmWallet(wallet, recoverySigner, signer, additionalSigners, deviceSignerKeyStorage, onAuthRequired) · CrossmintEvmWallet

Wraps a server-issued [CrossmintWallet] in a runtime [CrossmintEvmWallet].

Show parameters

wallet · CrossmintWallet · required

recoverySigner · CrossmintSignerConfig?

signer · CrossmintWalletApprovalSigner?

additionalSigners · List<CrossmintWalletApprovalSigner>

deviceSignerKeyStorage · DeviceSignerKeyStorage?

onAuthRequired · CrossmintSignerAuthRequiredCallback?

createSolanaWallet(wallet, recoverySigner, signer, additionalSigners, deviceSignerKeyStorage, onAuthRequired) · CrossmintSolanaWallet

Wraps a server-issued [CrossmintWallet] in a runtime [CrossmintSolanaWallet].

Show parameters

wallet · CrossmintWallet · required

recoverySigner · CrossmintSignerConfig?

signer · CrossmintWalletApprovalSigner?

additionalSigners · List<CrossmintWalletApprovalSigner>

deviceSignerKeyStorage · DeviceSignerKeyStorage?

onAuthRequired · CrossmintSignerAuthRequiredCallback?

createStellarWallet(wallet, recoverySigner, signer, additionalSigners, deviceSignerKeyStorage, onAuthRequired) · CrossmintStellarWallet

Wraps a server-issued [CrossmintWallet] in a runtime [CrossmintStellarWallet].

Show parameters

wallet · CrossmintWallet · required

recoverySigner · CrossmintSignerConfig?

signer · CrossmintWalletApprovalSigner?

additionalSigners · List<CrossmintWalletApprovalSigner>

deviceSignerKeyStorage · DeviceSignerKeyStorage?

onAuthRequired · CrossmintSignerAuthRequiredCallback?

createDeviceWalletSigner(signerLocator, address, storage) · CrossmintDeviceWalletSigner

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

Show parameters

signerLocator · String · required

address · String · required

storage · DeviceSignerKeyStorage?

createEvmExternalWalletSigner(address, signerLocator, onSign) · CrossmintEvmExternalWalletSigner

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.

Show parameters

address · String · required

signerLocator · String?

onSign · CrossmintExternalWalletSignCallback · required

createSolanaExternalWalletSigner(address, signerLocator, onSign) · CrossmintSolanaExternalWalletSigner

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

Show parameters

address · String · required

signerLocator · String?

onSign · CrossmintExternalWalletSignCallback · required

createStellarExternalWalletSigner(address, signerLocator, onSign) · CrossmintStellarExternalWalletSigner

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

Show parameters

address · String · required

signerLocator · String?

onSign · CrossmintExternalWalletSignCallback · required

createPasskeyApprovalSigner(credentialId, signerLocator, onSign) · CrossmintPasskeyApprovalSigner

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.

Show parameters

credentialId · String · required

signerLocator · String · required

onSign · Future<CrossmintPasskeySignResult> Function(String message) · required

dispose() · Future<void>

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>

Validates configuration and prepares the client for use.

Usage

import 'package:crossmint_flutter/crossmint_client.dart';

final client = CrossmintClient(
  config: CrossmintClientConfig(
    apiKey: 'YOUR_CLIENT_API_KEY',
    appScheme: 'myapp',
  ),
);

await client.initialize();
await client.auth.restoreSession();

---

CrossmintAuthClient

Manages authentication state and login flows. Exposes state via ValueListenable and Stream for reactive UI updates. Use setJwt() to provide your own JWT when not using the built-in auth flows.

Properties

state · CrossmintAuthState

The current auth state snapshot.

stateListenable · ValueListenable<CrossmintAuthState>

Reactive handle on [state] — suitable for [ValueListenableBuilder].

states · Stream<CrossmintAuthState>

Stream of auth-state changes. Emits on every state mutation.

Methods

restoreSession() · Future<void>

Reads any persisted session from [CrossmintAuthStorage] and applies it to the client. Safe to call once per app launch — prefer using the result of CrossmintClient.initialize which calls this internally.

loginWithOAuth(provider) · Future<void>

Opens the Crossmint-hosted OAuth flow for [provider] (Google, Twitter, etc.). The response comes back through [CrossmintAuthCallbackRouter] — make sure it is started before calling this.

Show parameters

provider · CrossmintOAuthProvider · required

sendEmailOtp(email) · Future<CrossmintEmailOtpChallenge>

Requests the Crossmint API to send an email OTP to [email]. Returns a challenge that [confirmEmailOtp] completes.

Show parameters

email · String · required

confirmEmailOtp(email, emailId, token) · Future<bool>

Submits an email OTP challenge — pass the emailId from the challenge and the token the user entered. Returns true on success.

Show parameters

email · String · required

emailId · String · required

token · String · required

completeOAuth(callbackUri) · Future<bool>

Completes an OAuth flow from a deep-link callback URI. This method accepts any link, also one from a login that the app did not start. For custom link routing, use [completePendingOAuth].

Show parameters

callbackUri · Uri · required

completePendingOAuth(callbackUri) · Future<bool>

Completes an OAuth flow from a deep-link callback URI only when it belongs to a login that [loginWithOAuth] started. Returns false and ignores the link when its scheme is not the app scheme or when no login is pending. [CrossmintAuthCallbackRouter] uses this for incoming links.

Show parameters

callbackUri · Uri · required

completeOAuthWithOneTimeSecret(oneTimeSecret) · Future<bool>

Completes an OAuth flow from a one-time secret (SSR / server-mediated callbacks). Returns true on success.

Show parameters

oneTimeSecret · String · required

signInWithWallet(address, type) · Future<CrossmintWalletAuthChallenge>

Starts wallet-based authentication. Returns a challenge that the wallet must sign. [type] is 'evm' or 'solana'.

Show parameters

address · String · required

type · String · required

authenticateWallet(address, type, signature) · Future<bool>

Completes wallet-based authentication with the signed challenge.

Show parameters

address · String · required

type · String · required

signature · String · required

getSession() · Future<CrossmintAuthSession?>

Returns the current session (JWT + metadata), or null if not signed in. Does not hit the network — reads from in-memory state.

getUser(forceRefresh) · Future<CrossmintAuthenticatedUser?>

Returns the authenticated user’s profile. Caches the result; pass forceRefresh: true to bypass the cache and refetch.

Show parameters

forceRefresh · bool

logout() · Future<void>

Signs the user out — clears persisted storage, cached session/user, and POSTs to the Crossmint (or custom) logout endpoint.

setJwt(jwt) · Future<void>

Sets a custom JWT for “Bring Your Own Auth” (BYOA) flows.

Show parameters

jwt · String? · required

Usage

import 'package:crossmint_flutter/crossmint_flutter_auth.dart';

client.auth.stateListenable.addListener(() {
  print('Auth state: ${client.auth.state}');
});

final challenge = await client.auth.sendEmailOtp('YOUR_USER_EMAIL');
await client.auth.confirmEmailOtp(
  email: 'YOUR_USER_EMAIL',
  emailId: challenge.id,
  token: 'YOUR_OTP_CODE',
);

await client.auth.loginWithOAuth(CrossmintOAuthProvider.google);

await client.auth.logout();

---

CrossmintWalletController

Manages wallet lifecycle — creation, loading, signing, and OTP flows. Extends ChangeNotifier for reactive UI updates.

Properties

client · CrossmintClient

The underlying client — exposed for code that needs direct access to sub-clients (auth, orders, credentials, etc.).

Show properties

config · CrossmintClientConfig · required

Show properties

authStorage · CrossmintAuthStorage?

Custom session / token store. When null, the SDK uses FlutterSecureStorage under the hood.

logger · CrossmintLogger?

Custom logger sink. When null, the SDK writes no logs.

refreshRoute · Uri?

Optional custom server endpoint for token refresh.

logoutRoute · Uri?

Optional custom server endpoint for logout.

auth · CrossmintAuthClient?

wallets · CrossmintWalletsClient?

credentials · CrossmintCredentialsClient?

orders · CrossmintOrdersClient?

tokens · CrossmintTokensClient?

users · CrossmintUsersClient?

transport · CrossmintTransport?

authLauncher · CrossmintAuthLauncher?

runtimeOverrides · CrossmintClientRuntimeOverrides?

Show properties

authStorage · CrossmintAuthStorage?

logger · CrossmintLogger?

config · CrossmintWalletControllerConfig

The configuration this controller was built with.

Show properties

createOnLogin · CrossmintCreateOnLoginConfig?

When set, the controller automatically creates (or loads) a wallet on the given chain once the user is authenticated. Fill recovery with the recovery signer config (e.g. CrossmintEmailSignerConfig()).

showOtpSignerPrompt · bool

Whether the SDK should surface the default OTP prompt automatically. Set to false to drive OTP UI yourself by listening to [CrossmintWalletController.otp].

callbacks · CrossmintWalletLifecycleCallbacks?

Optional lifecycle hooks — see [CrossmintWalletLifecycleCallbacks].

Show properties

onWalletCreationStart · Future<void> Function()?

Called immediately before the controller issues a createWallet API call. Await the returned future to block the operation until your UI is ready.

onTransactionStart · Future<void> Function()?

Called immediately before the controller issues a create-transaction API call. Await to block until your UI is ready.

deviceSignerKeyStorage · DeviceSignerKeyStorage?

Storage adapter used to persist device-signer keys. Defaults to a secure-enclave / keystore-backed implementation on device.

otp · CrossmintWalletOtpController

OTP controller for non-custodial email/phone signer challenges.

state · CrossmintWalletStateView

Read-only observation surface for the underlying wallet state. Advanced consumers can subscribe to wallet / status changes directly via this [Listenable] while still routing all mutations through the controller’s public API (getWallet, createWallet, refresh, clear, …).

currentWallet · CrossmintWallet?

The currently-loaded wallet, or null if none is loaded.

Show properties

id · String · required

chain · String?

address · String?

owner · String?

raw · CrossmintJsonMap

status · CrossmintWalletStatus

Current wallet lifecycle status.

onAuthRequired · CrossmintWalletAuthRequiredCallback

The auth-required callback the controller wires into every signer it builds. Exposed so apps building signers manually can share the same OTP-handling path.

pendingOtpChallenge · CrossmintOtpChallenge?

Shortcut to [CrossmintWalletOtpController.pendingChallenge].

Show properties

signerType · String · required

signerLocator · String · required

otpChallengeListenable · ValueListenable<CrossmintOtpChallenge?>

Shortcut to [CrossmintWalletOtpController.challengeListenable].

requireCurrentWallet · CrossmintWallet

Returns the currently-loaded wallet or throws [CrossmintWalletException] when none is loaded.

Show properties

id · String · required

chain · String?

address · String?

owner · String?

raw · CrossmintJsonMap

Methods

getWallet(request) · Future<CrossmintWallet?>

Looks up an existing wallet and stores the result in controller state. Returns null when no wallet matches. Listeners fire on state changes.

Show parameters

request · CrossmintWalletLookupRequest · required

loadWallet(request) · Future<CrossmintWallet?>

Deprecated: use [getWallet] instead.

Show parameters

request · CrossmintWalletLookupRequest · required

createWallet(request) · Future<CrossmintWallet>

Creates a new wallet and stores it in controller state. Validates passkey signers up-front via [crossmintValidatePasskeySigners] and fires [CrossmintWalletLifecycleCallbacks.onWalletCreationStart] if set.

Show parameters

request · CrossmintWalletCreateRequest · required

ensureLoaded() · Future<CrossmintWallet?>

Ensures a wallet is loaded, creating one if configured to do so.

refresh() · Future<CrossmintWallet?>

Re-fetches the currently-loaded wallet from the API. Returns null when nothing is loaded.

clear() · Future<void>

Drops the loaded wallet and any pending OTP challenge. Call during sign-out.

sendOtp() · Future<void>

Shortcut to [CrossmintWalletOtpController.sendOtp].

verifyOtp(otpCode) · Future<void>

Shortcut to [CrossmintWalletOtpController.verifyOtp].

Show parameters

otpCode · String · required

rejectOtp() · void

Shortcut to [CrossmintWalletOtpController.reject].

createEvmWallet(signer, additionalSigners, recoverySigner) · CrossmintEvmWallet

Wraps the currently-loaded wallet as a runtime [CrossmintEvmWallet]. Throws [CrossmintWalletException] if no wallet is loaded.

Show parameters

signer · CrossmintWalletApprovalSigner?

additionalSigners · List<CrossmintWalletApprovalSigner>

recoverySigner · CrossmintSignerConfig?

createSolanaWallet(signer, additionalSigners, recoverySigner) · CrossmintSolanaWallet

Wraps the currently-loaded wallet as a runtime [CrossmintSolanaWallet]. On Solana, device signer support depends on the wallet type and is validated server-side. A default device signer is not auto-injected for Solana; it is registered reactively and falls back to the recovery signer when the server rejects it.

Show parameters

signer · CrossmintWalletApprovalSigner?

additionalSigners · List<CrossmintWalletApprovalSigner>

recoverySigner · CrossmintSignerConfig?

createStellarWallet(signer, additionalSigners, recoverySigner) · CrossmintStellarWallet

Wraps the currently-loaded wallet as a runtime [CrossmintStellarWallet].

Show parameters

signer · CrossmintWalletApprovalSigner?

additionalSigners · List<CrossmintWalletApprovalSigner>

recoverySigner · CrossmintSignerConfig?

createEvmWalletWithDeviceSigner(signerLocator, address, storage, recoverySigner) · CrossmintEvmWallet

Builds a runtime EVM wallet backed by a hardware-backed device signer. Use for low-friction, day-to-day signing with keys in Secure Enclave / Android Keystore.

Show parameters

signerLocator · String · required

address · String?

storage · DeviceSignerKeyStorage?

recoverySigner · CrossmintSignerConfig?

createEvmWalletWithNonCustodialSigner(signerType, signerLocator, address, bridge, channel, recoverySigner) · CrossmintEvmWallet

Builds a runtime EVM wallet backed by a non-custodial email/phone signer. Requires [CrossmintWalletHost] (or CrossmintWalletProvider) mounted in the widget tree.

Show parameters

signerType · String · required

signerLocator · String · required

address · String?

bridge · HiddenSignerBridge?

channel · CrossmintOtpDeliveryChannel?

recoverySigner · CrossmintSignerConfig?

createSolanaWalletWithNonCustodialSigner(signerType, signerLocator, address, bridge, channel, recoverySigner) · CrossmintSolanaWallet

Builds a runtime Solana wallet backed by a non-custodial email/phone signer. Requires a mounted wallet host.

Show parameters

signerType · String · required

signerLocator · String · required

address · String?

bridge · HiddenSignerBridge?

channel · CrossmintOtpDeliveryChannel?

recoverySigner · CrossmintSignerConfig?

createStellarWalletWithNonCustodialSigner(signerType, signerLocator, address, bridge, channel, recoverySigner) · CrossmintStellarWallet

Builds a runtime Stellar wallet backed by a non-custodial email/phone signer. Requires a mounted wallet host.

Show parameters

signerType · String · required

signerLocator · String · required

address · String?

bridge · HiddenSignerBridge?

channel · CrossmintOtpDeliveryChannel?

recoverySigner · CrossmintSignerConfig?

createStellarWalletWithDeviceSigner(signerLocator, address, storage, recoverySigner) · CrossmintStellarWallet

Builds a runtime Stellar wallet backed by a hardware device signer.

Show parameters

signerLocator · String · required

address · String?

storage · DeviceSignerKeyStorage?

recoverySigner · CrossmintSignerConfig?

createEvmWalletWithExternalWalletSigner(address, signerLocator, onSign, recoverySigner) · CrossmintEvmWallet

Builds a runtime EVM wallet backed by a user-owned external wallet (e.g. MetaMask). The caller supplies [onSign] to perform signatures.

Show parameters

address · String · required

signerLocator · String?

onSign · CrossmintExternalWalletSignCallback · required

recoverySigner · CrossmintSignerConfig?

createSolanaWalletWithExternalWalletSigner(address, signerLocator, onSign, recoverySigner) · CrossmintSolanaWallet

Builds a runtime Solana wallet backed by a user-owned external wallet.

Show parameters

address · String · required

signerLocator · String?

onSign · CrossmintExternalWalletSignCallback · required

recoverySigner · CrossmintSignerConfig?

createStellarWalletWithExternalWalletSigner(address, signerLocator, onSign, recoverySigner) · CrossmintStellarWallet

Builds a runtime Stellar wallet backed by a user-owned external wallet.

Show parameters

address · String · required

signerLocator · String?

onSign · CrossmintExternalWalletSignCallback · required

recoverySigner · CrossmintSignerConfig?

createEvmWalletWithPasskeySigner(id, onSign, recoverySigner) · CrossmintEvmWallet

Builds a runtime EVM wallet backed by a passkey signer.

Show parameters

id · String?

onSign · Future<CrossmintPasskeySignResult> Function(String message) · required

recoverySigner · CrossmintSignerConfig?

createSolanaWalletWithPasskeySigner(id, onSign, recoverySigner) · CrossmintSolanaWallet

Builds a runtime Solana wallet backed by a passkey signer. See [createEvmWalletWithPasskeySigner] for passkey selection semantics.

Show parameters

id · String?

onSign · Future<CrossmintPasskeySignResult> Function(String message) · required

recoverySigner · CrossmintSignerConfig?

createStellarWalletWithPasskeySigner(id, onSign, recoverySigner) · CrossmintStellarWallet

Builds a runtime Stellar wallet backed by a passkey signer. See [createEvmWalletWithPasskeySigner] for passkey selection semantics.

Show parameters

id · String?

onSign · Future<CrossmintPasskeySignResult> Function(String message) · required

recoverySigner · CrossmintSignerConfig?

dispose() · void

The controller also provides chain-specific convenience factories that build the signer for you: createEvmWalletWithDeviceSigner, createEvmWalletWithPasskeySigner, createEvmWalletWithExternalWalletSigner, createEvmWalletWithNonCustodialSigner, and their Solana / Stellar counterparts.

Usage

import 'package:crossmint_flutter/crossmint_flutter_controllers.dart';

final controller = client.createWalletController(
  CrossmintWalletControllerConfig(
    createOnLogin: CrossmintCreateOnLoginConfig(
      chain: 'base-sepolia',
      recovery: const CrossmintEmailSignerConfig(),
    ),
  ),
);

// Listen to status changes
controller.addListener(() {
  print('Status: ${controller.status}');
  final wallet = controller.currentWallet;
  if (wallet != null) {
    print('Address: ${wallet.address}');
  }
});

// Manual OTP handling
controller.otp.challengeListenable.addListener(() {
  final challenge = controller.otp.challengeListenable.value;
  if (challenge != null) {
    // Show your own OTP prompt UI
    // Then call: controller.otp.verifyOtp('123456');
  }
});

---

CrossmintWallets

Stateless convenience facade for wallet operations. Mirrors the CrossmintWallets entry point used by the TS, Kotlin, and Swift SDKs. For reactive state management (e.g. listening to wallet changes in a widget tree), use CrossmintWalletController instead.

Unlike the controller, the facade does not auto-resolve signer configs. Callers must provide fully-resolved configs (e.g. include the email address in CrossmintEmailSignerConfig, or pre-create a device signer via createDeviceSigner()).

Constructor

CrossmintWallets.from() · CrossmintWallets

Creates a CrossmintWallets facade backed by client.

Methods

getWallet(chain, alias, plugins, recoverySigner) · Future<CrossmintRuntimeWalletBase>

Retrieves an existing wallet and returns a typed runtime wallet.

Show parameters

chain · String · required

alias · String?

plugins · List<String>

recoverySigner · CrossmintSignerConfig?

createWallet(chain, recovery, recoveryMethods, signers, owner, alias, plugins) · Future<CrossmintRuntimeWalletBase>

Creates a new wallet and returns a typed runtime wallet.

Show parameters

chain · String · required

recovery · @Deprecated('Use recoveryMethods.') CrossmintSignerConfig?

recoveryMethods · List<CrossmintSignerConfig>?

signers · List<CrossmintSignerConfig>

owner · String?

alias · String?

plugins · List<String>

createWalletWithRecoveryMethods(chain, recoveryMethods, signers, owner, alias, plugins) · Future<CrossmintRuntimeWalletBase>

Creates a new wallet with one or more recovery methods.

Show parameters

chain · String · required

recoveryMethods · List<CrossmintSignerConfig> · required

signers · List<CrossmintSignerConfig>

owner · String?

alias · String?

plugins · List<String>

createDeviceSigner(storage, address) · Future<CrossmintDeviceSignerDescriptor>

Creates a device signer descriptor.

Show parameters

storage · DeviceSignerKeyStorage?

address · String?

createPasskeySigner(name, config) · Future<CrossmintPasskeySignerConfig>

Creates a passkey signer configuration.

Show parameters

name · String · required

config · CrossmintPasskeyConfig · required

Usage

import 'package:crossmint_flutter/crossmint_flutter_wallets.dart';

final wallets = CrossmintWallets.from(
  client,
  onAuthRequired: (challenge) {
    // Show your OTP prompt UI, then call challenge.verify(code)
  },
);

// Get an existing wallet
final wallet = await wallets.getWallet(chain: 'base-sepolia');
print('Address: ${wallet.address}');

// Create a new wallet
final newWallet = await wallets.createWallet(
  chain: 'base-sepolia',
  recovery: CrossmintEmailSignerConfig(email: 'YOUR_USER_EMAIL'),
);

// Send tokens
final tx = await newWallet.sendToken('RECIPIENT_WALLET_ADDRESS', 'usdc', '10');

---

Wallet Methods

The runtime wallet instances returned by the controller provide methods for token transfers, balances, signing, and more.

Properties

Property	Type	Description
wallet.client	CrossmintClient	Top-level Crossmint client shared by all wallet operations.
wallet.wallet	CrossmintWallet	Server-issued wallet snapshot backing this runtime instance.
wallet.deviceSignerKeyStorage	DeviceSignerKeyStorage?	Storage backend for hardware-backed device signer keys.
wallet.onAuthRequired	CrossmintSignerAuthRequiredCallback?	Callback invoked when a signer operation requires user authentication.
wallet.defaultChain	String	Chain identifier used when the wallet snapshot has no explicit chain.
wallet.chain	String	Blockchain this wallet operates on (falls back to [defaultChain]).
wallet.address	String	On-chain address of the wallet.
wallet.owner	String?	Owner identifier associated with the wallet, if any.
wallet.recoveryMethods	List<CrossmintSignerConfig>	Every recovery method configured on the wallet.
wallet.recovery	CrossmintSignerConfig?	Primary recovery signer config, the first of [recoveryMethods].
wallet.locator	String	Unique wallet locator used for API calls.
wallet.signer	CrossmintWalletApprovalSigner?	Currently active approval signer, or null if none is selected.
wallet.additionalSigners	List<CrossmintWalletApprovalSigner>	Secondary signers available alongside the primary [signer].
wallet.needsRecovery	bool	Whether the wallet needs recovery (signer registration) before the next transaction.
wallet.canExportPrivateKey	bool	Whether the active signer supports private-key export.

Methods

Method	Description
wallet.useSigner(signer)	Sets the active signer for this wallet. Accepts a signer config object; the locator is inferred internally. Works for device, non-custodial, external-wallet, and passkey signers.
wallet.useRecoveryMethod(recoveryMethod)	Selects which recovery method authorizes admin operations: [addSigner], [removeSigner], and device-signer recovery. Unlike [useSigner], this does not change the active signer used for transactions and signatures.
wallet.balances(tokens)	Returns the wallet balances — always includes USDC and the native token. Pass additional [tokens] to request extra token balances.
wallet.transactions()	Lists transaction summaries for this wallet.
wallet.transaction(transactionId)	Retrieves details for a specific transaction by ID.
wallet.approve(request)	Approves a pending transaction or signature request.
wallet.nfts(page, perPage)	Returns the wallet’s NFTs (paginated).
wallet.fund(request)	Initiates a funding (on-ramp) request for this wallet.
wallet.transfers(page, perPage, tokens, status)	Reads transfer history for this wallet (unstable API).
wallet.send(request)	Sends a token transfer and waits for confirmation.
wallet.sendToken(to, token, amount)	Convenience wrapper around [send] for simple token transfers.
wallet.signers()	Lists all signers registered on this wallet with their current status.
wallet.removeSigner(signerLocator)	Removes a signer from the wallet by its locator.
wallet.signerIsRegistered(signerLocator)	Checks whether a signer with the given locator is registered.
wallet.isSignerApproved(signerLocator)	Checks whether a registered signer is approved and usable.
wallet.addSigner(signer)	Registers a new signer on the wallet and approves the registration.
wallet.preAuthIfNeeded()	Awaits any in-flight recovery; if _needsRecovery is set and no recovery is in-flight, starts one and awaits it. Concurrent callers coalesce onto the same future so a single recovery runs per wallet. Then authenticates a non-custodial active signer, so an OTP round-trip happens before the operation exists rather than inside the window in which a Solana blockhash stays valid. Mirrors the TypeScript SDK.
wallet.recover()	Runs device-signer recovery: resumes any pending operation or registers a new device signer using the recovery signer. Returns early if the device signer is already approved on-chain.
wallet.exportPrivateKey(bridge)	Exports the wallet’s private key via the export signer bridge.
wallet.approveTransactionAndWait(transactionId)	Approves a pending transaction and polls until it reaches a terminal state.
wallet.transactionApprovalPayload(transaction, pendingApproval, signer)	Extracts the signable payload from a pending transaction approval.
wallet.completeApprovedTransaction(transaction)	Polls a transaction until it reaches a terminal state and attaches explorer links.
wallet.waitForTransaction(transactionId)	Polls a transaction by ID until it succeeds or fails.
wallet.walletSnapshotForSigners()	Fetches a fresh wallet snapshot to inspect registered signers.
wallet.requireActiveSigner(operation)	Returns the active signer or throws if none is selected.

Chain-specific methods:

• CrossmintEvmWallet — sendTransaction(), signMessage(), signTypedData()
• CrossmintSolanaWallet — sendTransaction()
• CrossmintStellarWallet — sendTransaction()

Usage

controller.currentWallet holds the loaded domain model. Signing, balance, and transaction methods live on the runtime wallet returned by controller.createEvmWallet() (or createSolanaWallet / createStellarWallet).

if (controller.currentWallet == null) return;

final wallet = controller.createEvmWallet();

final balances = await wallet.balances(tokens: <String>['usdc']);
print('USDC: ${balances.usdc.amount}');
print('Native: ${balances.nativeToken.amount}');

final tx = await wallet.sendToken('RECIPIENT_WALLET_ADDRESS', 'usdc', '10');
print('Transaction: ${tx.id}');

final signature = await wallet.signMessage('Hello, Web3!');
print('Signature: $signature');