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

# CrossmintWalletController

> Flutter Final Class

**Final Class**

Stateful orchestrator for Crossmint wallets in a Flutter app.

```dart theme={null}
final class CrossmintWalletController extends ChangeNotifier
```

Holds the currently-loaded `CrossmintWallet`, exposes lifecycle operations
(`getWallet`, `createWallet`, `ensureLoaded`, `refresh`, `clear`),
surfaces OTP challenges via `otp`, and provides `create*Wallet*`
convenience methods that wire a runtime wallet with a signer of your
choosing (device, non-custodial, external, passkey).

Obtain one from `CrossmintClient.createWalletController` and pair it with
`CrossmintWalletHost` (headless) or `CrossmintWalletProvider`
(opt-in Material UI) so the hidden signer bridge has a place to mount.

Extends `ChangeNotifier` — listen to the controller for wallet-state
changes. Mutations go through the controller's public API; observation
can additionally go through `state` for a narrower, read-only surface.

## Constructors

### CrossmintWalletController

```dart theme={null}
CrossmintWalletController({
  required this.client,
  required this.config,
  CrossmintWalletStateRepository? stateRepository,
})
```

Creates a wallet controller. Prefer `CrossmintClient.createWalletController` over calling this directly.

## Properties

### client

```dart theme={null}
final CrossmintClient client
```

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

### config

```dart theme={null}
final CrossmintWalletControllerConfig config
```

The configuration this controller was built with.

### otp

```dart theme={null}
final CrossmintWalletOtpController otp
```

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

### state

```dart theme={null}
CrossmintWalletStateView get state
```

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

```dart theme={null}
CrossmintWallet? get currentWallet
```

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

### status

```dart theme={null}
CrossmintWalletStatus get status
```

Current wallet lifecycle status.

### onAuthRequired

```dart theme={null}
CrossmintWalletAuthRequiredCallback get onAuthRequired
```

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

```dart theme={null}
CrossmintOtpChallenge? get pendingOtpChallenge
```

Shortcut to `CrossmintWalletOtpController.pendingChallenge`.

### otpChallengeListenable

```dart theme={null}
ValueListenable<CrossmintOtpChallenge?> get otpChallengeListenable
```

Shortcut to `CrossmintWalletOtpController.challengeListenable`.

### requireCurrentWallet

```dart theme={null}
CrossmintWallet get requireCurrentWallet
```

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

## Methods

### getWallet

```dart theme={null}
Future<CrossmintWallet?> getWallet( CrossmintWalletLookupRequest request, )
```

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

### loadWallet

```dart theme={null}
Future<CrossmintWallet?> loadWallet(CrossmintWalletLookupRequest request)
```

Deprecated: use `getWallet` instead.

### createWallet

```dart theme={null}
Future<CrossmintWallet> createWallet( CrossmintWalletCreateRequest request, )
```

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

### ensureLoaded

```dart theme={null}
Future<CrossmintWallet?> ensureLoaded()
```

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

### refresh

```dart theme={null}
Future<CrossmintWallet?> refresh()
```

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

### clear

```dart theme={null}
Future<void> clear()
```

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

### sendOtp

```dart theme={null}
Future<void> sendOtp()
```

Shortcut to `CrossmintWalletOtpController.sendOtp`.

### verifyOtp

```dart theme={null}
Future<void> verifyOtp(String otpCode)
```

Shortcut to `CrossmintWalletOtpController.verifyOtp`.

### rejectOtp

```dart theme={null}
void rejectOtp([Object? error])
```

Shortcut to `CrossmintWalletOtpController.reject`.

### createEvmWallet

```dart theme={null}
CrossmintEvmWallet createEvmWallet({
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
})
```

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

### createSolanaWallet

```dart theme={null}
CrossmintSolanaWallet createSolanaWallet({
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
})
```

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.

### createStellarWallet

```dart theme={null}
CrossmintStellarWallet createStellarWallet({
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
})
```

Wraps the currently-loaded wallet as a runtime `CrossmintStellarWallet`.

### createEvmWalletWithDeviceSigner

```dart theme={null}
CrossmintEvmWallet createEvmWalletWithDeviceSigner({
  required String signerLocator,
  String? address,
  DeviceSignerKeyStorage? storage,
})
```

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.

### createEvmWalletWithNonCustodialSigner

```dart theme={null}
CrossmintEvmWallet createEvmWalletWithNonCustodialSigner({
  required String signerType,
  required String signerLocator,
  String? address,
  HiddenSignerBridge? bridge,
})
```

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

### createSolanaWalletWithNonCustodialSigner

```dart theme={null}
CrossmintSolanaWallet createSolanaWalletWithNonCustodialSigner({
  required String signerType,
  required String signerLocator,
  String? address,
  HiddenSignerBridge? bridge,
})
```

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

### createStellarWalletWithNonCustodialSigner

```dart theme={null}
CrossmintStellarWallet createStellarWalletWithNonCustodialSigner({
  required String signerType,
  required String signerLocator,
  String? address,
  HiddenSignerBridge? bridge,
})
```

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

### createStellarWalletWithDeviceSigner

```dart theme={null}
CrossmintStellarWallet createStellarWalletWithDeviceSigner({
  required String signerLocator,
  String? address,
  DeviceSignerKeyStorage? storage,
})
```

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

### createEvmWalletWithExternalWalletSigner

```dart theme={null}
CrossmintEvmWallet createEvmWalletWithExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})
```

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

### createSolanaWalletWithExternalWalletSigner

```dart theme={null}
CrossmintSolanaWallet createSolanaWalletWithExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})
```

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

### createStellarWalletWithExternalWalletSigner

```dart theme={null}
CrossmintStellarWallet createStellarWalletWithExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})
```

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

### createEvmWalletWithPasskeySigner

```dart theme={null}
CrossmintEvmWallet createEvmWalletWithPasskeySigner({
  String? id,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})
```

Builds a runtime EVM wallet backed by a passkey signer.

### createSolanaWalletWithPasskeySigner

```dart theme={null}
CrossmintSolanaWallet createSolanaWalletWithPasskeySigner({
  String? id,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})
```

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

### createStellarWalletWithPasskeySigner

```dart theme={null}
CrossmintStellarWallet createStellarWalletWithPasskeySigner({
  String? id,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})
```

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

### dispose

```dart theme={null}
void dispose()
```