How to Build Lightning Payments into Your App with Breez SDK

More than 75 applications now use Breez SDK to handle Lightning payments, from African fintech wallets to European Bitcoin brokers. The appeal is straightforward: developers get instant, non-custodial Bitcoin payments without running Lightning nodes or managing channel liquidity. But abstraction always involves tradeoffs. Here's how to actually build with the SDK, and what you should understand before shipping to production.

What Breez SDK Actually Does

Breez SDK is an open-source toolkit that wraps Lightning Network complexity behind high-level APIs. The Rust core compiles to bindings for Kotlin, Swift, React Native, Flutter, Python, Go, C#, and as of April 2025, WebAssembly for browser and Node.js deployments.

The SDK handles node management, channel operations, LSP liquidity, watchtower services, on-chain swaps, backups, and LNURL functionality. Your code calls simple methods like `send_payment` and `receive_payment`. The SDK does everything else.

As of mid-2026, Breez offers three implementations:

Liquid (nodeless): Released October 2024, this uses Liquid sidechain balances plus submarine swaps to bridge to Lightning. No channels to manage. Users see a simple wallet balance while sending and receiving Lightning payments.

Spark: Announced May 2025 and now in production, this builds on Lightspark's statechain Layer 2. Partner Bringin reported 70% lower send costs and settlement times dropping from 10-15 seconds to roughly 2 seconds after migrating users to Spark.

Greenlight (deprecated): The original implementation using Blockstream's hosted Lightning nodes reached its final release (v0.8.0) in May 2025. New integrations should use Liquid or Spark instead.

Getting Started with Integration

The integration pattern is consistent across implementations: initialize the SDK with configuration and a user seed, connect or create a wallet, then expose simple UI for sending and receiving.

Installation

For mobile apps, add the appropriate package. In Flutter:

```yaml

dependencies:

breez_sdk: ^0.11.0

```

For React Native:

```bash

npm install @breeztech/react-native-breez-sdk

```

The .NET bindings show active adoption, with NuGet reporting over 20,000 downloads by August 2025.

Initialization

The SDK requires a mnemonic seed phrase (which the user controls) and implementation-specific configuration:

```dart

import 'package:breez_sdk/breez_sdk.dart';

// Generate or recover a seed

final mnemonic = await BreezSDK.generateMnemonic();

// Configure for Liquid implementation

final config = LiquidConfig(

network: Network.mainnet,

workingDir: await getApplicationDocumentsDirectory(),

);

// Initialize

final sdk = await BreezSDK.connect(

config: config,

mnemonic: mnemonic,

);

```

For the Greenlight implementation (if maintaining legacy integrations), you'll need Greenlight certificates or invite codes plus a Breez API key for LSP access. BTCPay Server's Breez plugin documentation, updated July 2026, outlines this credential flow for merchants.

Sending Payments

The SDK supports multiple payment methods through a unified interface:

```dart

// Pay a BOLT11 invoice

await sdk.sendPayment(

bolt11: 'lnbc10u1p3...'

);

// Pay a Lightning address

await sdk.sendPayment(

destination: 'user@wallet.example.com'

);

// Pay via LNURL-Pay

await sdk.sendPayment(

lnurl: 'lnurl1dp68gurn8ghj7...'

);

```

The Liquid implementation converts your LBTC balance to Lightning satoshis via submarine swap automatically. Users don't see or manage this process.

Receiving Payments

Generating invoices is equally simple:

```dart

// Create a BOLT11 invoice

final invoice = await sdk.receivePayment(

amountMsat: 100000, // 100 sats

description: 'Coffee payment'

);

print(invoice.bolt11); // Display or encode as QR

```

The SDK handles inbound liquidity automatically. In the Greenlight implementation, Breez's LSP opens just-in-time channels when needed. The Liquid implementation sidesteps channels entirely.

Production Considerations

Error Handling

Lightning payments can fail for reasons outside your control: routing failures, insufficient liquidity, expired invoices. Build accordingly:

```dart

try {

final result = await sdk.sendPayment(bolt11: invoice);

if (result.status == PaymentStatus.complete) {

// Success path

}

} on PaymentError catch (e) {

if (e.type == PaymentErrorType.routeNotFound) {

// Suggest smaller amount or retry later

} else if (e.type == PaymentErrorType.invoiceExpired) {

// Request fresh invoice

}

// Log for debugging

}

```

