CraysAlby JS SDK
Alby JS SDK is the builder layer that turns Nostr Wallet Connect from a protocol idea into JavaScript code: pay invoices, request payments, expose WebLN, authorize app connections, build wallet services, use OAuth when needed and test against real payment flows.
The library is small until you trace the paths
Alby JS SDK looks like a developer package, and technically that is what it is. Install @getalby/sdk, import the piece you need, pass credentials, call a method. The repository description says it is a JavaScript SDK for the Alby OAuth2 Wallet API and the Nostr Wallet Connect API. That sentence is accurate, but it undersells the product role. The SDK is one of the places where Alby turns Lightning from an external wallet action into something a web app, mobile app, command-line tool or backend can speak directly.
That makes it a real Nostr Hub entry even though end users rarely open it. Nostr Wallet Connect only becomes usable when app developers can create connections, send requests, receive replies, interpret errors and avoid touching raw wallet credentials. Alby JS SDK packages that work for JavaScript builders. It does not invent the whole payment system; it wraps the edges where NWC, WebLN, Alby Account, Alby Hub, relay communication and Lightning payment primitives meet.
The right route is Developer Tools under Apps, with strong links to Wallets. It should not be filed as a wallet and it should not be swallowed by a generic NIP-47 page. The reader needs to know what the SDK lets a builder do, which payment model is being used, which credentials move, which pieces are open-source, and where the operational risks sit.
What Alby built for JavaScript developers
The current README introduces the package with a practical promise: build zero-custody bitcoin payments into apps with a few lines of code. It says the SDK interacts with a Bitcoin Lightning wallet through Nostr Wallet Connect or through the Alby Wallet API. It also points builders to the Developer Sandbox before coding, which is telling. Alby is not only shipping a package; it is trying to define a developer workflow for payment-enabled apps.
The repository is public, TypeScript-heavy, MIT licensed, and organized around source code, examples, docs and generated API documentation. The visible docs include a high-level LN client, NWC client material, NostrWebLNProvider, wallet-service helpers and OAuth examples. The generated TypeDoc exposes classes and types such as LNClient, NWCClient, NostrWebLNProvider, NWAClient, NWCWalletService, OAuth clients, NIP-47 request and response types, budget renewal period types, transaction types and error classes.
That breadth matters because the SDK is not one feature. It is a toolkit for different integration styles. A simple app may only need a high-level payment helper. A web app may want WebLN compatibility. A native app or backend may want direct NWC control. A wallet builder may want to implement a wallet service. An older Alby Account integration may need OAuth. A developer comparing these paths should leave the page understanding that they are different trust models, not only different imports.
The LN client is the friendly front door
The LN client is the friendly surface. The docs describe the LN class as a high-level wrapper around NWCClient that is compatible with many different Lightning wallets. It can pay a BOLT11 invoice, pay a Lightning address in sats or fiat-denominated amounts, attach payment metadata, request a payment, listen for it being paid and react to a timeout. That is the kind of API a product developer actually wants when they are building a paid download, a subscription gate, an event ticket, a tip button or a small pay-per-use service.
The important part is that the simple API does not erase NWC. The easiest credential path is still an NWC connection secret. The developer can pass a nostr+walletconnect:// URI from a wallet service such as Alby Hub or another NWC-enabled wallet, then let the SDK deal with request and response behavior. That is good because most app developers do not want to manually assemble NIP-47 events on day one.
But the friendly surface can also hide too much if the builder is careless. A call like pay this invoice can represent a payment from a real user wallet, a test wallet, a server wallet, a sub-wallet or a broad production connection. The SDK makes the code shorter. It does not decide whether the connection should have a tiny budget, a short expiration, a limited method set or a clear user-facing label. Those choices still belong to the app.
NWCClient is where the protocol becomes explicit
When a builder needs direct control, the SDK exposes NWCClient. Alby's NWC docs describe two client surfaces: direct NWCClient access, which is more powerful and recommended outside a normal web page, and NostrWebLNProvider, which exposes a WebLN-compatible interface. That split is useful. It tells builders not to use a browser-shaped abstraction for every environment.
Direct NWCClient work exposes the core NWC ingredients: the full connection URL, the relay URL, the wallet pubkey and the secret used to sign request events. It can initialize from a stored NWC URL or create a new local secret and send the user through an authorization URL such as an Alby Hub app-connection page. In product language, this is how an app creates a wallet relationship without asking for a raw node password.
NIP-47 explains why that is powerful. NWC uses encrypted request and response events over relays between a client and a wallet service. The user identity key is not supposed to be the payment key; unique keys per connection are preferred; and connection keys can be revoked or constrained with budgets. Alby JS SDK gives JavaScript developers a usable handle on that pattern. The SDK therefore belongs in payment-capability territory, not merely in the npm-convenience bucket.
NostrWebLNProvider keeps old web patterns useful
WebLN predates the current NWC boom as the common browser-facing JavaScript interface for Lightning apps. The WebLN guide describes a provider as exposing window.webln on a page so a web app can call functions such as get info, send a payment, make an invoice or sign a message. Alby Extension helped make that pattern familiar. The problem is that browser extensions are not the only wallet surface anymore, especially on mobile.
Alby's NostrWebLNProvider is the bridge. It exposes a WebLN-compatible object while sending the actual wallet commands through Nostr Wallet Connect. A web app can continue to use WebLN-style calls, but the wallet connection can come from Alby Hub or another NWC wallet service rather than only a local extension. The docs are clear that not every WebLN method is necessarily supported, so builders have to check the specific methods their product needs.
This matters for migration. A product that already understands webln.sendPayment can add an NWC-backed provider without redesigning its entire payment layer. A website that wants mobile-friendly payments can use Bitcoin Connect or a similar wallet selector on top. A Nostr client that already has zap UX can improve payment flow without forcing users to install the same desktop extension. The compatibility layer is not glamorous, but it is how ecosystems move without breaking every app.
Nostr Wallet Auth changes the mobile connection story
The current Alby NWC JS SDK guide includes Nostr Wallet Auth, or NWA, as an alternative flow for Lightning apps to initialize NWC connections with mobile-first or self-custodial wallets. In that flow, the app creates a secret and generates a connection URI; the user opens it in a wallet; the wallet shows a confirmation page and creates the connection. That is different from copying a finished NWC secret from a wallet into the app.
The practical benefit is onboarding. A mobile user should not have to understand relay strings, wallet pubkeys and secret parameters just to approve an app connection. A QR code or deep link can move the process into the wallet where the user can see the app name and requested methods. Alby JS SDK's NWAClient gives JavaScript builders a path into that mobile-first world.
The risk is familiar: the connection flow is only as safe as the product copy and approval screen. If the wallet service approves a connection with vague permissions, the user has not gained much. If the app generates a broad request and hides why it needs those methods, the SDK has merely made a bad idea easier. NWA is a better UX path when builders use it to ask for narrowly scoped capabilities and explain them plainly.
The SDK can also help wallet builders
Alby JS SDK is not only for apps that want to spend from a wallet. The docs include NWCWalletService for wallet services that want apps to connect to them through NWC. The wallet-service guide says a wallet service needs to access wallet transactions and information, create NWC URIs, and send and receive NWC messages for connected apps. That is the other side of the same bridge.
A wallet service is the component that listens on relays, publishes its capability info event, receives encrypted requests, talks to the real Lightning backend, and returns encrypted responses or notifications. The SDK example shows publishing a wallet service info event with supported methods, creating per-client key pairs and subscribing to requests such as get_info. That is not a full wallet product. It is the low-level glue that a wallet team can build on.
This is important for the wider map because NWC needs both sides. Everyone talks about apps connecting to wallets, but the wallet side has to be implemented carefully too. A wallet service needs policy, budgets, revocation, logging, method support, relay reliability, error handling and backend safety. Alby Hub is one production example. The SDK makes it more plausible that other JavaScript wallet services can exist.
OAuth is still part of the Alby story
The SDK also covers the Alby OAuth Wallet API. That is a different route from NWC and should not be confused with it. OAuth is an account API model: a user authorizes an application, the app receives tokens with scopes, and the SDK can call Alby Wallet API methods such as account balance, account information, invoice creation, incoming and outgoing invoices, payment sending, keysend, boostagrams and webhooks.
Alby's Wallet API guide says the production endpoint spends real sats when paying invoices, and the OAuth docs show scope lists such as invoices read, account read, balance read, invoice creation and payments send. That is a traditional web API shape. It can be useful for applications already built around Alby Account or account-style integration, but it has a different custody and service boundary than a user-controlled NWC connection from Alby Hub.
A careful article needs to keep the distinction visible. NWC is the open protocol path for apps talking to wallet services over Nostr relays. OAuth is the Alby Wallet API path. Both can send payments through JavaScript. Both can create real financial consequences. But they differ in identity, tokens, revocation, provider dependency and user expectation. Alby JS SDK is valuable partly because it lets builders choose, but choice only helps when the builder understands the tradeoff.
Boostagrams, zaps and media payments are not afterthoughts
The OAuth docs include boostagram helpers and references to BLIP-10 style podcast payment metadata. The Lightning Tools guide also names boosting and zapping a Lightning address as part of the backend payment toolbox. For a Nostr reader, that matters because Alby sits in the overlap between web payments, Podcasting 2.0, Lightning addresses and NIP-57 zaps.
NIP-57 defines zap requests and zap receipts so Nostr clients can associate Lightning payments with users and events. Lightning Address and LNURL make recipient discovery human-readable enough for normal people. The SDK does not replace those standards. It gives JavaScript products a way to build payment flows that can touch them: send a payment, request an invoice, attach metadata, listen for payment and move value through a wallet connection.
This is why Alby JS SDK belongs in the same mental neighborhood as Wavlake, Podcasting 2.0, zaps, paid APIs, creator tooling and small commerce. Developer libraries decide which payment patterns become easy. When a library makes one-invoice-at-a-time easy but split payments, metadata or receipts hard, the app culture follows. Alby's SDK is broad enough to encourage more than a tip button.
Bitcoin Connect is the user-facing cousin
Bitcoin Connect is not the same project as Alby JS SDK, but the two should be read together. Bitcoin Connect presents itself as a simple library that lets users connect a wallet to Lightning-powered websites through WebLN. Its website emphasizes a payment button, wallet choice, mobile-friendly flows and the ability to pay by connecting a wallet, scanning an invoice or opening a mobile wallet. Alby's NWC docs explicitly point frontend web developers toward Bitcoin Connect.
That tells you the intended layering. The SDK gives builders lower-level JavaScript payment primitives and NWC/WebLN tools. Bitcoin Connect gives web products a friendlier connection and payment UI. A serious product might use both: Bitcoin Connect for wallet selection and user interaction, Alby JS SDK for direct NWC or LN client logic behind a particular flow, and Alby Hub or another wallet service on the user's side.
For Crays, that distinction is important because the Apps hub should not treat every Alby project as one tile. Alby Extension is a browser wallet interface. Alby Go is a mobile wallet interface. Alby Hub is a wallet service. Bitcoin Connect is a frontend connection widget. Alby JS SDK is developer tooling. All are related, but each answers a different product question.
The developer sandbox changes how risk should be tested
Alby's Developer Sandbox is one of the strongest signals that Alby knows payment development needs more than code snippets. The guide says it provides zero-setup test wallets, different payment scenarios, ready-to-use code examples and prompts for agents. It describes a workflow where a developer creates test wallets with a faucet API, builds payment logic, runs end-to-end tests with real payment flows, then swaps in a production NWC connection from Alby Hub when ready.
That workflow is exactly right for the SDK. A payment integration that only passes unit tests can still be useless when invoices expire, wallets go offline, relays drop events, a connection is revoked, a payment times out, an amount conversion is wrong or a callback fires twice. NWC and Lightning need end-to-end testing because the failure modes are distributed across app, relay, wallet service and Lightning backend.
Developers should therefore treat the sandbox as part of the product, not a side toy. Build with fake or tiny balances, test wrong invoices, expired invoices, repeated clicks, lost websocket connections, revoked secrets, backend restarts and mobile handoffs. Then tighten permissions before production. The SDK lowers implementation friction; the sandbox is where teams learn what the happy path hides.
Where secrets and permissions can go wrong
The main risk in an Alby JS SDK integration is not that a function is hard to call. It is that a function is too easy to call with a powerful credential. An NWC connection URL includes enough information for a client to communicate with a wallet service, including a secret for signing and encrypting request traffic. NIP-47 treats unique per-connection keys, revocation and budgets as major privacy and control advantages. If a developer stores that URL carelessly, those advantages shrink fast.
A production app should not dump NWC secrets into local storage without thinking, send them to analytics, print them in logs, include them in screenshots, persist them unencrypted on shared servers or reuse one broad connection for unrelated contexts. The SDK can return connection URLs and initialize clients, but the storage and lifecycle model belongs to the app. A good app names connections clearly, scopes methods, sets budgets, expires access and gives the user a way to revoke.
OAuth tokens have their own version of the same problem. The SDK can refresh access tokens and listen for refresh events, but the app still needs secure token storage, one-client-per-token discipline, scope review and a recovery path when refresh fails. In both NWC and OAuth, the product question is not can the code pay? It is who authorized payment, how much, for how long, through which wallet, and how can that authorization be taken away?
Runtime details matter more than a README suggests
The README and docs point out runtime requirements because NWC is not a pure math library. The current README mentions Node.js 22 or higher for native fetch and WebSocket support, while the NWC guide calls out Node and React Native details such as websocket polyfills and crypto availability in older environments. Older package metadata and docs can still mention earlier Node assumptions, so builders should check the current release and docs before locking a runtime.
This is normal for a cross-environment JavaScript payment SDK. Browser pages, Node servers, React Native apps, command-line tools and service workers do not all have the same global objects. WebSockets, fetch, crypto, popups, deep links and secure storage behave differently. A demo that works in a browser can fail in Node. A Node backend flow can be wrong for mobile. A popup authorization helper can be awkward inside an embedded webview.
The practical recommendation is to choose the integration shape before choosing the import. Web app with user-facing payments? Look at Bitcoin Connect and NostrWebLNProvider. Backend worker with an app wallet? Consider direct NWCClient and secure server-side storage. Wallet-service builder? Study NWCWalletService and NIP-47 event handling. Alby Account integration? Use OAuth only with explicit scopes. The SDK is a toolbox, and toolboxes punish vague architecture.
How to evaluate an app that uses it
When a product says it uses Alby JS SDK, do not treat that as an automatic trust mark. Ask which part. Does it use the high-level LN client, direct NWC, WebLN compatibility, OAuth, a wallet-service helper or only Lightning Tools nearby? Does the app connect to the user's own Alby Hub, to Alby Account, to a custodial wallet, to a sandbox wallet, to a server wallet or to a shared business wallet?
Then ask what the user sees. A good integration labels the wallet connection, explains why it needs payment authority, shows budgets or method limits when available, handles errors in human language and never makes a payment feel invisible. It should also make small test payments easy before large ones. NWC's promise of no QR codes and no repeated confirmations is powerful, but invisible spending must be bounded.
Finally, test interoperability. Pay a BOLT11 invoice, pay a Lightning address, request an invoice, receive a notification, revoke the connection from the wallet, reconnect with a smaller budget, switch relays if supported and read transaction history from the wallet side. If the product still behaves sensibly under those conditions, the SDK is being used well. If the app collapses outside the demo path, the library cannot save it.
Why this SDK matters for the Crays map
Alby JS SDK matters because Nostr needs boring developer affordances. Protocol pages are important, but apps get built with packages, examples, sandboxes, typed docs, auth helpers and error classes. A developer who can add NWC in an afternoon is more likely to experiment with paid media, zaps, subscriptions, event tickets, tipping, metered APIs, games, marketplaces and agent tools. The SDK is one of the bridges from idea to shipped product.
It also teaches a larger lesson about classification. The NWC ecosystem map places Alby JS SDK under developer tools and libraries. That is correct. But its consequences reach Wallets, Apps, Commerce, Media and AI agents. Routing it as Developer Tools keeps the page honest while linking it to Alby Hub, NIP-47, Wallets and Lightning Zaps keeps the reader oriented. This is exactly the kind of entry that proves the hub cannot be a flat list.
The verdict is strong but careful. Alby JS SDK is one of the most useful JavaScript entry points for NWC and Alby payment integration. It is open-source, documented, actively connected to Alby's current developer strategy and broad enough to support both simple payment buttons and serious wallet-service work. The risk is that payment power becomes too easy to hide. The best apps built with it will be boringly explicit about permissions, secrets, budgets, relays, wallet backends and failure states.
Sources worth opening
Start with the getAlby/js-sdk repository and its docs, then compare Alby's current developer guide, NWC documentation, WebLN, NIP-47, zaps and Lightning Address material. The SDK sits across all of those surfaces.
- getAlby/js-sdk repository
- Alby JS SDK README
- Alby JS SDK releases
- Alby JS SDK issues
- Alby JS SDK generated TypeDoc
- Alby JS SDK LN client docs
- Alby JS SDK NWC client docs
- Alby JS SDK NWC wallet-service docs
- Alby JS SDK OAuth docs
- Alby Developer Guide
- Alby Wallet API getting started
- Alby NWC Wallet API overview
- Alby NWC JS SDK guide
- Alby NWC HTTP API guide
- Alby NWC Relay guide
- Alby Developer Sandbox
- Alby Lightning Tools guide
- Alby Browser Extension APIs
- Nostr Wallet Connect site
- NWC documentation
- NIP-47 Nostr Wallet Connect
- NIP-07 window.nostr browser capability
- NIP-57 Lightning Zaps
- WebLN Guide
- Bitcoin Connect
- Lightning Address
- Alby Hub
- getAlby organization
- Alby official site
