Expand description
§Breez SDK
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.
§Getting Started
First, make sure you have your API Key and Invite Code ready (see API Key and Invite Code section below).
The following code initialize the SDK and make it ready to be used:
ⓘ
let mnemonic = Mnemonic::generate_in(Language::English, 12)?;
let seed = mnemonic.to_seed("");
let invite_code = Some("...".into());
let mut config = BreezServices::default_config(
EnvironmentType::Production,
"your API key".into(),
breez_sdk_core::NodeConfig::Greenlight {
config: GreenlightNodeConfig { partner_credentials: None, invite_code },
},
);
// Customize the config object according to your needs
config.working_dir = "path to an existing directory".into();
// Connect to the Breez SDK make it ready for use
let sdk = BreezServices::connect(
config,
seed.to_vec(),
Box::new(AppEventListener {}),
)
.await?;
We can now receive payments
ⓘ
let invoice = sdk.receive_payment(3000, "Invoice for 3000 sats".into()).await?;or make payments
ⓘ
let bolt11 = "...";
sdk.send_payment(bolt11.into(), Some(3000)).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;
}or fetch other useful infos, like the current mempool RecommendedFees
ⓘ
let fees: RecommendedFees = sdk.recommended_fees().await?;These different types of operations are described below in more detail.
§A. Initializing the SDK
There are two simple steps necessary to initialize the SDK:
- BreezServices::default_config to construct the sdk configuration
- BreezServices::connect to connect to your node and start all required Breez SDK services
The first step takes the EnvironmentType and NodeConfig as arguments. Although you can create your own config from scratch it is recommended to use the BreezServices::default_config method and customize it according to your needs. Once the NodeConfig is created it is passed to the BreezServices::connect method along with the seed and and implementation of EventListener which is used to notify the caller of SDK events.
Now your SDK is ready to be used.
§B. Sending and receiving Lightning payments
Supported BOLT11 operations are
- BreezServices::receive_payment to create an invoice
- BreezServices::send_payment to pay an invoice
- BreezServices::send_spontaneous_payment for keysend payments
§C. Receiving an on-chain transaction (swap-in)
- BreezServices::receive_onchain accepting an optional user-selected OpeningFeeParams for the case when the operation requires a new channel with the LSP
- BreezServices::in_progress_swap
- BreezServices::list_refundables to get a list of swaps
- BreezServices::refund to broadcast a transaction for failed or expired swaps
§D. Sending to an on-chain address (swap-out)
- BreezServices::fetch_reverse_swap_fees to get the current swap-out fees
- BreezServices::prepare_onchain_payment to prepare the swap-out
- BreezServices::pay_onchain to start the swap-out
- BreezServices::in_progress_onchain_payments to see any in-progress swaps
§E. Using LNURL
- parse the LNURL endpoint URL to get the workflow parameters.
- After getting the user input or confirmation, complete the workflow with BreezServices::lnurl_pay or BreezServices::lnurl_withdraw.
§F. Supporting fiat currencies
- BreezServices::list_fiat_currencies to get the supported fiat currencies
- BreezServices::fetch_fiat_rates to get the current exchange rates
- BreezServices::recommended_fees for the recommended mempool fees
§G. Connecting to an LSP
- BreezServices::list_lsps to get a list of available LSPs
- BreezServices::connect_lsp to connect to a chosen LSP
- BreezServices::lsp_info to get LspInformation on the currently selected LSP
§H. Utilities
Use parse to parse generic input. The input can come from the user, from a clicked link or from a QR code. The resulting InputType will tell you what the input is and how to treat it, as well as present relevant payload data in a structured form.
§Bindings
- C#
- Dart
- Go
- Kotlin
- Python
- React-Native
- Swift
§API Key and Invite Code
You will need an API Key to use the SDK, as well as an Invite Code when you create a new node.
To get both of them, please contact Breez via email at contact@breez.technology or at https://breez.technology/#contact-us-form
§Support
Join this telegram group.
Modules§
- binding
- Bindings for the Dart integration
- bitcoin
- Rust Bitcoin Library
- error
- grpc
- input_
parser - invoice
- lightning
- Rust-Lightning, not Rusty’s Lightning!
- lightning_
invoice - This crate provides data structures to represent lightning BOLT11 invoices and functions to create, encode and decode these. If you just want to use the standard en-/decoding functionality this should get you started:
- lnurl
- moonpay
- specs
- tonic_
wrap - utils
Macros§
- ensure_
sdk - with_
connection_ retry - Executes the given grpc call function. If an error is returned that indicates the connection broke, the call is tried again.
Structs§
- AesSuccess
Action Data - Payload of the AES success action, as received from the LNURL endpoint
- AesSuccess
Action Data Decrypted - Wrapper for the decrypted AesSuccessActionData payload
- ApiKey
Interceptor - Backup
Failed Data - Backup
Status - Bitcoin
Address Data - Wrapped in a [BitcoinAddress], this is the result of parse when given a plain or BIP-21 BTC address.
- Breez
Server - Breez
Services - BreezServices is a facade and the single entry point for the SDK.
- BuyBitcoin
Request - BuyBitcoin
Response - Callback
Response - Channel
- Lightning channel
- Check
Message Request - Request to check a message was signed by a specific node id.
- Check
Message Response - Response to a CheckMessageRequest
- Closed
Channel Payment Details - Represents the funds that were on the user side of the channel at the time it was closed.
- Config
- Configuration for the Breez Services
- Configure
Node Request - Represents a configure node request.
- Connect
Request - Represents a connect request.
- Currency
Info - Details about a supported currency in the fiat rate feed
- Custom
Message - External
Input Parser - Configuration for an external input parser
- Fiat
Currency - Wrapper around the CurrencyInfo of a fiat currency
- Full
Reverse Swap Info - Details of past or ongoing reverse swaps, as stored in the Breez local DB
- Greenlight
Credentials - Client-specific credentials to connect to and manage a Greenlight node in the cloud
- Greenlight
Device Credentials - Device credentials used to authenticate to Greenlight with the current device.
- Greenlight
Node Config - Htlc
- Invoice
Paid Details - Details of an invoice that has been paid, included as payload in an emitted BreezEvent
- LNInvoice
- Wrapper for a BOLT11 LN invoice
- LNOffer
- List
Payments Request - Represents a list payments request.
- List
Swaps Request - LnOffer
Blinded Path - LnPayment
Details - Details of a LN payment, as included in a Payment
- LnUrl
Auth Request Data - Wrapped in a [LnUrlAuth], this is the result of [parse] when given a LNURL-auth endpoint.
- LnUrl
Error Data - Wrapped in a [LnUrlError], this represents a LNURL-endpoint error.
- LnUrl
PayError Data - LnUrl
PayRequest - Represents a LNURL-pay request.
- LnUrl
PayRequest Data - Wrapped in a [LnUrlPay], this is the result of parse when given a LNURL-pay endpoint.
- LnUrl
PaySuccess Data - LnUrl
Withdraw Request - LnUrl
Withdraw Request Data - Wrapped in a [LnUrlWithdraw], this is the result of parse when given a LNURL-withdraw endpoint.
- LnUrl
Withdraw Success Data - Locale
Overrides - Locale-specific settings for the representation of a currency
- Localized
Name - Localized name of a currency
- LogEntry
- Internal SDK log entry
- LspInformation
- Details of supported LSP
- MaxChannel
Amount - Message
Success Action Data - Metadata
Filter - A metadata filter which can be applied when retrieving the transaction list
- Metadata
Item - Key-value pair in the LnUrlPayRequestData, as returned by the LNURL-pay endpoint
- Moonpay
Provider - Node
State - The node state of a Greenlight LN node running in the cloud.
- Onchain
Payment Limits Response - Open
Channel FeeRequest - Open
Channel FeeResponse - Opening
FeeParams - Dynamic fee parameters offered by the LSP for opening a new channel.
- Opening
FeeParams Menu - See OpeningFeeParamsMenu::try_from
- PayOnchain
Request - PayOnchain
Response - Payment
- Represents a payment, including its PaymentType and PaymentDetails
- Payment
External Info - Represents a payments external information.
- Payment
Failed Data - Payment
Path - Payment
Path Edge - Payment
Response - Represents a payment response.
- Prepare
Onchain Payment Request - See ReverseSwapFeesRequest
- Prepare
Onchain Payment Response - Contains fields describing the reverse swap parameters (see ReverseSwapPairInfo), as well as the resulting send and receive amounts.
- Prepare
Redeem Onchain Funds Request - We need to prepare a redeem_onchain_funds transaction to know what fee will be charged in satoshis. This model holds the request data which consists of the address to redeem on-chain funds to and the fee rate in. satoshis per vbyte which will be converted to absolute satoshis.
- Prepare
Redeem Onchain Funds Response - We need to prepare a redeem_onchain_funds transaction to know what a fee it will be charged in satoshis this model holds the response data, which consists of the weight and the absolute fee in sats
- Prepare
Refund Request - Prepare
Refund Response - Rate
- Denominator in an exchange rate
- Receive
Onchain Request - Receive
Payment Request - Represents a receive payment request.
- Receive
Payment Response - Represents a receive payment response.
- Recommended
Fees - Wrapper containing the result of the recommended fees query, in sat/vByte, based on mempool.space data
- Redeem
Onchain Funds Request - Redeem
Onchain Funds Response - Refund
Request - Refund
Response - Report
Payment Failure Details - Reqwest
Rest Client - Reverse
Swap Fees Request - Reverse
Swap Info - Simplified version of FullReverseSwapInfo, containing only the user-relevant fields
- Reverse
Swap Info Cached - Reverse
Swap Pair Info - Details about the reverse swap fees and parameters, at this point in time
- Route
Hint - A route hint for a LN payment
- Route
Hint Hop - Details of a specific hop in a larger route hint
- Send
Payment Request - Represents a send payment request.
- Send
Payment Response - Represents a send payment response.
- Send
Spontaneous Payment Request - Represents a send spontaneous payment request.
- Service
Connectivity Error - Service
Health Check Response - Represents a service health check response.
- Sign
Message Request - Request to sign a message with the node’s private key.
- Sign
Message Response - Response to a SignMessageRequest.
- Static
Backup Request - Static
Backup Response - Swap
- Summary of an ongoing swap
- Swap
Info - Represents the details of an on-going swap.
- Symbol
- Settings for the symbol representation of a currency
- Sync
Response - Internal response to a [crate::node_api::NodeAPI::pull_changed] call
- TlvEntry
- Represents a TLV entry for a keysend payment.
- Unspent
Transaction Output - UTXO known to the LN node
- UrlSuccess
Action Data
Enums§
- AesSuccess
Action Data Result - Result of decryption of AesSuccessActionData payload
- Amount
- Breez
Event - Event emitted by the SDK. To listen for and react to these events, use an EventListener when initializing the BreezServices.
- BuyBitcoin
Provider - Different providers will demand different behaviours when the user is trying to buy bitcoin.
- Channel
State - State of a Lightning channel
- Dynamic
FeeType - Environment
Type - Indicates the different kinds of supported environments for crate::BreezServices.
- Feerate
Preset - Different types of supported feerates
- Health
Check Status - Indicates the different service health check statuses.
- Input
Type - Different kinds of inputs supported by parse, including any relevant details extracted from the input
- Invoice
Error - LnUrl
Auth Error - Error returned by [crate::breez_services::BreezServices::lnurl_auth]
- LnUrl
Callback Status - Contains the result of the entire LNURL interaction, as reported by the LNURL endpoint.
- LnUrl
Error - LnUrl
PayError - Error returned by [crate::breez_services::BreezServices::lnurl_pay]
- LnUrl
Request Data - Generic struct containing the possible LNURL payloads returned when contacting a LNURL endpoint
- LnUrl
Withdraw Error - LnUrl
Withdraw Result - LnUrlCallbackStatus specific to LNURL-withdraw, where the success case contains the invoice.
- Network
- The different supported bitcoin networks
- Node
Config - Node
Credentials - Payment
Details - Wrapper for the different types of payments
- Payment
Status - The status of a payment
- Payment
Type - Different types of supported payments
- Payment
Type Filter - Different types of supported filters which can be applied when retrieving the transaction list
- Report
Issue Request - Represents a report issue request.
- Reverse
Swap Status - The possible statuses of a reverse swap, from the Breez SDK perspective.
- Service
Connectivity Error Kind - Success
Action - Supported success action types
- Success
Action Processed - SuccessAction where contents are ready to be consumed by the caller
- Swap
Amount Type - Swap
Status - The status of a swap
- URISerialization
Error - Validated
Callback Response
Constants§
- ESTIMATED_
CLAIM_ TX_ VSIZE - ESTIMATED_
LOCKUP_ TX_ VSIZE - INVOICE_
PAYMENT_ FEE_ EXPIRY_ SECONDS - SWAP_
PAYMENT_ FEE_ EXPIRY_ SECONDS
Statics§
Traits§
- BuyBitcoin
Provider Api - Event
Listener - Trait that can be used to react to various BreezEvents emitted by the SDK.
- FiatAPI
- Trait covering fiat-related functionality
- Lnurl
Auth Signer - LogStream
- LspAPI
- Trait covering LSP-related functionality
- Rest
Client - SupportAPI
- Trait covering support-related functionality
- SwapperAPI
- Trait covering functionality involving swaps
Functions§
- add_
routing_ hints - build_
pay_ callback_ url - build_
withdraw_ callback_ url - get_
and_ check_ success - get_
derivation_ path - invoice_
pubkey - Try to take payee pubkey from the tagged fields, if doesn’t exist recover it from the signature
- mnemonic_
to_ seed - Attempts to convert the phrase to a mnemonic, then to a seed.
- parse
- Parses generic user input, typically pasted from clipboard or scanned from a QR.
- parse_
invoice - Parse a BOLT11 payment request and return a structure contains the parsed fields.
- parse_
json - parse_
with_ rest_ client - perform_
lnurl_ auth - Performs the third and last step of LNURL-auth, as per https://github.com/lnurl/luds/blob/luds/04.md
- validate_
invoice - validate_
lnurl_ pay - Validates invoice and performs the second and last step of LNURL-pay, as per https://github.com/lnurl/luds/blob/luds/06.md
- validate_
lnurl_ withdraw - Validates invoice and performs the second and last step of LNURL-withdraw, as per https://github.com/lnurl/luds/blob/luds/03.md
- validate_
network - validate_
request - validate_
user_ input