Breez SDK

What Is Breez SDK?

Breez SDK is a free, open-source development kit created by Breez Technology that enables developers to integrate instant, non-custodial Bitcoin payments into applications. Rather than requiring teams to manage Lightning nodes, handle channel operations, or build swap infrastructure from scratch, the SDK abstracts these layers behind a high-level API. Developers interact with simple functions for sending, receiving, and managing payments while the SDK handles the protocol-level complexity underneath.

Breez Technology, founded in 2018 in Tel Aviv, was one of the earliest commercial ventures focused on Lightning and is credited with coining the term "Lightning Service Provider." The company first built the Breez wallet app, then extracted its infrastructure into a reusable SDK so any developer could embed the same capabilities. The result is an end-to-end solution covering node management, liquidity provisioning, inbound liquidity, on-chain swaps, and fiat on-ramp integrations.

How It Works

Breez SDK has evolved through three distinct implementations, each using a different backend architecture while exposing a consistent developer API.

Greenlight Implementation (Deprecated)

The original Breez SDK used Blockstream's Greenlight cloud infrastructure to host dedicated Lightning nodes for each user. The architecture had three components:

1. Signer: the integrating app runs a validating signer that holds the user's keys locally, ensuring self-custody
2. Node: each user gets a dedicated Lightning node hosted on Greenlight's cloud, spun up on demand when payments occur
3. LSP: a Lightning Service Provider handles channel opening, routing, and inbound liquidity so users can receive payments without manual channel management

When a user needed to receive a payment, the LSP opened a zero-conf channel to their Greenlight node, providing instant inbound capacity. For on-chain interoperability, the SDK used submarine swaps (similar to Loop) to convert between on-chain BTC and Lightning. The Greenlight implementation reached its final release (v0.8.0) in May 2025 and is now deprecated.

Liquid Implementation (Nodeless)

The Liquid implementation eliminates Lightning nodes and channels entirely. Instead, it uses the Liquid sidechain as a settlement layer with submarine and reverse submarine swaps to bridge into Lightning:

• Receiving: incoming Lightning payments are converted to L-BTC on Liquid via a submarine swap
• Sending: L-BTC from the user's Liquid wallet is converted to Lightning sats via a reverse submarine swap

This "nodeless" approach means no channel setup fees, no LSP dependency, and no channel closure delays. The Liquid sidechain also provides Confidential Transactions, hiding amounts and asset types for improved privacy. The tradeoff: Liquid is a federated sidechain with its own trust model, and block times average around one minute rather than being truly instant.

Spark Implementation (Newest)

The most recent implementation is built on Spark, a Bitcoin-native Layer 2 developed by Lightspark. Spark uses a statechain model where users hold real Bitcoin (not wrapped tokens) with instant settlement and no minimum transaction amounts.

Key advantages of the Spark-based implementation:

• Instant settlement without waiting for block confirmations or channel state updates
• Offline receiving: recipients can receive payments even while their device is offline
• Multi-asset support: stablecoins via the BTKN protocol alongside native Bitcoin
• No channel management, no LSP required, and no minimum payment thresholds

Language Support and Integration

The SDK core is written in Rust, with language bindings generated for multiple platforms:

A typical integration involves obtaining an API key from Breez, installing the platform-specific package, and initializing the SDK with a few configuration parameters. For example, initializing the Spark-based SDK in a Node.js environment:

import { connect, defaultConfig, Network } from "@aspect-build/breez-sdk-spark";

// Configure and connect
const config = await defaultConfig(Network.BITCOIN);
const sdk = await connect({ config, seed });

// Receive a Lightning payment
const invoice = await sdk.receivePayment({
  amountSat: 50000,
  description: "Order #1234"
});
console.log(invoice.bolt11);

// Send a Lightning payment
const result = await sdk.sendPayment({
  bolt11: "lnbc500u1p..."
});

