Configuration

WalletSdkOptions is the single configuration object passed to WalletSdk.initialize. This page documents every field.

final sdk = await WalletSdk.initialize(
  WalletSdkOptions(
    baseUrl: 'https://api.stg.iden2.app',
    storageEncryptionKeyProvider: () => secureKeyStore.getOrCreateKey(),
    platformHttpClient: DioPlatformHttpClient(dio),
    promptHandler: promptHandler,
    trustNetworkModeProvider: () async => TrustNetworkMode.warn,
  ),
);

WalletSdk.initialize throws a WalletSdkException immediately if baseUrl is empty. Initialization runs once per process; repeated calls return the existing instance.

Required options

Option	Type	Description
baseUrl	String	Platform API base URL. Staging: https://api.stg.iden2.app.
storageEncryptionKeyProvider	Future<String> Function()	Returns the SQLCipher key that encrypts the SDK's wallet database. Must be stable across launches; persist it in platform secure storage.

Always-on modules

Issuance (acceptOffer / offerAcceptance) and presentation (present / presentation) are always wired at initialize. Provide a promptHandler so consent and selection UI can run; without it, those flows fail when they reach a user decision.

User interaction

Option	Type	Description
promptHandler	WalletPromptHandler?	The contract through which the SDK requests user decisions (credential consent, disclosure selection, trust warnings). Required for issuance and presentation. See Prompts.

HTTP and networking

Option	Type	Description
platformHttpClient	PlatformHttpClient?	Your HTTP stack for Platform API calls. Wrap a Dio instance with DioPlatformHttpClient from package:wallet_sdk/dio.dart (recommended). When omitted, the SDK creates a minimal Dio client from baseUrl.
externalHttpClient	ExternalHttpClient?	Client used for requests to third-party endpoints (issuer metadata, offer URIs). Defaults to an SDK-provided client.

Injecting your own client lets the SDK inherit your interceptors, logging, certificate pinning, and proxy settings:

import 'package:wallet_sdk/dio.dart';

final dio = Dio(BaseOptions(baseUrl: baseUrl))
  ..interceptors.add(myAuthInterceptor)
  ..interceptors.add(LogInterceptor());

WalletSdkOptions(
  baseUrl: baseUrl,
  platformHttpClient: DioPlatformHttpClient(dio),
  // ...
);

Storage

Option	Type	Default	Description
storageDatabaseFileName	String	'wallet_sdk.db'	SDK-owned database file name, created under the app documents directory.
storageForTesting	WalletStorage?	—	In-memory or fake storage for unit tests only.
keyStore	KeyStore?	—	Overrides the on-device holder key store (e.g. for tests).

The SDK owns its database exclusively — wallet, credential, DID, and sharing-log tables live in wallet_sdk.db, separate from any host app database.

Trust network

Option	Type	Description
trustNetworkModeProvider	Future<TrustNetworkMode> Function()?	Reads the current enforcement mode from your settings. Called at decision points, so mode changes take effect without re-initialization.
trustNetworkApi	TrustNetworkApi?	Override the default Trust Network client.

TrustNetworkMode has three values:

Mode	Issuance behavior	Presentation behavior
off	No trust checks	No trust checks
warn	Untrusted issuer → warning on the consent prompt	Untrusted verifier → VerifierTrustPrompt asks the user
strict	Untrusted issuer → flow blocked	Untrusted verifier → flow aborted without a prompt

Future<TrustNetworkMode> trustNetworkModeFromSettings() async {
  final prefs = await SharedPreferences.getInstance();
  return switch (prefs.getString('trust_mode')) {
    'strict' => TrustNetworkMode.strict,
    'warn' => TrustNetworkMode.warn,
    _ => TrustNetworkMode.off,
  };
}

Observability

Option	Type	Description
authObserver	AuthObserver?	Analytics/diagnostics hook for auth lifecycle events. Implementations must not throw.

class CrashReportingAuthObserver implements AuthObserver {
  @override
  void onAuthenticated(AuthSession session) =>
      crashlytics.setUserIdentifier(session.username);

  @override
  void onLoggedOut() => crashlytics.setUserIdentifier('');

  @override
  void onAuthError(AuthErrorCode code) =>
      analytics.logEvent('auth_error', {'code': code.name});
}

Advanced overrides

These replace default SDK implementations. Most integrations never set them; they exist for tests and specialized deployments.

Option	Type	Replaces
credentialOfferExchange	CredentialOfferExchange?	Default backend exchange used during issuance
presentationExchange	PresentationExchange?	Default backend exchange used during presentation
offerUriParser	CredentialOfferUriParser?	Default credential-offer deep-link parser (used for trust endpoint validation)
issuerTrustEvaluator	IssuerTrustEvaluator?	Default issuer trust evaluation
verifierTrustEvaluator	VerifierTrustEvaluator?	Default verifier trust evaluation

Testing configuration

For unit tests, combine the test-only options with the fakes in package:wallet_sdk/testing.dart:

import 'package:wallet_sdk/testing.dart';
import 'package:wallet_sdk/wallet_sdk.dart';

final sdk = await WalletSdk.initialize(
  WalletSdkOptions(
    baseUrl: 'https://test.invalid',
    storageEncryptionKeyProvider: () async => 'test-key',
    storageForTesting: MemoryWalletStorage(),
  ),
);

// Between tests:
await WalletSdk.resetForTest();