diff --git a/SKILL.md b/SKILL.md
index 8702191..c0a98a7 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -17,6 +17,78 @@ Use this skill to understand how to build apps that require bitcoin lightning wa
 - [Lightning Tools: Request invoices from a lightning address, parse BOLT-11 invoices, verify a preimage for a BOLT-11 invoice, LNURL-Verify, do bitcoin <-> fiat conversions](./references/lightning-tools/lightning-tools.md)
 - [Bitcoin Connect: Browser-only UI components for connecting wallets and accepting payments in React, Vue, or pure HTML web apps](./references/bitcoin-connect/bitcoin-connect.md)
 
+## Which library to use
+
+| Scenario | Library | Runtime |
+|---|---|---|
+| Backend / server-side / console app wallet operations (send, receive, balance, invoices, notifications) | NWC Client (`@getalby/sdk`) | Node.js, Deno, Bun, Browser |
+| Browser / frontend wallet connection UI and payment modals | Bitcoin Connect (`@getalby/bitcoin-connect`) | Browser only |
+| Utility: parse invoices, lightning address lookups, fiat conversion, LNURL | Lightning Tools (`@getalby/lightning-tools`) | Node.js, Deno, Bun, Browser |
+| Backend + Frontend in the same app | NWC Client (backend) + Bitcoin Connect (frontend) | Both |
+
+- **Do NOT use Bitcoin Connect in Node.js / server-side environments** — it requires a browser DOM.
+- **Do NOT use NWC Client in the frontend if the goal is wallet connection UI** — use Bitcoin Connect instead, which provides the UI and manages the NWC connection for you.
+- NWC Client and Lightning Tools can be freely combined in any environment.
+
+## ⚠️ Unit Warning
+
+NWC Client operates in **millisats** (1 sat = 1,000 millisats).
+Lightning Tools and Bitcoin Connect/WebLN operate in **sats**.
+
+When combining libraries, always convert:
+- NWC millisats → sats: `Math.floor(millisats / 1000)`
+- sats → NWC millisats: `sats * 1000`
+
+## Node.js Project Setup
+
+All packages in this skill are **ESM-only**. When creating a new Node.js project:
+
+1. Set `"type": "module"` in `package.json`
+2. For TypeScript, use the following minimal `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "strict": true
+  }
+}
+```
+
+3. Install dependencies based on what you need:
+
+```bash
+# NWC Client (wallet operations)
+npm install @getalby/sdk
+
+# Lightning Tools (invoices, lightning addresses, fiat conversion)
+npm install @getalby/lightning-tools
+
+# Both (common for backend apps)
+npm install @getalby/sdk @getalby/lightning-tools
+
+# Bitcoin Connect (browser only — do NOT install for Node.js-only projects)
+npm install @getalby/bitcoin-connect
+# or for React specifically:
+npm install @getalby/bitcoin-connect-react
+```
+
+4. If using TypeScript with Bitcoin Connect, also install WebLN types:
+
+```bash
+npm install -D @webbtc/webln-types
+```
+
+Then create a `webln-types.d.ts` file:
+
+```ts
+/// <reference types="@webbtc/webln-types" />
+```
+
 ## Prefer Typescript
 
 When the user says to use "JS" or "Javascript" or "NodeJS" or something similar, use typescript unless the user explicitly says to not use typescript or the project does not support it.
@@ -44,6 +116,46 @@ Testing wallets should be used for [automated testing](./references/automated-te
 
 It is recommended to write tests so that the agent can test its own work and fix bugs itself without requiring human input.
 
+## Cross-Library Recipe
+
+When combining NWC Client and Lightning Tools (e.g. fiat conversion + invoicing + forwarding payments), see the [cross-library recipe](./references/cross-library-recipe.md) for a full end-to-end example with proper unit conversion.
+
 ## Production Wallet
 
-If they do not have a wallet yet [here are some options](./references/production-wallets.md)
\ No newline at end of file
+If they do not have a wallet yet [here are some options](./references/production-wallets.md)
+
+## Quickstart Decision Guide
+
+- **Backend wallet ops (send/receive/balance/notifications)** → Use `NWCClient` (`@getalby/sdk`). Combine with Lightning Tools for fiat conversion and invoice parsing. Units: msats.
+- **Browser wallet connection + payment UI** → Use Bitcoin Connect (`@getalby/bitcoin-connect` or `-react`). Units: sats. SSR frameworks must gate imports to the client.
+- **Full-stack app** → Backend: `NWCClient` for wallet ops. Frontend: Bitcoin Connect for connect/pay UI. Shared utils: Lightning Tools for fiat, LNURL, invoice parsing.
+- **Lightning address pay/receive utilities** → Use Lightning Tools `lnurl` APIs (sats). For payment, either WebLN (browser) or `NWCClient.payInvoice` (backend).
+- **Fiat pricing** → Lightning Tools `fiat` APIs to convert fiat↔sats; multiply/divide by 1000 when handing amounts to/from `NWCClient`.
+- **Zaps (Nostr-tied payments)** → Lightning Tools zap helpers + WebLN provider (browser) or `NWCClient.payInvoice` (backend).
+- **L402 client** → Browser: `fetchWithL402` + Bitcoin Connect provider. Node: `fetchWithL402` + `NostrWebLNProvider` from `@getalby/sdk/webln`.
+- **L402 server** → `NWCClient.makeInvoice` + macaroon verification (see `lightning-tools/l402.md`).
+- **Testing** → Always prefer [testing wallets](./references/testing-wallets.md) and wire them into automated tests (Jest/Vitest/Playwright) per [automated testing](./references/automated-testing.md).
+
+## NWC Secret Handling (Security)
+
+- Treat `nostrWalletConnectUrl` as a secret API key. Never log, print, or expose it.
+- Backend: keep in environment variables (e.g., `NWC_URL`), never commit to source control, and redact in error messages.
+- Browser: request from user input; keep only in memory unless the user explicitly opts into persistence. Do not bake into bundles or HTML.
+- When wrapping errors, strip or mask the connection URL before surfacing to logs/telemetry.
+
+## Invoice Safety & Common Pitfalls
+
+- Always decode and check expiry before paying a BOLT-11 invoice; warn if expiry is under ~60 seconds.
+- Units: `NWCClient` = **msats**; Lightning Tools/Bitcoin Connect/WebLN = **sats**. Convert carefully when mixing.
+- Do not import Lightning Tools from the package root; always use subpath imports (e.g., `@getalby/lightning-tools/fiat`).
+- Bitcoin Connect requires a browser DOM; never import it in SSR server code. Call `init()` exactly once on the client.
+- Close resources: `unsub()` notifications and `client.close()` when shutting down long-lived processes.
+- Handle permission/budget errors: on `QUOTA_EXCEEDED` or `RESTRICTED`, prompt for a new or expanded connection; on `RATE_LIMITED`, back off and retry later.
+
+## Recipe Pointers
+
+- End-to-end msats↔sats with invoicing and forwarding: [cross-library recipe](./references/cross-library-recipe.md).
+- L402 client/server patterns: [L402 guide](./references/lightning-tools/l402.md).
+- LNURL-pay, comments, payer data, and verify: [lnurl guide](./references/lightning-tools/lnurl.md).
+- Invoice parsing/expiry/preimage verification: [invoice guide](./references/lightning-tools/invoice.md).
+- Automated wallet creation for tests: [testing wallets](./references/testing-wallets.md) and [automated testing](./references/automated-testing.md).
\ No newline at end of file
diff --git a/references/automated-testing.md b/references/automated-testing.md
index 52a9df7..d0191fb 100644
--- a/references/automated-testing.md
+++ b/references/automated-testing.md
@@ -10,31 +10,49 @@ Each test can create brand new wallet(s) as required to ensure reproducable resu
 
 ### Code Example
 
-The below example allows for temporary networking errors.
+The below example allows for temporary networking errors and is reusable as a fixture helper.
 
 ```ts
-async function createTestWallet(retries = 3): Promise<{ nwcUrl: string; lightningAddress: string }> {
+type TestWallet = { nwcUrl: string; lightningAddress: string };
+
+async function createTestWallet({
+  retries = 4,
+  delayMs = 500,
+  balance = 10000,
+}: {
+  retries?: number;
+  delayMs?: number;
+  balance?: number;
+} = {}): Promise<TestWallet> {
+  let lastError: Error | undefined;
   for (let i = 0; i < retries; i++) {
-    const response = await fetch("https://faucet.nwc.dev?balance=10000", { method: "POST" });
-    if (!response.ok) {
+    try {
+      const response = await fetch(`https://faucet.nwc.dev?balance=${balance}`, { method: "POST" });
+      if (!response.ok) {
+        throw new Error(`Faucet request failed: ${response.status} ${await response.text()}`);
+      }
+      const nwcUrl = (await response.text()).trim();
+      const lud16Match = nwcUrl.match(/lud16=([^&\s]+)/);
+      if (!lud16Match) {
+        throw new Error(`No lud16 found in NWC URL: ${nwcUrl}`);
+      }
+      const lightningAddress = decodeURIComponent(lud16Match[1]);
+      return { nwcUrl, lightningAddress };
+    } catch (error) {
+      lastError = error as Error;
       if (i < retries - 1) {
-        await new Promise((r) => setTimeout(r, 1000));
-        continue;
+        await new Promise((r) => setTimeout(r, delayMs * (i + 1)));
       }
-      throw new Error(`Faucet request failed: ${response.status} ${await response.text()}`);
-    }
-    const nwcUrl = (await response.text()).trim();
-    const lud16Match = nwcUrl.match(/lud16=([^&\s]+)/);
-    if (!lud16Match) {
-      throw new Error(`No lud16 found in NWC URL: ${nwcUrl}`);
     }
