bolthub 0.1.0__tar.gz

bolthub-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: bolthub
+Version: 0.1.0
+Summary: L402 client for AI agents — pay Lightning invoices automatically to access paywalled APIs
+License: MIT
+Project-URL: Homepage, https://bolthub.ai
+Project-URL: Repository, https://github.com/signaltech-org/bolthub.ai
+Keywords: l402,lightning,bitcoin,micropayments,ai-agent,paywall
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# bolthub
+
+L402 client for AI agents. Automatically handles 402 Payment Required challenges, pays Lightning invoices, and retries requests with proof of payment.
+
+## Install
+
+```bash
+pip install bolthub
+```
+
+## Quick Start
+
+```python
+from bolthub import L402Client, PhoenixdWallet
+
+wallet = PhoenixdWallet(
+    url="https://your-phoenixd:9740",
+    password="your-phoenixd-password",
+)
+
+client = L402Client(wallet, budget_sats=10_000)
+
+resp = client.get(
+    "https://acme.gw.bolthub.ai/v1/market-data",
+    params={"symbol": "BTC"},
+)
+data = resp.json()
+```
+
+## Wallet Adapters
+
+### Phoenixd (recommended)
+
+Fastest payment speed (<200ms). Get a hosted instance at [nodana.io](https://nodana.io) or self-host from [ACINQ](https://phoenix.acinq.co/server).
+
+```python
+from bolthub import PhoenixdWallet
+
+wallet = PhoenixdWallet(
+    url="https://your-phoenixd:9740",
+    password="your-phoenixd-password",
+    timeout_seconds=35,
+)
+```
+
+### LND
+
+Full Lightning node. Self-host or use [Umbrel](https://umbrel.com) / [Start9](https://start9.com).
+
+```python
+from bolthub import LndWallet
+
+wallet = LndWallet(
+    host="https://your-lnd-node:8080",
+    macaroon="admin-macaroon-hex",
+    timeout_seconds=30,
+)
+```
+
+For agent deployments, use a scoped pay-only macaroon instead of `admin.macaroon`:
+
+```bash
+lncli bakemacaroon uri:/lnrpc.Lightning/SendPaymentSync \
+  uri:/lnrpc.Lightning/DecodePayReq \
+  --save_to=pay-only.macaroon
+```
+
+### LNbits
+
+Lightweight Lightning wallet with multi-wallet support. Create a dedicated wallet for your agent.
+
+```python
+from bolthub import LnbitsWallet
+
+wallet = LnbitsWallet(
+    url="https://lnbits.example.com",
+    admin_key="your-admin-key",
+)
+```
+
+### NWC (Nostr Wallet Connect)
+
+Easiest to set up but slower (1-3s per payment). Get a free NWC connection from [CoinOS](https://coinos.io) or use [Alby Hub](https://getalby.com).
+
+```python
+from bolthub import NwcWallet
+
+# Provide a pay function that handles the NWC protocol.
+# With pynostr or another NWC library:
+def pay_via_nwc(bolt11: str) -> str:
+    # your NWC payment logic here
+    return preimage_hex
+
+wallet = NwcWallet(pay_fn=pay_via_nwc)
+```
+
+### Custom Wallet
+
+Implement the `WalletAdapter` protocol:
+
+```python
+class MyWallet:
+    def pay_invoice(self, bolt11: str) -> str:
+        preimage = my_payment_logic(bolt11)
+        return preimage
+```
+
+## Budget Guards
+
+```python
+client = L402Client(
+    wallet,
+    max_per_request_sats=100,  # reject invoices over 100 sats
+    budget_sats=10_000,         # total spending cap
+)
+
+print(client.total_spent)       # sats spent so far
+print(client.remaining_budget)  # sats remaining
+```
+
+## Session Persistence
+
+By default sessions are kept in memory. Use `FileSessionStore` to persist
+tokens across process restarts (stored in `~/.bolthub/sessions.json`):
+
+```python
+from bolthub import L402Client, PhoenixdWallet, FileSessionStore
+
+client = L402Client(
+    PhoenixdWallet(url=url, password=pw),
+    session_store=FileSessionStore(),
+)
+```
+
+## API Reference
+
+| Export | Description |
+|--------|-------------|
+| `L402Client` | HTTP client with automatic L402 challenge handling |
+| `LndWallet` | Wallet adapter for LND REST API |
+| `LnbitsWallet` | Wallet adapter for LNbits |
+| `PhoenixdWallet` | Wallet adapter for Phoenixd |
+| `NwcWallet` | Wallet adapter accepting a custom pay callback |
+| `WalletAdapter` | Protocol to implement for custom wallets |
+| `FileSessionStore` | Disk-backed session token persistence |
+| `SessionStore` | Protocol for custom session storage |
+| `L402Error` | Base exception for L402 failures |
+| `L402BudgetError` | Raised when budget limits are exceeded |
+
+## License
+
+MIT

bolthub-0.1.0/README.md

@@ -0,0 +1,152 @@
+# bolthub
+
+L402 client for AI agents. Automatically handles 402 Payment Required challenges, pays Lightning invoices, and retries requests with proof of payment.
+
+## Install
+
+```bash
+pip install bolthub
+```
+
+## Quick Start
+
+```python
+from bolthub import L402Client, PhoenixdWallet
+
+wallet = PhoenixdWallet(
+    url="https://your-phoenixd:9740",
+    password="your-phoenixd-password",
+)
+
+client = L402Client(wallet, budget_sats=10_000)
+
+resp = client.get(
+    "https://acme.gw.bolthub.ai/v1/market-data",
+    params={"symbol": "BTC"},
+)
+data = resp.json()
+```
+
+## Wallet Adapters
+
+### Phoenixd (recommended)
+
+Fastest payment speed (<200ms). Get a hosted instance at [nodana.io](https://nodana.io) or self-host from [ACINQ](https://phoenix.acinq.co/server).
+
+```python
+from bolthub import PhoenixdWallet
+
+wallet = PhoenixdWallet(
+    url="https://your-phoenixd:9740",
+    password="your-phoenixd-password",
+    timeout_seconds=35,
+)
+```
+
+### LND
+
+Full Lightning node. Self-host or use [Umbrel](https://umbrel.com) / [Start9](https://start9.com).
+
+```python
+from bolthub import LndWallet
+
+wallet = LndWallet(
+    host="https://your-lnd-node:8080",
+    macaroon="admin-macaroon-hex",
+    timeout_seconds=30,
+)
+```
+
+For agent deployments, use a scoped pay-only macaroon instead of `admin.macaroon`:
+
+```bash
+lncli bakemacaroon uri:/lnrpc.Lightning/SendPaymentSync \
+  uri:/lnrpc.Lightning/DecodePayReq \
+  --save_to=pay-only.macaroon
+```
+
+### LNbits
+
+Lightweight Lightning wallet with multi-wallet support. Create a dedicated wallet for your agent.
+
+```python
+from bolthub import LnbitsWallet
+
+wallet = LnbitsWallet(
+    url="https://lnbits.example.com",
+    admin_key="your-admin-key",
+)
+```
+
+### NWC (Nostr Wallet Connect)
+
+Easiest to set up but slower (1-3s per payment). Get a free NWC connection from [CoinOS](https://coinos.io) or use [Alby Hub](https://getalby.com).
+
+```python
+from bolthub import NwcWallet
+
+# Provide a pay function that handles the NWC protocol.
+# With pynostr or another NWC library:
+def pay_via_nwc(bolt11: str) -> str:
+    # your NWC payment logic here
+    return preimage_hex
+
+wallet = NwcWallet(pay_fn=pay_via_nwc)
+```
+
+### Custom Wallet
+
+Implement the `WalletAdapter` protocol:
+
+```python
+class MyWallet:
+    def pay_invoice(self, bolt11: str) -> str:
+        preimage = my_payment_logic(bolt11)
+        return preimage
+```
+
+## Budget Guards
+
+```python
+client = L402Client(
+    wallet,
+    max_per_request_sats=100,  # reject invoices over 100 sats
+    budget_sats=10_000,         # total spending cap
+)
+
+print(client.total_spent)       # sats spent so far
+print(client.remaining_budget)  # sats remaining
+```
+
+## Session Persistence
+
+By default sessions are kept in memory. Use `FileSessionStore` to persist
+tokens across process restarts (stored in `~/.bolthub/sessions.json`):
+
+```python
+from bolthub import L402Client, PhoenixdWallet, FileSessionStore
+
+client = L402Client(
+    PhoenixdWallet(url=url, password=pw),
+    session_store=FileSessionStore(),
+)
+```
+
+## API Reference
+
+| Export | Description |
+|--------|-------------|
+| `L402Client` | HTTP client with automatic L402 challenge handling |
+| `LndWallet` | Wallet adapter for LND REST API |
+| `LnbitsWallet` | Wallet adapter for LNbits |
+| `PhoenixdWallet` | Wallet adapter for Phoenixd |
+| `NwcWallet` | Wallet adapter accepting a custom pay callback |
+| `WalletAdapter` | Protocol to implement for custom wallets |
+| `FileSessionStore` | Disk-backed session token persistence |
+| `SessionStore` | Protocol for custom session storage |
+| `L402Error` | Base exception for L402 failures |
+| `L402BudgetError` | Raised when budget limits are exceeded |
+
+## License
+
+MIT

bolthub-0.1.0/bolthub/__init__.py

@@ -0,0 +1,17 @@
+from .client import L402Client, L402Error, L402BudgetError
+from .wallets import LndWallet, LnbitsWallet, PhoenixdWallet, NwcWallet, WalletAdapter
+from .session_store import FileSessionStore, SessionStore, SessionData
+
+__all__ = [
+    "L402Client",
+    "L402Error",
+    "L402BudgetError",
+    "LndWallet",
+    "LnbitsWallet",
+    "PhoenixdWallet",
+    "NwcWallet",
+    "WalletAdapter",
+    "FileSessionStore",
+    "SessionStore",
+    "SessionData",
+]

bolthub-0.1.0/bolthub/client.py

@@ -0,0 +1,205 @@
+"""L402 HTTP client with automatic payment-challenge handling."""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from .session_store import SessionStore, SessionData, InMemorySessionStore
+from .wallets import WalletAdapter
+
+
+class L402Error(Exception):
+    """Base exception for all L402-related failures."""
+
+
+class L402BudgetError(L402Error):
+    """Raised when an invoice exceeds per-request or total budget limits."""
+
+
+@dataclass
+class _SessionInfo:
+    token: str
+    expires_at: float
+    balance: int | None = None
+
+
+class L402Client:
+    """HTTP client that transparently handles the L402 payment protocol.
+
+    When a server responds with ``402 Payment Required`` and a
+    ``WWW-Authenticate: L402`` challenge, the client automatically pays the
+    embedded Lightning invoice via the configured wallet adapter, then
+    retries the request with proof of payment.
+
+    Args:
+        wallet: Lightning wallet adapter used to pay invoices.
+        max_per_request_sats: Maximum sats allowed for a single invoice.
+        budget_sats: Total sats the client may spend before refusing to pay.
+        timeout: Timeout in seconds for each HTTP round-trip.
+        session_store: Pluggable session store. Defaults to in-memory.
+    """
+
+    def __init__(
+        self,
+        wallet: WalletAdapter,
+        *,
+        max_per_request_sats: int | None = None,
+        budget_sats: int | None = None,
+        timeout: float = 30.0,
+        session_store: SessionStore | None = None,
+    ):
+        self._wallet = wallet
+        self._max_per_request = max_per_request_sats
+        self._budget = budget_sats
+        self._spent = 0
+        self._timeout = timeout
+        self._client = httpx.Client(timeout=timeout)
+        self._store: SessionStore = session_store or InMemorySessionStore()
+
+    @property
+    def total_spent(self) -> int:
+        """Total satoshis spent across all requests since construction."""
+        return self._spent
+
+    @property
+    def remaining_budget(self) -> int | None:
+        """Satoshis remaining, or ``None`` if no budget was set."""
+        if self._budget is None:
+            return None
+        return max(0, self._budget - self._spent)
+
+    def get_sessions(self) -> dict[str, _SessionInfo]:
+        """Return a snapshot of all cached session tokens."""
+        return {
+            k: _SessionInfo(token=s.token, expires_at=s.expires_at, balance=s.balance)
+            for k, s in self._store.items()
+        }
+
+    def clear_sessions(self) -> None:
+        """Remove all cached session tokens."""
+        self._store.clear()
+
+    def get(self, url: str, **kwargs: Any) -> httpx.Response:
+        """Convenience wrapper around :meth:`request` with ``method="GET"``."""
+        return self.request("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> httpx.Response:
+        """Convenience wrapper around :meth:`request` with ``method="POST"``."""
+        return self.request("POST", url, **kwargs)
+
+    def request(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        """Send an HTTP request, automatically handling L402 challenges."""
+        session_key = self._session_key(url)
+        session = self._store.get(session_key)
+
+        if session and session.expires_at > time.time():
+            headers = dict(kwargs.get("headers", {}))
+            headers["X-Session-Token"] = session.token
+            kw = {**kwargs, "headers": headers}
+            resp = self._client.request(method, url, **kw)
+            if resp.status_code != 402:
+                self._update_session(session_key, resp)
+                return resp
+            self._store.delete(session_key)
+
+        resp = self._client.request(method, url, **kwargs)
+
+        if resp.status_code != 402:
+            return resp
+
+        challenge = self._parse_challenge(resp)
+        if challenge is None:
+            raise L402Error("Failed to parse L402 challenge from 402 response")
+
+        macaroon, invoice = challenge
+        amount = self._extract_amount(resp)
+
+        if amount is not None:
+            if self._max_per_request is not None and amount > self._max_per_request:
+                raise L402BudgetError(
+                    f"Invoice amount {amount} sats exceeds per-request limit of {self._max_per_request} sats"
+                )
+            if self._budget is not None and self._spent + amount > self._budget:
+                raise L402BudgetError(
+                    f"Invoice amount {amount} sats would exceed total budget "
+                    f"(spent: {self._spent}, budget: {self._budget})"
+                )
+
+        preimage = self._wallet.pay_invoice(invoice)
+
+        if amount is not None:
+            self._spent += amount
+
+        headers = dict(kwargs.get("headers", {}))
+        headers["Authorization"] = f"L402 {macaroon}:{preimage}"
+        kwargs["headers"] = headers
+
+        resp = self._client.request(method, url, **kwargs)
+        self._update_session(session_key, resp)
+        return resp
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> L402Client:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    @staticmethod
+    def _session_key(url: str) -> str:
+        parsed = urlparse(url)
+        return f"{parsed.netloc}{parsed.path}"
+
+    def _update_session(self, key: str, resp: httpx.Response) -> None:
+        token = resp.headers.get("x-session-token")
+        if not token:
+            return
+        expires_str = resp.headers.get("x-session-expires", "")
+        balance_str = resp.headers.get("x-session-balance", "")
+
+        try:
+            from datetime import datetime, timezone
+            expires_at = datetime.fromisoformat(expires_str.replace("Z", "+00:00")).timestamp()
+        except Exception:
+            expires_at = time.time() + 3600
+
+        balance: int | None = None
+        if balance_str:
+            try:
+                balance = int(balance_str)
+            except ValueError:
+                pass
+
+        if balance is not None and balance <= 0:
+            self._store.delete(key)
+            return
+
+        self._store.set(key, SessionData(token=token, expires_at=expires_at, balance=balance))
+
+    @staticmethod
+    def _parse_challenge(resp: httpx.Response) -> tuple[str, str] | None:
+        www_auth = resp.headers.get("www-authenticate", "")
+        mac_match = re.search(r'macaroon="([^"]+)"', www_auth)
+        inv_match = re.search(r'invoice="([^"]+)"', www_auth)
+        if not mac_match or not inv_match:
+            return None
+        return mac_match.group(1), inv_match.group(1)
+
+    @staticmethod
+    def _extract_amount(resp: httpx.Response) -> int | None:
+        try:
+            body = resp.json()
+            val = body.get("amountSats")
+            if isinstance(val, (int, float)) and val > 0:
+                return int(val)
+            return None
+        except Exception:
+            return None

bolthub-0.1.0/bolthub/session_store.py

@@ -0,0 +1,157 @@
+"""Session token storage backends for the L402 client."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+import time
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Protocol, Iterator
+
+
+@dataclass
+class SessionData:
+    """A cached gateway session token with expiry and optional balance."""
+
+    token: str
+    expires_at: float
+    balance: int | None = None
+
+
+class SessionStore(Protocol):
+    """Pluggable storage backend for gateway session tokens.
+
+    The default in-memory store is suitable for short-lived scripts.
+    Use :class:`FileSessionStore` for CLI tools or long-running agents
+    that should survive restarts.
+    """
+
+    def get(self, key: str) -> SessionData | None: ...
+    def set(self, key: str, session: SessionData) -> None: ...
+    def delete(self, key: str) -> None: ...
+    def clear(self) -> None: ...
+    def items(self) -> Iterator[tuple[str, SessionData]]: ...
+
+
+class InMemorySessionStore:
+    def __init__(self) -> None:
+        self._sessions: dict[str, SessionData] = {}
+
+    def get(self, key: str) -> SessionData | None:
+        return self._sessions.get(key)
+
+    def set(self, key: str, session: SessionData) -> None:
+        self._sessions[key] = session
+
+    def delete(self, key: str) -> None:
+        self._sessions.pop(key, None)
+
+    def clear(self) -> None:
+        self._sessions.clear()
+
+    def items(self) -> Iterator[tuple[str, SessionData]]:
+        yield from self._sessions.items()
+
+
+_DEFAULT_DIR = os.path.join(os.path.expanduser("~"), ".bolthub")
+_DEFAULT_FILE = "sessions.json"
+
+
+class FileSessionStore:
+    """Persists session tokens to a JSON file on disk.
+
+    Defaults to ``~/.bolthub/sessions.json``. Writes are atomic
+    (write-to-temp then rename) and the file is created with ``0600``
+    permissions.
+
+    Args:
+        file_path: Custom path to the session file.
+    """
+
+    def __init__(self, file_path: str | None = None) -> None:
+        self._file_path = file_path or os.path.join(_DEFAULT_DIR, _DEFAULT_FILE)
+        self._sessions: dict[str, SessionData] = {}
+        self._load()
+
+    def get(self, key: str) -> SessionData | None:
+        session = self._sessions.get(key)
+        if session is None:
+            return None
+        if session.expires_at <= time.time():
+            del self._sessions[key]
+            self._persist()
+            return None
+        return session
+
+    def set(self, key: str, session: SessionData) -> None:
+        self._sessions[key] = session
+        self._persist()
+
+    def delete(self, key: str) -> None:
+        if key in self._sessions:
+            del self._sessions[key]
+            self._persist()
+
+    def clear(self) -> None:
+        self._sessions.clear()
+        self._persist()
+
+    def items(self) -> Iterator[tuple[str, SessionData]]:
+        yield from self._sessions.items()
+
+    def _load(self) -> None:
+        try:
+            with open(self._file_path, "r") as f:
+                data = json.load(f)
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            return
+
+        if data.get("v") != 1 or not isinstance(data.get("sessions"), dict):
+            return
+
+        now = time.time()
+        pruned = False
+        for key, raw in data["sessions"].items():
+            expires_at = raw.get("expires_at", raw.get("expiresAt", 0))
+            token = raw.get("token", "")
+            if expires_at > now and token:
+                balance = raw.get("balance")
+                self._sessions[key] = SessionData(
+                    token=token,
+                    expires_at=expires_at,
+                    balance=balance,
+                )
+            else:
+                pruned = True
+
+        if pruned:
+            self._persist()
+
+    def _persist(self) -> None:
+        dir_path = os.path.dirname(self._file_path)
+        os.makedirs(dir_path, mode=0o700, exist_ok=True)
+
+        sessions_dict: dict[str, dict] = {}
+        for key, s in self._sessions.items():
+            entry: dict = {"token": s.token, "expiresAt": s.expires_at}
+            if s.balance is not None:
+                entry["balance"] = s.balance
+            sessions_dict[key] = entry
+
+        payload = json.dumps({"v": 1, "sessions": sessions_dict}, indent=2)
+
+        fd, tmp_path = tempfile.mkstemp(dir=dir_path, suffix=".tmp")
+        try:
+            os.write(fd, payload.encode())
+            os.fchmod(fd, stat.S_IRUSR | stat.S_IWUSR)
+            os.close(fd)
+            os.rename(tmp_path, self._file_path)
+        except Exception:
+            os.close(fd) if not os.get_inheritable(fd) else None
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass

bolthub-0.1.0/bolthub/wallets.py

@@ -0,0 +1,129 @@
+"""Lightning wallet adapters for the L402 client."""
+
+from __future__ import annotations
+
+import base64
+from typing import Callable, Protocol, runtime_checkable
+
+import httpx
+
+
+@runtime_checkable
+class WalletAdapter(Protocol):
+    """Interface that any Lightning wallet must implement.
+
+    Supply a built-in adapter (``LndWallet``, ``LnbitsWallet``, etc.) or
+    provide your own object that satisfies this protocol.
+    """
+
+    def pay_invoice(self, bolt11: str) -> str:
+        """Pay a BOLT-11 invoice and return the preimage hex string."""
+        ...
+
+
+class LndWallet:
+    """Wallet adapter that pays invoices through an LND node's REST API.
+
+    Args:
+        host: LND REST endpoint, e.g. ``https://localhost:8080``.
+        macaroon: Hex-encoded admin macaroon with send permission.
+        timeout_seconds: Payment timeout passed to LND. Defaults to 30.
+    """
+
+    def __init__(self, host: str, macaroon: str, timeout_seconds: int = 30):
+        self._host = host.rstrip("/")
+        self._macaroon = macaroon
+        self._timeout = timeout_seconds
+
+    def pay_invoice(self, bolt11: str) -> str:
+        resp = httpx.post(
+            f"{self._host}/v2/router/send",
+            headers={
+                "Grpc-Metadata-macaroon": self._macaroon,
+                "Content-Type": "application/json",
+            },
+            json={
+                "payment_request": bolt11,
+                "timeout_seconds": self._timeout,
+            },
+            timeout=self._timeout + 5,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        preimage = data.get("result", {}).get("payment_preimage")
+        if not preimage:
+            raise RuntimeError("LND payment response missing preimage")
+        return preimage
+
+
+class LnbitsWallet:
+    """Wallet adapter that pays invoices through an LNbits instance.
+
+    Args:
+        url: LNbits base URL, e.g. ``https://lnbits.example.com``.
+        admin_key: Admin API key with outgoing payment permission.
+    """
+
+    def __init__(self, url: str, admin_key: str):
+        self._url = url.rstrip("/")
+        self._admin_key = admin_key
+
+    def pay_invoice(self, bolt11: str) -> str:
+        resp = httpx.post(
+            f"{self._url}/api/v1/payments",
+            headers={
+                "X-Api-Key": self._admin_key,
+                "Content-Type": "application/json",
+            },
+            json={"out": True, "bolt11": bolt11},
+            timeout=30,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        preimage = data.get("preimage") or data.get("payment_preimage")
+        if not preimage:
+            raise RuntimeError("LNbits payment response missing preimage")
+        return preimage
+
+
+class PhoenixdWallet:
+    """Wallet adapter for Phoenixd (ACINQ). Uses HTTP Basic auth.
+
+    Args:
+        url: Phoenixd HTTP base URL, e.g. ``http://localhost:9740``.
+        password: HTTP password used for Basic authentication.
+        timeout_seconds: Payment request timeout. Defaults to 35.
+    """
+
+    def __init__(self, url: str, password: str, timeout_seconds: int = 35):
+        self._url = url.rstrip("/")
+        self._auth = "Basic " + base64.b64encode(f":{password}".encode()).decode()
+        self._timeout = timeout_seconds
+
+    def pay_invoice(self, bolt11: str) -> str:
+        resp = httpx.post(
+            f"{self._url}/payinvoice",
+            headers={"Authorization": self._auth},
+            data={"invoice": bolt11},
+            timeout=self._timeout,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        preimage = data.get("paymentPreimage")
+        if not preimage:
+            raise RuntimeError("Phoenixd payment response missing preimage")
+        return preimage
+
+
+class NwcWallet:
+    """Wallet adapter that delegates to a callback (e.g. from an NWC library).
+
+    The ``pay_fn`` callable receives a BOLT11 invoice string and must return
+    the payment preimage as a hex string.
+    """
+
+    def __init__(self, pay_fn: Callable[[str], str]):
+        self._pay_fn = pay_fn
+
+    def pay_invoice(self, bolt11: str) -> str:
+        return self._pay_fn(bolt11)

bolthub-0.1.0/bolthub.egg-info/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: bolthub
+Version: 0.1.0
+Summary: L402 client for AI agents — pay Lightning invoices automatically to access paywalled APIs
+License: MIT
+Project-URL: Homepage, https://bolthub.ai
+Project-URL: Repository, https://github.com/signaltech-org/bolthub.ai
+Keywords: l402,lightning,bitcoin,micropayments,ai-agent,paywall
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# bolthub
+
+L402 client for AI agents. Automatically handles 402 Payment Required challenges, pays Lightning invoices, and retries requests with proof of payment.
+
+## Install
+
+```bash
+pip install bolthub
+```
+
+## Quick Start
+
+```python
+from bolthub import L402Client, PhoenixdWallet
+
+wallet = PhoenixdWallet(
+    url="https://your-phoenixd:9740",
+    password="your-phoenixd-password",
+)
+
+client = L402Client(wallet, budget_sats=10_000)
+
+resp = client.get(
+    "https://acme.gw.bolthub.ai/v1/market-data",
+    params={"symbol": "BTC"},
+)
+data = resp.json()
+```
+
+## Wallet Adapters
+
+### Phoenixd (recommended)
+
+Fastest payment speed (<200ms). Get a hosted instance at [nodana.io](https://nodana.io) or self-host from [ACINQ](https://phoenix.acinq.co/server).
+
+```python
+from bolthub import PhoenixdWallet
+
+wallet = PhoenixdWallet(
+    url="https://your-phoenixd:9740",
+    password="your-phoenixd-password",
+    timeout_seconds=35,
+)
+```
+
+### LND
+
+Full Lightning node. Self-host or use [Umbrel](https://umbrel.com) / [Start9](https://start9.com).
+
+```python
+from bolthub import LndWallet
+
+wallet = LndWallet(
+    host="https://your-lnd-node:8080",
+    macaroon="admin-macaroon-hex",
+    timeout_seconds=30,
+)
+```
+
+For agent deployments, use a scoped pay-only macaroon instead of `admin.macaroon`:
+
+```bash
+lncli bakemacaroon uri:/lnrpc.Lightning/SendPaymentSync \
+  uri:/lnrpc.Lightning/DecodePayReq \
+  --save_to=pay-only.macaroon
+```
+
+### LNbits
+
+Lightweight Lightning wallet with multi-wallet support. Create a dedicated wallet for your agent.
+
+```python
+from bolthub import LnbitsWallet
+
+wallet = LnbitsWallet(
+    url="https://lnbits.example.com",
+    admin_key="your-admin-key",
+)
+```
+
+### NWC (Nostr Wallet Connect)
+
+Easiest to set up but slower (1-3s per payment). Get a free NWC connection from [CoinOS](https://coinos.io) or use [Alby Hub](https://getalby.com).
+
+```python
+from bolthub import NwcWallet
+
+# Provide a pay function that handles the NWC protocol.
+# With pynostr or another NWC library:
+def pay_via_nwc(bolt11: str) -> str:
+    # your NWC payment logic here
+    return preimage_hex
+
+wallet = NwcWallet(pay_fn=pay_via_nwc)
+```
+
+### Custom Wallet
+
+Implement the `WalletAdapter` protocol:
+
+```python
+class MyWallet:
+    def pay_invoice(self, bolt11: str) -> str:
+        preimage = my_payment_logic(bolt11)
+        return preimage
+```
+
+## Budget Guards
+
+```python
+client = L402Client(
+    wallet,
+    max_per_request_sats=100,  # reject invoices over 100 sats
+    budget_sats=10_000,         # total spending cap
+)
+
+print(client.total_spent)       # sats spent so far
+print(client.remaining_budget)  # sats remaining
+```
+
+## Session Persistence
+
+By default sessions are kept in memory. Use `FileSessionStore` to persist
+tokens across process restarts (stored in `~/.bolthub/sessions.json`):
+
+```python
+from bolthub import L402Client, PhoenixdWallet, FileSessionStore
+
+client = L402Client(
+    PhoenixdWallet(url=url, password=pw),
+    session_store=FileSessionStore(),
+)
+```
+
+## API Reference
+
+| Export | Description |
+|--------|-------------|
+| `L402Client` | HTTP client with automatic L402 challenge handling |
+| `LndWallet` | Wallet adapter for LND REST API |
+| `LnbitsWallet` | Wallet adapter for LNbits |
+| `PhoenixdWallet` | Wallet adapter for Phoenixd |
+| `NwcWallet` | Wallet adapter accepting a custom pay callback |
+| `WalletAdapter` | Protocol to implement for custom wallets |
+| `FileSessionStore` | Disk-backed session token persistence |
+| `SessionStore` | Protocol for custom session storage |
+| `L402Error` | Base exception for L402 failures |
+| `L402BudgetError` | Raised when budget limits are exceeded |
+
+## License
+
+MIT

bolthub-0.1.0/bolthub.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+bolthub/__init__.py
+bolthub/client.py
+bolthub/session_store.py
+bolthub/wallets.py
+bolthub.egg-info/PKG-INFO
+bolthub.egg-info/SOURCES.txt
+bolthub.egg-info/dependency_links.txt
+bolthub.egg-info/requires.txt
+bolthub.egg-info/top_level.txt
+tests/test_client.py
+tests/test_session_store.py
+tests/test_wallets.py

bolthub-0.1.0/bolthub.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bolthub-0.1.0/bolthub.egg-info/requires.txt

@@ -0,0 +1,4 @@
+httpx>=0.24
+
+[dev]
+pytest

bolthub-0.1.0/bolthub.egg-info/top_level.txt

@@ -0,0 +1 @@
+bolthub

bolthub-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bolthub"
+version = "0.1.0"
+description = "L402 client for AI agents — pay Lightning invoices automatically to access paywalled APIs"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.24"]
+keywords = ["l402", "lightning", "bitcoin", "micropayments", "ai-agent", "paywall"]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://bolthub.ai"
+Repository = "https://github.com/signaltech-org/bolthub.ai"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

bolthub-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bolthub-0.1.0/tests/test_client.py

@@ -0,0 +1,90 @@
+import pytest
+from unittest.mock import MagicMock, patch
+import httpx
+
+from bolthub import L402Client, L402Error, L402BudgetError
+
+
+class MockWallet:
+    def __init__(self, preimage="abc123"):
+        self._preimage = preimage
+        self.calls = []
+
+    def pay_invoice(self, bolt11: str) -> str:
+        self.calls.append(bolt11)
+        return self._preimage
+
+
+def make_402_response(amount_sats=100):
+    return httpx.Response(
+        status_code=402,
+        headers={
+            "WWW-Authenticate": 'L402 macaroon="mac123", invoice="lnbc1000..."',
+        },
+        json={"error": "Payment Required", "amountSats": amount_sats},
+    )
+
+
+def make_200_response(data=None):
+    return httpx.Response(status_code=200, json=data or {"ok": True})
+
+
+class TestL402Client:
+    def test_returns_response_if_not_402(self):
+        wallet = MockWallet()
+        client = L402Client(wallet)
+        with patch.object(client._client, "request", return_value=make_200_response()):
+            resp = client.get("https://example.com/api")
+        assert resp.status_code == 200
+        assert len(wallet.calls) == 0
+
+    def test_handles_402_and_retries(self):
+        wallet = MockWallet("preimage123")
+        client = L402Client(wallet)
+        responses = [make_402_response(), make_200_response()]
+        call_count = 0
+
+        def side_effect(*args, **kwargs):
+            nonlocal call_count
+            resp = responses[call_count]
+            call_count += 1
+            return resp
+
+        with patch.object(client._client, "request", side_effect=side_effect):
+            resp = client.get("https://example.com/api")
+
+        assert resp.status_code == 200
+        assert wallet.calls == ["lnbc1000..."]
+
+    def test_raises_on_402_without_challenge(self):
+        wallet = MockWallet()
+        client = L402Client(wallet)
+        bare_402 = httpx.Response(status_code=402, json={"error": "pay"})
+        with patch.object(client._client, "request", return_value=bare_402):
+            with pytest.raises(L402Error, match="Failed to parse"):
+                client.get("https://example.com/api")
+
+    def test_budget_exceeded(self):
+        wallet = MockWallet()
+        client = L402Client(wallet, budget_sats=50)
+        with patch.object(client._client, "request", return_value=make_402_response(100)):
+            with pytest.raises(L402BudgetError, match="exceed total budget"):
+                client.get("https://example.com/api")
+
+    def test_per_request_limit(self):
+        wallet = MockWallet()
+        client = L402Client(wallet, max_per_request_sats=10)
+        with patch.object(client._client, "request", return_value=make_402_response(100)):
+            with pytest.raises(L402BudgetError, match="per-request limit"):
+                client.get("https://example.com/api")
+
+    def test_tracks_spent(self):
+        wallet = MockWallet()
+        client = L402Client(wallet, budget_sats=1000)
+        assert client.total_spent == 0
+        assert client.remaining_budget == 1000
+
+    def test_context_manager(self):
+        wallet = MockWallet()
+        with L402Client(wallet) as client:
+            assert client is not None

bolthub-0.1.0/tests/test_session_store.py

@@ -0,0 +1,121 @@
+import os
+import shutil
+import tempfile
+import time
+
+import pytest
+
+from bolthub.session_store import (
+    FileSessionStore,
+    InMemorySessionStore,
+    SessionData,
+)
+
+
+class TestInMemorySessionStore:
+    def test_get_set_delete(self):
+        store = InMemorySessionStore()
+        session = SessionData(token="tok1", expires_at=time.time() + 60)
+        store.set("k", session)
+        assert store.get("k") is session
+        store.delete("k")
+        assert store.get("k") is None
+
+    def test_clear(self):
+        store = InMemorySessionStore()
+        store.set("a", SessionData(token="t1", expires_at=time.time() + 60))
+        store.set("b", SessionData(token="t2", expires_at=time.time() + 60))
+        store.clear()
+        assert store.get("a") is None
+        assert store.get("b") is None
+
+    def test_items(self):
+        store = InMemorySessionStore()
+        store.set("x", SessionData(token="t1", expires_at=time.time() + 60))
+        store.set("y", SessionData(token="t2", expires_at=time.time() + 60))
+        keys = sorted(k for k, _ in store.items())
+        assert keys == ["x", "y"]
+
+
+class TestFileSessionStore:
+    def _tmp_path(self):
+        d = tempfile.mkdtemp(prefix="bolthub-test-")
+        return os.path.join(d, "sessions.json")
+
+    def test_stores_and_retrieves(self):
+        path = self._tmp_path()
+        try:
+            store = FileSessionStore(file_path=path)
+            s = SessionData(token="tok1", expires_at=time.time() + 60, balance=5)
+            store.set("host/path", s)
+            got = store.get("host/path")
+            assert got is not None
+            assert got.token == "tok1"
+            assert got.balance == 5
+        finally:
+            shutil.rmtree(os.path.dirname(path), ignore_errors=True)
+
+    def test_returns_none_for_missing(self):
+        path = self._tmp_path()
+        try:
+            store = FileSessionStore(file_path=path)
+            assert store.get("no-key") is None
+        finally:
+            shutil.rmtree(os.path.dirname(path), ignore_errors=True)
+
+    def test_prunes_expired_on_get(self):
+        path = self._tmp_path()
+        try:
+            store = FileSessionStore(file_path=path)
+            store.set("old", SessionData(token="t", expires_at=time.time() - 10))
+            assert store.get("old") is None
+        finally:
+            shutil.rmtree(os.path.dirname(path), ignore_errors=True)
+
+    def test_persists_and_reloads(self):
+        path = self._tmp_path()
+        try:
+            store1 = FileSessionStore(file_path=path)
+            store1.set("k", SessionData(token="disk", expires_at=time.time() + 60))
+
+            store2 = FileSessionStore(file_path=path)
+            got = store2.get("k")
+            assert got is not None
+            assert got.token == "disk"
+        finally:
+            shutil.rmtree(os.path.dirname(path), ignore_errors=True)
+
+    def test_prunes_expired_on_load(self):
+        path = self._tmp_path()
+        try:
+            store1 = FileSessionStore(file_path=path)
+            store1.set("fresh", SessionData(token="a", expires_at=time.time() + 60))
+            store1.set("stale", SessionData(token="b", expires_at=time.time() - 10))
+
+            store2 = FileSessionStore(file_path=path)
+            assert store2.get("fresh") is not None
+            assert store2.get("stale") is None
+        finally:
+            shutil.rmtree(os.path.dirname(path), ignore_errors=True)
+
+    def test_delete(self):
+        path = self._tmp_path()
+        try:
+            store = FileSessionStore(file_path=path)
+            store.set("k", SessionData(token="t", expires_at=time.time() + 60))
+            store.delete("k")
+            assert store.get("k") is None
+        finally:
+            shutil.rmtree(os.path.dirname(path), ignore_errors=True)
+
+    def test_clear(self):
+        path = self._tmp_path()
+        try:
+            store = FileSessionStore(file_path=path)
+            store.set("a", SessionData(token="t1", expires_at=time.time() + 60))
+            store.set("b", SessionData(token="t2", expires_at=time.time() + 60))
+            store.clear()
+            assert store.get("a") is None
+            assert store.get("b") is None
+        finally:
+            shutil.rmtree(os.path.dirname(path), ignore_errors=True)

bolthub-0.1.0/tests/test_wallets.py

@@ -0,0 +1,108 @@
+import pytest
+from unittest.mock import patch, MagicMock
+
+from bolthub import LndWallet, LnbitsWallet, PhoenixdWallet, NwcWallet
+
+
+class TestLndWallet:
+    def test_pays_invoice(self):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.raise_for_status = MagicMock()
+        mock_resp.json.return_value = {"result": {"payment_preimage": "abc123"}}
+
+        with patch("bolthub.wallets.httpx.post", return_value=mock_resp) as mock_post:
+            wallet = LndWallet(host="https://lnd.example.com:8080", macaroon="deadbeef")
+            preimage = wallet.pay_invoice("lnbc1000...")
+
+        assert preimage == "abc123"
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        assert "/v2/router/send" in call_args[0][0]
+        assert call_args[1]["headers"]["Grpc-Metadata-macaroon"] == "deadbeef"
+
+    def test_strips_trailing_slash(self):
+        mock_resp = MagicMock()
+        mock_resp.raise_for_status = MagicMock()
+        mock_resp.json.return_value = {"result": {"payment_preimage": "ok"}}
+
+        with patch("bolthub.wallets.httpx.post", return_value=mock_resp) as mock_post:
+            wallet = LndWallet(host="https://lnd.example.com/", macaroon="m")
+            wallet.pay_invoice("lnbc...")
+
+        url = mock_post.call_args[0][0]
+        assert url == "https://lnd.example.com/v2/router/send"
+
+    def test_raises_on_missing_preimage(self):
+        mock_resp = MagicMock()
+        mock_resp.raise_for_status = MagicMock()
+        mock_resp.json.return_value = {"result": {}}
+
+        with patch("bolthub.wallets.httpx.post", return_value=mock_resp):
+            wallet = LndWallet(host="https://lnd.example.com", macaroon="m")
+            with pytest.raises(RuntimeError, match="missing preimage"):
+                wallet.pay_invoice("lnbc...")
+
+
+class TestLnbitsWallet:
+    def test_pays_invoice(self):
+        mock_resp = MagicMock()
+        mock_resp.raise_for_status = MagicMock()
+        mock_resp.json.return_value = {"preimage": "lnbits_pre"}
+
+        with patch("bolthub.wallets.httpx.post", return_value=mock_resp) as mock_post:
+            wallet = LnbitsWallet(url="https://lnbits.example.com", admin_key="key1")
+            preimage = wallet.pay_invoice("lnbc500...")
+
+        assert preimage == "lnbits_pre"
+        assert mock_post.call_args[1]["headers"]["X-Api-Key"] == "key1"
+
+    def test_accepts_payment_preimage_field(self):
+        mock_resp = MagicMock()
+        mock_resp.raise_for_status = MagicMock()
+        mock_resp.json.return_value = {"payment_preimage": "alt"}
+
+        with patch("bolthub.wallets.httpx.post", return_value=mock_resp):
+            wallet = LnbitsWallet(url="https://lnbits.example.com", admin_key="k")
+            assert wallet.pay_invoice("lnbc...") == "alt"
+
+
+class TestPhoenixdWallet:
+    def test_pays_invoice(self):
+        mock_resp = MagicMock()
+        mock_resp.raise_for_status = MagicMock()
+        mock_resp.json.return_value = {"paymentPreimage": "phx_pre"}
+
+        with patch("bolthub.wallets.httpx.post", return_value=mock_resp) as mock_post:
+            wallet = PhoenixdWallet(url="http://localhost:9740", password="pass")
+            preimage = wallet.pay_invoice("lnbc300...")
+
+        assert preimage == "phx_pre"
+        assert "Basic" in mock_post.call_args[1]["headers"]["Authorization"]
+
+    def test_raises_on_missing_preimage(self):
+        mock_resp = MagicMock()
+        mock_resp.raise_for_status = MagicMock()
+        mock_resp.json.return_value = {}
+
+        with patch("bolthub.wallets.httpx.post", return_value=mock_resp):
+            wallet = PhoenixdWallet(url="http://localhost:9740", password="p")
+            with pytest.raises(RuntimeError, match="missing preimage"):
+                wallet.pay_invoice("lnbc...")
+
+
+class TestNwcWallet:
+    def test_delegates_to_pay_fn(self):
+        pay_fn = MagicMock(return_value="nwc_pre")
+        wallet = NwcWallet(pay_fn=pay_fn)
+        result = wallet.pay_invoice("lnbc...")
+
+        assert result == "nwc_pre"
+        pay_fn.assert_called_once_with("lnbc...")
+
+    def test_propagates_errors(self):
+        pay_fn = MagicMock(side_effect=RuntimeError("NWC error"))
+        wallet = NwcWallet(pay_fn=pay_fn)
+
+        with pytest.raises(RuntimeError, match="NWC error"):
+            wallet.pay_invoice("lnbc...")