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

Custom configuration API docs

The SDK supports various configuration options to customize its behavior. During initialization, you must provide a configuration object, which we recommend creating by modifying the default configuration. This page describes the available configuration options.

Max deposit claim fee

Receiving Bitcoin payments through onchain deposits may involve fees. This configuration option controls the automatic claiming of incoming funds, allowing it when the required fees are below specified thresholds (either an absolute fee amount or a feerate). You can also disable automatic claiming entirely. Deposits that are not automatically claimed require manual intervention.

By default, automatic claiming is enabled with a maximum feerate of 1 sat/vB.

More information can be found in the Handling unclaimed deposits page.

Rust
// Create the default config
let mut config = default_config(Network::Mainnet);
config.api_key = Some("<breez api key>".to_string());

// Disable automatic claiming
config.max_deposit_claim_fee = None;

// Set a maximum feerate of 10 sat/vB
config.max_deposit_claim_fee = Some(Fee::Rate { sat_per_vbyte: 10 });

// Set a maximum fee of 1000 sat
config.max_deposit_claim_fee = Some(Fee::Fixed { amount: 1000 });
Swift
// Create the default config
var config = defaultConfig(network: Network.mainnet)
config.apiKey = "<breez api key>"

// Disable automatic claiming
config.maxDepositClaimFee = nil

// Set a maximum feerate of 10 sat/vB
config.maxDepositClaimFee = Fee.rate(satPerVbyte: 10)

// Set a maximum fee of 1000 sat
config.maxDepositClaimFee = Fee.fixed(amount: 1000)
Kotlin
// Create the default config
val config = defaultConfig(Network.MAINNET)
config.apiKey = "<breez api key>"

// Disable automatic claiming
config.maxDepositClaimFee = null

// Set a maximum feerate of 10 sat/vB
config.maxDepositClaimFee = Fee.Rate(10u)

// Set a maximum fee of 1000 sat
config.maxDepositClaimFee = Fee.Fixed(1000u)
C#
// Create the default config with API key
var config = BreezSdkSparkMethods.DefaultConfig(Network.Mainnet) with
{
    apiKey = "<breez api key>"
};

// Disable automatic claiming
config = config with { maxDepositClaimFee = null };

// Set a maximum feerate of 10 sat/vB
config = config with { maxDepositClaimFee = new Fee.Rate(satPerVbyte: 10) };

// Set a maximum fee of 1000 sat
config = config with { maxDepositClaimFee = new Fee.Fixed(amount: 1000) };
Javascript
// Create the default config
const config = defaultConfig('mainnet')
config.apiKey = '<breez api key>'

// Disable automatic claiming
config.maxDepositClaimFee = undefined

// Set a maximum feerate of 10 sat/vB
config.maxDepositClaimFee = { type: 'rate', satPerVbyte: 10 }

// Set a maximum fee of 1000 sat
config.maxDepositClaimFee = { type: 'fixed', amount: 1000 }
React Native
// Create the default config
const config = defaultConfig(Network.Mainnet)
config.apiKey = '<breez api key>'

// Disable automatic claiming
config.maxDepositClaimFee = undefined

// Set a maximum feerate of 10 sat/vB
config.maxDepositClaimFee = new Fee.Rate({ satPerVbyte: BigInt(10) })

// Set a maximum fee of 1000 sat
config.maxDepositClaimFee = new Fee.Fixed({ amount: BigInt(1000) })
Flutter
// Create the default config
var config = defaultConfig(network: Network.mainnet)
    .copyWith(apiKey: "<breez api key>");

// Disable automatic claiming
config = config.copyWith(maxDepositClaimFee: null);

// Set a maximum feerate of 10 sat/vB
config = config.copyWith(maxDepositClaimFee: Fee.rate(satPerVbyte: BigInt.from(10)));

// Set a maximum fee of 1000 sat
config = config.copyWith(maxDepositClaimFee: Fee.fixed(amount: BigInt.from(1000)));
Python
# Create the default config
config = default_config(network=Network.MAINNET)
config.api_key = "<breez api key>"