-    const lightningAddress = decodeURIComponent(lud16Match[1]);
-    return { nwcUrl, lightningAddress };
   }
-  throw new Error("Failed to create test wallet after retries");
+  throw lastError ?? new Error("Failed to create test wallet after retries");
 }
 ```
 
-## What to test
+#### Fixture patterns (Jest/Vitest/Playwright)
 
-Test both happy path and failure cases (payment failed with insufficient balance etc.)
+- Create a fresh wallet per test (or per suite) to avoid state bleed and flakiness.
+- Expose `nwcUrl` via env or in-memory fixtures; never log or print the secret.
+- In Playwright E2E, pass `nwcUrl` to the app via query param or `page.evaluate` to set it in localStorage/sessionStorage as a setup step.
+- Add a top-up helper for balance-sensitive flows: `POST https://faucet.nwc.dev/wallets/<username>/topup?amount=...`.
+- Cover failure cases with real flows (insufficient balance, expired invoice, rate limit) and not just mocks.
diff --git a/references/bitcoin-connect/bitcoin-connect.md b/references/bitcoin-connect/bitcoin-connect.md
index 5da3580..3146f04 100644
--- a/references/bitcoin-connect/bitcoin-connect.md
+++ b/references/bitcoin-connect/bitcoin-connect.md
@@ -35,6 +35,76 @@ or
 </script>
 ```
 
+## ⚠️ SSR / SSG Warning (Next.js, Nuxt, SvelteKit, Remix, Astro)
+
+Bitcoin Connect requires a browser DOM and **will crash if imported on the server**. In frameworks that do server-side rendering or static site generation, you MUST use dynamic imports or client-only wrappers. Never import `@getalby/bitcoin-connect` or `@getalby/bitcoin-connect-react` in server code or shared modules that execute during SSR — gate imports to the client and dynamically load components.
+
+### Next.js (App Router)
+
+Mark the component as client-only and use dynamic import:
+
+```tsx
+"use client";
+
+import dynamic from "next/dynamic";
+import { useEffect } from "react";
+
+// Dynamic import — prevents server-side import of bitcoin-connect
+const BitcoinConnectButton = dynamic(
+  () => import("@getalby/bitcoin-connect-react").then((mod) => {
+    // init() must be called once before using components
+    mod.init({ appName: "My App" });
+    return { default: mod.Button };
+  }),
+  { ssr: false }
+);
+
+export default function WalletButton() {
+  return <BitcoinConnectButton />;
+}
+```
+
+### Next.js (Pages Router)
+
+```tsx
+import dynamic from "next/dynamic";
+
+const WalletButton = dynamic(
+  () => import("../components/WalletButton"),
+  { ssr: false }
+);
+```
+
+### Nuxt 3
+
+```vue
+<template>
+  <ClientOnly>
+    <BitcoinConnectButton />
+  </ClientOnly>
+</template>
+```
+
+### SvelteKit
+
+```svelte
+<script>
+  import { onMount } from "svelte";
+  import { browser } from "$app/environment";
+
+  let Button;
+  onMount(async () => {
+    const bc = await import("@getalby/bitcoin-connect");
+    bc.init({ appName: "My App" });
+    // use bc.launchModal(), bc.requestProvider(), etc.
+  });
+</script>
+```
+
+### General Rule
+
+If using any SSR framework, **never import `@getalby/bitcoin-connect` or `@getalby/bitcoin-connect-react` at the top level of a server-rendered file**. Always gate the import behind a browser/client check or dynamic import.
+
 ## Key concepts
 
 - Web components for connecting Lightning wallets and enabling WebLN
@@ -49,6 +119,15 @@ Unlike NWC, WebLN operates on sats, not millisats. (1000 millisats = 1 satoshi)
 
 ## Initialization
 
+Call `init()` **once** when your app starts. Do NOT call it multiple times or conditionally inside render loops. If you have multiple entry points/components, centralize `init()` to a single client-only location to avoid duplicate initialization.
+
+**Where to call `init()`:**
+
+- **React (Vite / CRA):** in `main.tsx` or `App.tsx`, outside any component, at the top level
+- **React (Next.js):** inside the dynamically imported client component (see SSR warning above)
+- **Vue:** in `main.ts` before `createApp()`
+- **Plain HTML:** in a `<script type="module">` tag in the `<head>` or before your app code
+
 ```ts
 import { init } from "@getalby/bitcoin-connect";
 
diff --git a/references/cross-library-recipe.md b/references/cross-library-recipe.md
new file mode 100644
index 0000000..92c93f3
--- /dev/null
+++ b/references/cross-library-recipe.md
@@ -0,0 +1,104 @@
+# Cross-Library Recipe: NWC Client + Lightning Tools
+
+This example combines NWC Client and Lightning Tools to build a common real-world pattern:
+
+> Receive a payment in USD, then forward 90% to a lightning address.
+
+## Libraries Used
+
+- **NWC Client** (`@getalby/sdk`) — create invoices, subscribe to payment notifications, send payments
+- **Lightning Tools** (`@getalby/lightning-tools`) — convert fiat to sats, request invoices from a lightning address
+
+## ⚠️ Unit Conversion
+
+NWC Client uses **millisats**. Lightning Tools uses **sats**. This recipe converts between them:
+- NWC → Lightning Tools: `Math.floor(millisats / 1000)`
+- Lightning Tools → NWC: `sats * 1000`
+
+## Full Example
+
+IMPORTANT: read the [NWC Client typings](./nwc-client/nwc.d.ts) and [Lightning Tools typings](./lightning-tools/index.d.ts) to better understand how this works.
+
+```ts
+import { NWCClient, Nip47WalletError } from "@getalby/sdk/nwc";
+import { getSatoshiValue } from "@getalby/lightning-tools/fiat";
+import { LightningAddress } from "@getalby/lightning-tools/lnurl";
+
+const client = new NWCClient({
+  nostrWalletConnectUrl: process.env.NWC_URL,
+});
+
+// Step 1: Convert $5 USD to sats using Lightning Tools
+const amountSats = await getSatoshiValue({ amount: 5, currency: "USD" });
+console.log(`$5 USD = ${amountSats} sats`);
+
+// Step 2: Create an invoice using NWC Client (amount in millisats)
+const amountMillisats = amountSats * 1000;
+const transaction = await client.makeInvoice({
+  amount: amountMillisats,
+  description: "Payment for service - $5 USD",
+});
+console.log("Invoice created:", transaction.invoice);
+console.log("Share this invoice with the payer.");
+
+// Step 3: Wait for the payment to arrive
+const unsub = await client.subscribeNotifications(async (notification) => {
+  if (notification.notification_type !== "payment_received") {
+    return;
+  }
+  if (notification.notification.payment_hash !== transaction.payment_hash) {
+    return;
+  }
+
+  const receivedMillisats = notification.notification.amount;
+  const receivedSats = Math.floor(receivedMillisats / 1000);
+  console.log(`Payment received: ${receivedSats} sats`);
+
+  // Step 4: Calculate 90% to forward
+  const forwardSats = Math.floor(receivedSats * 0.9);
+  console.log(`Forwarding 90%: ${forwardSats} sats to recipient`);
+
+  // Step 5: Request an invoice from a lightning address using Lightning Tools
+  const recipientAddress = new LightningAddress("hello@getalby.com", {
+    proxy: false, // server-side, no CORS proxy needed
+  });
+  await recipientAddress.fetch();
+  const recipientInvoice = await recipientAddress.requestInvoice({
+    satoshi: forwardSats,
+  });
+
+  // Step 6: Pay the invoice using NWC Client
+  try {
+    const payResponse = await client.payInvoice({
+      invoice: recipientInvoice.paymentRequest,
+    });
+    console.log("Forwarded payment! Preimage:", payResponse.preimage);
+  } catch (error) {
+    if (error instanceof Nip47WalletError) {
+      console.error(`Payment failed [${error.code}]: ${error.message}`);
+    } else {
+      throw error;
+    }
+  }
+
+  unsub();
+  client.close();
+});
+
+// Graceful shutdown
+process.on("SIGINT", () => {
+  unsub();
+  client.close();
+  process.exit();
+});
+```
+
+## Key Takeaways
+
+1. **Fiat conversion** happens via Lightning Tools (`getSatoshiValue`) which returns sats.
+2. **Invoice creation** happens via NWC Client (`makeInvoice`) which expects millisats — so multiply by 1000.
+3. **Notification amounts** from NWC Client are in millisats — divide by 1000 before passing to Lightning Tools.
+4. **Lightning address invoice requests** happen via Lightning Tools (`requestInvoice`) which expects sats.
+5. **Paying the invoice** happens via NWC Client (`payInvoice`) which takes a BOLT-11 string directly.
+6. **Error handling** uses `Nip47WalletError` for wallet-level failures.
+7. **Cleanup** always unsubscribes and closes the client.
\ No newline at end of file
diff --git a/references/lightning-tools/fiat.md b/references/lightning-tools/fiat.md
index 5ee6481..ada831f 100644
--- a/references/lightning-tools/fiat.md
+++ b/references/lightning-tools/fiat.md
@@ -8,7 +8,7 @@ Useful to give the user ability to pick a currency, or verify if a fiat currency
 
 ```ts
 import { getFiatCurrencies } from "@getalby/lightning-tools/fiat";
-const fiatCurrencies = await fiat.getFiatCurrencies();
+const fiatCurrencies = await getFiatCurrencies();
 ```
 
 ## Fiat amount to Sats
