make sure when topup from untrusted mint to refund from primary mint

pin pnpm version

Dockerfile.full

@@ -4,7 +4,7 @@ FROM node:23-alpine AS ui-builder
 WORKDIR /app/ui
 
 # Install pnpm
-RUN corepack enable pnpm && corepack prepare pnpm@latest --activate
+RUN corepack enable pnpm && corepack prepare pnpm@10.15.0 --activate
 
 # Copy UI source
 COPY ui/package.json ui/pnpm-lock.yaml* ./

docs/provider/configuration.md

@@ -78,9 +78,15 @@ Which mints to accept payments from:
 
 Automatic profit withdrawal:
 
-| Setting               | Description                     |
-| --------------------- | ------------------------------- |
-| **Lightning Address** | Your LN address for withdrawals |
+| Setting                              | Description                                                                                                | Default |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------- |
+| **Lightning Address**                | Your LN address for withdrawals                                                                            | —       |
+| **Minimum Payout (sat)**             | Min available balance (in sats) before profit is paid out. Applies to both `sat` and `msat` mints (auto-converted). | `210`   |
+| **Payout Interval (seconds)**        | How often the payout loop wakes up and checks balances                                                     | `900`   |
+
+All payout amounts must be positive. Set the minimums above your wallet's
+minimum-invoice constraint (typically 1 sat) and high enough to amortise
+routing fees.
 
 ### Security
 
@@ -126,6 +132,8 @@ Use environment variables for:
 | `ENABLE_ANALYTICS_SHARING` | Enable usage analytics sharing to Nostr | `true`                         |
 | `CASHU_MINTS`        | Comma-separated mint URLs         | `https://mint.minibits.cash/Bitcoin` |
 | `RECEIVE_LN_ADDRESS` | Lightning address for withdrawals | —                                    |
+| `MIN_PAYOUT_SAT`     | Min payout balance in sats (applies to all mints) | `210`                |
+| `PAYOUT_INTERVAL_SECONDS` | Payout loop interval (seconds) | `900`                            |
 | `TOR_PROXY_URL`      | SOCKS5 proxy for Tor              | `socks5://127.0.0.1:9050`            |
 | `CORS_ORIGINS`       | Allowed CORS origins              | `*`                                  |
 | `RELAYS`             | Nostr relays (comma-separated)    | (default set)                        |

routstr/balance.py

@@ -337,21 +337,26 @@ async def refund_wallet_endpoint(
         )
 
     # --- MINT: balance is locked at zero, safe to create the refund token ---
+    # Proofs from untrusted mints are swapped to primary_mint on receive.
+    # Use primary_mint unless key.refund_mint_url is an explicitly trusted mint.
+    effective_refund_mint = (
+        key.refund_mint_url
+        if key.refund_mint_url and key.refund_mint_url in settings.cashu_mints
+        else settings.primary_mint
+    )
     try:
         if key.refund_address:
-            from .core.settings import settings as global_settings
-
             await send_to_lnurl(
                 remaining_balance,
                 key.refund_currency or "sat",
-                key.refund_mint_url or global_settings.primary_mint,
+                effective_refund_mint,
                 key.refund_address,
             )
             result = {"recipient": key.refund_address}
         else:
             refund_currency = key.refund_currency or "sat"
             token = await send_token(
-                remaining_balance, refund_currency, key.refund_mint_url
+                remaining_balance, refund_currency, effective_refund_mint
             )
             result = {"token": token}
 
@@ -379,15 +384,26 @@ async def refund_wallet_endpoint(
         # Minting failed — restore the debited balance
         await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved)
         error_msg = str(e)
+        logger.error(
+            "refund_wallet_endpoint: mint/send failed",
+            extra={
+                "error": error_msg,
+                "error_type": type(e).__name__,
+                "hashed_key": key.hashed_key,
+                "remaining_balance": remaining_balance,
+                "refund_currency": key.refund_currency,
+                "refund_mint_url": key.refund_mint_url,
+                "has_refund_address": bool(key.refund_address),
+            },
+        )
         if (
             "mint" in error_msg.lower()
             or "connection" in error_msg.lower()
-            or isinstance(e, Exception)
-            and "ConnectError" in str(type(e))
+            or "ConnectError" in str(type(e))
         ):
-            raise HTTPException(status_code=503, detail="Mint service unavailable")
+            raise HTTPException(status_code=503, detail=f"Mint service unavailable: {error_msg}")
         else:
-            raise HTTPException(status_code=500, detail="Refund failed")
+            raise HTTPException(status_code=500, detail=f"Refund failed: {error_msg}")
 
     await _refund_cache_set(bearer_value, result)
 

routstr/core/admin.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from pydantic import BaseModel, RootModel
+from pydantic.v1 import ValidationError as PydanticValidationError
 from sqlmodel import select
 
 from ..payment.models import _row_to_model, list_models
@@ -160,8 +161,13 @@ async def update_settings(request: Request, update: SettingsUpdate) -> dict:
         if field in settings_data:
             del settings_data[field]
 
-    async with create_session() as session:
-        new_settings = await SettingsService.update(settings_data, session)
+    try:
+        async with create_session() as session:
+            new_settings = await SettingsService.update(settings_data, session)
+    except PydanticValidationError as e:
+        # Surface validation issues (e.g. non-positive payout amounts)
+        # as a clean 400 instead of a 500.
+        raise HTTPException(status_code=400, detail=e.errors()) from e
     data = new_settings.dict()
     if "upstream_api_key" in data:
         data["upstream_api_key"] = "[REDACTED]" if data["upstream_api_key"] else ""

routstr/core/settings.py

@@ -41,6 +41,15 @@ class Settings(BaseSettings):
     primary_mint: str = Field(default="", env="PRIMARY_MINT_URL")
     primary_mint_unit: str = Field(default="sat", env="PRIMARY_MINT_UNIT")
 
+    # Lightning payout configuration
+    # Minimum available balance (in satoshis) before profit is paid out over
+    # Lightning
+    min_payout_sat: int = Field(default=210, gt=0, env="MIN_PAYOUT_SAT")
+    # Interval (seconds) between periodic payout attempts. Must be positive.
+    payout_interval_seconds: int = Field(
+        default=900, gt=0, env="PAYOUT_INTERVAL_SECONDS"
+    )
+
     # Pricing
     # Default behavior: derive pricing from MODELS
     # If fixed_pricing is True -> use fixed_cost_per_request and ignore tokens

routstr/core/version.py

@@ -55,9 +55,14 @@ def _on_tagged_release() -> bool:
     if tag:
         return tag.lstrip("v") == BASE_VERSION
     described = _run_git("describe", "--tags", "--exact-match", "HEAD")
-    if not described:
-        return False
-    return described.lstrip("v") == BASE_VERSION
+    if described and described.lstrip("v") == BASE_VERSION:
+        return True
+    current_branch = _run_git("rev-parse", "--abbrev-ref", "HEAD")
+    if current_branch == "main":
+        branch_tag = _run_git("describe", "--tags", "--abbrev=0", "HEAD")
+        if branch_tag and branch_tag.lstrip("v") == BASE_VERSION:
+            return True
+    return False
 
 
 @lru_cache(maxsize=1)

