Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

SDK Documentation Spark
Request API Key

User settings

The SDK exposes a set of user settings that are shared across all SDK instances, even from different partners.

Available user settings API docs

The following user settings are available:

  • Spark private mode: Spark supports opt-in wallet privacy. When enabled, the wallet's Bitcoin payments and balance will not be accessible through public indexers like Sparkscan. The SDK enables this by default for new wallets, and we highly recommend keeping it enabled. However, some applications may require the wallet to be visible to the public.

Note: Spark private mode only applies to Bitcoin payments. Token payments are not affected by the private mode and will still be publicly available.

  • Stable balance active label: Controls which stable token is active for automatic Bitcoin-to-token conversion. Set to a label from your stable balance configuration to activate, or unset to deactivate. See the Stable balance guide for details.

  • Spark master identity public key: A second public key that Spark accepts as a reader of the wallet while private mode is enabled. It enables watch-only views of a private wallet: designate a key you control, and a Spark client authenticating with the corresponding private key can query the wallet's Bitcoin balance and payment history. The master identity is read-only, so making payments still requires the wallet's own keys. The same public key can be designated across many wallets.

Getting the current user settings API docs

Rust
let user_settings = sdk.get_user_settings().await?;
info!("User settings: {:?}", user_settings);
Swift
let userSettings = try await sdk.getUserSettings()
print("User settings: \(userSettings)")
Kotlin
try {
    val userSettings = sdk.getUserSettings()
    println("User settings: $userSettings")
} catch (e: Exception) {
    // handle error
}
C#
var userSettings = await sdk.GetUserSettings();

Console.WriteLine($"User settings: {userSettings}");
Javascript
const userSettings = await sdk.getUserSettings()
console.log(`User settings: ${JSON.stringify(userSettings)}`)
React Native
const userSettings = await sdk.getUserSettings()
console.log(`User settings: ${JSON.stringify(userSettings)}`)
Flutter
final userSettings = await sdk.getUserSettings();
print('User settings: $userSettings');
Python
try:
    user_settings = await sdk.get_user_settings()

    print(f"User settings: {user_settings}")
except Exception as error:
    logging.error(error)
    raise
Go
userSettings, err := sdk.GetUserSettings()

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return err
}

log.Printf("User settings: %v", userSettings)

Updating the user settings API docs

Every field of UpdateUserSettingsRequestUpdateUserSettingsRequestUpdateUserSettingsRequestUpdateUserSettingsRequestUpdateUserSettingsRequestUpdateUserSettingsRequestUpdateUserSettingsRequestUpdateUserSettingsRequestUpdateUserSettingsRequest is optional, and a field left unset is not changed. Settings that hold a value use an enum to distinguish assigning one from clearing it: SparkMasterIdentityPublicKey::SetSparkMasterIdentityPublicKey.SETSparkMasterIdentityPublicKey.setSparkMasterIdentityPublicKey.SetSparkMasterIdentityPublicKey.SetSparkMasterIdentityPublicKey.SetSparkMasterIdentityPublicKey.SetSparkMasterIdentityPublicKeySetSparkMasterIdentityPublicKey.Set and StableBalanceActiveLabel::SetStableBalanceActiveLabel.SETStableBalanceActiveLabel.setStableBalanceActiveLabel.SetStableBalanceActiveLabel.SetStableBalanceActiveLabel.SetStableBalanceActiveLabel.SetStableBalanceActiveLabelSetStableBalanceActiveLabel.Set assign, SparkMasterIdentityPublicKey::UnsetSparkMasterIdentityPublicKey.UNSETSparkMasterIdentityPublicKey.unsetSparkMasterIdentityPublicKey.UnsetSparkMasterIdentityPublicKey.UnsetSparkMasterIdentityPublicKey.UnsetSparkMasterIdentityPublicKey.UnsetSparkMasterIdentityPublicKeyUnsetSparkMasterIdentityPublicKey.Unset and StableBalanceActiveLabel::UnsetStableBalanceActiveLabel.UNSETStableBalanceActiveLabel.unsetStableBalanceActiveLabel.UnsetStableBalanceActiveLabel.UnsetStableBalanceActiveLabel.UnsetStableBalanceActiveLabel.UnsetStableBalanceActiveLabelUnsetStableBalanceActiveLabel.Unset clear.