@@ -30,3 +30,17 @@ const fiatValue = await getFiatValue({
   currency,
 });
 ```
+
+## Sats to Formatted Fiat String
+
+Returns a locale-formatted string like `"$1.23"` or `"€1,23"` — preferred for displaying to users:
+
+```ts
+import { getFormattedFiatValue } from "@getalby/lightning-tools/fiat";
+const formatted = await getFormattedFiatValue({
+  satoshi,
+  currency, // e.g. "USD"
+  locale, // e.g. "en-US"
+});
+console.log(formatted); // e.g. "$1.23"
+```
diff --git a/references/lightning-tools/invoice.md b/references/lightning-tools/invoice.md
index 4818ed9..dba1b3e 100644
--- a/references/lightning-tools/invoice.md
+++ b/references/lightning-tools/invoice.md
@@ -2,15 +2,111 @@
 
 IMPORTANT: read the [typings](./index.d.ts) to better understand how this works.
 
-## Decode an invoice
+## Decode an Invoice (Quick)
+
+The `decodeInvoice` function returns a simple object without creating a full `Invoice` instance. Useful for quick parsing:
+
+```ts
+import { decodeInvoice } from "@getalby/lightning-tools/bolt11";
+
+const decoded = decodeInvoice(paymentRequest);
+if (decoded) {
+  console.log("Payment hash:", decoded.paymentHash);
+  console.log("Amount:", decoded.satoshi, "sats");
+  console.log("Description:", decoded.description);
+  console.log("Timestamp:", decoded.timestamp);
+  console.log("Expiry (seconds):", decoded.expiry); // may be undefined
+}
+```
+
+## Decode an Invoice (Full)
+
+The `Invoice` class provides richer functionality including expiry checking and payment verification:
+
+```ts
+import { Invoice } from "@getalby/lightning-tools/bolt11";
+const invoice = new Invoice({ pr: paymentRequest });
+
+console.log("Payment hash:", invoice.paymentHash);
+console.log("Amount:", invoice.satoshi, "sats");
+console.log("Description:", invoice.description);
+console.log("Created:", invoice.createdDate);
+console.log("Expires:", invoice.expiryDate); // may be undefined
+```
+
+## Invoice Expiration & Safety Checklist
+
+Lightning invoices expire — typically after 1 hour, but the expiry varies by wallet. Always check expiry before presenting an invoice to a user or attempting to pay it.
+
+Payment safety checklist before paying:
+- Decode the invoice and ensure the `paymentHash` matches what you expect to pay.
+- Check expiry and warn if the remaining time is low (e.g., under 60 seconds).
+- If the invoice is amountless, ensure you set the intended amount explicitly when paying.
+- When mixing libraries, remember units: `NWCClient` uses **msats**, Lightning Tools / WebLN / Bitcoin Connect use **sats**.
+- For invoices sourced from LNURL-pay, use LNURL-Verify when available to confirm external payments.
+
+### Check if an invoice has expired
+
+```ts
+if (invoice.hasExpired()) {
+  console.log("This invoice has expired. Create a new one.");
+} else {
+  console.log("Invoice is still valid.");
+  if (invoice.expiryDate) {
+    const remainingMs = invoice.expiryDate.getTime() - Date.now();
+    console.log("Expires in:", Math.floor(remainingMs / 1000), "seconds");
+    if (remainingMs < 60_000) {
+      console.warn("Invoice expires in less than 60 seconds.");
+    }
+  }
+}
+```
+
+### Guard before paying
+
+Always check expiry before paying an invoice to avoid failed payments:
 
 ```ts
 import { Invoice } from "@getalby/lightning-tools/bolt11";
-const decodedInvoice = new Invoice({ pr: paymentRequest });
+
+function validateInvoiceBeforePayment(paymentRequest: string): Invoice {
+  const invoice = new Invoice({ pr: paymentRequest });
+
+  if (invoice.hasExpired()) {
+    throw new Error("Invoice has expired. Request a new one.");
+  }
+
+  if (invoice.expiryDate) {
+    const remainingMs = invoice.expiryDate.getTime() - Date.now();
+    if (remainingMs < 60_000) {
+      console.warn("Invoice expires in less than 60 seconds.");
+    }
+  }
+
+  return invoice;
+}
+```
+
+## Verify a Preimage for an Invoice
+
+After a payment is made, you can verify the preimage matches the invoice's payment hash:
+
+```ts
+const isValid = invoice.validatePreimage(preimage);
+console.log("Preimage valid:", isValid);
 ```
 
-## Verify a preimage for an invoice
+## Check if an Invoice Was Paid (LNURL-Verify)
+
+If the invoice was created from a lightning address (via `LightningAddress.requestInvoice()`), it may have a verify URL that allows checking payment status without a wallet connection:
 
 ```ts