The SDK handles all protocol negotiation, routing, and settlement internally. Developers work with straightforward send/receive functions rather than managing HTLCs, payment hashes, or channel state machines directly.

Breez SDK vs LDK

The most common comparison is between Breez SDK and LDK (Lightning Dev Kit). Both enable Lightning integration, but they serve different developer needs. For a comprehensive comparison, see the Bitcoin Wallet SDK Comparison research article.

A notable example: the wallet app lipa migrated from LDK to Breez SDK because running both a wallet client and all required services (LSP, channel state persistence, key management) proved too burdensome for a single development team.

Use Cases

Mobile Wallets

The most common use case is embedding Lightning payments into mobile wallet apps. Breez SDK handles the challenges specific to mobile: intermittent connectivity, background processing constraints, and the need for seamless key management. Apps like Cake Wallet (with over one million users) and Klever use the SDK to offer non-custodial Lightning alongside other assets. For deeper context on mobile wallet architecture, see the Lightning Mobile Wallets Architecture research article.

Neobanks and Fintech Apps

Financial applications use Breez SDK to add Bitcoin payment rails without building Lightning infrastructure. Deblock, a European neobank, integrated the SDK to offer customers instant Bitcoin payments alongside traditional banking services. The SDK's built-in fiat on-ramp integrations (including Cash App and MoonPay) simplify the bridge between fiat and Bitcoin.

Payment Processors

BTCPay Server, the open-source payment processor, integrated Breez SDK via a plugin. This lets merchants accept Lightning payments without running and managing their own LND or Core Lightning node, significantly lowering the operational burden for small businesses.

Social and Messaging Apps

Primal, a Nostr-based social application, replaced its previous custodial Bitcoin setup with Breez SDK to give users self-custodial wallets directly within the social app. This pattern of embedded wallets is growing across social platforms where users send tips, pay for content, or settle peer-to-peer transactions.

Key Features Beyond Payments

Beyond basic send and receive, the SDK includes several features that simplify production deployments:

• LNURL support: full compatibility with LNURL-Pay, LNURL-Withdraw, LNURL-Auth, Lightning addresses, and BOLT12 offers
• Fiat on-ramps: built-in integrations with Cash App and MoonPay via FiatLink, an open API standard Breez created for on/off-ramp providers
• Passkey login: seedless onboarding using WebAuthn biometric authentication, so users do not need to manage a seed phrase upfront (optional export remains available for recovery)
• Multi-device sync: real-time state backup and cross-device synchronization
• USD stable balance: volatility protection that denominate holdings in dollars while keeping funds in Bitcoin

Risks and Considerations

Trust Assumptions Vary by Implementation

Each SDK backend carries different trust tradeoffs. The Greenlight version relied on Blockstream's cloud infrastructure to host nodes. The Liquid version depends on the Liquid federation (a consortium of functionaries) to process transactions. The Spark version uses Spark's operator model. Developers should understand which trust assumptions their chosen implementation introduces and communicate them clearly to users.

Vendor Dependency

While the SDK is open source (MIT license), production deployments require an API key from Breez and depend on Breez-operated infrastructure for certain services. If Breez were to discontinue support for an implementation (as happened with the Greenlight version), applications would need to migrate. The deprecation of the Greenlight backend in 2025 demonstrated this risk: existing integrators had to move to either the Liquid or Spark implementation.

Reduced Flexibility

The SDK's opinionated design trades customization for convenience. Applications with unique requirements around routing, channel policies, or fee management may find the abstractions limiting. Teams needing fine-grained control over Lightning behavior may be better served by LDK or direct node implementations, accepting the higher integration effort.

Migration Between Implementations

Moving from one SDK backend to another (for example, Greenlight to Spark) is not a seamless upgrade. Each implementation manages funds differently, so migrations involve draining balances from one backend and re-depositing into another. Applications must handle this migration path carefully to avoid user confusion or temporary loss of access to funds.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.