Breez SDK
Breez SDK is not a social Nostr client. It is the payment engine that an app can embed when it wants users to send, receive, zap, settle or hold bitcoin-like balances without building a Lightning wallet stack from scratch.
Breez SDK is infrastructure, not a social app
Breez SDK belongs in a Nostr ecosystem map because Nostr apps need usable money, but the SDK itself is not a timeline, a profile client or a relay browser. It is infrastructure for builders who want bitcoin payments inside another product. A social client can use it for zaps. A marketplace can use it for checkout. A wallet can use it for send and receive flows. A service can use it to expose a user wallet through a protocol surface. The reader should therefore judge Breez SDK like a payment engine, not like an app with a nice feed.
That difference matters because payment infrastructure has a different failure mode from social software. A broken feed is annoying. A broken payment backend can strand funds, hide fees, confuse recovery, leak metadata or authorize a transfer the user did not understand. Breez's public positioning is ambitious: instant non-custodial bitcoin, broad language support, passkey onboarding, stable balance, multi-device sync, contacts, external signer support, on-ramps and server mode. Those are not small interface features. They are parts of a wallet system that other products inherit when they integrate the SDK.
The useful mental model is simple. Breez SDK is the layer that lets an app say yes to value transfer without asking every product team to become a Lightning wallet company. That can be good for Nostr because clients, commerce tools and creator apps need small payments to feel native. It also means the builder must understand which Breez implementation is being used, where keys live, what servers are contacted, how payment state is synchronized and what Nostr permissions are created when NWC enters the picture.
The product line has several eras
Breez SDK is not one static repository. The public footprint shows an evolution. The Greenlight implementation is the older Lightning-node style branch. The Liquid implementation moved the SDK toward a nodeless model using Liquid and Lightning swaps. The Spark implementation is now the public center of the product page, described as built on Spark, a Bitcoin-native Layer 2 with instant settlement, no minimum limits and multi-asset support. A reader who only sees the words Breez SDK can miss that the underlying tradeoffs changed over time.
The GitHub data checked on June 13, 2026 reflects that split. The `breez/breez-sdk-greenlight` repository is the oldest and largest by stars among the branches checked here, with a latest release `0.8.0` from May 20, 2025 and later commits including NWC URI parsing work. The `breez/breez-sdk-liquid` repository has release `0.12.2` from April 6, 2026 and commits in May 2026. The `breez/spark-sdk` repository is younger, created in June 2025, with release `0.15.1` published June 9, 2026 and commits on June 12, 2026.
This is why a builder should never integrate from a logo alone. Spark, Liquid and Greenlight can all be described under the Breez SDK umbrella, but they do not ask the same questions from the app. Spark brings passkeys, stable balance, Spark addresses, private mode defaults and sync-server decisions. Liquid brings Liquid-sidechain behavior, swaps and a documented NWC plugin. Greenlight brings a more traditional self-custodial Lightning service story. The right article question is not whether Breez SDK is good in the abstract. It is which branch you are shipping and what that branch makes true.
Spark is the current center of gravity
The Breez SDK product page now points builders first to Breez SDK - Spark. The Spark documentation describes an end-to-end solution for integrating instant non-custodial bitcoin into apps and services, and the main SDK page lists more than 75 integrated apps or services. Spark is where the product language around passkey login, stable balance, multi-device and app sync, contacts, external signer support, on-ramps and multi-user server mode becomes most visible.
From a developer standpoint, Spark is not merely a payment button. The docs cover initialization, payment parsing, sending, receiving, listing payments, token payments, conditional payments, LNURL, Lightning addresses, stable balance, custom configuration and user-experience guidance. The npm package `@breeztech/breez-sdk-spark` was at `0.15.1` when checked, matching the latest GitHub release. The React Native Spark bindings also showed `0.15.1`, which matters because many Nostr and wallet products are mobile first.
For the reader, the most important part of Spark is the shift from raw Lightning-node operations to embedded wallet behavior. A product can prepare a payment, show estimated fees, choose whether to send through Lightning or Spark where possible, receive through Lightning invoices, Bitcoin addresses or Spark addresses, and list payment history. That is powerful, but it makes the app responsible for explaining payment methods, fees, recovery and trust. The SDK lowers the implementation burden. It does not remove the need for a serious wallet UX.
Liquid still matters because NWC is explicit there
Breez SDK - Liquid is not the default headline on the current SDK marketing page, but it is still one of the most important sources for Nostr readers because its documentation has a detailed Nostr Wallet Connect guide. The Liquid docs describe a nodeless non-custodial bitcoin integration using the Liquid Network and Lightning, with send and receive support for BOLT11, BOLT12, BIP353, LNURL and Lightning addresses, plus Liquid-side multi-asset support and real-time backup.
The Liquid NWC guide is concrete. It says Nostr Wallet Connect can control a Breez SDK instance from any NIP-47 compatible Nostr application. It shows the NWC service being started as a plugin after the SDK connects. The config can include custom relay URLs, a custom Nostr secret key and a listen-to-events option. The service can return wallet pubkey and relay information, and it has event listeners for connected, disconnected, connection-expired, connection-refreshed, pay-invoice and zap-received events.
That is the most direct Nostr bridge in Breez SDK today. A Nostr app does not need Breez to become a social client. It needs a wallet service that can answer NIP-47 requests over relays. The Liquid implementation shows how a Breez SDK instance can become that wallet service. The security reading is obvious: the app should treat the NWC secret, relay list, wallet service key and listener behavior as payment authority. A copied connection string is not a login nicety. It is an operational capability.
Greenlight remains part of the background
Greenlight is the older branch in the public Breez SDK family. It matters because many people first encountered Breez SDK as a way to get a self-custodial Lightning experience without hosting every part of node infrastructure themselves. BTCPay Server's Breez plugin documentation still frames Breez SDK and Greenlight together as a way to enable Lightning for stores with built-in liquidity and channel automation.
The `breez/breez-sdk-greenlight` repository still exists, is MIT licensed, and had a 2025 release line when checked. Its more recent commits are not the same kind of product signal as the Spark branch, but they show why old references cannot simply be ignored. Some integrations, documents and mental models still say Breez SDK while meaning Greenlight. Others now mean Liquid. The current product page means Spark first. That ambiguity is manageable only when builders name the implementation.
If you are auditing a Nostr wallet, marketplace or social app that says it uses Breez, ask for precision. Is it Greenlight, Liquid, Spark or a binding package around one of those implementations? Does it run inside a mobile app, a browser, a server or a point-of-sale system? Does it use a Breez API key? Does it depend on Breez-operated services? Does it expose NWC? A good integration can answer those questions plainly because the answers determine custody, availability, payment methods and failure recovery.
Where Nostr enters the SDK
The Nostr relevance is narrower and more interesting than a category label. Breez SDK is not posting Nostr notes. It intersects with Nostr where wallet control, payment notification and identity-adjacent key discovery matter. The clearest example is NWC in the Liquid documentation. NIP-47 defines a way for a client to access a remote Lightning wallet by sending encrypted request events through relays to a wallet service. That is exactly the kind of bridge a Nostr app needs when it wants to pay invoices without holding funds itself.
NIP-47 uses event kinds for info, request, response and notification traffic. The connection URI contains a wallet service public key, relay URL and a client secret. The client sends encrypted requests such as `pay_invoice`, `make_invoice`, `lookup_invoice`, `list_transactions`, `get_balance` and `get_info`; the wallet service sends encrypted responses. The protocol recommends unique keys per connection and avoids linking the user's main identity key to payment activity. Those details are not abstract standards trivia. They define the permission boundary for every NWC-enabled app.
Spark adds a different Nostr-shaped detail through passkey login. The docs say passkey-derived wallet labels can be discoverable via Nostr relays, and the RP ID `keys.breez.technology` can help cross-app passkey sharing when configured. That is not the same as NWC, but it still means Nostr can appear in account and key discovery. A builder should explain this honestly. Nostr in Breez SDK can mean wallet control over NIP-47, or relay-assisted discovery around passkeys. Both are infrastructure uses, not a social-feed feature.
Payment preparation is the safety surface
Breez SDK - Spark puts a preparation step before sending. The docs describe payment sending as prepare, then send. During preparation, the SDK checks the input type and returns fees so the app can confirm them before the payment is created. That is the right shape for payment UX. The user should not learn about fees, routes or payment type only after funds have moved.
The supported input surface is broad. Spark can prepare payments for Lightning invoices, Bitcoin addresses, Spark addresses and Spark invoices. A BOLT11 invoice can be amountless, and if a Lightning invoice also carries a Spark fallback, the SDK can expose the choice between Lightning fee and Spark transfer fee. The builder therefore has to decide what to show. Hiding that choice may keep the interface clean, but it also hides the reason a payment took one path instead of another.
This matters especially in Nostr products because zaps and small payments are intentionally lightweight. The payment can feel like a reaction button. Breez SDK can help make that possible, but a social app still needs limits, confirmation rules, sensible defaults and clear error states. If the app wraps Breez SDK behind NWC, the NWC permission and the SDK payment-preparation surface must line up. A user should know what the app can ask the wallet to do and what the wallet will display before sending.
Receiving is more than showing a QR code
Receiving payments is often treated as the easy half of a wallet, but Breez SDK shows why it is not only a QR code. Spark's receive documentation says the SDK currently supports receiving by Lightning, Bitcoin and Spark. A Lightning receive flow can generate a BOLT11 invoice with optional amount and expiry. The docs also note that a payment may fall back to a direct Spark payment if the payer's client supports it.
The user-experience guidance around receiving is practical. Breez recommends showing an LNURL-Pay QR code by default because it is reusable and widely supported, with BOLT11 as a fallback for one-off payment requests. It recommends exposing a human-readable Lightning address and making fees or limits visible before users attempt payment. That is exactly the kind of detail that separates a real wallet integration from a demo.
A Nostr app that receives zaps, donations, marketplace payments or AI-agent payments must keep this visible. The payer may use one method, the recipient may see another, and the app may be holding payment state in an SDK database, a sync server and Nostr events at the same time. If receipt state is wrong, users may think a zap failed, a product did not unlock or a sender did not pay. The integration should test one-time invoices, reusable addresses, expiration, fallback behavior, duplicate attempts and what another client sees.
Passkeys change the custody conversation
Spark's passkey work is one of the most important parts of the newer Breez SDK story. The docs describe passkey login as a way for users to access a wallet with biometrics, face scan, fingerprint or device PIN instead of writing down and safeguarding a seed phrase on day one. It uses the WebAuthn PRF extension to derive wallet keys deterministically, regenerating keys on demand when the user authenticates.
That sounds smoother than old seed handling, but it is not magic. Passkeys move risk into platform support, relying-party configuration, device ecosystems, backup behavior and recovery design. The docs say `keys.breez.technology` can serve as a common relying party to enable cross-app passkey sharing, and that applications need their origins or app identifiers authorized. That is a serious product choice, not just a login button.
The seed guidance is still relevant. Breez's own UX page says onboarding should be smooth, but users should be encouraged to back up and understand recovery. It recommends allowing seed backup after wallet creation or after the first received payment, explaining the need to save the seed phrase and considering partial re-entry validation. A builder using Breez SDK should decide where passkey convenience ends and explicit recovery education begins. The user deserves a wallet that is easy to start and still understandable when a phone is lost.
Sync and default services need scrutiny
A non-custodial SDK can still depend on operated services. Spark's configuration docs say the SDK can synchronize user data across different SDK instances through a real-time sync server, using a Breez instance by default unless the builder configures another URL or disables it. The same docs discuss the default LNURL server for receiving through LNURL and Lightning addresses. These defaults can be useful, but they are still dependencies.
The practical audit is to separate key custody from service availability. If the keys are held or derived by the user, that answers one question. It does not answer whether payments, addresses, sync, metadata, contacts or recovery labels depend on Breez infrastructure or another service chosen by the app. A good integration tells the user what happens when the sync server is unreachable, when LNURL routing fails, when a device is offline or when the app moves between mobile and web.
Private mode is another subtle configuration point. Spark's docs say private mode is enabled by default on first initialization unless disabled. They also warn against enabling preference for Spark over Lightning because it can remove a Lightning preimage proof and make received fallback payments harder to link back to the invoice. These are the details that make payment engineering real. The integration should decide which defaults are acceptable, test them, and document the consequences where the user makes a choice.
Stable balance and tokens add reach and risk
Breez's SDK page presents stable balance as a feature: users can hold their balance in USD to avoid BTC price volatility. The Spark docs go further. They describe token payments, stable-balance sending and automatic conversion when the user does not have enough bitcoin balance to cover a payment. For mainstream apps, that can be attractive. Users may want bitcoin payment rails without mentally holding every balance as volatile BTC.
The tradeoff is complexity. Stable balance introduces token identifiers, conversion options, slippage, token-to-bitcoin movement, token metadata and rules around sending an entire balance. The docs say builders can override conversion options when they need custom slippage settings. That means the application now needs to explain not only payment amount and fee, but also asset exposure and conversion risk.
For Nostr, this is especially important because social payments are emotionally small but technically real. A creator tip, a marketplace purchase or an app-to-agent payment might cross from a stable balance into bitcoin before it leaves. If the user interface only says pay, the user may not know what asset moved. Breez SDK can make that path work. The app has to make the path legible, especially where stablecoins, token balances or automatic conversion are involved.
Case studies show the intended market
Breez does not frame the SDK only as wallet-library plumbing. Its case studies page presents it as infrastructure for crypto wallets, neobanks, swaps, social apps and remittances. The Primal case study is the most relevant one for Nostr readers. It says Primal originally launched with a custodial wallet in 2023 because instant social payments were difficult to deliver non-custodially, then moved toward a Breez SDK - Spark based wallet path.
The Primal example explains the product-market target. A social app wants payments inside the feed without forcing the user into channel management, KYC friction or a separate wallet journey. The case study says the migration preserved Lightning addresses, balances and transaction histories while removing the custodial intermediary. Even if a reader treats marketing claims carefully, that is a useful signal: Breez SDK is designed for applications that want wallet behavior to feel native, not bolted on.
The same case-study library mentions other kinds of users: Cake Wallet, Deblock, Klever, Garden, Yolat and more. The product page says more than 75 teams have integrated the SDK. Those names do not prove every integration is safe, but they show the scope of the ambition. Breez is positioning itself as a general embedded bitcoin layer. Nostr apps should read it as a serious candidate for wallet and payment infrastructure, then still test the exact implementation they adopt.
What to test before building on Breez SDK
Start with the implementation branch. If a project says it uses Breez SDK, identify whether it uses Spark, Liquid, Greenlight or a binding package such as Go, React Native, Flutter, Swift, Kotlin, JavaScript, Python, C Sharp or WASM. Check the latest release, recent commits, open issues and package version. For Spark, the checked public release was `0.15.1`; for Liquid, GitHub release `0.12.2`; for Greenlight, `0.8.0`. Those dates should be rechecked before production work.
Then test the money path with small amounts. Initialize the SDK in the intended platform. Send a BOLT11 invoice. Receive through Lightning. Try a Bitcoin address if the branch supports it. Try a Spark address or fallback if you are using Spark. Inspect fees during preparation, not only after completion. List payment history. Disconnect and reconnect. Move between devices. Test offline states and sync recovery. If you use NWC, create a limited connection, revoke it and confirm the wallet stops answering requests.
Finally audit user-facing language. Does the app say who holds keys? Does it distinguish passkey recovery from seed backup? Does it explain whether a Breez default server is used? Does it expose fees, limits, expiry and payment method? Does it show when a stable balance conversion happens? Does it log enough detail for support without leaking payment secrets? A Breez SDK integration can be excellent, but only if the product around it treats payment UX as a first-class surface.
Who should care about Breez SDK
Breez SDK is most relevant to builders, wallet teams and product owners who want bitcoin payments in an app without asking users to manage the whole Lightning stack directly. That includes Nostr social clients, creator tools, commerce apps, point-of-sale flows, AI agents, mobile wallets, remittance products and embedded payment services. It is less relevant to a reader who only wants a finished wallet today, except as background for understanding what their app may be using underneath.
For Nostr specifically, Breez SDK matters because it can help turn zaps, wallet connections and app payments from novelty into ordinary behavior. NIP-47 gives apps a way to talk to wallets over relays. Breez's Liquid NWC plugin gives a concrete implementation path for a Breez SDK wallet service. Spark's passkey and sync work points to easier embedded wallet onboarding. Those pieces can make Nostr payments more usable if the app respects permission boundaries.
The durable lesson is that embedded payments are not automatically safer because they are smooth. Breez SDK removes a great deal of engineering burden, but it concentrates important decisions in defaults, configuration, services, recovery and UI. Use it as infrastructure, not a black box. If you are a builder, test every payment path before trusting it. If you are a user, ask which wallet engine an app uses when meaningful funds are involved. Convenience should earn trust through clear behavior, boring reliability and honest boundaries.
Sources worth opening
Open Breez's own SDK page first, then compare the Spark, Liquid and Greenlight repositories, Spark and Liquid documentation, NWC and NIP-47 references, package metadata, case studies and recent release data. Breez SDK is serious payment infrastructure, so the useful reading path is product promise, implementation branch, protocol surface, custody boundary and operational risk.
- Breez SDK official product page
- Breez SDK - Spark documentation
- Breez Spark SDK GitHub repository
- Breez SDK - Spark release 0.15.1
- Breez SDK - Spark npm package
- Breez SDK - Spark React Native package
- Breez SDK - Spark Go bindings
- Breez SDK - Spark React Native repository
- Spark payment fundamentals
- Spark initializing the SDK
- Spark sending payments
- Spark receiving payments
- Spark listing payments
- Spark passkey login
- Spark seed and key-management guidance
- Spark custom configuration
- Spark stable balance
- Spark token payments
- Spark conditional payments
- Spark end-user fees
- Breez SDK - Liquid documentation
- Breez SDK - Liquid GitHub repository
- Breez SDK - Liquid release 0.12.2
- Breez SDK - Liquid npm package
- Liquid connecting and API key setup
- Liquid Nostr Wallet Connect guide
- Breez SDK - Greenlight repository
- Breez SDK - Greenlight release 0.8.0
- Breez SDK documentation repository
- Breez GitHub organization
- Breez case studies
- Breez SDK Primal case study
- Breez Glow Playground
- Breez blog
- Breez Nostr profile
- NIP-47 Nostr Wallet Connect
- NWC references and SDKs
- Nostr Wallet Connect overview
- NIP-57 Lightning zaps
- BTCPay Server Breez plugin documentation
- Liquid Network announcement on Breez nodeless SDK
- Bitcoin Magazine on Breez Liquid SDK support
