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 on-chain deposits may involve fees. This configuration option controls the automatic claiming of incoming funds, allowing it when the required fees are below specified thresholds. The available options are:

Absolute fee amount in sats
Feerate in sats/vbyte
Fastest network recommended fee at the time of claim, with a leeway in sats/vbyte

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 sats/vbyte.

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(MaxFee::Rate { sat_per_vbyte: 10 });

// Set a maximum fee of 1000 sat
config.max_deposit_claim_fee = Some(MaxFee::Fixed { amount: 1000 });

// Set the maximum fee to the fastest network recommended fee at the time of claim
// with a leeway of 1 sats/vbyte
config.max_deposit_claim_fee = Some(MaxFee::NetworkRecommended {
    leeway_sat_per_vbyte: 1,
});

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 = MaxFee.rate(satPerVbyte: 10)

// Set a maximum fee of 1000 sat
config.maxDepositClaimFee = MaxFee.fixed(amount: 1000)

// Set the maximum fee to the fastest network recommended fee at the time of claim
// with a leeway of 1 sats/vbyte
config.maxDepositClaimFee = MaxFee.networkRecommended(leewaySatPerVbyte: 1)

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 = MaxFee.Rate(10u)

// Set a maximum fee of 1000 sat
config.maxDepositClaimFee = MaxFee.Fixed(1000u)

// Set the maximum fee to the fastest network recommended fee at the time of claim
// with a leeway of 1 sats/vbyte
config.maxDepositClaimFee = MaxFee.NetworkRecommended(1u)

// 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 MaxFee.Rate(satPerVbyte: 10) };

// Set a maximum fee of 1000 sat
config = config with { maxDepositClaimFee = new MaxFee.Fixed(amount: 1000) };

// Set the maximum fee to the fastest network recommended fee at the time of claim
// with a leeway of 1 sats/vbyte
config = config with { maxDepositClaimFee = new MaxFee.NetworkRecommended(leewaySatPerVbyte: 1) };

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 }

// Set the maximum fee to the fastest network recommended fee at the time of claim
// with a leeway of 1 sats/vbyte
config.maxDepositClaimFee = { type: 'networkRecommended', leewaySatPerVbyte: 1 }

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 MaxFee.Rate({ satPerVbyte: BigInt(10) })

// Set a maximum fee of 1000 sat
config.maxDepositClaimFee = new MaxFee.Fixed({ amount: BigInt(1000) })

// Set the maximum fee to the fastest network recommended fee at the time of claim
// with a leeway of 1 sats/vbyte
config.maxDepositClaimFee = new MaxFee.NetworkRecommended({ leewaySatPerVbyte: BigInt(1) })

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: MaxFee.rate(satPerVbyte: BigInt.from(10)));

// Set a maximum fee of 1000 sat
config = config.copyWith(
    maxDepositClaimFee: MaxFee.fixed(amount: BigInt.from(1000)));

// Set the maximum fee to the fastest network recommended fee at the time of claim
// with a leeway of 1 sats/vbyte
config = config.copyWith(
    maxDepositClaimFee:
        MaxFee.networkRecommended(leewaySatPerVbyte: BigInt.from(1)));

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 = MaxFee.RATE(sat_per_vbyte=10)

# Set a maximum fee of 1000 sat
config.max_deposit_claim_fee = MaxFee.FIXED(amount=1000)

# Set the maximum fee to the fastest network recommended fee at the time of claim
# with a leeway of 1 sats/vbyte
config.max_deposit_claim_fee = MaxFee.NETWORK_RECOMMENDED(leeway_sat_per_vbyte=1)

// 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.MaxFee(breez_sdk_spark.MaxFeeRate{SatPerVbyte: 10})
config.MaxDepositClaimFee = &feeRateInterface

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

// Set the maximum fee to the fastest network recommended fee at the time of claim
// with a leeway of 1 sats/vbyte
networkRecommendedInterface := breez_sdk_spark.MaxFee(breez_sdk_spark.MaxFeeNetworkRecommended{LeewaySatPerVbyte: 1})
config.MaxDepositClaimFee = &networkRecommendedInterface

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.

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

// 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

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

Optimization configuration

The SDK can automatically optimize the Spark leaf set to maximize unilateral exit efficiency or increase payment speed. Fewer, larger leaves allow more funds to be exited unilaterally, while having more leaves enables payments without requiring swaps, improving payment speed.

This configuration controls optimization through the following options:

Automatic optimization enabled: whether optimization runs automatically when a payment is sent or received. Enabled by default.
Multiplicity: the desired multiplicity for the leaf set. Values range from 0 to 5. Default value is 1. Setting it to 0 fully optimizes for unilateral exit efficiency. Setting it to a value greater than 0 also optimizes for payment speed, with higher values prioritizing payment speed more aggressively at the cost of higher unilateral exit fees.

See Custom leaf optimization for more information and recommendations on how to configure optimization.

Rust

let mut config = default_config(Network::Mainnet);
config.optimization_config = OptimizationConfig {
    auto_enabled: true,
    multiplicity: 1,
};

Swift

var config = defaultConfig(network: Network.mainnet)
config.optimizationConfig = OptimizationConfig(autoEnabled: true, multiplicity: 1)

Kotlin

val config = defaultConfig(Network.MAINNET)
config.optimizationConfig = OptimizationConfig(autoEnabled = true, multiplicity = 1u)

var config = BreezSdkSparkMethods.DefaultConfig(Network.Mainnet) with
{
    optimizationConfig = new OptimizationConfig(autoEnabled: true, multiplicity: 1)
};

Javascript

const config = defaultConfig('mainnet')
config.optimizationConfig = { autoEnabled: true, multiplicity: 1 }

React Native

const config = defaultConfig(Network.Mainnet)
config.optimizationConfig = { autoEnabled: true, multiplicity: 1 }

Flutter

var config = defaultConfig(network: Network.mainnet).copyWith(
    optimizationConfig:
        OptimizationConfig(autoEnabled: true, multiplicity: 1));

Python

config = default_config(network=Network.MAINNET)
config.optimization_config = OptimizationConfig(auto_enabled=True, multiplicity=1)

config := breez_sdk_spark.DefaultConfig(breez_sdk_spark.NetworkMainnet)
config.OptimizationConfig = breez_sdk_spark.OptimizationConfig{AutoEnabled: true, Multiplicity: 1}

Keyboard shortcuts

Breez SDK - Nodeless (Spark)