routstr/proxy.py

@@ -1,8 +1,9 @@
 import json
+from pathlib import Path
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Request
-from fastapi.responses import Response, StreamingResponse
+from fastapi.responses import HTMLResponse, JSONResponse, Response, StreamingResponse
 from sqlmodel import select
 
 from .algorithm import create_model_mappings
@@ -150,10 +151,51 @@ async def refresh_model_maps_periodically() -> None:
             )
 
 
+_API_PATH_PREFIXES = ("v1/", "responses")
+
+_NOT_FOUND_HTML_FILE = Path(__file__).parent.parent / "ui_out" / "404.html"
+
+
+def _read_not_found_html() -> str | None:
+    try:
+        return _NOT_FOUND_HTML_FILE.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+_NOT_FOUND_HTML: str | None = _read_not_found_html()
+
+
+def _build_not_found_response(request: Request, path: str) -> Response:
+    """Return a 404 for unknown paths.
+    """
+    accept = request.headers.get("accept", "").lower()
+    prefers_json = "application/json" in accept and "text/html" not in accept
+    request_id = getattr(request.state, "request_id", "unknown")
+
+    if not prefers_json and _NOT_FOUND_HTML is not None:
+        return HTMLResponse(content=_NOT_FOUND_HTML, status_code=404)
+
+    return JSONResponse(
+        status_code=404,
+        content={
+            "error": {
+                "message": f"Path '/{path}' not found",
+                "type": "not_found",
+                "code": 404,
+            },
+            "request_id": request_id,
+        },
+    )
+
+
 @proxy_router.api_route("/{path:path}", methods=["GET", "POST"], response_model=None)
 async def proxy(
     request: Request, path: str, session: AsyncSession = Depends(get_session)
 ) -> Response | StreamingResponse:
+    if not path.startswith(_API_PATH_PREFIXES):
+        return _build_not_found_response(request, path)
+
     headers = dict(request.headers)
 
     is_responses_api = path.startswith("v1/responses") or path.startswith("responses")

routstr/upstream/base.py

@@ -42,11 +42,23 @@ from ..payment.models import (
 from ..payment.price import sats_usd_price
 from ..wallet import recieve_token, send_token
 from . import messages_dispatch
+from .count_tokens import count_tokens_locally
 from .litellm_routing import detect_litellm_prefix
 
 logger = get_logger(__name__)
 
 
+def _is_json_content_type(content_type: str | None) -> bool:
+    """Return True when the upstream response should be parsed as JSON.
+    """
+    if not content_type:
+        return False
+    main = content_type.split(";", 1)[0].strip().lower()
+    if main in ("application/json", "text/json"):
+        return True
+    return main.startswith("application/") and main.endswith("+json")
+
+
 class TopupData(BaseModel):
     """Universal top-up data schema for Lightning Network invoices."""
 
@@ -523,7 +535,8 @@ class BaseUpstreamProvider:
     async def forward_upstream_error_response(
         self, request: Request, path: str, upstream_response: httpx.Response
     ) -> Response:
-        """Log upstream errors and forward the upstream response unchanged."""
+        """Log upstream errors and forward the response in a JSON envelope.
+        """
         status_code = upstream_response.status_code
         headers = dict(upstream_response.headers)
         content_type = headers.get("content-type") or headers.get("Content-Type", "")
@@ -545,9 +558,10 @@ class BaseUpstreamProvider:
 
         message, upstream_code = self._extract_upstream_error_message(body_bytes)
         body_preview = body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+        is_json_body = _is_json_content_type(content_type)
 
         logger.warning(
-            "Forwarding upstream error response as-is",
+            "Forwarding upstream error response",
             extra={
                 "path": path,
                 "provider": self.provider_type,
@@ -559,6 +573,7 @@ class BaseUpstreamProvider:
                 "body_preview": body_preview,
                 "body_read_error": body_read_error,
                 "method": request.method,
+                "json_normalized": not is_json_body,
             },
         )
 
@@ -586,17 +601,40 @@ class BaseUpstreamProvider:
         ):
             headers.pop(header_name, None)
 
-        if not content_type:
-            headers.pop("content-type", None)
-            headers.pop("Content-Type", None)
+        if is_json_body:
+            if not content_type:
+                headers.pop("content-type", None)
+                headers.pop("Content-Type", None)
+            media_type = content_type or None
+            return Response(
+                content=body_bytes,
+                status_code=status_code,
+                headers=headers,
+                media_type=media_type,
+            )
 