Rust
sdk.update_user_settings(UpdateUserSettingsRequest {
    spark_private_mode_enabled: Some(true),
    stable_balance_active_label: None,
    spark_master_identity_public_key: Some(SparkMasterIdentityPublicKey::Set {
        public_key: "<hex encoded public key>".to_string(),
    }),
})
.await?;
Swift
try await sdk.updateUserSettings(
    request: UpdateUserSettingsRequest(
        sparkPrivateModeEnabled: true,
        stableBalanceActiveLabel: nil,
        sparkMasterIdentityPublicKey: .set(publicKey: "<hex encoded public key>")
    ))
Kotlin
try {
    sdk.updateUserSettings(UpdateUserSettingsRequest(
        sparkPrivateModeEnabled = true,
        stableBalanceActiveLabel = null,
        sparkMasterIdentityPublicKey = SparkMasterIdentityPublicKey.Set(
            publicKey = "<hex encoded public key>"
        )
    ))
} catch (e: Exception) {
    // handle error
}
C#
await sdk.UpdateUserSettings(
    request: new UpdateUserSettingsRequest(
        sparkPrivateModeEnabled: true,
        stableBalanceActiveLabel: null,
        sparkMasterIdentityPublicKey: new SparkMasterIdentityPublicKey.Set(
            publicKey: "<hex encoded public key>"
        )
    )
);
Javascript
await sdk.updateUserSettings({
  sparkPrivateModeEnabled: true,
  stableBalanceActiveLabel: undefined,
  sparkMasterIdentityPublicKey: {
    type: 'set',
    publicKey: '<hex encoded public key>'
  }
})
React Native
await sdk.updateUserSettings({
  sparkPrivateModeEnabled: true,
  stableBalanceActiveLabel: undefined,
  sparkMasterIdentityPublicKey: new SparkMasterIdentityPublicKey.Set({
    publicKey: '<hex encoded public key>'
  })
})
Flutter
await sdk.updateUserSettings(
    request: UpdateUserSettingsRequest(
        sparkPrivateModeEnabled: true,
        stableBalanceActiveLabel: null,
        sparkMasterIdentityPublicKey: SparkMasterIdentityPublicKey_Set(
            publicKey: "<hex encoded public key>")));
Python
try:
    await sdk.update_user_settings(
        request=UpdateUserSettingsRequest(
            spark_private_mode_enabled=True,
            stable_balance_active_label=None,
            spark_master_identity_public_key=SparkMasterIdentityPublicKey.SET(
                public_key="<hex encoded public key>"
            )
        )
    )
except Exception as error:
    logging.error(error)
    raise
Go
sparkPrivateModeEnabled := true
masterIdentityPublicKey := breez_sdk_spark.SparkMasterIdentityPublicKey(
	breez_sdk_spark.SparkMasterIdentityPublicKeySet{
		PublicKey: "<hex encoded public key>",
	},
)
err := sdk.UpdateUserSettings(breez_sdk_spark.UpdateUserSettingsRequest{
	SparkPrivateModeEnabled:      &sparkPrivateModeEnabled,
	StableBalanceActiveLabel:     nil,
	SparkMasterIdentityPublicKey: &masterIdentityPublicKey,
})

if err != nil {
	var sdkErr *breez_sdk_spark.SdkError
	if errors.As(err, &sdkErr) {
		// Handle SdkError - can inspect specific variants if needed
		// e.g., switch on sdkErr variant for InsufficientFunds, NetworkError, etc.
	}
	return err
}