breez-sdk-docs/src/guide/getting_started.md

Getting Started

The Breez SDK enables mobile developers to integrate Lightning and bitcoin payments into their apps with a very shallow learning curve. The use cases are endless – from social apps that want to integrate tipping between users to content-creation apps interested in adding bitcoin monetization. Crucially, this SDK is an end-to-end, non-custodial, drop-in solution powered by Greenlight, a built-in LSP, on-chain interoperability, third-party fiat on-ramps, and other services users and operators need.

The Breez SDK provides the following services:

• Sending payments (via various protocols such as: bolt11, keysend, lnurl-pay, lightning address, etc.)
• Receiving payments (via various protocols such as: bolt11, lnurl-withdraw, etc.)
• Fetching node status (e.g. balance, max allow to pay, max allow to receive, on-chain balance, etc.)
• Connecting to a new or existing node.

Connecting to a node requires a seed (your master key) and credentials. The seed is a bip39 mnemonic and the credentials are retrieved by registering a new node or recovering an existing one.

Installing

Breez SDK is available in several platforms. Follow the Installing page for instructions on how to install on your platform.

Rust

The first step is to register a new node. In order to do that a seed is needed.

Registering a new node

let seed = <your seed>;
let invite_code = <your greenlight invite code>;

// register_node takes either greenlight credentials (certifate & key) or invite code. 
// At this example we are using the invite code option.
let credentials = BreezServices::register_node(Network::Bitcoin, seed, None, Some(invite_code)).await?;

Recovering an existing node

let seed = <your seed>;
let credentials = BreezServices::recover_node(Network::Bitcoin, seed).await?;

Once the credentials are retrieved they should be saved in a secured storage. The next step is to initialize the SDK and start the node:

Initializing the SDK

// Create the default config
let mut config = BreezServices::default_config(EnvironmentType::Production);

// Customize the config object according to your needs
config.api_key = Some("your API key".into());
config.working_dir = "path to an existing directory".into();

let sdk = BreezServices::init_services(
        config,
        seed.to_vec(),
        credentials.clone(),
        Box::new(AppEventListener {}),
    )
    .await?;

BreezServices::start(rt(), &sdk).await?;

At any point we can fetch our balance from the Greenlight node:

if let Some(node_state) = sdk.node_info()? {
    let balance_ln = node_state.channels_balance_msat;
    let balance_onchain = node_state.onchain_balance_msat;
}

Swift

The first step is to register a new node

Registering a new node

do {
 let seed = try mnemonicToSeed(phrase: "<mnemonics words>")
 let inviteCode = ""

 // register_node takes either greenlight credentials (certifate & key) or invite code.
 // At this example we are using the invite code option.
 let credentials = try registerNode(network: Network.bitcoin, seed: seed, registerCredentials: nil,  inviteCode: inviteCode)
} catch  {
  // handle error
}

Recovering an existing node

do {
  let seed = try mnemonicToSeed(phrase: "<mnemonics words>")
  let credentials = try recoverNode(network: Network.bitcoin, seed: seed)
} catch  {
  // handle error
}

Once the credentials are retrieved they should be saved in a secured storage. The next step is to initialize the SDK and start the node:

Initializing the SDK

// SDK events listener
class SDKListener: EventListener {
  func onEvent(e: BreezEvent) {
    print("received event ", e)
  }
}

// Create the default config
var config = defaultConfig(envType: EnvironmentType.production)

// Customize the config object according to your needs
config.apiKey = "your API key";
config.workingDir = "path to an existing directory";

do { 
  let sdk = try initServices(config: config, seed: seed, creds: credentials, listener: SDKListener());
  try sdk.start();
} catch{
    // handle error
}

At any point we can fetch our balance from the Greenlight node:

do {
  let nodeInfo = try sdk.nodeInfo()
  let lnBalance = nodeInfo?.channelsBalanceMsat
  let onchainBalance = nodeInfo?.onchainBalanceMsat
} catch {
  // handle error
}

React Native

The first step is to register a new node

Registering a new node

try {
    const seed = await mnemonicToSeed("<mnemonics words>");
    const inviteCode = "<your greenlight invite code>";

    // register_node takes either greenlight credentials (certifate & key) or invite code. 
    // At this example we are using the invite code option.
    const credentials = await registerNode(Network.BITCOIN, seed, null, inviteCode); 
} catch (error) {
    console.log(error)
}

Recovering an existing node

    const seed = await mnemonicToSeed("<mnemonics words>");
    const credentials = await recoverNode(Network.BITCOIN, seed);

Once the credentials are retrieved they should be saved in a secured storage. The next step is to initialize the SDK and start the node:

Initializing the SDK

// SDK events listener
addEventListener((type, data) => {
    console.log(`received event ${type}`);
})

// Create the default config
let config = defaultConfig(EnvironmentType.PRODUCTION)

// Customize the config object according to your needs
config.apiKey = "your API key";
config.workingDir = "path to an existing directory";

try {
    const sdkServices = await initServices(config, credentials.deviceKey, credentials.deviceCert, seed);
    await start();
} catch (error) {
    console.log(error);
}

At any point we can fetch our balance from the Greenlight node:

try {
    const nodeInfo = await nodeInfo();
    const lnBalance = nodeInfo.channelsBalanceMsat;
    const onchainBalance = nodeInfo.onchainBalanceMsat;
} catch (error) {
    console.log(error);
}

Go

The first step is to register a new node

Registering a new node

if seed, err := breez_sdk.MnemonicToSeed("<mnemonics words>"); err != nil {
    inviteCode := "<your greenlight invite code>"

    // register_node takes either greenlight credentials (certifate & key) or invite code. 
    // At this example we are using the invite code option.
    credentials, err := breez_sdk.RegisterNode(breez_sdk.NetworkBitcoin, seed, nil, &inviteCode)
}

Recovering an existing node

if seed, err := breez_sdk.MnemonicToSeed("<mnemonics words>"); err != nil {
    credentials := breez_sdk.RecoverNode(Network.BITCOIN, seed)
}

Once the credentials are retrieved they should be saved in a secured storage. The next step is to initialize the SDK and start the node:

Initializing the SDK

// SDK events listener
type BreezListener struct{}

func (BreezListener) OnEvent(e breez_sdk.BreezEvent) {
    log.Printf("received event %#v", e)
}

// Create the default config
config := breez_sdk.DefaultConfig(breez_sdk.EnvironmentTypeProduction)

// Customize the config object according to your needs
config.apiKey = "your API key"
config.workingDir = "path to an existing directory"

if sdkServices, err := breez_sdk.InitServices(config, seed, credentials, BreezListener{}); err != nil {
    sdkServices.Start()
}

At any point we can fetch our balance from the Greenlight node:

if nodeInfo, err := sdkServices.NodeInfo(); err != nil {
    lnBalance := nodeInfo.ChannelsBalanceMsat
    onchainBalance := nodeInfo.OnchainBalanceMsat
}

You are now ready to receive a Lightning payment.