Providers

Flutter providers and scopes for the Flutter SDK reference for Crossmint wallets

The Flutter SDK provides widget-based providers and scopes for integrating wallet functionality into your widget tree. These are optional — the SDK is headless-first and all features can be used directly via controllers.

1. CrossmintWalletProvider — All-in-one provider (recommended)
2. CrossmintClientScope — Low-level client scope
3. CrossmintAuthScope — Low-level auth scope
4. CrossmintWalletScope — Low-level wallet scope

---

CrossmintWalletProvider

All-in-one provider that initializes the client, auth, and wallet controller. Handles session restoration, OAuth callback routing, and OTP prompt display automatically. This is the recommended entry point for widget-based apps.

Props

config · CrossmintWalletProviderConfig · required

The configuration this provider was built with.

Show properties

clientConfig · CrossmintClientConfig?

Config used to build a new [CrossmintClient]. Mutually exclusive with [dependencies].

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 uses a no-op logger in release and a debugPrint-backed logger in debug.

refreshRoute · Uri?

Optional custom server endpoint for token refresh.

logoutRoute · Uri?

Optional custom server endpoint for logout.

walletControllerConfig · CrossmintWalletControllerConfig

Config for the wallet controller the provider creates.

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

deviceSignerKeyStorage · DeviceSignerKeyStorage?

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

dependencies · CrossmintWalletProviderDependencies?

Pre-built dependencies — use this when you want to share a client or controller between mount points. Mutually exclusive with [clientConfig].

Show properties

client · CrossmintClient · required

An already-initialized client. The provider will not dispose this unless [CrossmintWalletProviderConfig.disposeInjectedDependencies] is true.

walletController · CrossmintWalletController · required

An already-built wallet controller bound to [client].

authCallbackRouter · CrossmintAuthCallbackRouter?

Optional pre-built callback router for OAuth deep links.

disposeInjectedDependencies · bool

When the provider was handed pre-built dependencies, controls whether they are disposed alongside the provider. Defaults to false — the caller retains ownership.

authLinkProvider · CrossmintAuthLinkProvider?

Optional resolver for the OAuth callback URL. Leave null to use the default deep-link resolver.

startAuthCallbackRouter · bool

When true (default) the provider starts [CrossmintAuthCallbackRouter] automatically so OAuth redirects land correctly.

autoLoadWallet · bool

When true (default) the provider triggers ensureLoaded() on the wallet controller once a session is detected.

jwt · String?

BYOA JWT — when supplied, the provider seeds auth.setJwt(jwt) on startup (Bring Your Own Auth). Apps not using BYOA can leave this null.

otpPromptBuilder · CrossmintOtpPromptBuilder?

Builder for the default OTP prompt UI — pass crossmintDefaultOtpPromptBuilder for the Material default. Leave null to drive OTP UI headlessly via walletController.otp.

mountBridgeHosts · bool

When true (default) the provider mounts CrossmintWalletHost so the hidden signer bridge has a place to run. Set to false only if your subtree already hosts the bridge.

child · Widget · required

The subtree rendered once dependencies are ready. Pair with [CrossmintWalletGate] to show a loading state until then.

Usage

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: CrossmintWalletProvider(
        config: CrossmintWalletProviderConfig(
          clientConfig: CrossmintClientConfig(
            apiKey: 'YOUR_CLIENT_API_KEY',
            appScheme: 'myapp',
          ),
          walletControllerConfig: CrossmintWalletControllerConfig(
            createOnLogin: CrossmintCreateOnLoginConfig(
              chain: 'base-sepolia',
              recovery: const CrossmintEmailSignerConfig(),
            ),
            showOtpSignerPrompt: true,
          ),
          otpPromptBuilder: crossmintDefaultOtpPromptBuilder,
        ),
        child: const HomeScreen(),
      ),
    );
  }
}

---

CrossmintWalletControllerConfig

Configuration for the wallet controller, used by both CrossmintWalletProvider and the headless CrossmintClient.createWalletController().

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.

---

CrossmintClientScope

Low-level scope that provides a CrossmintClient instance to the widget subtree.

Access the client from descendant widgets:

final client = CrossmintClientScope.of(context);

Usage

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

CrossmintClientScope(
  config: CrossmintClientConfig(
    apiKey: 'YOUR_CLIENT_API_KEY',
    appScheme: 'myapp',
  ),
  child: const MyApp(),
)

---

CrossmintAuthScope

Provides the auth client to the widget subtree. Must be nested inside a CrossmintClientScope.

Usage

CrossmintClientScope(
  config: CrossmintClientConfig(apiKey: 'YOUR_CLIENT_API_KEY'),
  child: CrossmintAuthScope(
    child: const LoginScreen(),
  ),
)

---

CrossmintWalletScope

Provides the wallet controller to the widget subtree. Must be nested inside a CrossmintClientScope.

Usage

CrossmintClientScope(
  config: CrossmintClientConfig(apiKey: 'YOUR_CLIENT_API_KEY'),
  child: CrossmintWalletScope(
    config: CrossmintWalletControllerConfig(
      createOnLogin: CrossmintCreateOnLoginConfig(
        chain: 'base-sepolia',
        recovery: const CrossmintEmailSignerConfig(),
      ),
    ),
    child: const WalletScreen(),
  ),
)

---

CrossmintWalletGate

Status-based widget that renders different builders depending on the wallet state. Must be used within a CrossmintWalletProvider or CrossmintWalletScope.

All builders receive a CrossmintWalletContextData object, which provides access to the current state, auth client, wallet controller, and actions.

Props

readyBuilder · CrossmintWalletGateBuilder · required

initializingBuilder · CrossmintWalletGateBuilder?

unauthenticatedBuilder · CrossmintWalletGateBuilder?

errorBuilder · CrossmintWalletGateBuilder?

Usage

CrossmintWalletGate(
  readyBuilder: (context, data) {
    // readyBuilder fires once authenticated — the wallet may
    // still be loading. Guard on hasWallet before accessing it.
    if (!data.state.hasWallet) {
      return const Center(child: CircularProgressIndicator());
    }
    return DashboardScreen(wallet: data.state.currentWallet!);
  },
  unauthenticatedBuilder: (context, data) => const LoginScreen(),
  initializingBuilder: (context, data) => const Center(
    child: CircularProgressIndicator(),
  ),
)