# Disable automatic claiming
config.max_deposit_claim_fee = None

# Set a maximum feerate of 10 sat/vB
config.max_deposit_claim_fee = Fee.RATE(sat_per_vbyte=10)

# Set a maximum fee of 1000 sat
config.max_deposit_claim_fee = Fee.FIXED(amount=1000)
Go
// Create the default config
config := breez_sdk_spark.DefaultConfig(breez_sdk_spark.NetworkMainnet)
apiKey := "<breez api key>"
config.ApiKey = &apiKey

// Disable automatic claiming
config.MaxDepositClaimFee = nil

// Set a maximum feerate of 10 sat/vB
feeRateInterface := breez_sdk_spark.Fee(breez_sdk_spark.FeeRate{SatPerVbyte: 10})
config.MaxDepositClaimFee = &feeRateInterface

// Set a maximum fee of 1000 sat
feeFixedInterface := breez_sdk_spark.Fee(breez_sdk_spark.FeeFixed{Amount: 1000})
config.MaxDepositClaimFee = &feeFixedInterface

Synchronization interval

The SDK performs regular background synchronization to check for payment status updates. You can configure how often this synchronization occurs.

The synchronization process is used to detect some payment status updates that are not detected in real-time through event streams.

A shorter synchronization interval provides more responsive detection of payment updates but increases resource usage and may trigger API rate limits. The default interval balances responsiveness with resource efficiency for most use cases.

LNURL Domain

The LNURL domain to be used for receiving LNURL and Lightning address payments. By default, the Breez LNURL server instance will be used. You may configure a different domain, or set no domain to disable receiving payments using LNURL. For more information, see Receiving payments using LNURL-Pay.

Prefer Spark over Lightning

An on-off switch that determines whether to prefer settlement using Spark when sending and receiving payments via Lightning invoices. Direct settlement using Spark offers lower fees but reduces privacy.

External input parsing

The SDK's parsing module can be extended by providing external parsers that are used when input is not recognized. Some default external parsers are provided but can be disabled. You can add new external parsers as described in Configuring external parsers.

Real-time sync server URL

The SDK synchronizes user data across different SDK instances using a real-time synchronization server. By default, a Breez instance will be used, but you may configure a different instance by providing its URL, or disable it entirely by providing no URL.

Private mode enabled by default

Configures whether the Spark private mode should be enabled by default. By default, it is enabled. When enabled, the Spark private mode will be enabled on the first initialization of the SDK. If disabled, no changes will be made to the Spark private mode.

Rust
// Disable Spark private mode by default
let mut config = default_config(Network::Mainnet);
config.private_enabled_default = false;
Swift
// Disable Spark private mode by default
var config = defaultConfig(network: Network.mainnet)
config.privateEnabledDefault = false
Kotlin
// Disable Spark private mode by default
val config = defaultConfig(Network.MAINNET)
config.privateEnabledDefault = false
C#
// Disable Spark private mode by default
var config = BreezSdkSparkMethods.DefaultConfig(Network.Mainnet) with
{
    privateEnabledDefault = false
};
Javascript
// Disable Spark private mode by default
const config = defaultConfig('mainnet')
config.privateEnabledDefault = false
React Native
// Disable Spark private mode by default
const config = defaultConfig(Network.Mainnet)
config.privateEnabledDefault = false
Flutter
// Disable Spark private mode by default
var config = defaultConfig(network: Network.mainnet).copyWith(privateEnabledDefault: false);
Python
# Disable Spark private mode by default
config = default_config(network=Network.MAINNET)
config.private_enabled_default = False
Go
// Disable Spark private mode by default
config := breez_sdk_spark.DefaultConfig(breez_sdk_spark.NetworkMainnet)
config.PrivateEnabledDefault = false

Developer note

This configuration option is only relevant when the SDK is initialized for the first time. To update the user settings after that, or to explicitly disable the Spark private mode, see the User settings page.