How to Add Lightning Payments to Your App with Breez SDK

The Lightning Network crossed $1 billion in monthly transaction volume in 2025, with payment success rates above 99% in well-configured implementations. For developers, the question has shifted from whether to add Lightning payments to how to do it without managing nodes, channels, and liquidity themselves.

Breez SDK has emerged as a leading answer. In 2025 alone, over 30 apps integrated Lightning through the SDK, spanning prediction markets, social platforms, wallets, trading platforms, and healthcare finance applications. The appeal is straightforward: end-to-end, non-custodial Lightning integration without infrastructure management.

Here's how to actually implement it.

Understanding What Breez SDK Handles For You

Before diving into code, it helps to understand what you're not building. Traditional Lightning integration requires running a node, managing channel liquidity, handling backups, and dealing with the operational complexity of staying online. Breez SDK abstracts all of this through Lightning Service Providers (LSPs).

The SDK handles automatic channel creation, real-time payment backups, multi-app and multi-device support, and built-in liquidity management. Your app interacts with a clean API while the underlying infrastructure runs elsewhere.

As of 2025, Breez has shifted toward two primary implementations: Liquid (using Liquid Network) and Spark (a nodeless solution built on Bitcoin-native Layer 2 infrastructure). The older Native Greenlight version is being deprecated in favor of these simpler approaches.

Choosing Your Implementation Path

Breez SDK supports bindings for Rust, Dart, Swift, Kotlin, TypeScript, and WebAssembly. Your choice depends on your platform:

• Mobile apps (iOS): Swift bindings
• Mobile apps (Android): Kotlin bindings
• Cross-platform mobile (Flutter): Dart bindings
• Web applications: TypeScript or WebAssembly
• Backend services: Rust or TypeScript

The Spark implementation, released in 2025, is particularly attractive for new projects. It operates as a fully nodeless solution, eliminating server management entirely. For apps prioritizing simplicity and quick integration, this is often the right starting point.

Setting Up Your Development Environment

The SDK is free for developers. Start by adding the appropriate package to your project. For a Flutter app, your `pubspec.yaml` would include the Breez SDK Dart package. For a React Native project, you'd use the npm package.

The initial setup involves connecting to a Breez LSP. You'll need to generate or import a mnemonic seed phrase for the underlying wallet. In production, this seed belongs to your user, making the solution non-custodial.

```

// Pseudocode for initial connection

const sdk = await BreezSDK.connect({

mnemonic: userMnemonic,

network: "mainnet",

lspId: "your-lsp-id"

});

```

The actual implementation varies by language binding, but the pattern remains consistent: initialize with credentials, connect to the network, and you're ready to handle payments.

Handling Incoming Payments

Receiving Lightning payments requires generating invoices. The SDK handles the complexity of channel capacity and routing; you just specify the amount and description.

```

// Generate a payment request

const invoice = await sdk.receivePayment({

amountMsat: 100000, // 100 sats in millisatoshis

description: "Payment for coffee"

});

// Display invoice.bolt11 to the payer

```

The SDK supports multiple payment protocols: Bolt11 invoices, LNURL-Pay, Lightning addresses, standard BTC addresses, and (with the Spark implementation) Spark addresses and BTKN tokens.

For apps where users receive recurring payments, Lightning addresses provide a cleaner experience than generating individual invoices. The format looks like an email address (user@yourdomain.com), making it more user-friendly for senders.

Processing Outgoing Payments

Sending payments is similarly straightforward. The SDK parses various input formats automatically:

```

// Send to a Lightning invoice

const payment = await sdk.sendPayment({

bolt11: invoiceString

});

// Or send to a Lightning address

const payment = await sdk.sendPayment({

lnAddress: "merchant@example.com",

amountMsat: 500000

});

```

Payment status updates come through event listeners, allowing your UI to reflect pending, completed, or failed states in real time.

Channel Management (Or Rather, Not Managing It)

One of Breez SDK's core value propositions is that you don't manage channels directly. The LSP handles inbound liquidity, opening channels when needed, and routing optimization.

However, you should understand what's happening underneath. When a user receives their first payment, the LSP opens a channel. This involves an on-chain transaction, which means there's a minimum viable first payment amount (to cover channel opening costs) and some delay before the channel confirms.

