Add payment watch, unauthenticated invoice creation, LNURL support

- Add payments.watch() SSE stream for real-time payment events (settled/failed)
- Add invoices.create_for_wallet() and create_for_address() for unauthenticated invoice creation
- Add PaymentEvent, AddressInvoiceResponse types (sync + async)
- Update payment docs to mention LNURL as accepted target
- Bump version to 0.3.0

Made-with: Cursor

Author: realbub

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lnbot"
-version = "0.1.1"
+version = "0.3.0"
 description = "Official Python SDK for LnBot — Bitcoin for AI Agents. Send and receive sats over Lightning with a few lines of code."
 readme = "README.md"
 license = "MIT"

src/lnbot/__init__.py

@@ -15,6 +15,7 @@
     UnauthorizedError,
 )
 from .types import (
+    AddressInvoiceResponse,
     AddressResponse,
     ApiKeyResponse,
     BackupPasskeyBeginResponse,
@@ -23,6 +24,7 @@
     InvoiceEvent,
     InvoiceResponse,
     InvoiceStatus,
+    PaymentEvent,
     PaymentResponse,
     PaymentStatus,
     RecoveryBackupResponse,
@@ -54,8 +56,10 @@
     "InvoiceResponse",
     "InvoiceStatus",
     "InvoiceEvent",
+    "AddressInvoiceResponse",
     "PaymentResponse",
     "PaymentStatus",
+    "PaymentEvent",
     "AddressResponse",
     "TransferAddressResponse",
     "TransactionResponse",

src/lnbot/client.py

@@ -18,13 +18,15 @@
     _extract_message,
 )
 from .types import (
+    AddressInvoiceResponse,
     AddressResponse,
     ApiKeyResponse,
     BackupPasskeyBeginResponse,
     CreateWalletResponse,
     CreateWebhookResponse,
     InvoiceEvent,
     InvoiceResponse,
+    PaymentEvent,
     PaymentResponse,
     RecoveryBackupResponse,
     RecoveryRestoreResponse,
@@ -137,6 +139,16 @@ def get(self, number: int) -> InvoiceResponse:
         """Get a single invoice by its number."""
         return parse(InvoiceResponse, self._c._get(f"/v1/invoices/{number}"))
 
+    def create_for_wallet(self, *, wallet_id: str, amount: int, reference: str | None = None, comment: str | None = None) -> AddressInvoiceResponse:
+        """Create an invoice for a specific wallet by ID. No authentication required."""
+        body = to_camel({"wallet_id": wallet_id, "amount": amount, "reference": reference, "comment": comment})
+        return parse(AddressInvoiceResponse, self._c._post("/v1/invoices/for-wallet", body))
+
+    def create_for_address(self, *, address: str, amount: int, tag: str | None = None, comment: str | None = None) -> AddressInvoiceResponse:
+        """Create an invoice for a Lightning address. No authentication required."""
+        body = to_camel({"address": address, "amount": amount, "tag": tag, "comment": comment})
+        return parse(AddressInvoiceResponse, self._c._post("/v1/invoices/for-address", body))
+
     def watch(self, number: int, *, timeout: int | None = None) -> Iterator[InvoiceEvent]:
         """Stream SSE events until the invoice is settled or expires."""
         params = _qs({"timeout": timeout})
@@ -161,13 +173,13 @@ def watch(self, number: int, *, timeout: int | None = None) -> Iterator[InvoiceE
 
 
 class PaymentsResource:
-    """Send sats to Lightning addresses or BOLT11 invoices."""
+    """Send sats to Lightning addresses, LNURLs, or BOLT11 invoices."""
 
     def __init__(self, client: LnBot) -> None:
         self._c = client
 
     def create(self, *, target: str, amount: int | None = None, idempotency_key: str | None = None, max_fee: int | None = None, reference: str | None = None) -> PaymentResponse:
-        """Send a payment to *target* (Lightning address or BOLT11 invoice)."""
+        """Send a payment to *target* (Lightning address, LNURL, or BOLT11 invoice)."""
         body = to_camel({"target": target, "amount": amount, "idempotency_key": idempotency_key, "max_fee": max_fee, "reference": reference})
         return parse(PaymentResponse, self._c._post("/v1/payments", body))
 
@@ -179,6 +191,28 @@ def get(self, number: int) -> PaymentResponse:
         """Get a single payment by its number."""
         return parse(PaymentResponse, self._c._get(f"/v1/payments/{number}"))
 
+    def watch(self, number: int, *, timeout: int | None = None) -> Iterator[PaymentEvent]:
+        """Stream SSE events until the payment settles or fails."""
+        params = _qs({"timeout": timeout})
+        headers = {"Accept": "text/event-stream", "User-Agent": _USER_AGENT}
+        if self._c._api_key:
+            headers["Authorization"] = f"Bearer {self._c._api_key}"
+        with self._c._http.stream("GET", f"{self._c._base_url}/v1/payments/{number}/events", params=params, headers=headers) as resp:
+            _raise_for_status(resp)
+            event_type = ""
+            for line in resp.iter_lines():
+                if line.startswith("event:"):
+                    event_type = line[6:].strip()
+                elif line.startswith("data:"):
+                    raw = line[5:].strip()
+                    if raw and event_type:
+                        try:
+                            data = parse(PaymentResponse, json.loads(raw))
+                            yield PaymentEvent(event=event_type, data=data)  # type: ignore[arg-type]
+                        except (json.JSONDecodeError, TypeError):
+                            pass
+                        event_type = ""
+
 
 class AddressesResource:
     """Lightning address management."""
@@ -397,6 +431,16 @@ async def get(self, number: int) -> InvoiceResponse:
         """Get a single invoice by its number."""
         return parse(InvoiceResponse, await self._c._get(f"/v1/invoices/{number}"))
 
+    async def create_for_wallet(self, *, wallet_id: str, amount: int, reference: str | None = None, comment: str | None = None) -> AddressInvoiceResponse:
+        """Create an invoice for a specific wallet by ID. No authentication required."""
+        body = to_camel({"wallet_id": wallet_id, "amount": amount, "reference": reference, "comment": comment})
+        return parse(AddressInvoiceResponse, await self._c._post("/v1/invoices/for-wallet", body))
+
+    async def create_for_address(self, *, address: str, amount: int, tag: str | None = None, comment: str | None = None) -> AddressInvoiceResponse:
+        """Create an invoice for a Lightning address. No authentication required."""
+        body = to_camel({"address": address, "amount": amount, "tag": tag, "comment": comment})
+        return parse(AddressInvoiceResponse, await self._c._post("/v1/invoices/for-address", body))
+
     async def watch(self, number: int, *, timeout: int | None = None) -> AsyncIterator[InvoiceEvent]:
         """Stream SSE events until the invoice is settled or expires."""
         params = _qs({"timeout": timeout})
@@ -421,13 +465,13 @@ async def watch(self, number: int, *, timeout: int | None = None) -> AsyncIterat
 
 
 class AsyncPaymentsResource:
-    """Send sats to Lightning addresses or BOLT11 invoices (async)."""
+    """Send sats to Lightning addresses, LNURLs, or BOLT11 invoices (async)."""
 
     def __init__(self, client: AsyncLnBot) -> None:
         self._c = client
 
     async def create(self, *, target: str, amount: int | None = None, idempotency_key: str | None = None, max_fee: int | None = None, reference: str | None = None) -> PaymentResponse:
-        """Send a payment to *target* (Lightning address or BOLT11 invoice)."""
+        """Send a payment to *target* (Lightning address, LNURL, or BOLT11 invoice)."""
         body = to_camel({"target": target, "amount": amount, "idempotency_key": idempotency_key, "max_fee": max_fee, "reference": reference})
         return parse(PaymentResponse, await self._c._post("/v1/payments", body))
 
@@ -439,6 +483,28 @@ async def get(self, number: int) -> PaymentResponse:
         """Get a single payment by its number."""
         return parse(PaymentResponse, await self._c._get(f"/v1/payments/{number}"))
 
+    async def watch(self, number: int, *, timeout: int | None = None) -> AsyncIterator[PaymentEvent]:
+        """Stream SSE events until the payment settles or fails."""
+        params = _qs({"timeout": timeout})
+        headers = {"Accept": "text/event-stream", "User-Agent": _USER_AGENT}
+        if self._c._api_key:
+            headers["Authorization"] = f"Bearer {self._c._api_key}"
+        async with self._c._http.stream("GET", f"{self._c._base_url}/v1/payments/{number}/events", params=params, headers=headers) as resp:
+            _raise_for_status(resp)
+            event_type = ""
+            async for line in resp.aiter_lines():
+                if line.startswith("event:"):
+                    event_type = line[6:].strip()
+                elif line.startswith("data:"):
+                    raw = line[5:].strip()
+                    if raw and event_type:
+                        try:
+                            data = parse(PaymentResponse, json.loads(raw))
+                            yield PaymentEvent(event=event_type, data=data)  # type: ignore[arg-type]
+                        except (json.JSONDecodeError, TypeError):
+                            pass
+                        event_type = ""
+
 
 class AsyncAddressesResource:
     """Lightning address management (async)."""

src/lnbot/types.py

@@ -71,6 +71,17 @@ class InvoiceResponse:
     expires_at: str | None = None
 
 
+# ---------------------------------------------------------------------------
+# Invoices (unauthenticated)
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class AddressInvoiceResponse:
+    bolt11: str
+    amount: int
+    expires_at: str | None = None
+
+
 # ---------------------------------------------------------------------------
 # Payments
 # ---------------------------------------------------------------------------
@@ -194,6 +205,12 @@ class InvoiceEvent:
     data: InvoiceResponse
 
 
+@dataclass(frozen=True)
+class PaymentEvent:
+    event: Literal["settled", "failed"]
+    data: PaymentResponse
+
+
 # ---------------------------------------------------------------------------
 # JSON key mapping (snake_case <-> camelCase)
 # ---------------------------------------------------------------------------