Bitcoin Connect
Bitcoin Connect gives a website the wallet button, modal, WebLN provider and payment flow that would otherwise have to be built by hand. Its Nostr role is practical: it can turn NWC wallet connections into a WebLN-style interface for web apps.
A wallet connection layer, not a wallet
Bitcoin Connect is best understood as the user-interface and provider layer between a Lightning-powered website and the user's wallet. The project README says it includes web components for connecting to Lightning wallets and enabling WebLN. That is the right sentence to keep in your head: it gives a site a wallet connection surface, but it does not become the wallet.
For a Nostr reader, the important distinction is practical. Bitcoin Connect does not custody funds, route Lightning payments, run a Nostr relay, hold your nsec or replace an NWC wallet service. It helps a website obtain a WebLN-compatible provider, and one of the ways it can do that is by connecting to wallets through Nostr Wallet Connect.
That makes it a developer tool rather than a consumer wallet. A social client, merchant site, donation page, game, publication or tool can add a connect-wallet button, payment modal and provider request flow without inventing its own wallet UX. The user still needs a real wallet or wallet service behind the connection.
The project belongs in Developer Tools & Libraries because it lowers integration friction. It is the kind of package that disappears when everything works. The reader sees a button and a modal. The app developer sees a package, exported methods, connector configuration, event subscriptions and the responsibility to treat wallet permissions carefully.
Why it exists
Lightning web apps used to depend heavily on browser extensions or custom wallet-specific integration paths. If the user had Alby Extension or another WebLN provider installed, a website could ask `window.webln` to send a payment or create an invoice. If the user was on mobile, inside a PWA or using a browser without that extension, the experience was often worse.
Bitcoin Connect tries to make that gap less awkward. The README says websites only need to interface with WebLN to connect with multiple wallets, while Bitcoin Connect supplies the website-side component. In other words, the site can ask for a WebLN provider and let Bitcoin Connect help the user choose how that provider is created.
NWC is the key Nostr-era piece. Nostr Wallet Connect lets an app communicate with a remote Lightning wallet through Nostr relays, using an encrypted connection URI and wallet-service permissions. Bitcoin Connect can use an NWC URL to create a NostrWebLNProvider from the Alby SDK, then expose that provider through a WebLN-style interface.
This is useful because a web app can speak one web-facing interface even when the user's real wallet path differs. One user may have a desktop extension. Another may connect Alby Hub over NWC. Another may provide a generic NWC URL. Another may use CoinOS, LNbits or LNC through the connectors the project exposes. The app still needs to handle real payment state; Bitcoin Connect just makes the first mile more humane.
The public project is active and still cautious
The GitHub repository checked on June 14, 2026 was `getAlby/bitcoin-connect`, created on July 14, 2023, pushed on June 12, 2026 and licensed under MIT. GitHub metadata showed 150 stars, 69 forks, 60 open issues, TypeScript as the main language and topics including bitcoin, lightning, nostr, nwc, wallet and webln.
The package state needs a slightly careful reading. npm reported `@getalby/bitcoin-connect` version 3.12.3 and `@getalby/bitcoin-connect-react` version 3.12.3. The latest GitHub release endpoint still showed v3.12.2, published on February 18, 2026, with fixes around PayButton state, modal height and QR presentation.
That mismatch is not a scandal. It is a normal signal that package publication and GitHub release notes can lag each other. For developers, it means you should not infer the latest shipped npm behavior only from the releases tab. Pin the exact package version you deploy and read the package metadata, changelog, README and commits around that version.
The README also keeps an alpha warning. It says the package uses newer protocol features such as WebLN and NWC that have not been finalized and may have breaking changes or bugs. That warning matters more than the clean demo page. A library can be useful and still demand version pinning, integration tests and a rollback plan.
What the packages ship
The core package is `@getalby/bitcoin-connect`. Its package metadata describes it as web components to connect to a Lightning wallet and power a website with WebLN. It is an ESM package with CommonJS, module and type outputs, built from TypeScript and shipped with dependencies such as `@getalby/sdk`, `@getalby/lightning-tools`, `@lightninglabs/lnc-web`, `qrcode-generator` and `zustand`.
The React wrapper is `@getalby/bitcoin-connect-react`. It depends on the core package and declares React 18.2 or newer as a peer dependency. That wrapper exists so React apps can use components such as Button, PayButton, Connect and Payment without hand-wiring the web components directly.
The core export file shows the product shape. It exports `bc-button`, `bc-pay-button`, `bc-modal`, connector list components, balance and currency components, send-payment pages, connect and payment flows, store state, public API functions and provider classes. It also exposes WebLN provider classes for NWC, LNC and LNbits.
This matters because Bitcoin Connect is not only a pretty button. It is a bundle of UI, state, connector creation, local persistence, event subscriptions and WebLN-compatible provider access. A site integrating it should treat it as payment infrastructure inside the front end, not as decorative UI.
The main components
The README lists four obvious web components. `
The payment components accept invoice-related attributes and emit payment events. For example, the pay button can take a BOLT11 invoice, a payment-methods setting and a preimage for externally completed payment state. The payment flow can emit a `bc:onpaid` event with the WebLN payment response in the event detail.
The public API gives the same capability to JavaScript code. The common calls are `init`, `launchModal`, `launchPaymentModal`, `requestProvider`, `connect`, `connectNWC`, `disconnect`, `getConnectorConfig`, `refreshBalance` and event subscriptions such as `onConnected`, `onDisconnected`, `onModalOpened` and `onModalClosed`.
A developer should decide which layer owns the product flow. A simple static page might use a web component. A React checkout may use the wrapper. A custom app might call `requestProvider()` inside a user gesture and then call WebLN methods itself. The safer integration is the one where the app can clearly account for invoice state, wallet permissions and disconnect behavior.
NWC is one connector family
The connector index in the source maps several connector types to classes. The NWC family includes `nwc.alby`, `nwc.albyhub`, `nwc.generic`, `nwc.lnfi`, `nwc.coinos`, `nwc.flash`, `nwc.cashume`, `nwc.lnbits` and `nwc.rizful`. Each of those maps to the same NWCConnector class, while the display and authorization experience can differ by connector.
The NWCConnector source is intentionally small. It requires an `nwcUrl` in its config and returns a `NostrWebLNProvider` from `@getalby/sdk` with `nostrWalletConnectUrl` set to that URL. The heavy protocol work lives in the SDK and the wallet service behind the connection, not in a giant connector class.
NIP-47 is the relevant standard behind that URL. It describes how clients can access a remote Lightning wallet through a Nostr-based protocol. A wallet service has access to the wallet APIs, a client sends encrypted requests, relays carry events and the connection URI tells the client which service key, relay and secret to use.
Bitcoin Connect does not make every NWC connection equally safe. Safety depends on the wallet service, requested methods, budget rules, connection lifetime, relay choice and revocation path. A site that asks for broad wallet power because it is easier to code is misusing the convenience Bitcoin Connect provides.
Other connectors have different trust shapes
Bitcoin Connect can also use existing WebLN extension providers, LNbits and Lightning Node Connect. These connectors are not interchangeable from a security point of view. They may all end up looking like WebLN to the website, but their underlying custody and permission boundaries differ.
The LNbits connector requires an LNbits instance URL and an admin key. Its WebLN provider uses that key in the `X-Api-Key` header, calls LNbits wallet and payments endpoints, can make invoices, send payments and read balance, and throws for methods that are not implemented. An LNbits admin key in a browser-side config is a serious secret, so this path belongs only in controlled settings.
The LNC connector imports `@lightninglabs/lnc-web`, connects to LND through Lightning Node Connect and contains a source comment that says the user must trust the website not to use funds without permission. Its password constant is written as `ONLY CONNECT TO TRUSTED WEBSITES`, which is blunt and useful.
The extension connector path is familiar to WebLN users: if a browser extension already supplies a provider, Bitcoin Connect can use it as the default connector. That can be pleasant on desktop. On mobile or PWA surfaces, the NWC connector family is often the more important reason Bitcoin Connect exists.
Payment modals do not replace settlement logic
Bitcoin Connect can make invoice payment UX feel polished. The README says it supports an invoice payment UI with multiple options and can accept payments with a single line of code. That is true for the interface layer, but it should not be mistaken for complete commerce accounting.
The `launchPaymentModal` API takes an invoice, optional payment-method settings, an `onPaid` callback and an `onCancelled` callback. When WebLN pays through the connected provider, Bitcoin Connect can receive a WebLN payment response and mark the flow paid. If the user pays externally with another wallet, the library cannot automatically know that the invoice settled.
The README calls this out: for external peer-to-peer payments, the app needs to check the invoice itself and call `setPaid` when it has verified settlement. That is especially important for e-commerce, downloads, access unlocks, tickets, subscriptions and any action where payment state should trigger a durable server-side consequence.
A careful site treats Bitcoin Connect as the front-end payment assistant. The server or trusted backend still verifies invoice status, handles retries, avoids duplicate unlocks, records order IDs and decides what happens after cancellation, expiry or late payment. The modal is not the ledger.
Persistence is convenient and sensitive
The store source shows that Bitcoin Connect saves connection configuration to `localStorage` under `bc:config` when `persistConnection` is not set to false. It also stores selected currency under `bc:currency`. On boot, the library reads that state and reconnects if configuration is present.
That behavior is good for repeat use. A user who connected a wallet yesterday does not want to walk through the full connection ceremony every time a site loads. It is also security-relevant because the browser profile now holds wallet connection configuration that can be read by scripts running in that origin.
The config has a switch for this. `persistConnection` defaults to true, but a developer can set it to false when the app only needs a short connection or when storing connector configuration is not appropriate. The app should also expose a real disconnect path, because `disconnect()` clears saved config and unloads the connector.
Do not bury this behind vague copy. If a site remembers a wallet connection, tell the user how to disconnect. If the site only needs a one-time payment, consider avoiding persistence. If your page includes third-party scripts, analytics tags or user-generated HTML, local wallet configuration raises the stakes of every XSS bug.
Auto-connect uses the URL hash
Bitcoin Connect can automatically connect when a page loads with an encoded NWC URL in the hash parameter `nwc`. The config type describes this pattern and the store implementation checks whether the hash contains a `nostr+walletconnect://` URL with both relay and secret parameters.
The implementation then removes the `nwc` value from the hash and calls `connectNWC`. That cleanup is a good sign because NWC connection strings are sensitive. Leaving them in the visible URL, browser history, copied links, referrer flows or error screenshots would be a bad habit.
The feature is useful for one-click wallet connection flows. A wallet or authorization page can hand the user back to the app with a connection URI, and the app can finish the connection without asking the user to paste a long string. That is exactly the kind of user experience NWC needs if it is going to feel normal outside developer demos.
It still deserves caution. A site should avoid logging full URLs before the hash is cleared, avoid asking users to share connection URLs, and make sure failed auto-connect attempts do not expose secrets in visible error text. If auto-connect is inappropriate for a route, `autoConnect: false` exists for a reason.
The v3 migration changed important habits
The v3 migration guide is worth reading before copying old snippets from examples or older apps. The most important change is that `window.webln` is no longer set by default. If an app wants a global WebLN object, it must set it explicitly when connected.
That change is a safety improvement. The README warns that if you manually assign `window.webln`, you must also clear it on disconnect. Bitcoin Connect does not own the global object after you assign it, so a disconnected wallet can remain callable if the site forgets cleanup.
Other v3 changes moved configuration such as filters and app name into `init`, moved payment launching into `launchPaymentModal`, removed the need to render `
The lesson is boring in the best possible way: read the migration guide, pin a major version, and write a small integration wrapper in your own app rather than sprinkling old snippets through the codebase. Payment connection code ages faster than a normal button component.
Mobile and SSR need deliberate handling
Bitcoin Connect is attractive because it works on mobile browsers and PWAs, but the README still lists a known issue: NWC connectors do not work on iOS in non-secure contexts because `window.crypto.subtle` is unavailable. The practical answer is to test with HTTPS, even during mobile development, or use an HTTPS tunnel.
That issue is easy to miss if your desktop localhost test works. A developer may see a clean modal on a laptop and then wonder why a phone fails. NWC uses browser crypto APIs, and mobile browser security contexts matter. Treat HTTPS as part of the integration, not a final production polish step.
Server-side rendering has its own boundary. The README tells Next.js users to import and render components client-side only, for example with `next/dynamic` and `ssr: false`, and to use the `use client` directive in the App Router. That is because wallet APIs, custom elements and browser state live in the browser.
A polished integration should test desktop with an extension, desktop without an extension, mobile Safari, mobile Chrome, PWA install mode, a fresh browser profile, a returning profile with persisted config, and a route rendered by the production framework. The happy path is not enough for wallet UX.
Security starts with the host page
Bitcoin Connect's FAQ gives a direct safety warning: you should trust the website you connect your wallet with, and the site should prevent malicious third-party scripts from reading wallet connection configuration from memory or storage. That is not theoretical. The library deliberately stores connection state unless configured otherwise.
The README recommends Content Security Policy rules and XSS best practices. That is the right source trail. If a page can execute attacker-controlled JavaScript, a wallet connection helper can become the path from a cosmetic XSS bug to payment risk, balance exposure or connection-secret theft.
The safest product posture is layered. Use CSP. Avoid unnecessary third-party scripts on payment routes. Sanitize user content. Keep NWC permissions narrow. Prefer wallet-side budgets and confirmation dialogs. Separate marketing pages from payment surfaces when possible. Do not put admin keys or broad wallet credentials in browser-side code.
Users need a similar habit. Connect wallets to sites you trust. Prefer budgeted NWC connections. Use a dedicated wallet for experiments. Revoke connections you no longer use. If a site asks for spending access but only needs to receive a payment, slow down. Bitcoin Connect makes the prompt nicer; it cannot make a bad permission request safe.
What developers should test
Start with version and import behavior. Confirm the exact npm version, the React wrapper version if used, the build output, tree-shaking behavior, CSS variables, dark mode, modal layout and SSR boundaries. Test that your app initializes Bitcoin Connect once and does not create duplicate modals.
Then test connection behavior. Verify extension detection, NWC connect, generic NWC URL paste, auto-connect hash handling, failed relay connection, rejected wallet authorization, disconnect cleanup, persisted connection reload, `localStorage` clearing and the behavior when `persistConnection` is false.
Payment tests need real state checks. Use tiny invoices. Test WebLN internal payment, external wallet payment, expired invoice, cancelled modal, late settlement, repeated payment event, wrong invoice, amountless invoice when your backend supports it, payment verification and duplicate order unlock prevention.
Finally test failure language. The page should tell a user what happened without leaking secrets. It should not dump full NWC URLs into console logs, user-visible errors, analytics events or support screenshots. A payment integration is finished only when failure is understandable and boring.
Where it fits in the NWC ecosystem
The NWC docs point developers of web applications toward Bitcoin Connect because it does the front-end work of letting users connect from desktop and mobile devices or make one-time payments from wallets that do not yet support NWC. The NWC site also frames Bitcoin Connect as a simple library that combines NWC with WebLN for websites.
That gives Bitcoin Connect a bridge role. NWC is the wallet-to-app protocol. WebLN is the web-facing wallet API pattern many Lightning websites already understand. Bitcoin Connect lets those worlds meet in a way that can be presented to users as a normal wallet connection flow.
It pairs naturally with Alby Hub, Alby Cloud, Alby Extension, CoinOS, LNbits, Cashu.me and other wallet services appearing in the NWC ecosystem, but it is not limited to one brand story. The generic NWC connector is important because the protocol should not collapse into a single provider.
The most useful mental model is this: Bitcoin Connect sits on the website side of the connection. It helps the app ask for wallet capability. The wallet service, relay choice, permissions and user's real balance live behind that connection. The app should never pretend those layers are all the same thing.
What it is not
Bitcoin Connect is not a replacement for Alby Hub or any other wallet service. It can connect to Alby Hub through NWC, but the hub still holds the sub-wallets, permissions and Lightning backend. Bitcoin Connect is the web integration surface that asks for access.
It is not a Nostr identity client. A user does not need to read notes, follow people or manage a Nostr profile to use Bitcoin Connect. Nostr enters the picture when NWC uses relays and encrypted events to connect the app and wallet service.
It is not a guarantee that every wallet method is available. Connector providers differ. The LNbits and LNC connector code throws for several methods. NWC wallet services advertise or support different command sets. A site should feature-detect, handle missing methods and avoid assuming that every provider can pay, invoice, show balance and list transactions.
It is also not a complete compliance, accounting or fraud system. If you use it for commerce, you still need invoices, order state, settlement checks, refunds, support language, logs that do not leak secrets, and legal review appropriate to the product. The wallet modal is just one part of the money path.
Who should use it
Bitcoin Connect is a strong fit for web developers who want a Lightning-capable app without writing wallet-specific connection UX from scratch. It suits donation pages, creator tools, games, small commerce flows, paid publishing, nostr-native clients, prototypes, hackathon apps and products that want mobile-friendly NWC access.
It is also useful for teams migrating away from assuming `window.webln` will always exist. The request-provider pattern lets the app ask for a provider when the user acts, while the modal gives the user choices if no provider is already available. That is healthier than silently failing on mobile.
It is less suited to apps that need deep node control, complex accounting in the browser, unattended backend payments or full wallet administration. Those projects should look at the Alby SDK, NWC HTTP API, direct wallet-service APIs, backend NWC clients, LNbits server integration, LND, CLN or other infrastructure depending on the real need.
For readers, the decision question is direct: do you need a better website connection and payment flow, or do you need wallet infrastructure? If it is the first, Bitcoin Connect belongs on the shortlist. If it is the second, Bitcoin Connect may still appear in the front end, but it cannot be the backend answer by itself.
The practical close
Bitcoin Connect is one of the more practical pieces in the Nostr Wallet Connect stack because it cares about the moment a normal user actually meets the protocol. NWC can be elegant on paper and still fail if the website makes the user paste a long connection string, switch apps awkwardly or guess what a permission means.
The library's value is that it turns several messy edges into a familiar web pattern: a button, a modal, a provider, a payment flow and a disconnect path. That is exactly where many Lightning and Nostr apps lose users. Small UX infrastructure can change adoption more than another abstract protocol explainer.
The risk is the same convenience. A clean wallet button can make a dangerous site feel legitimate. A saved connection can make repeated use effortless while increasing exposure to scripts in the same origin. A generic WebLN provider can hide very different trust models behind the same method calls.
Use Bitcoin Connect with clear eyes. Pin versions. Read the connector code. Verify payments outside the modal. Use HTTPS. Keep NWC permissions small. Clean up `window.webln` if you set it manually. Harden the page against XSS. Then the library does what it should: it makes wallet-connected web apps feel usable without pretending the trust problem disappeared.
Useful Nostr context
These pages help readers compare the user-facing wallet button with the protocol and wallet-service layers underneath it.
- NIP-47 and Nostr Wallet Connect: The protocol behind Bitcoin Connect NWC URLs.
- Alby JavaScript SDK: The SDK route behind the NostrWebLNProvider path.
- Alby Hub: A common wallet-service target for NWC connections.
- NIP-07 signing model: Useful context for browser permissions and user trust surfaces.
- Wallets: The broader wallet map behind the modal.
Sources worth opening
Begin with the Bitcoin Connect README, demo site, package metadata and v3 migration guide. Then read the connector source files, the NWC docs, NIP-47, WebLN references and the security guidance around CSP and XSS before integrating it into a page that can move real sats.
- Bitcoin Connect official demo site
- getAlby/bitcoin-connect repository
- bitcoin-connect GitHub API metadata
- bitcoin-connect README
- Bitcoin Connect v3 migration guide
- bitcoin-connect package.json
- npm registry metadata for @getalby/bitcoin-connect
- npm registry metadata for @getalby/bitcoin-connect-react
- bitcoin-connect latest GitHub release API
- bitcoin-connect GitHub releases
- bitcoin-connect connector index
- bitcoin-connect NWC connector
- bitcoin-connect LNbits connector
- bitcoin-connect LNC connector
- bitcoin-connect public exports
- bitcoin-connect public API source
- bitcoin-connect state store
- bitcoin-connect boot state
- BitcoinConnectConfig type
- ConnectorConfig type
- NWC docs code examples for bitcoin apps and websites
- NWC docs getting started for apps and websites
- NWC docs best practices
- Nostr Wallet Connect official site
- NIP-47 Nostr Wallet Connect
- WebLN guide
- WebLN types repository
- Alby developer guide for Nostr Wallet Connect API
- Alby NWC JS SDK guide
- getAlby awesome-nwc list
- Alby blog introducing Bitcoin Connect
- OWASP Content Security Policy Cheat Sheet
- OWASP Cross Site Scripting Prevention Cheat Sheet
- Lit documentation
- Lightning Node Connect repository
- LNbits documentation