-        media_type = content_type or None
+        # Non-JSON upstream error (HTML, plain text, empty, ...). Wrap it in
+        # the standard JSON envelope so callers don't need a second parser.
+        for header_name in ("content-type", "Content-Type"):
+            headers.pop(header_name, None)
+
+        envelope = {
+            "error": {
+                "message": message or "Upstream returned a non-JSON error response",
+                "type": "upstream_error",
+                "code": upstream_code or status_code,
+                "upstream_status": status_code,
+                "upstream_content_type": content_type or None,
+                "upstream_body_preview": body_preview or None,
+            },
+            "request_id": getattr(request.state, "request_id", None),
+        }
 
         return Response(
-            content=body_bytes,
+            content=json.dumps(envelope).encode(),
             status_code=status_code,
             headers=headers,
-            media_type=media_type,
+            media_type="application/json",
         )
 
     async def handle_streaming_chat_completion(
@@ -2159,6 +2197,12 @@ class BaseUpstreamProvider:
         """
         path = self.normalize_request_path(path, model_obj)
 
+        if (
+            path.endswith("messages/count_tokens")
+            and not self.supports_anthropic_messages
+        ):
+            return count_tokens_locally(request_body, model_obj)
+
         if (
             path.endswith("messages")
             and not path.endswith("count_tokens")
@@ -3357,6 +3401,12 @@ class BaseUpstreamProvider:
 
         request_body = await request.body()
 
+        if (
+            path.endswith("messages/count_tokens")
+            and not self.supports_anthropic_messages
+        ):
+            return count_tokens_locally(request_body, model_obj)
+
         if (
             path.endswith("messages")
             and not path.endswith("count_tokens")

routstr/upstream/count_tokens.py

@@ -0,0 +1,108 @@
+"""Local handling of Anthropic ``/v1/messages/count_tokens`` for upstreams
+that do not natively expose the endpoint.
+
+Most non-Anthropic upstreams (OpenAI-compat, Gemini OpenAI-compat,
+OpenRouter chat-completions, generic providers) return 400/404 when asked
+to ``POST /messages/count_tokens``. Claude Code and other Anthropic SDK
+clients call this endpoint before each turn to size context windows and
+trigger compaction, so a failure breaks the whole chat.
+
+We answer locally. ``litellm.token_counter`` understands the Anthropic
+message shape and the per-model tokenizers, so we prefer it. If it raises
+(unknown model, encoding lookup failure, ...), we fall back to the
+project's own ``estimate_tokens`` heuristic, which is always defined and
+never raises.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import litellm
+from fastapi.responses import Response
+
+from ..core import get_logger
+from ..payment.helpers import estimate_tokens
+from ..payment.models import Model
+
+logger = get_logger(__name__)
+
+
+def _parse_request_body(request_body: bytes | None) -> dict[str, Any]:
+    if not request_body:
+        return {}
+    try:
+        parsed = json.loads(request_body)
+    except (ValueError, TypeError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _count_with_litellm(model: str, body: dict[str, Any]) -> int:
+    messages = body.get("messages")
+    if not isinstance(messages, list):
+        messages = []
+
+    system = body.get("system")
+    if isinstance(system, str) and system:
+        messages = [{"role": "system", "content": system}, *messages]
+    elif isinstance(system, list):
+        text = "".join(
+            block.get("text", "")
+            for block in system
+            if isinstance(block, dict) and block.get("type") == "text"
+        )
+        if text:
+            messages = [{"role": "system", "content": text}, *messages]
+
+    tools = body.get("tools") if isinstance(body.get("tools"), list) else None
+
+    return int(
+        litellm.token_counter(
+            model=model,
+            messages=messages,
+            tools=tools,
+        )
+    )
+
+
+def count_tokens_locally(
+    request_body: bytes | None,
+    model_obj: Model | None,
+) -> Response:
+    """Return an Anthropic-compatible count_tokens response without
+    touching the upstream. Always returns 200; never raises."""
+    body = _parse_request_body(request_body)
+
+    model_name = ""
+    if model_obj is not None:
+        model_name = model_obj.forwarded_model_id or model_obj.id or ""
+    if not model_name:
+        body_model = body.get("model")
+        if isinstance(body_model, str):
+            model_name = body_model
+
+    input_tokens: int
+    try:
+        input_tokens = _count_with_litellm(model_name, body)
+    except Exception as exc:
+        messages = body.get("messages")
+        fallback_messages = messages if isinstance(messages, list) else []
+        input_tokens = estimate_tokens(fallback_messages)
+        logger.debug(
+            "litellm token_counter failed; using local estimator",
+            extra={
+                "model": model_name,
+                "error": str(exc),
+                "error_type": type(exc).__name__,
+                "estimated_tokens": input_tokens,
+            },
+        )
+
+    payload = {"input_tokens": max(0, int(input_tokens))}
+    return Response(
+        content=json.dumps(payload).encode(),
+        status_code=200,
+        media_type="application/json",
+    )

routstr/upstream/routstr.py

@@ -18,6 +18,10 @@ class RoutstrUpstreamProvider(BaseUpstreamProvider):
     provider_type = "routstr"
     default_base_url = None
     platform_url = None
+    # Upstream Routstr nodes serve `/v1/messages` natively, so forward the
+    # request as-is instead of round-tripping through litellm's
+    # Anthropic→OpenAI translator.
+    supports_anthropic_messages = True
 
     def __init__(
         self,
@@ -43,6 +47,13 @@ class RoutstrUpstreamProvider(BaseUpstreamProvider):
         )
         self.settings = provider_settings or {}
 
+    def normalize_request_path(
+        self, path: str, model_obj: "Model | None" = None
+    ) -> str:
+        """Preserve the ``v1/`` prefix when forwarding to an upstream Routstr.
+        """
+        return path.lstrip("/")
+
     @classmethod
     def from_db_row(
         cls, provider_row: "UpstreamProviderRow"

routstr/wallet.py

@@ -56,17 +56,56 @@ async def recieve_token(
 
 async def send(amount: int, unit: str, mint_url: str | None = None) -> tuple[int, str]:
     """Internal send function - returns amount and serialized token"""
-    wallet: Wallet = await get_wallet(mint_url or settings.primary_mint, unit)
-    proofs = get_proofs_per_mint_and_unit(
-        wallet, mint_url or settings.primary_mint, unit
+    effective_mint_url = mint_url or settings.primary_mint
+    wallet: Wallet = await get_wallet(effective_mint_url, unit)
+    proofs = get_proofs_per_mint_and_unit(wallet, effective_mint_url, unit)
+    proofs_for_mint = sum(p.amount for p in proofs)
+
+    # Fallback: proofs from untrusted source mints are swapped to primary_mint
+    # during receive, so the user's preferred refund_mint_url may have no proofs
+    # even though the global wallet has the balance.
+    if proofs_for_mint < amount and effective_mint_url != settings.primary_mint:
+        logger.info(
+            f"send: insufficient proofs at {effective_mint_url} "
+            f"(have {proofs_for_mint}, need {amount}), falling back to primary_mint={settings.primary_mint}"
+        )
+        effective_mint_url = settings.primary_mint
+        wallet = await get_wallet(effective_mint_url, unit)
+        proofs = get_proofs_per_mint_and_unit(wallet, effective_mint_url, unit)
+        proofs_for_mint = sum(p.amount for p in proofs)
+
+    all_mint_urls = list({k.mint_url for k in wallet.keysets.values()})
+    proof_summary = {
+        f"{k.mint_url}/{k.unit.name}": sum(p.amount for p in wallet.proofs if p.id == k.id)
+        for k in wallet.keysets.values()
+    }
+    # Show ALL proofs in DB by keyset_id, regardless of whether the loaded wallet
+    # knows about that keyset. This reveals proofs orphaned under stale keysets.
+    raw_proofs_by_keyset: dict[str, int] = {}
+    for p in wallet.proofs:
+        raw_proofs_by_keyset[p.id] = raw_proofs_by_keyset.get(p.id, 0) + p.amount
+    logger.info(
+        f"send: proof inventory | mint={effective_mint_url} unit={unit} amount={amount} "
+        f"primary_mint={settings.primary_mint} proofs_for_mint={proofs_for_mint} "
+        f"all_mints={all_mint_urls} by_keyset={proof_summary} "
+        f"raw_proofs_by_keyset_id={raw_proofs_by_keyset} "
+        f"total_wallet_proofs={sum(p.amount for p in wallet.proofs)}"
     )
 
+    # Reserve proofs only after serialization succeeds — if serialize_proofs or
+    # swap_to_send fails mid-way, proofs stay unreserved so dashboard balance
+    # doesn't go negative.
     send_proofs, _ = await wallet.select_to_send(
-        proofs, amount, set_reserved=True, include_fees=False
-    )
-    token = await wallet.serialize_proofs(
-        send_proofs, include_dleq=False, legacy=False, memo=None
+        proofs, amount, set_reserved=False, include_fees=False
     )
+    try:
+        token = await wallet.serialize_proofs(
+            send_proofs, include_dleq=False, legacy=False, memo=None
+        )
+    except Exception:
+        await wallet.set_reserved_for_send(send_proofs, reserved=False)
+        raise
+    await wallet.set_reserved_for_send(send_proofs, reserved=True)
     return amount, token
 
 
@@ -81,10 +120,11 @@ async def _calculate_swap_amount(
     token_mint_url: str,
     token_wallet: Wallet,
     primary_wallet: Wallet,
+    proofs: list,
 ) -> int:
     """
     Calculate the amount to mint on the primary mint after accounting for
-    potential swap fees (melt fees) on the foreign mint.
+    melt fees and NUT-02 input fees on the foreign mint.
     """
     if settings.primary_mint_unit == "sat":
         receive_amount = amount_msat // 1000
@@ -111,10 +151,11 @@ async def _calculate_swap_amount(
         dummy_melt_quote = await token_wallet.melt_quote(dummy_mint_quote.request)
 
         fee_reserve = dummy_melt_quote.fee_reserve
+        input_fees = token_wallet.get_fees_for_proofs(proofs)
         if token_unit == "sat":
-            fee_msat = fee_reserve * 1000
+            fee_msat = (fee_reserve + input_fees) * 1000
         else:
-            fee_msat = fee_reserve
+            fee_msat = fee_reserve + input_fees
 
         amount_msat_after_fee = amount_msat - fee_msat
 
@@ -124,13 +165,14 @@ async def _calculate_swap_amount(
             minted_amount = int(amount_msat_after_fee)
 
         if minted_amount <= 0:
-            raise ValueError(f"Fees ({fee_reserve} {token_unit}) exceed token amount")
+            raise ValueError(f"Fees ({fee_reserve + input_fees} {token_unit}) exceed token amount")
 
         logger.info(
             "swap_to_primary_mint: fee estimation result",
             extra={
                 "token_amount_sat": amount_msat // 1000,
                 "estimated_fee_sat": fee_msat // 1000,
+                "input_fees": input_fees,
                 "minted_amount": minted_amount,
                 "minted_unit": settings.primary_mint_unit,
             },
@@ -191,6 +233,7 @@ async def swap_to_primary_mint(
         token_obj.mint,
         token_wallet,
         primary_wallet,
+        token_obj.proofs,
     )
 
     mint_quote = await primary_wallet.request_mint(minted_amount)
@@ -200,13 +243,15 @@ async def swap_to_primary_mint(
     )
 
     melt_quote = await token_wallet.melt_quote(mint_quote.request)
-    total_needed = melt_quote.amount + melt_quote.fee_reserve
+    input_fees = token_wallet.get_fees_for_proofs(token_obj.proofs)
+    total_needed = melt_quote.amount + melt_quote.fee_reserve + input_fees
     logger.info(
         "swap_to_primary_mint: melt quote received",
         extra={
             "melt_quote_id": melt_quote.quote,
             "melt_amount": melt_quote.amount,
             "melt_fee_reserve": melt_quote.fee_reserve,
+            "input_fees": input_fees,
             "total_needed": total_needed,
             "token_amount": token_amount,
         },
@@ -219,6 +264,7 @@ async def swap_to_primary_mint(
                 "token_amount": token_amount,
                 "melt_amount": melt_quote.amount,
                 "melt_fee_reserve": melt_quote.fee_reserve,
+                "input_fees": input_fees,
                 "total_needed": total_needed,
                 "shortfall": total_needed - token_amount,
             },
@@ -226,7 +272,7 @@ async def swap_to_primary_mint(
         raise ValueError(
             f"Token amount ({token_amount} {token_obj.unit}) is insufficient to cover "
             f"melt fees. Needed: {total_needed} {token_obj.unit} "
-            f"(amount: {melt_quote.amount} + fee: {melt_quote.fee_reserve})"
+            f"(amount: {melt_quote.amount} + fee: {melt_quote.fee_reserve} + input_fees: {input_fees})"
         )
 
     try:
@@ -257,19 +303,66 @@ async def swap_to_primary_mint(
         extra={"minted_amount": minted_amount, "mint_quote_id": mint_quote.quote},
     )
 
+    await primary_wallet.load_proofs(reload=True)
+    pre_mint_balance = primary_wallet.available_balance.amount
     try:
         _ = await primary_wallet.mint(minted_amount, quote_id=mint_quote.quote)
     except Exception as e:
-        logger.error(
-            "swap_to_primary_mint: mint on primary failed after successful melt",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "minted_amount": minted_amount,
-                "mint_quote_id": mint_quote.quote,
-            },
-        )
-        raise
+        if "11003" in str(e) or "outputs already signed" in str(e).lower():
+            # Previous mint call signed outputs at the mint but failed before
+            # bump_secret_derivation ran locally. Recover orphaned proofs and
+            # advance the counter so the next request derives fresh secrets.
+            logger.warning(
+                "swap_to_primary_mint: outputs already signed — recovering orphaned proofs",
+                extra={"mint_quote_id": mint_quote.quote, "minted_amount": minted_amount},
+            )
+            try:
+                for keyset_id in primary_wallet.keysets:
+                    await primary_wallet.restore_tokens_for_keyset(keyset_id, to=1, batch=25)
+                await primary_wallet.load_proofs(reload=True)
+                post_recovery_balance = primary_wallet.available_balance.amount
+                balance_gained = post_recovery_balance - pre_mint_balance
+                logger.info(
+                    "swap_to_primary_mint: recovery scan completed",
+                    extra={
+                        "pre_mint_balance": pre_mint_balance,
+                        "post_recovery_balance": post_recovery_balance,
+                        "balance_gained": balance_gained,
+                        "expected": minted_amount,
+                    },
+                )
+                if balance_gained < minted_amount:
+                    # Recovery scan ran but did NOT restore the orphaned proofs
+                    # (mint reports them as spent — they're stuck). Refuse to
+                    # credit the API key balance for proofs we don't actually hold.
+                    raise ValueError(
+                        f"Swap recovery failed: mint signed outputs but proofs are "
+                        f"unrecoverable (mint reports them spent). "
+                        f"Expected {minted_amount}, recovered {balance_gained}. "
+                        f"Local wallet DB ('.wallet/') state is corrupted — "
+                        f"the counter for keyset is stuck at a bad index range."
+                    )
+            except ValueError:
+                raise
+            except Exception as recovery_err:
+                logger.error(
+                    "swap_to_primary_mint: recovery failed",
+                    extra={"error": str(recovery_err)},
+                )
+                raise ValueError(
+                    f"Mint on primary failed and recovery unsuccessful: {e}"
+                ) from e
+        else:
+            logger.error(
+                "swap_to_primary_mint: mint on primary failed after successful melt",
+                extra={
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                    "minted_amount": minted_amount,
+                    "mint_quote_id": mint_quote.quote,
+                },
+            )
+            raise
 
     logger.info(
         "swap_to_primary_mint: completed successfully",
@@ -443,7 +536,7 @@ async def fetch_all_balances(
                 "unit": unit,
                 "wallet_balance": proofs_balance,
                 "user_balance": user_balance,
-                "owner_balance": proofs_balance - user_balance,
+                "owner_balance": proofs_balance - user_balance if proofs_balance != 0 else 0,
             }
             return result
         except Exception as e:
@@ -491,7 +584,9 @@ async def fetch_all_balances(
             total_wallet_balance_sats += proofs_balance_sats
             total_user_balance_sats += user_balance_sats
 
-    owner_balance = total_wallet_balance_sats - total_user_balance_sats
+    owner_balance = 0
+    if total_wallet_balance_sats != 0:
+        owner_balance = total_wallet_balance_sats - total_user_balance_sats
 
     return (
         balance_details,
@@ -502,11 +597,11 @@ async def fetch_all_balances(
 
 
 async def periodic_payout() -> None:
-    if not settings.receive_ln_address:
-        logger.warning("RECEIVE_LN_ADDRESS is not set, periodic payout disabled")
-        return
     while True:
-        await asyncio.sleep(60 * 15)
+        await asyncio.sleep(settings.payout_interval_seconds)
+        print(settings.payout_interval_seconds)
+        if not settings.receive_ln_address:
+            continue
         try:
             async with db.create_session() as session:
                 for mint_url in settings.cashu_mints:
@@ -524,7 +619,12 @@ async def periodic_payout() -> None:
                             user_balance = user_balance // 1000
                         proofs_balance = sum(proof.amount for proof in proofs)
                         available_balance = proofs_balance - user_balance
-                        min_amount = 210 if unit == "sat" else 210000
+                        # Threshold is configured in sats; convert for msat wallets.
+                        min_amount = (
+                            settings.min_payout_sat
+                            if unit == "sat"
+                            else settings.min_payout_sat * 1000
+                        )
                         if available_balance > min_amount:
                             amount_received = await raw_send_to_lnurl(
                                 wallet,

tests/unit/test_count_tokens_local.py

@@ -0,0 +1,177 @@
+"""Unit tests for the local count_tokens shim.
+
+The shim runs whenever an upstream that does not support Anthropic's
+``/v1/messages`` endpoint is asked for a token count. It must always
+return a 200 JSON ``{"input_tokens": N}`` response and must never raise.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import patch
+
+from routstr.payment.models import Architecture, Model, Pricing
+from routstr.upstream import count_tokens as count_tokens_module
+from routstr.upstream.count_tokens import count_tokens_locally
+
+
+def _make_model(model_id: str = "anthropic/claude-3-5-sonnet") -> Model:
+    pricing = Pricing(prompt=0.000003, completion=0.000015)
+    architecture = Architecture(
+        modality="text",
+        input_modalities=["text"],
+        output_modalities=["text"],
+        tokenizer="cl100k_base",
+        instruct_type=None,
+    )
+    return Model(
+        id=model_id,
+        name=model_id,
+        created=0,
+        description="",
+        context_length=200_000,
+        architecture=architecture,
+        pricing=pricing,
+    )
+
+
+def _body(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload).encode()
+
+
+def _read_payload(response: Any) -> dict[str, Any]:
+    body = response.body if isinstance(response.body, bytes) else bytes(response.body)
+    return json.loads(body.decode())
+
+
+def test_returns_input_tokens_for_simple_messages() -> None:
+    model = _make_model()
+    request_body = _body(
+        {
+            "model": model.id,
+            "messages": [{"role": "user", "content": "hello world"}],
+        }
+    )
+
+    response = count_tokens_locally(request_body, model)
+
+    assert response.status_code == 200
+    assert response.media_type == "application/json"
+    payload = _read_payload(response)
+    assert "input_tokens" in payload
+    assert isinstance(payload["input_tokens"], int)
+    assert payload["input_tokens"] >= 0
+
+
+def test_falls_back_to_estimator_when_litellm_raises() -> None:
+    model = _make_model()
+    request_body = _body(
+        {
+            "model": model.id,
+            "messages": [{"role": "user", "content": "this is a longer message"}],
+        }
+    )
+
+    with patch.object(
+        count_tokens_module,
+        "_count_with_litellm",
+        side_effect=RuntimeError("boom"),
+    ):
+        response = count_tokens_locally(request_body, model)
+
+    assert response.status_code == 200
+    payload = _read_payload(response)
+    assert payload["input_tokens"] >= 1
+
+
+def test_handles_missing_model_object() -> None:
+    request_body = _body(
+        {
+            "model": "anthropic/claude-3-5-sonnet",
+            "messages": [{"role": "user", "content": "hi"}],
+        }
+    )
+
+    response = count_tokens_locally(request_body, None)
+
+    assert response.status_code == 200
+    payload = _read_payload(response)
+    assert payload["input_tokens"] >= 0
+
+
+def test_handles_empty_request_body() -> None:
+    response = count_tokens_locally(b"", _make_model())
+
+    assert response.status_code == 200
+    payload = _read_payload(response)
+    assert payload["input_tokens"] >= 0
+
+
+def test_handles_malformed_json() -> None:
+    response = count_tokens_locally(b"not-json", _make_model())
+
+    assert response.status_code == 200
+    payload = _read_payload(response)
+    assert payload["input_tokens"] >= 0
+
+
+def test_includes_system_prompt_in_count() -> None:
+    model = _make_model()
+    short = _body(
+        {
+            "model": model.id,
+            "messages": [{"role": "user", "content": "hi"}],
+        }
+    )
+    with_system = _body(
+        {
+            "model": model.id,
+            "system": "You are a helpful assistant with a long preamble " * 10,
+            "messages": [{"role": "user", "content": "hi"}],
+        }
+    )
+
+    short_count = _read_payload(count_tokens_locally(short, model))["input_tokens"]
+    long_count = _read_payload(count_tokens_locally(with_system, model))["input_tokens"]
+
+    assert long_count > short_count
+
+
+def test_supports_anthropic_system_block_list() -> None:
+    model = _make_model()
+    request_body = _body(
+        {
+            "model": model.id,
+            "system": [{"type": "text", "text": "be terse" * 50}],
+            "messages": [{"role": "user", "content": "ok"}],
+        }
+    )
+
+    response = count_tokens_locally(request_body, model)
+
+    payload = _read_payload(response)
+    assert payload["input_tokens"] > 0
+
+
+def test_uses_forwarded_model_id_when_present() -> None:
+    model = _make_model("anthropic/claude-3-5-sonnet")
+    model.forwarded_model_id = "claude-3-5-sonnet-20241022"
+    request_body = _body(
+        {
+            "model": "ignored",
+            "messages": [{"role": "user", "content": "hi"}],
+        }
+    )
+
+    captured: dict[str, Any] = {}
+
+    def _capture(model_name: str, body: dict[str, Any]) -> int:
+        captured["model"] = model_name
+        return 7
+
+    with patch.object(count_tokens_module, "_count_with_litellm", side_effect=_capture):
+        response = count_tokens_locally(request_body, model)
+
+    assert captured["model"] == "claude-3-5-sonnet-20241022"
+    assert _read_payload(response)["input_tokens"] == 7

tests/unit/test_messages_litellm_dispatch.py

@@ -908,7 +908,7 @@ async def test_forward_request_skips_litellm_when_provider_supports_messages() -
 
 
 @pytest.mark.asyncio
-async def test_forward_request_skips_litellm_for_count_tokens() -> None:
+async def test_forward_request_handles_count_tokens_locally() -> None:
     provider = _make_provider()
     key = _make_key()
     model = _make_model()
@@ -923,19 +923,25 @@ async def test_forward_request_skips_litellm_for_count_tokens() -> None:
         with patch.object(
             provider,
             "prepare_request_body",
-            side_effect=RuntimeError("stop here"),
+            side_effect=AssertionError("upstream should not be called"),
         ):
-            with pytest.raises(RuntimeError, match="stop here"):
-                await provider.forward_request(
-                    request=request,
-                    path="messages/count_tokens",
-                    headers={},
-                    request_body=_anthropic_request_body(),
-                    key=key,
-                    max_cost_for_model=10_000,
-                    session=session,
-                    model_obj=model,
-                )
+            response = await provider.forward_request(
+                request=request,
+                path="messages/count_tokens",
+                headers={},
+                request_body=_anthropic_request_body(),
+                key=key,
+                max_cost_for_model=10_000,
+                session=session,
+                model_obj=model,
+            )
+
+    assert response.status_code == 200
+    body = response.body if isinstance(response.body, bytes) else bytes(response.body)
+    payload = json.loads(body.decode())
+    assert "input_tokens" in payload
+    assert isinstance(payload["input_tokens"], int)
+    assert payload["input_tokens"] >= 0
 
 
 # ---------------------------------------------------------------------------
@@ -1010,7 +1016,7 @@ async def test_forward_x_cashu_request_skips_litellm_when_native_messages() -> N
 
 
 @pytest.mark.asyncio
-async def test_forward_x_cashu_request_skips_litellm_for_count_tokens() -> None:
+async def test_forward_x_cashu_request_handles_count_tokens_locally() -> None:
     provider = _make_provider()
     model = _make_model()
     request = _make_request()
@@ -1024,18 +1030,24 @@ async def test_forward_x_cashu_request_skips_litellm_for_count_tokens() -> None:
         with patch.object(
             provider,
             "prepare_request_body",
-            side_effect=RuntimeError("stop here"),
+            side_effect=AssertionError("upstream should not be called"),
         ):
-            with pytest.raises(RuntimeError, match="stop here"):
-                await provider.forward_x_cashu_request(
-                    request=request,
-                    path="v1/messages/count_tokens",
-                    headers={},
-                    amount=5_000,
-                    unit="sat",
-                    max_cost_for_model=10_000,
-                    model_obj=model,
-                )
+            response = await provider.forward_x_cashu_request(
+                request=request,
+                path="v1/messages/count_tokens",
+                headers={},
+                amount=5_000,
+                unit="sat",
+                max_cost_for_model=10_000,
+                model_obj=model,
+                mint="https://mint",
+                payment_token_hash="h",
+            )
+
+    assert response.status_code == 200
+    body = response.body if isinstance(response.body, bytes) else bytes(response.body)
+    payload = json.loads(body.decode())
+    assert "input_tokens" in payload
 
 
 # ---------------------------------------------------------------------------

tests/unit/test_proxy_not_found.py

@@ -0,0 +1,64 @@
+"""Tests for the built-in 404 handler in routstr.proxy."""
+
+from __future__ import annotations
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from routstr import proxy
+from routstr.proxy import proxy_router
+
+
+def _make_app() -> FastAPI:
+    app = FastAPI()
+    app.include_router(proxy_router)
+    return app
+
+
+@pytest.mark.skipif(
+    proxy._NOT_FOUND_HTML is None,
+    reason="UI bundle (ui_out/404.html) not present in this environment",
+)
+def test_unknown_path_returns_html_404_for_browser() -> None:
+    client = TestClient(_make_app())
+    response = client.get("/some/random/page", headers={"accept": "text/html"})
+    assert response.status_code == 404
+    assert response.headers["content-type"].startswith("text/html")
+    assert "404" in response.text
+
+
+def test_unknown_path_returns_json_404_for_api_client() -> None:
+    client = TestClient(_make_app())
+    response = client.get(
+        "/some/random/page", headers={"accept": "application/json"}
+    )
+    assert response.status_code == 404
+    assert response.headers["content-type"].startswith("application/json")
+    payload = response.json()
+    assert payload["error"]["type"] == "not_found"
+    assert payload["error"]["code"] == 404
+    assert "/some/random/page" in payload["error"]["message"]
+
+
+def test_root_path_returns_404_for_proxy_router() -> None:
+    client = TestClient(_make_app())
+    response = client.get("/", headers={"accept": "application/json"})
+    assert response.status_code == 404
+
+
+def test_v1_path_is_not_intercepted_by_404_handler() -> None:
+    """Paths starting with v1/ must reach the proxy logic, not the 404 handler."""
+    client = TestClient(_make_app(), raise_server_exceptions=False)
+    response = client.get("/v1/anything")
+    if response.status_code == 404:
+        # Any 404 here must come from inner proxy logic, not our HTML page.
+        assert "<!DOCTYPE html>" not in response.text
+
+
+def test_json_returned_when_ui_html_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(proxy, "_NOT_FOUND_HTML", None)
+    client = TestClient(_make_app())
+    response = client.get("/some/random/page", headers={"accept": "text/html"})
+    assert response.status_code == 404
+    assert response.headers["content-type"].startswith("application/json")

tests/unit/test_settings.py

@@ -1,11 +1,12 @@
 import os
 
 import pytest
+from pydantic.v1 import ValidationError
 from sqlalchemy.ext.asyncio import create_async_engine
 from sqlmodel import text
 from sqlmodel.ext.asyncio.session import AsyncSession
 
-from routstr.core.settings import SettingsService
+from routstr.core.settings import Settings, SettingsService
 
 
 @pytest.mark.asyncio
@@ -46,6 +47,54 @@ async def test_settings_db_precedence_over_env() -> None:
         assert again.enable_analytics_sharing is False
 
 
+def test_payout_settings_have_sensible_defaults() -> None:
+    s = Settings()
+    assert s.min_payout_sat == 210
+    assert s.payout_interval_seconds == 900
+
+
+@pytest.mark.parametrize(
+    "field,bad_value",
+    [
+        ("min_payout_sat", 0),
+        ("min_payout_sat", -1),
+        ("payout_interval_seconds", 0),
+        ("payout_interval_seconds", -10),
+    ],
+)
+def test_payout_settings_reject_invalid_values(field: str, bad_value: int) -> None:
+    kwargs: dict[str, object] = {field: bad_value}
+    with pytest.raises(ValidationError):
+        Settings(**kwargs)  # type: ignore[arg-type]
+
+
+def test_payout_settings_accept_custom_positive_values() -> None:
+    s = Settings(min_payout_sat=500, payout_interval_seconds=60)
+    assert s.min_payout_sat == 500
+    assert s.payout_interval_seconds == 60
+
+
+@pytest.mark.asyncio
+async def test_payout_settings_persist_via_settings_service() -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with AsyncSession(engine, expire_on_commit=False) as session:
+        await SettingsService.initialize(session)
+        updated = await SettingsService.update(
+            {"min_payout_sat": 1000, "payout_interval_seconds": 300}, session
+        )
+        assert updated.min_payout_sat == 1000
+        assert updated.payout_interval_seconds == 300
+
+
+@pytest.mark.asyncio
+async def test_payout_settings_update_rejects_invalid() -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with AsyncSession(engine, expire_on_commit=False) as session:
+        await SettingsService.initialize(session)
+        with pytest.raises(ValidationError):
+            await SettingsService.update({"min_payout_sat": 0}, session)
+
+
 @pytest.mark.asyncio
 async def test_settings_initialize_discards_unknown_keys() -> None:
     engine = create_async_engine("sqlite+aiosqlite:///:memory:")

tests/unit/test_upstream_error_response.py

@@ -0,0 +1,150 @@
+"""Tests for ``BaseUpstreamProvider.forward_upstream_error_response``.
+
+Upstream services (e.g. an Express server that doesn't expose ``/messages``)
+sometimes return a non-JSON error body. The proxy must surface those errors
+in a consistent JSON envelope so clients don't have to parse HTML.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import Mock
+
+import httpx
+import pytest
+
+from routstr.upstream.base import BaseUpstreamProvider, _is_json_content_type
+
+
+def _make_request(request_id: str = "req-123") -> Mock:
+    request = Mock(spec=["method", "state"])
+    request.method = "POST"
+    request.state = Mock()
+    request.state.request_id = request_id
+    return request
+
+
+def _make_upstream_response(
+    *,
+    body: bytes,
+    status_code: int = 404,
+    content_type: str | None = "text/html",
+    extra_headers: dict[str, str] | None = None,
+) -> httpx.Response:
+    headers: dict[str, str] = {}
+    if content_type is not None:
+        headers["content-type"] = content_type
+    if extra_headers:
+        headers.update(extra_headers)
+    return httpx.Response(status_code=status_code, headers=headers, content=body)
+
+
+@pytest.fixture
+def provider() -> BaseUpstreamProvider:
+    return BaseUpstreamProvider(
+        base_url="https://privateprovider.xyz", api_key="k", provider_fee=1.0
+    )
+
+
+@pytest.mark.parametrize(
+    "content_type,expected",
+    [
+        ("application/json", True),
+        ("application/json; charset=utf-8", True),
+        ("text/json", True),
+        ("application/problem+json", True),
+        ("application/vnd.api+json", True),
+        ("text/html", False),
+        ("text/html; charset=utf-8", False),
+        ("text/plain", False),
+        ("", False),
+        (None, False),
+    ],
+)
+def test_is_json_content_type(content_type: str | None, expected: bool) -> None:
+    assert _is_json_content_type(content_type) is expected
+
+
+@pytest.mark.asyncio
+async def test_html_error_is_normalized_to_json_envelope(
+    provider: BaseUpstreamProvider,
+) -> None:
+    html_body = (
+        b"<!DOCTYPE html><html><head><title>Error</title></head>"
+        b"<body><pre>Cannot POST /messages</pre></body></html>"
+    )
+    upstream = _make_upstream_response(body=html_body, status_code=404)
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/messages", upstream
+    )
+
+    assert response.status_code == 404
+    assert response.media_type == "application/json"
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["upstream_status"] == 404
+    assert payload["error"]["upstream_content_type"] == "text/html"
+    assert "Cannot POST /messages" in payload["error"]["upstream_body_preview"]
+    assert payload["request_id"] == "req-123"
+    # The upstream's text/html content-type must not survive — Response()
+    # sets the JSON content-type for us via media_type.
+    assert response.headers["content-type"].startswith("application/json")
+
+
+@pytest.mark.asyncio
+async def test_plain_text_error_is_normalized(
+    provider: BaseUpstreamProvider,
+) -> None:
+    upstream = _make_upstream_response(
+        body=b"Service Unavailable", status_code=503, content_type="text/plain"
+    )
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/messages", upstream
+    )
+
+    assert response.status_code == 503
+    assert response.media_type == "application/json"
+    payload = json.loads(bytes(response.body))
+    assert payload["error"]["message"] == "Service Unavailable"
+
+
+@pytest.mark.asyncio
+async def test_empty_body_with_non_json_content_type_normalizes(
+    provider: BaseUpstreamProvider,
+) -> None:
+    upstream = _make_upstream_response(
+        body=b"", status_code=502, content_type="text/html"
+    )
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/messages", upstream
+    )
+
+    assert response.status_code == 502
+    assert response.media_type == "application/json"
+    payload = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["upstream_body_preview"] is None
+
+
+@pytest.mark.asyncio
+async def test_json_error_body_is_passed_through_unchanged(
+    provider: BaseUpstreamProvider,
+) -> None:
+    json_body = json.dumps(
+        {"error": {"message": "Invalid model", "type": "invalid_request_error"}}
+    ).encode()
+    upstream = _make_upstream_response(
+        body=json_body, status_code=400, content_type="application/json"
+    )
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/messages", upstream
+    )
+
+    assert response.status_code == 400
+    assert bytes(response.body) == json_body
+    assert response.media_type == "application/json"

tests/unit/test_upstream_routstr.py

@@ -74,3 +74,39 @@ async def test_get_balance_returns_none_on_connect_timeout(
     balance = await provider.get_balance()
 
     assert balance is None
+
+
+def test_normalize_request_path_keeps_v1_prefix() -> None:
+    """Routstr upstream stores ``base_url`` without ``/v1``; the prefix
+    must stay on the path so ``build_request_url`` produces ``/v1/<endpoint>``
+    instead of ``/<endpoint>`` (which the upstream Routstr 404s with HTML)."""
+    provider = RoutstrUpstreamProvider(
+        base_url="https://privateprovider.xyz", api_key="key"
+    )
+
+    assert provider.normalize_request_path("v1/messages") == "v1/messages"
+    assert provider.normalize_request_path("/v1/messages") == "v1/messages"
+    assert (
+        provider.normalize_request_path("v1/chat/completions")
+        == "v1/chat/completions"
+    )
+
+
+def test_build_request_url_for_v1_messages() -> None:
+    """Forwarding ``/v1/messages`` must hit the upstream's ``/v1/messages``."""
+    provider = RoutstrUpstreamProvider(
+        base_url="https://privateprovider.xyz", api_key="key"
+    )
+
+    normalized = provider.normalize_request_path("v1/messages")
+
+    assert (
+        provider.build_request_url(normalized)
+        == "https://privateprovider.xyz/v1/messages"
+    )
+
+
+def test_supports_anthropic_messages_natively() -> None:
+    """Routstr nodes serve ``/v1/messages`` directly, so the proxy must
+    forward as-is instead of round-tripping through litellm."""
+    assert RoutstrUpstreamProvider.supports_anthropic_messages is True

tests/unit/test_wallet.py

@@ -123,6 +123,7 @@ async def test_swap_to_primary_mint_insufficient_for_fees() -> None:
     mock_token_wallet = Mock()
     mock_token_wallet.load_mint = AsyncMock()
     mock_token_wallet.load_proofs = AsyncMock()
+    mock_token_wallet.get_fees_for_proofs = Mock(return_value=0)
 
     mock_primary_wallet = Mock()
     mock_primary_wallet.load_mint = AsyncMock()
@@ -166,6 +167,7 @@ async def test_swap_to_primary_mint_melt_error_wrapped() -> None:
     mock_token_wallet = Mock()
     mock_token_wallet.load_mint = AsyncMock()
     mock_token_wallet.load_proofs = AsyncMock()
+    mock_token_wallet.get_fees_for_proofs = Mock(return_value=0)
 
     mock_primary_wallet = Mock()
     mock_primary_wallet.load_mint = AsyncMock()
@@ -261,6 +263,7 @@ async def test_swap_to_primary_mint_success() -> None:
     mock_token_wallet = Mock()
     mock_token_wallet.load_mint = AsyncMock()
     mock_token_wallet.load_proofs = AsyncMock()
+    mock_token_wallet.get_fees_for_proofs = Mock(return_value=0)
 
     mock_primary_wallet = Mock()
     mock_primary_wallet.load_mint = AsyncMock()

ui/components/settings/admin-settings.tsx

@@ -32,9 +32,18 @@ interface SettingsData {
   onion_url?: string;
   cashu_mints?: string[];
   relays?: string[];
+  receive_ln_address?: string;
+  min_payout_sat?: number;
+  payout_interval_seconds?: number;
   [key: string]: unknown;
 }
 
+const PAYOUT_KEYS = [
+  'receive_ln_address',
+  'min_payout_sat',
+  'payout_interval_seconds',
+] as const;
+
 const HANDLED_KEYS = [
   'name',
   'description',
@@ -48,6 +57,7 @@ const HANDLED_KEYS = [
   'admin_password',
   'id',
   'updated_at',
+  ...PAYOUT_KEYS,
 ];
 
 const IGNORED_KEYS = [
@@ -369,6 +379,7 @@ export function AdminSettings() {
   const cashuMintsChanged = hasFieldChanged('cashu_mints');
   const relaysChanged = hasFieldChanged('relays');
   const analyticsSharingChanged = hasFieldChanged('enable_analytics_sharing');
+  const payoutChanged = PAYOUT_KEYS.some(hasFieldChanged);
   const advancedKeys = Object.keys(settings).filter(
     (key) => !HANDLED_KEYS.includes(key) && !IGNORED_KEYS.includes(key)
   );
@@ -401,8 +412,44 @@ export function AdminSettings() {
     setNewRelay('');
   };
   const resetAnalyticsSharing = () => resetFields(['enable_analytics_sharing']);
+  const resetPayout = () => resetFields([...PAYOUT_KEYS]);
   const resetAdvanced = () => resetFields(advancedKeys);
 
+  const payoutFields: ReadonlyArray<{
+    key: (typeof PAYOUT_KEYS)[number];
+    label: string;
+    placeholder: string;
+    type: 'text' | 'number';
+    helpText: string;
+    min?: number;
+  }> = [
+    {
+      key: 'receive_ln_address',
+      label: 'Lightning Receive Address',
+      placeholder: 'you@walletofsatoshi.com or LNURL',
+      type: 'text',
+      helpText:
+        'Lightning address (or LNURL) profits are paid out to. Leave empty to disable periodic payouts.',
+    },
+    {
+      key: 'min_payout_sat',
+      label: 'Minimum Payout (sat)',
+      placeholder: '210',
+      type: 'number',
+      min: 1,
+      helpText:
+        'Wallet payouts only fire when at least this many satoshis are available. Must be > 0.',
+    },
+    {
+      key: 'payout_interval_seconds',
+      label: 'Payout Interval (seconds)',
+      placeholder: '900',
+      type: 'number',
+      min: 1,
+      helpText: 'How often the payout loop wakes up to check balances.',
+    },
+  ];
+
   if (loading) {
     return (
       <div className='space-y-4'>
@@ -620,6 +667,89 @@ export function AdminSettings() {
           ) : null}
         </Card>
 
+        {/* Lightning Payout Settings */}
+        <Card>
+          <CardHeader>
+            <CardTitle>Lightning Payout Settings</CardTitle>
+            <CardDescription>
+              Tune how node profit is paid out over Lightning. Amounts must be
+              positive and above your wallet&apos;s minimum-invoice constraints.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className='space-y-4'>
+            {payoutFields.map((field) => {
+              const value = settings[field.key];
+              if (field.type === 'number') {
+                return (
+                  <div key={field.key} className='space-y-2'>
+                    <Label htmlFor={field.key}>{field.label}</Label>
+                    <Input
+                      id={field.key}
+                      type='number'
+                      min={field.min}
+                      value={
+                        typeof value === 'number'
+                          ? value
+                          : value === undefined || value === null
+                            ? ''
+                            : Number(value)
+                      }
+                      placeholder={field.placeholder}
+                      onChange={(e) => {
+                        const raw = e.target.value;
+                        if (raw === '') {
+                          handleInputChange(field.key, undefined);
+                        } else {
+                          const parsed = Number(raw);
+                          handleInputChange(
+                            field.key,
+                            Number.isFinite(parsed) ? parsed : undefined
+                          );
+                        }
+                      }}
+                    />
+                    <p className='text-muted-foreground text-xs'>
+                      {field.helpText}
+                    </p>
+                  </div>
+                );
+              }
+              return (
+                <div key={field.key} className='space-y-2'>
+                  <Label htmlFor={field.key}>{field.label}</Label>
+                  <Input
+                    id={field.key}
+                    value={(value as string) || ''}
+                    placeholder={field.placeholder}
+                    onChange={(e) =>
+                      handleInputChange(field.key, e.target.value)
+                    }
+                  />
+                  <p className='text-muted-foreground text-xs'>
+                    {field.helpText}
+                  </p>
+                </div>
+              );
+            })}
+          </CardContent>
+          {payoutChanged ? (
+            <CardFooter className='justify-start'>
+              <div className='flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center'>
+                <Button
+                  variant='outline'
+                  onClick={resetPayout}
+                  disabled={loading || saving}
+                >
+                  Cancel
+                </Button>
+                <Button onClick={handleSave} disabled={loading || saving}>
+                  {saving ? 'Saving...' : 'Save'}
+                </Button>
+              </div>
+            </CardFooter>
+          ) : null}
+        </Card>
+
         {/* Relays */}
         <Card>
           <CardHeader>

ui/package.json

@@ -1,5 +1,6 @@
 {
   "name": "routstr-service",
+  "packageManager": "pnpm@10.15.0",
   "version": "0.1.0",
   "private": true,
   "scripts": {
@@ -88,5 +89,11 @@
     "prettier-plugin-tailwindcss": "^0.7.2",
     "tailwindcss": "^4.2.0",
     "typescript": "^5.9.3"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "sharp",
+      "unrs-resolver"
+    ]
   }
 }