-decodedInvoice.validatePreimage(preimage)
+// Only works for invoices created via LightningAddress.requestInvoice()
+// The invoice must have a verify URL
+if (invoice.verify) {
+  const isPaid = await invoice.isPaid();
+  console.log("Paid:", isPaid);
+}
 ```
+
+NOTE: not all lightning address providers support LNURL-Verify. The `verify` property will be `null` if unsupported.
\ No newline at end of file
diff --git a/references/lightning-tools/l402.md b/references/lightning-tools/l402.md
new file mode 100644
index 0000000..706d0f5
--- /dev/null
+++ b/references/lightning-tools/l402.md
@@ -0,0 +1,372 @@
+# L402: Lightning HTTP 402 Paywalls
+
+IMPORTANT: read the [typings](./index.d.ts) to better understand how this works.
+
+L402 is a protocol for monetizing APIs and web resources using Lightning payments. It uses the HTTP `402 Payment Required` status code. The flow works like this:
+
+1. Client requests a protected resource
+2. Server responds with `402` and a `WWW-Authenticate` header containing a **macaroon** (access token) and a Lightning **invoice**
+3. Client pays the invoice, receiving a **preimage** as proof of payment
+4. Client retries the request with an `Authorization` header containing the macaroon + preimage
+5. Server verifies the preimage matches the invoice's payment hash embedded in the macaroon, and grants access
+
+## Client: Consuming L402-Protected Resources
+
+### `fetchWithL402` (Browser — with Bitcoin Connect)
+
+The simplest way to consume L402 resources. It automatically handles the 402 challenge, pays the invoice via WebLN, and retries with the token:
+
+```ts
+import { fetchWithL402, MemoryStorage } from "@getalby/lightning-tools";
+import { requestProvider } from "@getalby/bitcoin-connect";
+
+const provider = await requestProvider();
+
+// MemoryStorage caches tokens so repeat requests don't require new payments
+const store = new MemoryStorage();
+
+const response = await fetchWithL402(
+  "https://api.example.com/premium/data",
+  { method: "GET" },
+  {
+    webln: provider,
+    store,
+  }
+);
+
+const data = await response.json();
+console.log("Protected data:", data);
+```
+
+### `fetchWithL402` (Node.js — with NWC)
+
+In Node.js, there is no browser wallet. Use the `NostrWebLNProvider` from the Alby SDK, which wraps an NWC connection as a WebLN-compatible provider:
+
+```ts
+import { fetchWithL402, MemoryStorage } from "@getalby/lightning-tools";
+import { NostrWebLNProvider } from "@getalby/sdk/webln";
+
+const webln = new NostrWebLNProvider({
+  nostrWalletConnectUrl: process.env.NWC_URL,
+});
+await webln.enable();
+
+const store = new MemoryStorage();
+
+const response = await fetchWithL402(
+  "https://api.example.com/premium/data",
+  { method: "GET" },
+  {
+    webln,
+    store,
+  }
+);
+
+const data = await response.json();
+console.log("Protected data:", data);
+
+webln.close();
+```
+
+### Token Caching with `MemoryStorage`
+
+Once an L402 token is acquired (macaroon + preimage), it can be reused for subsequent requests until it expires. `MemoryStorage` keeps tokens in memory for the lifetime of the process:
+
+```ts
+import { MemoryStorage } from "@getalby/lightning-tools";
+
+const store = new MemoryStorage();
+
+// First call: pays the invoice automatically
+await fetchWithL402(url, {}, { webln: provider, store });
+
+// Second call: reuses the cached token, no payment needed
+await fetchWithL402(url, {}, { webln: provider, store });
+```
+
+Use `NoStorage` if you never want to cache tokens (every request pays again):
+
+```ts
+import { NoStorage } from "@getalby/lightning-tools";
+
+const store = new NoStorage();
+```
+
+### LSAT Backwards Compatibility
+
+Some older services use the `LSAT` header key instead of `L402`. Use the `headerKey` option:
+
+```ts
+const response = await fetchWithL402(
+  "https://old-api.example.com/resource",
+  { method: "GET" },
+  {
+    webln: provider,
+    store,
+    headerKey: "LSAT",
+  }
+);
+```
+
+### Manual L402 Flow with `parseL402`
+
+For full control over the L402 flow (e.g. custom payment logic, displaying the invoice to the user), use `parseL402` to parse the 402 challenge yourself:
+
+```ts
+import { parseL402 } from "@getalby/lightning-tools";
+
+// Step 1: Make the initial request
+const response = await fetch("https://api.example.com/premium/data");
+
+if (response.status === 402) {
+  // Step 2: Parse the WWW-Authenticate header
+  const header = response.headers.get("WWW-Authenticate");
+  const { macaroon, invoice } = parseL402(header);
+
+  console.log("Macaroon:", macaroon);
+  console.log("Invoice to pay:", invoice);
+
+  // Step 3: Pay the invoice (any method — NWC Client, QR code, WebLN, etc.)
+  const { preimage } = await client.payInvoice({ invoice });
+
+  // Step 4: Retry with the L402 token
+  const protectedResponse = await fetch("https://api.example.com/premium/data", {
+    headers: {
+      Authorization: `L402 ${macaroon}:${preimage}`,
+    },
+  });
+
+  const data = await protectedResponse.json();
+  console.log("Protected data:", data);
+}
+```
+
+---
+
+## Server: Protecting Resources with L402
+
+Building an L402 server requires:
+1. Generating a Lightning invoice for each new client request (via NWC Client)
+2. Creating a macaroon that embeds the invoice's payment hash
+3. Returning a `402` response with the `WWW-Authenticate` header
+4. Verifying the preimage in subsequent requests
+
+### Express.js L402 Middleware
+
+```ts
+import crypto from "node:crypto";
+import { NWCClient } from "@getalby/sdk/nwc";
+import express from "express";
+
+const app = express();
+
+const client = new NWCClient({
+  nostrWalletConnectUrl: process.env.NWC_URL,
+});
+
+// --- Macaroon helpers ---
+
+const MACAROON_SECRET = process.env.MACAROON_SECRET || "change-me-in-production";
+
+interface MacaroonData {
+  paymentHash: string;
+  identifier: string;
+  expiresAt: number;
+}
+
+function createMacaroon(data: MacaroonData): string {
+  const payload = JSON.stringify(data);
+  const signature = crypto
+    .createHmac("sha256", MACAROON_SECRET)
+    .update(payload)
+    .digest("hex");
+  return Buffer.from(JSON.stringify({ payload, signature })).toString("base64");
+}
+
+function verifyMacaroon(macaroon: string): MacaroonData | null {
+  try {
+    const { payload, signature } = JSON.parse(
+      Buffer.from(macaroon, "base64").toString()
+    );
+    const expectedSig = crypto
+      .createHmac("sha256", MACAROON_SECRET)
+      .update(payload)
+      .digest("hex");
+    if (signature !== expectedSig) return null;
+
+    const data: MacaroonData = JSON.parse(payload);
+    if (data.expiresAt < Date.now()) return null;
+
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+// --- Preimage verification ---
+
+function verifyPreimage(preimage: string, paymentHash: string): boolean {
+  const preimageBytes = Buffer.from(preimage, "hex");
+  const hash = crypto.createHash("sha256").update(preimageBytes).digest("hex");
+  return hash === paymentHash;
+}
+
+// --- L402 middleware ---
+
+interface L402Options {
+  /** Price in millisats */
+  priceMsats: number;
+  /** Invoice description */
+  description?: string;
+  /** Token validity in milliseconds (default: 1 hour) */
+  ttlMs?: number;
+  /** Resource identifier for the macaroon */
+  identifier?: string;
+}
+
+function l402(options: L402Options) {
+  const {
+    priceMsats,
+    description = "L402 API access",
+    ttlMs = 3600_000,
+    identifier = "api-access",
+  } = options;
+
+  return async (
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction
+  ) => {
+    const authHeader = req.headers.authorization;
+
+    // Check for existing L402 token
+    if (authHeader?.startsWith("L402 ")) {
+      const parts = authHeader.slice(5).split(":");
+      if (parts.length === 2) {
+        const [macaroon, preimage] = parts;
+        const data = verifyMacaroon(macaroon);
+
+        if (data && verifyPreimage(preimage, data.paymentHash)) {
+          // Valid token — grant access
+          return next();
+        }
+      }
+
+      return res.status(401).json({ error: "Invalid or expired L402 token" });
+    }
+
+    // No token — create an invoice and return 402
+    try {
+      const transaction = await client.makeInvoice({
+        amount: priceMsats,
+        description,
+      });
+
+      const macaroon = createMacaroon({
+        paymentHash: transaction.payment_hash,
+        identifier,
+        expiresAt: Date.now() + ttlMs,
+      });
+
+      res
+        .status(402)
+        .set(
+          "WWW-Authenticate",
+          `L402 macaroon="${macaroon}", invoice="${transaction.invoice}"`
+        )
+        .json({
+          error: "Payment Required",
+          message: `Pay ${Math.floor(priceMsats / 1000)} sats to access this resource.`,
+        });
+    } catch (error) {
+      console.error("Failed to create L402 invoice:", error);
+      res.status(500).json({ error: "Failed to generate payment challenge" });
+    }
+  };
+}
+
+// --- Routes ---
+
+// Protect a route: 1000 sats per request
+app.get(
+  "/api/premium/data",
+  l402({
+    priceMsats: 1_000_000, // 1000 sats in millisats
+    description: "Premium API data access",
+    identifier: "premium-data",
+  }),
+  (req, res) => {
+    res.json({ data: "This is the premium content!" });
+  }
+);
+
+// Protect a different route with a different price
+app.get(
+  "/api/premium/report",
+  l402({
+    priceMsats: 5_000_000, // 5000 sats
+    description: "Premium report generation",
+    identifier: "premium-report",
+    ttlMs: 24 * 60 * 60 * 1000, // 24 hour token validity
+  }),
+  (req, res) => {
+    res.json({ report: "Detailed analytics report..." });
+  }
+);
+
+// Free route — no L402
+app.get("/api/public/info", (req, res) => {
+  res.json({ message: "This is free." });
+});
+
+app.listen(3000, () => {
+  console.log("L402 API server running on http://localhost:3000");
+});
+
+// Cleanup
+process.on("SIGINT", () => {
+  client.close();
+  process.exit();
+});
+```
+
+### How the Server Verification Works
+
+1. The macaroon is an HMAC-signed JSON token containing the `paymentHash`, an `identifier`, and an `expiresAt` timestamp. The HMAC ensures it cannot be forged without the server's `MACAROON_SECRET`.
+2. When a client presents `Authorization: L402 <macaroon>:<preimage>`, the server:
+   - Verifies the macaroon signature (was it issued by this server?)
+   - Checks the macaroon hasn't expired
+   - Hashes the preimage with SHA-256 and compares it to the `paymentHash` in the macaroon
+   - If the hash matches, the client has proven they paid the invoice — access is granted
+
+### End-to-End Test
+
+Using [testing wallets](../testing-wallets.md), you can test the full L402 flow without real bitcoin:
+
+```ts
+import { fetchWithL402, MemoryStorage } from "@getalby/lightning-tools";
+import { NostrWebLNProvider } from "@getalby/sdk/webln";
+
+// Create a test wallet
+const faucetResponse = await fetch("https://faucet.nwc.dev?balance=10000", {
+  method: "POST",
+});
+const nwcUrl = (await faucetResponse.text()).trim();
+
+const webln = new NostrWebLNProvider({ nostrWalletConnectUrl: nwcUrl });
+await webln.enable();
+
+const store = new MemoryStorage();
+
+// This will: get a 402, pay the invoice, retry with the token
+const response = await fetchWithL402(
+  "http://localhost:3000/api/premium/data",
+  { method: "GET" },
+  { webln, store }
+);
+
+console.log("Status:", response.status);
+console.log("Data:", await response.json());
+
+webln.close();
+```
diff --git a/references/lightning-tools/lightning-tools.md b/references/lightning-tools/lightning-tools.md
index f17d5e1..7f17e68 100644
--- a/references/lightning-tools/lightning-tools.md
+++ b/references/lightning-tools/lightning-tools.md
@@ -4,6 +4,16 @@
 
 Install the NPM package `@getalby/lightning-tools`. The latest version is 6.1.0.
 
+## Imports
+
+Use subpath imports to import only what you need:
+
+- `@getalby/lightning-tools/lnurl` — `LightningAddress` and LNURL utilities
+- `@getalby/lightning-tools/fiat` — Fiat currency conversion functions
+- `@getalby/lightning-tools/bolt11` — `Invoice` class and `decodeInvoice`
+
+Do NOT import from the package root (e.g. `import { LightningAddress } from "@getalby/lightning-tools"`). Always use the subpath imports shown in the examples.
+
 ## Units
 
 All referenced files in this folder operate in satoshis (sats).
@@ -15,3 +25,5 @@ Make sure to read the [Lightning tools typings](./index.d.ts) when using any of
 - [Request BOLT-11 invoices from a lightning address](./lnurl.md)
 - [Convert between bitcoin and fiat currency amounts](./fiat.md)
 - [Decode and work with invoices](./invoice.md)
+- [Nostr Zaps: send lightning payments tied to Nostr events and profiles](./zaps.md)
+- [L402: consume and build Lightning-gated APIs and paywalled resources](./l402.md)
diff --git a/references/lightning-tools/lnurl.md b/references/lightning-tools/lnurl.md
index eea4b89..5a7c666 100644
--- a/references/lightning-tools/lnurl.md
+++ b/references/lightning-tools/lnurl.md
@@ -11,6 +11,101 @@ await ln.fetch();
 const invoice = await ln.requestInvoice({ satoshi: 1000 });
 ```
 
+## Request an Invoice with a Comment
+
+If the lightning address supports comments (LUD-12), you can attach a message:
+
+```ts
+const invoice = await ln.requestInvoice({
+  satoshi: 1000,
+  comment: "Great work, keep it up!",
+});
+```
+
+Check the maximum comment length before sending — see [Metadata Introspection](#metadata-introspection) below.
+
+## Request an Invoice with Payer Data
+
+If the lightning address supports payer data (LUD-18), you can identify the sender:
+
+```ts
+const invoice = await ln.requestInvoice({
+  satoshi: 1000,
+  payerdata: {
+    name: "Alice",
+    email: "alice@example.com",
+  },
+});
+```
+
+Check which payer data fields the recipient supports and which are mandatory — see [Metadata Introspection](#metadata-introspection) below.
+
+## Metadata Introspection
+
+After calling `ln.fetch()`, the `LightningAddress` instance exposes metadata from the LNURL-pay endpoint. Always check these before requesting an invoice to avoid errors.
+
+### Min / Max Sendable Amounts
+
+```ts
+await ln.fetch();
+
+if (ln.lnurlpData) {
+  console.log("Min sendable:", ln.lnurlpData.min, "sats");
+  console.log("Max sendable:", ln.lnurlpData.max, "sats");
+  console.log("Fixed amount only:", ln.lnurlpData.fixed); // true if min === max
+  console.log("Description:", ln.lnurlpData.description);
+}
+```
+
+### Validate Amount Before Requesting
+
+```ts
+function validateAmount(ln: LightningAddress, satoshi: number): void {
+  if (!ln.lnurlpData) {
+    throw new Error("Call ln.fetch() first");
+  }
+  if (satoshi < ln.lnurlpData.min) {
+    throw new Error(`Amount too low. Minimum: ${ln.lnurlpData.min} sats`);
+  }
+  if (satoshi > ln.lnurlpData.max) {
+    throw new Error(`Amount too high. Maximum: ${ln.lnurlpData.max} sats`);
+  }
+}
+```
+
+### Check Comment Support
+
+```ts
+if (ln.lnurlpData?.commentAllowed) {
+  console.log("Comments supported, max length:", ln.lnurlpData.commentAllowed);
+} else {
+  console.log("Comments not supported by this lightning address.");
+}
+```
+
+### Check Payer Data Requirements
+
+```ts
+if (ln.lnurlpData?.payerData) {
+  const pd = ln.lnurlpData.payerData;
+  if (pd.name) console.log("Name:", pd.name.mandatory ? "required" : "optional");
+  if (pd.email) console.log("Email:", pd.email.mandatory ? "required" : "optional");
+  if (pd.pubkey) console.log("Pubkey:", pd.pubkey.mandatory ? "required" : "optional");
+} else {
+  console.log("Payer data not supported by this lightning address.");
+}
+```
+
+### Nostr Integration
+
+```ts
+if (ln.nostrPubkey) {
+  console.log("Nostr pubkey:", ln.nostrPubkey);
+  console.log("Nostr relays:", ln.nostrRelays);
+  console.log("Supports Nostr zaps:", ln.lnurlpData?.allowsNostr);
+}
+```
+
 ## Check if an invoice was paid (LNURL-Verify)
 
 NOTE: not all lightning address providers support LNURL-Verify.
@@ -18,3 +113,23 @@ NOTE: not all lightning address providers support LNURL-Verify.
 ```ts
 const isPaid = await invoice.isPaid();
 ```
+
+## Proxy Configuration (Browser vs Node.js)
+
+In the browser, lightning address requests are subject to CORS restrictions. By default, `LightningAddress` routes requests through a proxy (`https://api.getalby.com/lnurl`) to avoid CORS errors. This works out of the box for browser apps.
+
+In Node.js / server-side environments, you can disable the proxy for direct requests:
+
+```ts
+const ln = new LightningAddress("hello@getalby.com", {
+  proxy: false,
+});
+```
+
+You can also provide a custom proxy URL:
+
+```ts
+const ln = new LightningAddress("hello@getalby.com", {
+  proxy: "https://my-proxy.example.com/lnurl",
+});
+```
diff --git a/references/lightning-tools/zaps.md b/references/lightning-tools/zaps.md
new file mode 100644
index 0000000..7f54cd7
--- /dev/null
+++ b/references/lightning-tools/zaps.md
@@ -0,0 +1,167 @@
+# Nostr Zaps
+
+IMPORTANT: read the [typings](./index.d.ts) to better understand how this works.
+
+Nostr Zaps are lightning payments tied to Nostr events or profiles, defined by [NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md). They allow users to send sats to a Nostr user's lightning address with a signed Nostr event that proves who sent the zap and (optionally) which note was zapped.
+
+## Prerequisites
+
+- The recipient must have a lightning address that supports Nostr zaps (`allowsNostr: true` — see [metadata introspection](./lnurl.md#metadata-introspection))
+- The sender needs a **Nostr provider** that can sign events (e.g. a NIP-07 browser extension like Alby or nos2x, or a custom signer with a private key)
+
+## Generate a Zap Invoice (Without Paying)
+
+Use `zapInvoice()` to get a BOLT-11 invoice that includes the zap event. You can then pay this invoice yourself (e.g. via NWC Client) or display it as a QR code:
+
+```ts
+import { LightningAddress } from "@getalby/lightning-tools/lnurl";
+
+const ln = new LightningAddress("hello@getalby.com");
+await ln.fetch();
+
+// Verify the recipient supports zaps
+if (!ln.lnurlpData?.allowsNostr) {
+  throw new Error("This lightning address does not support Nostr zaps.");
+}
+
+// nostrProvider must implement: getPublicKey() and signEvent()
+// In a browser, this is typically window.nostr (NIP-07 extension)
+const nostrProvider = window.nostr;
+
+const invoice = await ln.zapInvoice(
+  {
+    satoshi: 1000,
+    comment: "Great post! ⚡",
+    relays: ["wss://relay.damus.io", "wss://relay.nostr.band"],
+    // e: noteId,  // optional: the Nostr event ID being zapped
+  },
+  { nostr: nostrProvider }
+);
+
+console.log("Zap invoice:", invoice.paymentRequest);
+// Pay this invoice via NWC Client, QR code, or any other method
+```
+
+### Pay the Zap Invoice with NWC Client
+
+Since NWC Client uses millisats, no conversion is needed for `payInvoice` — it takes the BOLT-11 string directly:
+
+```ts
+import { NWCClient } from "@getalby/sdk/nwc";
+
+const client = new NWCClient({
+  nostrWalletConnectUrl: process.env.NWC_URL,
+});
+
+const response = await client.payInvoice({
+  invoice: invoice.paymentRequest,
+});
+console.log("Zap sent! Preimage:", response.preimage);
+```
+
+## Zap and Pay in One Step (WebLN / Browser)
+
+If a WebLN provider is available (e.g. via Bitcoin Connect), `zap()` generates the zap invoice and pays it in a single call:
+
+```ts
+import { LightningAddress } from "@getalby/lightning-tools/lnurl";
+import { requestProvider } from "@getalby/bitcoin-connect";
+
+const provider = await requestProvider();
+const nostrProvider = window.nostr;
+
+const ln = new LightningAddress("hello@getalby.com", {
+  webln: provider,
+});
+await ln.fetch();
+
+const response = await ln.zap(
+  {
+    satoshi: 500,
+    comment: "Zapping from the browser!",
+    relays: ["wss://relay.damus.io"],
+  },
+  { nostr: nostrProvider }
+);
+
+console.log("Zap paid! Preimage:", response.preimage);
+```
+
+## Generate a Zap Event Manually
+
+For advanced use cases, you can generate the zap request event yourself using `generateZapEvent`:
+
+```ts
+import { generateZapEvent } from "@getalby/lightning-tools/lnurl";
+
+const zapEvent = await generateZapEvent(
+  {
+    satoshi: 1000,
+    comment: "Nice work!",
+    relays: ["wss://relay.damus.io", "wss://nos.lol"],
+    p: recipientNostrPubkeyHex, // recipient's Nostr pubkey (hex)
+    e: noteIdHex,               // optional: event ID being zapped (hex)
+  },
+  { nostr: nostrProvider }
+);
+
+console.log("Zap request event:", zapEvent);
+// This event can be included in a LNURL-pay request as the `nostr` parameter
+```
+
+## Zapping a Specific Note vs a Profile
+
+- **Zap a profile:** Omit the `e` field. The zap is attributed to the user, not a specific note.
+- **Zap a note:** Include the `e` field with the Nostr event ID (hex) of the note being zapped.
+
+```ts
+// Zap a profile (no specific note)
+const profileZap = await ln.zapInvoice(
+  {
+    satoshi: 100,
+    relays: ["wss://relay.damus.io"],
+  },
+  { nostr: nostrProvider }
+);
+
+// Zap a specific note
+const noteZap = await ln.zapInvoice(
+  {
+    satoshi: 100,
+    relays: ["wss://relay.damus.io"],
+    e: "note-event-id-hex",
+  },
+  { nostr: nostrProvider }
+);
+```
+
+## Custom Nostr Provider (Server-Side)
+
+In Node.js there is no `window.nostr`. You need to create a Nostr provider from a private key. You can use the `nostr-tools` package for this:
+
+```ts
+import { generateSecretKey, getPublicKey, finalizeEvent } from "nostr-tools/pure";
+import { LightningAddress } from "@getalby/lightning-tools/lnurl";
+
+// Use an existing key or generate one
+const secretKey = generateSecretKey();
+
+const nostrProvider = {
+  getPublicKey: async () => getPublicKey(secretKey),
+  signEvent: async (event) => finalizeEvent(event, secretKey),
+};
+
+const ln = new LightningAddress("hello@getalby.com", { proxy: false });
+await ln.fetch();
+
+const invoice = await ln.zapInvoice(
+  {
+    satoshi: 1000,
+    comment: "Server-side zap",
+    relays: ["wss://relay.damus.io"],
+  },
+  { nostr: nostrProvider }
+);
+
+// Pay with NWC Client
+```
diff --git a/references/nwc-client/common-operations.md b/references/nwc-client/common-operations.md
new file mode 100644
index 0000000..4dec205
--- /dev/null
+++ b/references/nwc-client/common-operations.md
@@ -0,0 +1,210 @@
+# Common Operations
+
+IMPORTANT: read the [typings](./nwc.d.ts) to better understand how this works.
+
+## Get Wallet Info
+
+```ts
+const info = await client.getInfo();
+console.log("Alias:", info.alias);
+console.log("Network:", info.network);
+console.log("Supported methods:", info.methods);
+console.log("Lightning address:", info.lud16); // may be undefined
+```
+
+## Get Balance
+
+```ts
+const { balance } = await client.getBalance();
+console.log("Balance:", Math.floor(balance / 1000), "sats"); // balance is in millisats
+```
+
+## Create an Invoice (Receive a Payment)
+
+```ts
+const transaction = await client.makeInvoice({
+  amount: 1000000, // 1000 sats in millisats
+  description: "Payment for order #123",
+});
+console.log("Invoice:", transaction.invoice);
+console.log("Payment hash:", transaction.payment_hash);
+```
+
+### Create an invoice with metadata
+
+Metadata lets you attach structured information to an invoice, such as payer requirements or internal identifiers:
+
+```ts
+const transaction = await client.makeInvoice({
+  amount: 500000, // 500 sats in millisats
+  description: "Donation",
+  metadata: {
+    comment: "Thanks for the great work!",
+    recipient_data: {
+      identifier: "order-456",
+    },
+  },
+});
+```
+
+To wait for the invoice to be paid, use [notifications](./notifications.md).
+
+## Look Up an Invoice
+
+```ts
+// Look up by payment hash
+const transaction = await client.lookupInvoice({
+  payment_hash: paymentHash,
+});
+console.log("State:", transaction.state); // "settled", "pending", "failed", or "accepted"
+console.log("Amount:", Math.floor(transaction.amount / 1000), "sats");
+
+// Or look up by BOLT-11 invoice string
+const transaction2 = await client.lookupInvoice({
+  invoice: bolt11Invoice,
+});
+```
+
+## List Transactions
+
+```ts
+// List recent settled transactions
+const { transactions } = await client.listTransactions({
+  limit: 10,
+});
+
+for (const tx of transactions) {
+  const amountSats = Math.floor(tx.amount / 1000);
+  console.log(`${tx.type} | ${amountSats} sats | ${tx.description || "(no description)"} | ${tx.state}`);
+}
+```
+
+### Filter by type and time range
+
+```ts
+// Only incoming payments in the last 24 hours
+const oneDayAgo = Math.floor((Date.now() - 24 * 60 * 60 * 1000) / 1000);
+const { transactions } = await client.listTransactions({
+  type: "incoming",
+  from: oneDayAgo,
+  limit: 50,
+});
+```
+
+### Include pending/unpaid transactions
+
+```ts
+const { transactions } = await client.listTransactions({
+  unpaid: true,
+  limit: 20,
+});
+
+const pending = transactions.filter((tx) => tx.state === "pending");
+```
+
+## Get Budget
+
+Check how much of the app connection's budget has been used:
+
+```ts
+const budget = await client.getBudget();
+
+if ("total_budget" in budget) {
+  const usedSats = Math.floor(budget.used_budget / 1000);
+  const totalSats = Math.floor(budget.total_budget / 1000);
+  console.log(`Budget: ${usedSats} / ${totalSats} sats used`);
+  if (budget.renews_at) {
+    console.log("Renews at:", new Date(budget.renews_at * 1000).toISOString());
+  }
+} else {
+  console.log("No budget restrictions on this connection.");
+}
+```
+
+## Sign a Message
+
+```ts
+const { signature, message } = await client.signMessage({
+  message: "Proof of wallet ownership",
+});
+console.log("Signature:", signature);
+```
+
+## Pay Multiple Invoices at Once
+
+```ts
+const result = await client.multiPayInvoice({
+  invoices: [
+    { invoice: bolt11Invoice1, id: "payment-1" },
+    { invoice: bolt11Invoice2, id: "payment-2" },
+  ],
+});
+
+for (const paid of result.invoices) {
+  console.log(`Paid ${paid.dTag}: preimage ${paid.preimage}`);
+}
+```
+
+## Pay an Amountless Invoice
+
+Some invoices are created without a fixed amount (e.g. tip jars, donations). When paying these, you must provide the `amount` field (in millisats):
+
+```ts
+const response = await client.payInvoice({
+  invoice: amountlessInvoice,
+  amount: 5000000, // 5000 sats in millisats — you choose the amount
+});
+console.log("Preimage:", response.preimage);
+```
+
+If you try to pay an amountless invoice without specifying `amount`, the wallet will return an error.
+
+## Send a Payment with Metadata
+
+You can attach metadata when sending a payment. This is useful for adding context visible to the recipient:
+
+```ts
+const response = await client.payInvoice({
+  invoice,
+  metadata: {
+    comment: "Payment for invoice #789",
+    payer_data: {
+      name: "Alice",
+      email: "alice@example.com",
+    },
+  },
+});
+```
+
+## Reading Transaction Metadata
+
+Transactions returned from `listTransactions`, `lookupInvoice`, `makeInvoice`, and notifications may include metadata:
+
+```ts
+const { transactions } = await client.listTransactions({ limit: 10 });
+
+for (const tx of transactions) {
+  if (tx.metadata?.comment) {
+    console.log("Comment:", tx.metadata.comment);
+  }
+  if (tx.metadata?.payer_data?.name) {
+    console.log("Payer:", tx.metadata.payer_data.name);
+  }
+  if (tx.metadata?.payer_data?.email) {
+    console.log("Email:", tx.metadata.payer_data.email);
+  }
+  if (tx.metadata?.recipient_data?.identifier) {
+    console.log("Recipient ID:", tx.metadata.recipient_data.identifier);
+  }
+}
+```
+
+## Access the Lightning Address
+
+The lightning address is available directly on the client if the NWC connection secret includes a `lud16` parameter:
+
+```ts
+if (client.lud16) {
+  console.log("Lightning address:", client.lud16);
+}
+```
diff --git a/references/nwc-client/error-handling.md b/references/nwc-client/error-handling.md
new file mode 100644
index 0000000..12c2899
--- /dev/null
+++ b/references/nwc-client/error-handling.md
@@ -0,0 +1,126 @@
+# Error Handling
+
+IMPORTANT: read the [typings](./nwc.d.ts) to better understand how this works.
+
+## Error Types
+
+All errors extend `Nip47Error`, which has a `code` and `message` property.
+
+| Error Class | When it occurs |
+|---|---|
+| `Nip47WalletError` | The wallet received the request but rejected it (e.g. insufficient balance, quota exceeded). Check the `.code` property for the specific reason. |
+| `Nip47TimeoutError` | Base class for timeout errors (see below). |
+| `Nip47PublishTimeoutError` | The request could not be published to the relay in time. |
+| `Nip47ReplyTimeoutError` | The request was published but the wallet did not reply in time. |
+| `Nip47NetworkError` | A network-level failure (e.g. relay unreachable, WebSocket dropped). |
+| `Nip47PublishError` | The relay rejected the published event. |
+| `Nip47ResponseDecodingError` | The wallet's response could not be decrypted or decoded. |
+| `Nip47ResponseValidationError` | The wallet's response was decoded but failed validation. |
+| `Nip47UnexpectedResponseError` | An unexpected response type was received. |
+| `Nip47UnsupportedEncryptionError` | The wallet does not support a compatible encryption type. |
+
+## Common Wallet Error Codes (`Nip47WalletError`)
+
+These are returned by the wallet when it rejects a request:
+
+| Code | Description |
+|---|---|
+| `INSUFFICIENT_BALANCE` | The wallet does not have enough funds for this payment. |
+| `QUOTA_EXCEEDED` | The app connection's budget has been exceeded. |
+| `NOT_FOUND` | The requested invoice or transaction was not found. |
+| `RATE_LIMITED` | Too many requests — the wallet is rate limiting. |
+| `NOT_IMPLEMENTED` | The wallet does not support this method. |
+| `INTERNAL` | An internal wallet error occurred. |
+| `OTHER` | An unspecified error. |
+| `RESTRICTED` | The app connection does not have permission for this method. |
+| `UNAUTHORIZED` | The app connection is not authorized. |
+| `PAYMENT_FAILED` | The payment could not be completed (e.g. no route found). |
+
+## Example: Handling Payment Errors
+
+```ts
+import { NWCClient, Nip47WalletError, Nip47TimeoutError, Nip47NetworkError } from "@getalby/sdk/nwc";
+
+try {
+  const response = await client.payInvoice({ invoice });
+  console.log("Payment successful! Preimage:", response.preimage);
+} catch (error) {
+  if (error instanceof Nip47WalletError) {
+    // The wallet received the request but rejected it
+    switch (error.code) {
+      case "INSUFFICIENT_BALANCE":
+        console.error("Not enough funds to complete this payment.");
+        break;
+      case "QUOTA_EXCEEDED":
+        console.error("Budget limit reached. Try again after the budget renews.");
+        break;
+      case "PAYMENT_FAILED":
+        console.error("Payment failed (e.g. no route to destination).");
+        break;
+      case "RATE_LIMITED":
+        console.error("Too many requests. Try again later.");
+        break;
+      default:
+        console.error(`Wallet error [${error.code}]: ${error.message}`);
+    }
+  } else if (error instanceof Nip47TimeoutError) {
+    // Request timed out — the relay or wallet may be slow or unreachable
+    console.error("Request timed out. The wallet or relay may be temporarily unavailable.");
+  } else if (error instanceof Nip47NetworkError) {
+    // Network-level failure
+    console.error("Network error. Check relay connectivity.");
+  } else {
+    throw error; // Unexpected error, re-throw
+  }
+}
+```
+
+## Example: Handling Invoice Creation Errors
+
+```ts
+try {
+  const transaction = await client.makeInvoice({
+    amount: 1000000, // 1000 sats in millisats
+    description: "Order #123",
+  });
+  console.log("Invoice created:", transaction.invoice);
+} catch (error) {
+  if (error instanceof Nip47WalletError) {
+    console.error(`Failed to create invoice [${error.code}]: ${error.message}`);
+  } else {
+    throw error;
+  }
+}
+```
+
+## Budget and Permission Guardrails
+
+- `QUOTA_EXCEEDED`: surface a clear message (e.g., "Budget reached. Approve a higher budget or wait for renewal.") and prompt the user to re-authorize with a larger budget or wait until `renewal_period`. You can inspect `getBudget()` to show `used_budget`, `total_budget`, and `renews_at`.
+- `RESTRICTED`: the connection lacks the required permission for the requested method. Ask the user to create a new connection with the needed methods enabled (`request_methods`) and reconnect.
+- `UNAUTHORIZED`: connection is invalid/expired; request a fresh connection secret.
+- `RATE_LIMITED`: back off and retry later with exponential backoff.
+- Always redact the `nostrWalletConnectUrl` and secrets from logs and error messages.
+
+## Retry Pattern for Transient Errors
+
+Network and timeout errors are often transient. Here is a simple retry wrapper:
+
+```ts
+async function withRetry<T>(fn: () => Promise<T>, retries = 3, delayMs = 1000): Promise<T> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      const isTransient = error instanceof Nip47TimeoutError || error instanceof Nip47NetworkError;
+      if (!isTransient || i === retries - 1) {
+        throw error;
+      }
+      await new Promise((r) => setTimeout(r, delayMs * (i + 1)));
+    }
+  }
+  throw new Error("Unreachable");
+}
+
+// Usage:
+const response = await withRetry(() => client.payInvoice({ invoice }));
+```
diff --git a/references/nwc-client/notifications.md b/references/nwc-client/notifications.md
index 412b09a..d3aa68e 100644
--- a/references/nwc-client/notifications.md
+++ b/references/nwc-client/notifications.md
@@ -1,12 +1,65 @@
-# Example
+# Notifications Guide
 
 IMPORTANT: read the [typings](./nwc.d.ts) to better understand how this works.
 
+## Subscribe with Filtering, Dedupe, and Cleanup
+
 ```ts
-const onNotification = (notification) =>
-  console.info("Got notification", notification);
+// Track processed payment_hash values to avoid double-handling
+const seen = new Set<string>();
+
+// Filter by notification type to reduce noise
+const notificationTypes = ["payment_received", "payment_sent", "hold_invoice_accepted"] as const;
+
+const onNotification = (notification: { notification_type: (typeof notificationTypes)[number]; notification: any }) => {
+  const { notification_type, notification: payload } = notification;
+  const { payment_hash, amount, state, type } = payload;
+
+  // Dedupe by payment hash (idempotent handling)
+  if (payment_hash && seen.has(payment_hash)) return;
+  if (payment_hash) seen.add(payment_hash);
+
+  // Ignore irrelevant states (optional)
+  if (state && state === "failed") {
+    console.warn("Ignoring failed notification", payment_hash);
+    return;
+  }
 
-const unsub = await client.subscribeNotifications(onNotification);
+  // Convert msats → sats for display
+  const sats = Math.floor((amount ?? 0) / 1000);
 
-// later you can call unsub(); if you don't need to subscribe any more
+  switch (notification_type) {
+    case "payment_received":
+      console.info(`Received ${sats} sats (${payment_hash})`);
+      break;
+    case "payment_sent":
+      console.info(`Sent ${sats} sats (${payment_hash})`);
+      break;
+    case "hold_invoice_accepted":
+      console.info(`Hold invoice accepted (${payment_hash}) — decide to settle or cancel.`);
+      break;
+    default:
+      console.info("Other notification", notification);
+  }
+};
+
+// Subscribe (stays alive while the subscription is active)
+const unsub = await client.subscribeNotifications(onNotification, notificationTypes);
+
+// Graceful shutdown / page unload
+const cleanup = () => {
+  unsub?.();
+  client.close();
+};
+if (typeof window !== "undefined") {
+  window.addEventListener("beforeunload", cleanup);
+} else {
+  process.on("SIGINT", cleanup);
+}
 ```
+
+## Resilience Tips
+
+- If the process exits or the page reloads, the subscription ends; re-subscribe on startup.
+- Handle transient network issues by allowing the client to reconnect; if you detect a dropped relay/WebSocket, recreate the client and `subscribeNotifications`.
+- Keep the handler idempotent (dedupe by `payment_hash`) to tolerate reconnects and wallet replays.
diff --git a/references/nwc-client/nwc-client.md b/references/nwc-client/nwc-client.md
index ba49bbb..05a2c37 100644
--- a/references/nwc-client/nwc-client.md
+++ b/references/nwc-client/nwc-client.md
@@ -25,19 +25,146 @@ When displaying to humans, please use satoshis (rounded to a whole value).
 
 ## Initialization
 
+### Node.js / Backend
+
+```ts
+import { NWCClient } from "@getalby/sdk/nwc";
+
+const client = new NWCClient({
+  nostrWalletConnectUrl: process.env.NWC_URL,
+});
+```
+
+### Browser (with bundler)
+
+In a browser, the NWC connection secret typically comes from user input, a URL parameter, or `localStorage` — never hardcoded:
+
 ```ts
 import { NWCClient } from "@getalby/sdk/nwc";
-// or from e.g. https://esm.sh/@getalby/sdk@7.0.0
 
+// From user input (e.g. a text field or paste event)
 const client = new NWCClient({
-  nostrWalletConnectUrl,
+  nostrWalletConnectUrl: userProvidedNwcUrl,
 });
 ```
 
+### Browser (CDN, no build step)
+
+```html
+<script type="module">
+  import { NWCClient } from "https://esm.sh/@getalby/sdk@7.0.0/nwc";
+
+  const client = new NWCClient({
+    nostrWalletConnectUrl: nwcUrl,
+  });
+</script>
+```
+
+### Browser: Using NWC Client with Bitcoin Connect
+
+If the user connects their wallet via [Bitcoin Connect](../bitcoin-connect/bitcoin-connect.md), you can access the underlying NWC Client for advanced operations (e.g. notifications, hold invoices) that aren't available through WebLN alone:
+
+```ts
+import { WebLNProviders, requestProvider } from "@getalby/bitcoin-connect";
+import { NWCClient } from "@getalby/sdk/nwc";
+
+const provider = await requestProvider();
+
+if (provider instanceof WebLNProviders.NostrWebLNProvider) {
+  // Get the NWC connection URL from the connected provider
+  const nwcUrl = provider.client.nostrWalletConnectUrl;
+
+  // Create a dedicated NWCClient for advanced operations
+  const client = new NWCClient({ nostrWalletConnectUrl: nwcUrl });
+
+  // Now you can use notifications, hold invoices, etc.
+  const unsub = await client.subscribeNotifications((notification) => {
+    console.log("Payment notification:", notification);
+  });
+}
+```
+
 ## Referenced files
 
 Make sure to read the [NWC Client typings](./nwc.d.ts) when using any of the below referenced files.
 
+- [Common operations: getBalance, makeInvoice, getInfo, listTransactions, lookupInvoice, getBudget, signMessage, multiPayInvoice](./common-operations.md)
 - [subscribe to notifications of sent or received payments](./notifications.md)
 - [How to pay a BOLT-11 lightning invoice](pay-invoice.md)
 - [How to create, settle and cancel HOLD invoices for conditional payments](hold-invoices.md)
+- [Error handling: error types, wallet error codes, and retry patterns](./error-handling.md)
+
+## Cleanup
+
+### Node.js
+
+Always close the client when your application exits to avoid leaked WebSocket connections:
+
+```ts
+process.on("SIGINT", () => {
+  client.close();
+  process.exit();
+});
+```
+
+If you are using `subscribeNotifications`, unsubscribe before closing:
+
+```ts
+const unsub = await client.subscribeNotifications(onNotification);
+
+// later, when shutting down:
+unsub();
+client.close();
+```
+
+### Browser
+
+In the browser, clean up on page unload or when the component unmounts:
+
+```ts
+// On page unload
+window.addEventListener("beforeunload", () => {
+  unsub?.();
+  client.close();
+});
+```
+
+In React, clean up in a `useEffect` return:
+
+```tsx
+useEffect(() => {
+  const client = new NWCClient({ nostrWalletConnectUrl: nwcUrl });
+  let unsub: (() => void) | undefined;
+
+  client.subscribeNotifications((notification) => {
+    console.log("Notification:", notification);
+  }).then((unsubFn) => {
+    unsub = unsubFn;
+  });
+
+  return () => {
+    unsub?.();
+    client.close();
+  };
+}, [nwcUrl]);
+```
+
+### Long-Lived Node.js Processes
+
+When subscribing to notifications in a Node.js script, the process must stay alive for the subscription to work. The WebSocket connection kept open by `subscribeNotifications` will keep the Node.js event loop running automatically — no extra keep-alive code is needed. The process will stay alive as long as the subscription is active. Call `unsub()` and `client.close()` when you want the process to exit.
+
+## Advanced: Creating new connections and NWA/NWCWalletService
+
+To mint new app connections programmatically, use the authorization helpers:
+
+- `NWCClient.getAuthorizationUrl(basePath, options, pubkey)` to build a deeplink/QR for a wallet UI that will provision a new connection with requested methods, budget, expiry, isolated flag, etc.
+- `NWCClient.fromAuthorizationUrl(basePath, options?, secret?)` to generate and return a ready `NWCClient` plus the full `nostrWalletConnectUrl` you should persist (store securely, never log). Show the resulting URL to the user (deeplink or QR) so they can approve it.
+- `client.createConnection({ pubkey, name, request_methods, ... })` to request a scoped connection from within an existing session.
+
+When you receive the resulting `nostrWalletConnectUrl`, persist it securely (env var on backend; user-controlled persistence on frontend) and never print or log it.
+
+The typings also export `NWAClient` (Nostr Wallet Auth — wallet-initiated connections) and `NWCWalletService` (build a wallet provider). These are **advanced** and should only be used when you intend to:
+- Build a wallet service/provider (use `NWCWalletService`).
+- Implement wallet-initiated auth flows (use `NWAClient`).
+
+For typical application development (sending/receiving payments, checking balances, notifications, budgets), use `NWCClient` as documented above.
\ No newline at end of file