Subsequent payments flow instantly over the established channel. The SDK abstracts these details, but your UX should account for first-payment scenarios differently than ongoing usage.

Implementing Passkey Login for Seedless Onboarding

Introduced in March 2026, Passkey Login addresses one of Bitcoin's persistent UX challenges: seed phrase management. Users can now authenticate using biometrics (Face ID, Touch ID, or device PIN) without ever seeing a 12 or 24-word backup phrase.

This doesn't compromise self-custody. The cryptographic keys still belong to the user; they're just protected by the device's secure enclave rather than a memorable word sequence.

For consumer apps where Lightning is a feature rather than the core product, this dramatically reduces onboarding friction. Users familiar with "Sign in with Apple" or fingerprint authentication find this flow intuitive.

```

// Initialize with Passkey instead of mnemonic

const sdk = await BreezSDK.connectWithPasskey({

passkeyCredential: webAuthnCredential,

network: "mainnet"

});

```

The tradeoff is recoverability. Traditional seed phrases work across any compatible wallet; passkeys are device-bound. Your app should offer seed phrase export for users who want that backup option.

Real-Time Balance and Transaction Monitoring

The SDK provides event streams for monitoring wallet state:

```

sdk.addEventListener('paymentReceived', (payment) => {

console.log(`Received ${payment.amountMsat / 1000} sats`);

updateBalance();

});

sdk.addEventListener('paymentSent', (payment) => {

console.log(`Sent ${payment.amountMsat / 1000} sats`);

updateBalance();

});

```

Balance queries return both spendable balance and pending amounts (funds in unconfirmed channels or in-flight payments). Display both clearly to avoid user confusion about why their "balance" doesn't match what they can spend.

Handling Edge Cases and Failures

Lightning payments can fail for several reasons: insufficient liquidity along the route, recipient offline, expired invoices, or network issues. The SDK returns detailed error codes.

Good UX requires handling these gracefully:

• Route not found: Suggest smaller amount or try again later
• Invoice expired: Prompt user to request new invoice from recipient
• Insufficient balance: Show clear balance and payment amount
• Timeout: Indicate payment status is uncertain; provide way to check

Payments that timeout are particularly tricky. The funds may have reached the recipient, or they may return after the timeout expires. Never assume a timeout means failure; query the payment status explicitly.

Testing Before Production

Breez SDK supports testnet and signet for development. Use these networks liberally before touching real funds. Testnet coins are free from faucets, allowing you to test payment flows, channel behavior, and edge cases without financial risk.

Integration testing should cover:

• First payment (channel opening) scenarios
• Rapid successive payments
• Payments at maximum channel capacity
• App backgrounding during payment processing
• Network interruption recovery

What This Costs

The SDK itself is free. Your costs come from Lightning routing fees (typically fractions of a cent per payment) and LSP fees for channel management. These are dramatically lower than traditional payment processing, with businesses reporting cost savings exceeding 80% compared to on-chain Bitcoin transactions.

For context, the average Lightning transaction size reached $223 in November 2025, up from $118 in 2024. This suggests Lightning has matured beyond micropayments into practical everyday commerce, which has implications for your app's target use cases.

The Limitations to Acknowledge

Breez SDK isn't the right choice for every scenario. Some honest tradeoffs:

Custodial reliance on LSPs: While users hold their keys, they depend on Breez's LSP infrastructure for liquidity and routing. This is a different trust model than running your own node.

Newer implementations: The Spark implementation is powerful but recent. Documentation and community examples are less mature than for older solutions.

Mobile-first design: While web support exists, the SDK's architecture assumes mobile contexts. Backend-only integrations may find other tools more suitable.

Regulatory ambiguity: Depending on jurisdiction, non-custodial Lightning integration may have licensing implications. This isn't a Breez-specific issue, but it affects any Lightning implementation.

Moving Forward

If you're building an app where payments are a feature (social tipping, creator monetization, in-app purchases, gaming rewards), Breez SDK offers a path to Lightning integration measured in days rather than months.

Start with the official documentation and example projects. The Dart and Swift implementations have the most mature examples. Join the Breez developer community for implementation questions; the SDK is actively developed and the team responds to developer feedback.

Lightning's trajectory suggests it could handle over 30% of all BTC transfers for payments and remittances by end of 2026 if current growth continues. Building that capability into your app now positions you ahead of that curve, whether or not the most optimistic projections materialize.