{"id":15288295,"url":"https://github.com/getalby/js-lightning-tools","last_synced_at":"2026-02-28T09:06:04.224Z","repository":{"id":103952061,"uuid":"553780008","full_name":"getAlby/js-lightning-tools","owner":"getAlby","description":"Collection of helpful building blocks and tools to develop Bitcoin Lightning web apps","archived":false,"fork":false,"pushed_at":"2025-02-03T10:18:57.000Z","size":1631,"stargazers_count":38,"open_issues_count":11,"forks_count":15,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-03T01:04:56.878Z","etag":null,"topics":["javascript-library","lightning","lightning-web-components","lnurl","nostr","webln"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@getalby/lightning-tools","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getAlby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-18T18:57:57.000Z","updated_at":"2025-02-18T00:17:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"5b1cc7d7-a1b9-4430-82b7-48fa7f377b9c","html_url":"https://github.com/getAlby/js-lightning-tools","commit_stats":{"total_commits":197,"total_committers":14,"mean_commits":"14.071428571428571","dds":0.7055837563451777,"last_synced_commit":"9c606a466b4b2f9d7033a6d6250ee274a63cd5fe"},"previous_names":["getalby/js-lightning-tools","getalby/alby-tools"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getAlby%2Fjs-lightning-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getAlby%2Fjs-lightning-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getAlby%2Fjs-lightning-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getAlby%2Fjs-lightning-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getAlby","download_url":"https://codeload.github.com/getAlby/js-lightning-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247276177,"owners_count":20912288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript-library","lightning","lightning-web-components","lnurl","nostr","webln"],"created_at":"2024-09-30T15:46:37.681Z","updated_at":"2026-02-28T09:06:04.147Z","avatar_url":"https://github.com/getAlby.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"100%\" src=\"docs/Header.png\"\u003e\n\u003c/p\u003e\n\n# Lightning Web SDK\n\nAn npm package that provides useful and common tools and helpers to build lightning web applications.\n\n## 🚀 Quick Start\n\n```\nnpm install @getalby/lightning-tools\n```\n\nor\n\n```\nyarn add @getalby/lightning-tools\n```\n\nor for use without any build tools:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { LightningAddress } from \"https://esm.sh/@getalby/lightning-tools@5.0.0\"; // jsdelivr.net, skypack.dev also work\n\n  // use LightningAddress normally...\n  (async () =\u003e {\n    const ln = new LightningAddress(\"hello@getalby.com\");\n    // fetch the LNURL data\n    await ln.fetch();\n    // get the LNURL-pay data:\n    console.log(ln.lnurlpData);\n  })();\n\u003c/script\u003e\n```\n\n**This library relies on a global `fetch()` function which will work in [browsers](https://caniuse.com/?search=fetch) and node v18 or newer.** (In older versions you have to use a polyfill.)\n\n## 🤙 Usage\n\n### Lightning Address\n\nThe `LightningAddress` class provides helpers to work with lightning addresses\n\n```js\nimport { LightningAddress } from \"@getalby/lightning-tools\";\n\nconst ln = new LightningAddress(\"hello@getalby.com\");\n\n// fetch the LNURL data\nawait ln.fetch();\n\n// get the LNURL-pay data:\nconsole.log(ln.lnurlpData); // returns a [LNURLPayResponse](https://github.com/getAlby/js-lightning-tools/blob/master/src/types.ts#L1-L15)\n// get the keysend data:\nconsole.log(ln.keysendData);\n```\n\n#### Get an invoice:\n\n```js\nimport { LightningAddress } from \"@getalby/lightning-tools\";\n\nconst ln = new LightningAddress(\"hello@getalby.com\");\n\nawait ln.fetch();\n// request an invoice for 1000 satoshis\n// this returns a new `Invoice` class that can also be used to validate the payment\nconst invoice = await ln.requestInvoice({ satoshi: 1000 });\n\nconsole.log(invoice.paymentRequest); // print the payment request\nconsole.log(invoice.paymentHash); // print the payment hash\n```\n\n#### Verify a payment\n\n```js\nimport { LightningAddress } from \"@getalby/lightning-tools\";\nconst ln = new LightningAddress(\"hello@getalby.com\");\nawait ln.fetch();\n\nconst invoice = await ln.requestInvoice({ satoshi: 1000 });\n\n// if the LNURL providers supports LNURL-verify:\nconst paid = await invoice.verifyPayment(); // returns true of false\nif (paid) {\n  console.log(invoice.preimage);\n}\n\n// if you have the preimage for example in a WebLN context\nawait window.webln.enable();\nconst response = await window.webln.sendPayment(invoice.paymentRequest);\nconst paid = invoice.validatePreimage(response.preimage); // returns true or false\nif (paid) {\n  console.log(\"paid\");\n}\n\n// or use the convenenice method:\nawait invoice.isPaid();\n```\n\nIt is also possible to manually initialize the `Invoice`\n\n```js\nconst { Invoice } = require(\"alby-tools\");\n\nconst invoice = new Invoice({ pr: pr, preimage: preimage });\nawait invoice.isPaid();\n```\n\n#### Boost a LN address:\n\nYou can also attach additional metadata information like app name, version, name of the podcast which is boosted etc. to the keysend payment.\n\n```js\nimport { LightningAddress } from \"@getalby/lightning-tools\";\nconst ln = new LightningAddress(\"hello@getalby.com\");\nawait ln.fetch();\n\nconst boost = {\n  action: \"boost\",\n  value_msat: 21000,\n  value_msat_total: 21000,\n  app_name: \"Podcastr\",\n  app_version: \"v2.1\",\n  feedId: \"21\",\n  podcast: \"random podcast\",\n  episode: \"1\",\n  ts: 2121,\n  name: \"Satoshi\",\n  sender_name: \"Alby\",\n};\nawait ln.boost(boost);\n```\n\n#### Zapping a LN address on Nostr:\n\nNostr is a simple, open protocol that enables truly censorship-resistant and global value-for-value publishing on the web. Nostr integrates deeply with Lightning. [more info](https://nostr.how/)\n\nThis librarys provides helpers to create [zaps](https://github.com/nostr-protocol/nips/blob/master/57.md).\n\n```js\nimport { LightningAddress } from \"@getalby/lightning-tools\";\nconst ln = new LightningAddress(\"hello@getalby.com\");\nawait ln.fetch();\n\nconst response = await ln.zap({\n  satoshi: 1000,\n  comment: \"Awesome post\",\n  relays: [\"wss://relay.damus.io\"],\n  e: \"44e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245\",\n});\nconsole.log(response.preimage); // print the preimage\n```\n\nFor a full example see [examples/zaps](examples/zaps.js)\n\n#### Zapping a LN address on Nostr using Nostr Wallet Connect:\n\nNative zaps without a browser extension are possible by using a Nostr Wallet Connect WebLN provider.\n\nSee [examples/zaps-nwc](examples/zaps-nwc.js)\n\n### L402\n\nL402 is a protocol standard based on the HTTP 402 Payment Required error code\ndesigned to support the use case of charging for services and\nauthenticating users in distributed networks.\n\nThis library includes a `fetchWithL402` function to consume L402 protected resources.\n\n#### fetchWithL402(url: string, fetchArgs, options)\n\n- url: the L402 protected URL\n- fetchArgs: arguments are passed to the underlying `fetch()` function used to do the HTTP request\n- options:\n  - webln: the webln object used to call `sendPayment()` defaults to globalThis.webln\n  - store: a key/value store object to persiste the l402 for each URL. The store must implement a `getItem()`/`setItem()` function as the browser's localStorage. By default a memory storage is used.\n  - headerKey: defaults to L402 but if you need to consume an old LSAT API set this to LSAT\n\n##### Examples\n\n```js\nimport { fetchWithL402 } from \"@getalby/lightning-tools\";\n\n// this will fetch the resource and pay the invoice with window.webln.\n// the tokens/preimage data will be stored in the browser's localStorage and used for any following request\nawait fetchWithL402(\n  \"https://lsat-weather-api.getalby.repl.co/kigali\",\n  {},\n  { store: window.localStorage }\n)\n  .then((res) =\u003e res.json())\n  .then(console.log);\n```\n\n```js\nimport { fetchWithL402 } from \"@getalby/lightning-tools\";\nimport { webln } from \"@getalby/sdk\";\n\n// use a NWC WebLN provide to do the payments\nconst nwc = new webln.NostrWebLNProvider({\n  nostrWalletConnectUrl: loadNWCUrl(),\n});\n\n// this will fetch the resource and pay the invoice with a NWC webln object\nawait fetchWithL402(\n  \"https://lsat-weather-api.getalby.repl.co/kigali\",\n  {},\n  { webln: nwc }\n)\n  .then((res) =\u003e res.json())\n  .then(console.log);\n```\n\n```js\nimport { l402 } from \"@getalby/lightning-tools\";\nimport { fiat } from \"@getalby/lightning-tools\";\n\n// do not store the tokens\nawait l402.fetchWithL402(\n  \"https://lsat-weather-api.getalby.repl.co/kigali\",\n  {},\n  { store: new l402.storage.NoStorage() }\n);\n```\n\n### Basic invoice decoding\n\nYou can initialize an `Invoice` to decode a payment request.\n\n```js\nconst { Invoice } = require(\"alby-tools\");\n\nconst invoice = new Invoice({ pr });\n\nconst { paymentHash, satoshi, description, createdDate, expiryDate } = invoice;\n```\n\n\u003e If you need more details about the invoice, use a dedicated BOLT11 decoding library.\n\n### 💵 Fiat conversions\n\nHelpers to convert sats values to fiat and fiat values to sats.\n\n##### getFiatValue(satoshi: number, currency: string): number\n\nReturns the fiat value for a specified currency of a satoshi amount\n\n##### getSatoshiValue(amount: number, currency: string): number\n\nReturns the satoshi value for a specified amount (in the smallest denomination) and currency\n\n##### getFormattedFiatValue(satoshi: number, currency: string, locale: string): string\n\nLike `getFiatValue` but returns a formatted string for a given locale using JavaScript's `toLocaleString`\n\n#### Examples\n\n```js\nawait fiat.getFiatValue({ satoshi: 2100, currency: \"eur\" });\nawait fiat.getSatoshiValue({ amount: 100, currency: \"eur\" }); // for 1 EUR\nawait fiat.getFormattedFiatValue({\n  satoshi: 2100,\n  currency: \"usd\",\n  locale: \"en\",\n});\n```\n\n### 🤖 Lightning Address Proxy\n\nThis library uses a [proxy](https://github.com/getAlby/lightning-address-details-proxy) to simplify requests to lightning providers.\n\n- Many ln addresses don't support CORS, which means fetching the data directly in a browser environment will not always work.\n- Two requests are required to retrieve lnurlp and keysend data for a lightning address. The proxy will do these for you with a single request.\n\nYou can disable the proxy by explicitly setting the proxy to false when initializing a lightning address:\n\n```js\nconst lightningAddress = new LightningAddress(\"hello@getalby.com\", {\n  proxy: false,\n});\n```\n\n## crypto dependency\n\nIf you get an `crypto is not defined` in NodeJS error you have to import it first:\n\n```js\nimport * as crypto from 'crypto'; // or 'node:crypto'\nglobalThis.crypto = crypto as any;\n//or: global.crypto = require('crypto');\n```\n\n## fetch() dependency\n\nThis library relies on a global fetch object which will work in browsers and node v18.x or newer. In old version you can manually install a global fetch option or polyfill if needed.\n\nFor example:\n\n```js\nimport fetch from \"cross-fetch\"; // or \"@inrupt/universal-fetch\"\nglobalThis.fetch = fetch;\n\n// or as a polyfill:\nimport \"cross-fetch/polyfill\";\n```\n\n## 🛠 Development\n\n```\nyarn install\nyarn run build\n```\n\n## Need help?\n\nWe are happy to help, please contact us or create an issue.\n\n- [Twitter: @getAlby](https://twitter.com/getAlby)\n- [Telegram group](https://t.me/getAlby)\n- support at getalby.com\n- [bitcoin.design](https://bitcoin.design/) Discord community (find us on the #alby channel)\n- Read the [Alby developer guide](https://guides.getalby.com/overall-guide/alby-for-developers/getting-started) to better understand how Alby packages and APIs can be used to power your app.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetalby%2Fjs-lightning-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetalby%2Fjs-lightning-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetalby%2Fjs-lightning-tools/lists"}