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

Initializing the SDK API docs

Basic Initialization

The easiest way to initialize the SDK is with the connect method. This method requires:

  • The network, mnemonic, and Breez API key you intend to use
  • A storage directory path where the SDK can manage its data

Developer note

For WASM Web, SDK storage is managed using IndexedDB.

The storage is used to persist the SDK’s state. If you run multiple SDK instances, each must have its own unique storage directory.

Once connected, you’re ready to start interacting with the SDK.

Rust
// Construct the seed using mnemonic words or entropy bytes
let mnemonic = "<mnemonic words>".to_string();
let seed = Seed::Mnemonic {
    mnemonic,
    passphrase: None,
};

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

// Connect to the SDK using the simplified connect method
let sdk = connect(ConnectRequest {
    config,
    seed,
    storage_dir: "./.data".to_string(),
})
.await?;
Swift
// Construct the seed using mnemonic words or entropy bytes
let mnemonic = "<mnemonic words>"
let seed = Seed.mnemonic(mnemonic: mnemonic, passphrase: nil)

// Create the default config
var config = defaultConfig(network: Network.mainnet)
config.apiKey = "<breez api key>"

// Connect to the SDK using the simplified connect method
let sdk = try await connect(request: ConnectRequest(
    config: config,
    seed: seed,
    storageDir: "./.data"
))
Kotlin
// Construct the seed using mnemonic words or entropy bytes
val mnemonic = "<mnemonic words>"
val seed = Seed.Mnemonic(mnemonic, null)

// Create the default config
val config = defaultConfig(Network.MAINNET)
config.apiKey = "<breez api key>"

try {
    // Connect to the SDK using the simplified connect method
    val sdk = connect(ConnectRequest(
        config = config,
        seed = seed,
        storageDir = "./.data"
    ))
} catch (e: Exception) {
    // handle error
}
Javascript
// Call init when using the SDK in a web environment before calling any other SDK
// methods. This is not needed when using the SDK in a Node.js/Deno environment.
//
// import init, { BreezSdk, defaultConfig } from '@breeztech/breez-sdk-spark'
await init()

// Construct the seed using mnemonic words or entropy bytes
const mnemonic = '<mnemonic words>'
const seed: Seed = { type: 'mnemonic', mnemonic, passphrase: undefined }

// Create the default config
let config = defaultConfig('mainnet')
config.apiKey = '<breez api key>'

// Connect to the SDK using the simplified connect method
const sdk = await connect({
  config,
  seed,
  storageDir: './.data'
})
React Native
// Construct the seed using mnemonic words or entropy bytes
const mnemonic = '<mnemonics words>'
const seed = new Seed.Mnemonic({ mnemonic, passphrase: undefined })

// Create the default config
let config = defaultConfig(Network.Mainnet)
config.apiKey = '<breez api key>'

const sdk = await connect({
  config,
  seed,
  storageDir: `${RNFS.DocumentDirectoryPath}/data`
})
Flutter
// Call once on your Dart entrypoint file, e.g.; `lib/main.dart`
// or singleton SDK service. It is recommended to use a single instance
// of the SDK across your Flutter app.
await BreezSdkSparkLib.init();

// Construct the seed using mnemonic words or entropy bytes
String mnemonic = "<mnemonic words>";
final seed = Seed.mnemonic(mnemonic: mnemonic, passphrase: null);

// Create the default config
final config = defaultConfig(network: Network.mainnet)
    .copyWith(apiKey: "<breez api key>");

final connectRequest =
    ConnectRequest(config: config, seed: seed, storageDir: "./.data");

final sdk = await connect(request: connectRequest);
Python
# Construct the seed using mnemonic words or entropy bytes
mnemonic = "<mnemonic words>"
seed = Seed.MNEMONIC(mnemonic=mnemonic, passphrase=None)
# Create the default config
config = default_config(network=Network.MAINNET)
config.api_key = "<breez api key>"
try:
    # Connect to the SDK using the simplified connect method
    sdk = await connect(
        request=ConnectRequest(config=config, seed=seed, storage_dir="./.data")
    )
    return sdk
except Exception as error:
    logging.error(error)
    raise
