> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/sdk-reference/wallets/flutter/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

<ResponseField name="config" type="CrossmintWalletProviderConfig" required>
  Configuration for the provider, containing client and wallet controller settings.

  <Expandable title="properties">
    <ResponseField name="clientConfig" type="CrossmintClientConfig" required>
      Client configuration including API key and app scheme.

      <Expandable title="properties">
        <ResponseField name="apiKey" type="String" required>
          Your Crossmint client-side API key.
        </ResponseField>

        <ResponseField name="appScheme" type="String">
          Deep link scheme for OAuth callbacks (e.g. `"myapp"`).
        </ResponseField>

        <ResponseField name="authStorage" type="CrossmintAuthStorage">
          Custom auth storage implementation. Defaults to `flutter_secure_storage`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="walletControllerConfig" type="CrossmintWalletControllerConfig" required>
      Wallet controller configuration. See [CrossmintWalletControllerConfig](#crossmintwalletcontrollerconfig) below.
    </ResponseField>

    <ResponseField name="otpPromptBuilder" type="CrossmintOtpPromptBuilder">
      Builder for the OTP prompt dialog. Use `crossmintDefaultOtpPromptBuilder` from `crossmint_flutter_ui.dart` for the built-in dialog, or supply your own.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="child" type="Widget" required>
  The widget subtree that can access the wallet context.
</ResponseField>

### Usage

```dart theme={null}
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()`.

<ResponseField name="createOnLogin" type="CrossmintCreateOnLoginConfig">
  Wallet configuration for automatic creation on user login.

  <Expandable title="properties">
    <ResponseField name="chain" type="String" required>
      The blockchain to create the wallet on (e.g. `"base-sepolia"`).
    </ResponseField>

    <ResponseField name="recovery" type="CrossmintSignerConfig" required>
      The recovery signer configuration (e.g. `CrossmintEmailSignerConfig()`). Used for wallet recovery and adding new signers.
    </ResponseField>

    <ResponseField name="signers" type="List<CrossmintSignerConfig>">
      Optional list of operational signers. Defaults to a device signer if omitted.
    </ResponseField>

    <ResponseField name="alias" type="String">
      Optional wallet alias.
    </ResponseField>

    <ResponseField name="plugins" type="List<String>">
      Optional list of wallet plugin identifiers.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="showOtpSignerPrompt" type="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.
</ResponseField>

<ResponseField name="callbacks" type="CrossmintWalletLifecycleCallbacks">
  Optional lifecycle callbacks invoked during wallet creation and transaction signing.
</ResponseField>

<ResponseField name="deviceSignerKeyStorage" type="DeviceSignerKeyStorage">
  Storage implementation for device signer keys. Defaults to native Secure Enclave (iOS) / Android Keystore.
</ResponseField>

***

## CrossmintClientScope

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

### Usage

```dart theme={null}
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:

```dart theme={null}
final client = CrossmintClientScope.of(context);
```

***

## CrossmintAuthScope

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

### Usage

```dart theme={null}
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

```dart theme={null}
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

<ResponseField name="readyBuilder" type="Widget Function(BuildContext, CrossmintWalletContextData)" required>
  Builder called when the wallet is loaded and ready. Access the wallet via `data.state.currentWallet`.
</ResponseField>

<ResponseField name="unauthenticatedBuilder" type="Widget Function(BuildContext, CrossmintWalletContextData)">
  Builder called when the user is not authenticated.
</ResponseField>

<ResponseField name="initializingBuilder" type="Widget Function(BuildContext, CrossmintWalletContextData)">
  Builder called while the SDK is initializing. Defaults to a `CircularProgressIndicator`.
</ResponseField>

<ResponseField name="errorBuilder" type="Widget Function(BuildContext, CrossmintWalletContextData)">
  Builder called when an error occurs.
</ResponseField>

### Usage

```dart theme={null}
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(),
  ),
)
```