Skip to main content
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
Configuration for the provider, containing client and wallet controller settings.
​
child
Widget
required
The widget subtree that can access the wallet context.

​
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
Wallet configuration for automatic creation on user login.
​
showOtpSignerPrompt
bool
When true (default), OTP signer prompts are shown during signing flows. When false, signing flows must be handled manually via the wallet controller’s OTP API.
​
callbacks
CrossmintWalletLifecycleCallbacks
Optional lifecycle callbacks invoked during wallet creation and transaction signing.
​
deviceSignerKeyStorage
DeviceSignerKeyStorage
Storage implementation for device signer keys. Defaults to native Secure Enclave (iOS) / Android Keystore.

​
CrossmintClientScope

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

​
Usage

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

CrossmintClientScope(
  config: CrossmintClientConfig(
    apiKey: 'YOUR_CLIENT_API_KEY',
    appScheme: 'myapp',
  ),
  child: const MyApp(),
)
Access the client from descendant widgets: 
final client = CrossmintClientScope.of(context);

​
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
Widget Function(BuildContext, CrossmintWalletContextData)
required
Builder called when the wallet is loaded and ready. Access the wallet via data.state.currentWallet.
​
unauthenticatedBuilder
Widget Function(BuildContext, CrossmintWalletContextData)
Builder called when the user is not authenticated.
​
initializingBuilder
Widget Function(BuildContext, CrossmintWalletContextData)
Builder called while the SDK is initializing. Defaults to a CircularProgressIndicator.
​
errorBuilder
Widget Function(BuildContext, CrossmintWalletContextData)
Builder called when an error occurs.

​
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(),
  ),
)