Go
// Construct the seed using mnemonic words or entropy bytes
mnemonic := "<mnemonic words>"
var seed breez_sdk_spark.Seed = breez_sdk_spark.SeedMnemonic{
    Mnemonic:   mnemonic,
    Passphrase: nil,
}

// Create the default config
apiKey := "<breez api key>"
config := breez_sdk_spark.DefaultConfig(breez_sdk_spark.NetworkMainnet)
config.ApiKey = &apiKey

connectRequest := breez_sdk_spark.ConnectRequest{
    Config:     config,
    Seed:       seed,
    StorageDir: "./.data",
}

// Connect to the SDK using the simplified connect method
sdk, err := breez_sdk_spark.Connect(connectRequest)

return sdk, err

Developer note

On some platforms (e.g., Android, iOS), you must use an application-specific writable directory within the app’s sandbox for SDK storage.

Advanced Initialization

For advanced use cases where you need more control, you can configure the SDK using the Builder pattern. With the SDK Builder you can define:

  • Custom storage management (bring your own implementation)
  • Which chain service to use (custom or the SDK’s default)
  • Which REST client to use for LNURL requests (custom or the SDK’s default)
  • Which keyset to use for the signer (custom or the SDK’s default)
Rust
// Construct the seed using mnemonic words or entropy bytes
let mnemonic = "<mnemonic words>".to_string();
let seed = Seed::Mnemonic {
    mnemonic,
    passphrase: None,
};

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

// Create the default storage
let storage = default_storage("./.data".to_string())?;

// Build the SDK using the config, seed and storage
let builder = SdkBuilder::new(config, seed, storage);

// You can also pass your custom implementations:
// let builder = builder.with_chain_service(<your chain service implementation>)
// let builder = builder.with_rest_client(<your rest client implementation>)
// let builder = builder.with_key_set(<your key set type>, <use address index>)
let sdk = builder.build().await?;
Swift
// Construct the seed using mnemonic words or entropy bytes
let mnemonic = "<mnemonic words>"
let seed = Seed.mnemonic(mnemonic: mnemonic, passphrase: nil)

// Create the default config
var config = defaultConfig(network: Network.mainnet)
config.apiKey = "<breez api key>"

// Create the default storage
let storage = try defaultStorage(dataDir: "./.data")

// Build the SDK using the config, seed and storage
let builder = SdkBuilder(config: config, seed: seed, storage: storage)

// You can also pass your custom implementations:
// builder = builder.withChainService(<your chain service implementation>)
// builder = builder.withRestClient(<your rest client implementation>)
let sdk = try await builder.build()
Kotlin
// Construct the seed using mnemonic words or entropy bytes
val mnemonic = "<mnemonic words>"
val seed = Seed.Mnemonic(mnemonic, null)

// Create the default config
val config = defaultConfig(Network.MAINNET)
config.apiKey = "<breez api key>"

try {
    // Create the default storage
    val storage = defaultStorage("./.data")

    val builder = SdkBuilder(config, seed, storage)
    // You can also pass your custom implementations:
    // builder.withChainService(<your chain service implementation>)
    // builder.withRestClient(<your rest client implementation>)
    // builder.withKeySet(<your key set type>, <use address index>)
    val sdk = builder.build()
} catch (e: Exception) {
    // handle error
}
Javascript
// Call init when using the SDK in a web environment before calling any other SDK
// methods. This is not needed when using the SDK in a Node.js/Deno environment.
await init()

// Construct the seed using mnemonic words or entropy bytes
const mnemonic = '<mnemonic words>'
const seed: Seed = { type: 'mnemonic', mnemonic, passphrase: undefined }

// Create the default config
let config = defaultConfig('mainnet')
config.apiKey = '<breez api key>'

// Create the default storage
const storage = await defaultStorage('./.data')

// Build the SDK using the config, seed and storage
const builder = SdkBuilder.new(config, seed, storage)

// You can also pass your custom implementations:
// builder = builder.withChainService(<your chain service implementation>)
// builder = builder.withRestClient(<your rest client implementation>)
// builder = builder.withKeySet(<your key set type>, <use address index>)
const sdk = await builder.build()
React Native
// Construct the seed using mnemonic words or entropy bytes
const mnemonic = '<mnemonics words>'
const seed = new Seed.Mnemonic({ mnemonic, passphrase: undefined })