State Management and Backups

The SDK provides real-time state backup, but your app architecture matters. Subscribe to payment events for UI updates:

```dart

sdk.paymentEvents.listen((event) {

switch (event.type) {

case PaymentEventType.pending:

updateUI(PaymentState.processing);

break;

case PaymentEventType.complete:

updateUI(PaymentState.success);

notifyUser();

break;

case PaymentEventType.failed:

updateUI(PaymentState.failed);

break;

}

});

```

Fiat On-Ramps

Breez announced FiatLink in November 2025, an open API standard for integrating fiat on/off-ramps. The SDK also supports MoonPay integration directly:

```dart

// Generate on-ramp URL

final onrampInfo = await sdk.prepareBuyBitcoin(

provider: OnrampProvider.moonpay,

amount: 50.00, // USD

);

// User completes KYC and purchase on provider's site

openUrl(onrampInfo.url);

// BTC arrives at generated address, SDK handles the rest

```

FiatLink supports SEPA transfers, credit cards, and bank transfers, with LNURL-Withdraw handling the actual Bitcoin delivery.

Understanding the Trust Tradeoffs

Breez SDK is non-custodial in that users hold their own keys. But the different implementations introduce varying trust assumptions.

The Liquid implementation relies on the Liquid federation, a group of 15 functionaries who collectively secure the sidechain. This isn't the same as trusting a single custodian, but it's not trustless either. Your users' LBTC balances depend on this federation operating honestly.

The Spark implementation centralizes some functionality with Lightspark and Spark Service Providers. Breez operates as an SSP alongside Lightspark. Performance is excellent (those 2-second settlements are real), but you're depending on this infrastructure layer.

For BTCPay Server merchants, there's an operational security consideration: storing a seed phrase on a shared BTCPay instance exposes it to the server administrator. The SDK being non-custodial doesn't help if your deployment architecture creates other custody relationships.

Real-World Integration Patterns

Q2 2025 saw 12 new apps integrate via Breez SDK, up from 10 in Q1 2025. The use cases offer useful patterns:

Wallets (Bitmo, Grimm App): Full Lightning support with fiat conversion. Grimm specifically targets low-bandwidth environments in Africa, showing the SDK works in constrained network conditions.

Merchant tools (Loom21): Inventory management with integrated payments. The interesting pattern here is treating Bitcoin as just another payment method alongside fiat, not a separate system.

Food delivery (Ordermoon): Streaming micropayments for tips and small transactions. The Spark implementation's lack of minimum transaction amounts makes this practical.

Cross-border payments (Yolat): Avoiding traditional remittance fees. Lightning's settlement speed matters more here than in domestic payments.

Relai, a European Bitcoin broker, integrated in early 2024 to support direct Lightning purchases deposited into users' self-custodial wallets, combining fiat on-ramp and Lightning in one flow.

Browser and Backend Deployments

The April 2025 WebAssembly announcement expanded Breez SDK beyond mobile. Browser-based wallets and Node.js backends can now integrate directly:

```javascript

import { BreezSDK } from '@breeztech/wasm';

const sdk = await BreezSDK.init({

workingDir: '/breez-data',

network: 'mainnet'

});

// Same API as mobile

const invoice = await sdk.receivePayment({

amountMsat: 100000,

description: 'Web payment'

});

```

This closes the gap for applications that need Lightning on web without forcing users to install extensions or connect external wallets.

When Breez SDK Makes Sense

The SDK fits best when you need Lightning payments but don't want to become Lightning infrastructure experts. The Q2 2025 integrations suggest the sweet spot is apps where payments are important but not the entire product: fintech features, tipping systems, merchant tools, content monetization.

If you need maximum trustlessness and don't mind operational complexity, running your own Lightning node with your own LSP relationships gives you more control. If you're building a dedicated Lightning wallet and want to differentiate on node management, Breez SDK's abstraction might hide features your users want.

For most applications adding Bitcoin payments to existing functionality, the SDK's "few lines of code" promise holds up. The complexity it hides (channel management, liquidity, backups, LNURL parsing) is substantial. You trade some control and introduce infrastructure dependencies, but you also ship faster and avoid classes of bugs that have plagued DIY Lightning integrations.

The 75+ applications using Breez SDK by mid-2026 suggest the tradeoff works for many teams. Just understand what you're trading before you commit.