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
const 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
const 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>, <account number>)
// let builder = builder.with_payment_observer(<your payment observer implementation>)
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:
// await builder.withChainService(<your chain service implementation>)
// await builder.withRestClient(<your rest client implementation>)
// await builder.withKeySet(<your key set type>, <use address index>, <account number>)
// await builder.withPaymentObserver(<your payment observer 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>, <account number>)
    // builder.withPaymentObserver(<your payment observer implementation>)
    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
const 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>, <account number>)
// builder = builder.withPaymentObserver(<your payment observer implementation>)
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
const config = defaultConfig(Network.Mainnet)
config.apiKey = '<breez api key>'

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

const builder = new SdkBuilder(config, seed, storage)
// You can also pass your custom implementations:
// await builder.withChainService(<your chain service implementation>)
// await builder.withRestClient(<your rest client implementation>)
// await builder.withKeySet(<your key set type>, <use address index>, <account number>)
// await builder.withPaymentObserver(<your payment observer implementation>)
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>, accountNumber: <account number>);
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:
    # await builder.with_chain_service(<your chain service implementation>)
    # await builder.with_rest_client(<your rest client implementation>)
    # await builder.with_key_set(<your key set type>, <use address index>, <account number>)
    # await builder.with_payment_observer(<your payment observer implementation>)
    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>, <account number>)
// builder.WithPaymentObserver(<your payment observer implementation>)
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) async fn disconnect(sdk: &BreezSdk) -> Result<()> {
    sdk.disconnect().await?;
    Ok(())
}
Swift
func disconnect(sdk: BreezSdk) async throws {
    try await sdk.disconnect()
}
Kotlin
suspend fun disconnect(sdk: BreezSdk)  {
    try {
        sdk.disconnect()
    } catch (e: Exception) {
        // handle error
    }
}
Javascript
await sdk.disconnect()
React Native
await sdk.disconnect()
Flutter
Future<void> disconnect(BreezSdk sdk) async {
  await sdk.disconnect();
}
Python
async def disconnect(sdk: BreezSdk):
    try:
        await sdk.disconnect()
    except Exception as error:
        logging.error(error)
        raise
Go
func Disconnect(sdk *breez_sdk_spark.BreezSdk) {
    sdk.Disconnect()
}