// Create the default config
let config = defaultConfig(Network.Mainnet)
config.apiKey = '<breez api key>'

// Create the default storage
const storage = await defaultStorage(`${RNFS.DocumentDirectoryPath}/data`)

const builder = new SdkBuilder(config, seed, storage)
// You can also pass your custom implementations:
// builder.withRestChainService("https://custom.chain.service", {
//   username: "service-username",
//   password: "service-password",
// });
const sdk = await builder.build()
Flutter
// Construct the seed using mnemonic words or entropy bytes
String mnemonic = "<mnemonic words>";
final seed = Seed.mnemonic(mnemonic: mnemonic, passphrase: null);

// Create the default config
final config = defaultConfig(network: Network.mainnet)
    .copyWith(apiKey: "<breez api key>");

// Create the default storage
final storage = defaultStorage(dataDir: "./.data");

final builder =
    SdkBuilder(config: config, seed: seed, storage: storage);
// You can also pass your custom implementations:
// builder.withRestChainService(
//     url: "https://custom.chain.service",
//     credentials: Credentials(
//         username: "service-username", password: "service-password"));
// builder.withKeySet(keySetType: <your key set type>, useAddressIndex: <use address index>);
final sdk = await builder.build();
Python
# Construct the seed using mnemonic words or entropy bytes
mnemonic = "<mnemonic words>"
seed = Seed.MNEMONIC(mnemonic=mnemonic, passphrase=None)
# Create the default config
config = default_config(network=Network.MAINNET)
config.api_key = "<breez api key>"
try:
    # Create the default storage
    storage = default_storage(data_dir="./.data")
    # Build the SDK using the config, seed and storage
    builder = SdkBuilder(config=config, seed=seed, storage=storage)
    # You can also pass your custom implementations:
    # builder.with_chain_service(<your chain service implementation>)
    # builder.with_rest_client(<your rest client implementation>)
    # builder.with_key_set(<your key set type>, <use address index>)
    sdk = await builder.build()
    return sdk
except Exception as error:
    logging.error(error)
    raise
Go
// Construct the seed using mnemonic words or entropy bytes
mnemonic := "<mnemonic words>"
var seed breez_sdk_spark.Seed = breez_sdk_spark.SeedMnemonic{
    Mnemonic:   mnemonic,
    Passphrase: nil,
}

// Create the default config
apiKey := "<breez api key>"
config := breez_sdk_spark.DefaultConfig(breez_sdk_spark.NetworkMainnet)
config.ApiKey = &apiKey

storage, err := breez_sdk_spark.DefaultStorage("./.data")
if err != nil {
    return nil, err
}

builder := breez_sdk_spark.NewSdkBuilder(config, seed, storage)
// You can also pass your custom implementations:
// builder.WithChainService(<your chain service implementation>)
// builder.WithRestClient(<your rest client implementation>)
// builder.WithKeySet(<your key set type>, <use address index>)
sdk, err := builder.Build()

return sdk, err

Disconnecting API docs

When you’re done using the SDK, call the disconnect method to release any resources in use.

This is particularly useful if you need to re-instantiate the SDK, such as when changing the mnemonic or updating configuration.

Rust
pub(crate) fn disconnect(sdk: &BreezSdk) -> Result<()> {
    sdk.disconnect()?;
    Ok(())
}
Swift
func disconnect(sdk: BreezSdk) throws {
    try sdk.disconnect()
}
Kotlin
fun disconnect(sdk: BreezSdk)  {
    try {
        sdk.disconnect()
    } catch (e: Exception) {
        // handle error
    }
}
Javascript
sdk.disconnect()
React Native
sdk.disconnect()
Flutter
void disconnect(BreezSdk sdk) {
  sdk.disconnect();
}
Python
def disconnect(sdk: BreezSdk):
    try:
        sdk.disconnect()
    except Exception as error:
        logging.error(error)
        raise
Go
func Disconnect(sdk *breez_sdk_spark.BreezSdk) {
    sdk.Disconnect()
}