chore: fix ruff lint errors (E402, F401, I001)

Fixes three issues that caused per-mint rate-limit state to never recover:

1. _is_mint_rate_limited: remove substring matching on 'rate limit' /
   'too many requests' in exception messages.  Only HTTP 429
   (httpx.HTTPStatusError) is now classified as a rate limit, preventing
   false positives (e.g. a 503 with 'database rate exceeded' in its body).

2. _run_probe: use apply_cooldown() instead of apply_rate_limit_cooldown()
   when a probe fails due to a rate limit.  The probe is a recovery check,
   not a new request, so it should not escalate the exponential backoff
   counter (_consecutive_rate_limits).  This prevents the cooldown from
   ratcheting 60s → 120s → 240s → ... → 7h on repeated probe failures.

3. classify_redemption_error: split the combined _is_mint_rate_limited ||
   is_mint_connection_error check into two separate classifications:
   - mint_rate_limited / cashu_mint_rate_limited (503, retryable)
   - mint_unreachable / cashu_mint_unreachable (503, retryable)
   Callers (routstrd) can now distinguish temporary rate limits from
   permanent connection failures when deciding fallback strategy.

Tests: 20 new tests covering strict 429 detection, classification
priority, probe non-escalation, and cooldown reset behaviour.

Dockerfile.full

@@ -7,7 +7,7 @@ WORKDIR /app/ui
 RUN corepack enable pnpm && corepack prepare pnpm@10.15.0 --activate
 
 # Copy UI source
-COPY ui/package.json ui/pnpm-lock.yaml* ./
+COPY ui/package.json ui/pnpm-lock.yaml* ui/pnpm-workspace.yaml* ./
 RUN pnpm install --frozen-lockfile
 
 COPY ui/ ./

docs/api/errors.md

@@ -113,42 +113,109 @@ All errors follow a consistent JSON structure:
 **Status:** 402  
 **Resolution:** Top up API key balance
 
-#### Invalid Token
+### Cashu Token Redemption Errors
+
+These errors are returned when a Cashu token you pay with cannot be redeemed.
+They apply to every endpoint that accepts a token:
+
+- **Per-request payment** via the `X-Cashu` header (chat completions + Responses API).
+- **API key top-up** via `POST /v1/wallet/topup`.
+- **Minting an API key** from a token sent in `Authorization: Bearer <cashu-token>`.
+
+All three share one classifier, so the same failure yields the same HTTP status
+and sanitized message everywhere. Structured error envelopes (`X-Cashu` and
+`Authorization: Bearer <cashu-token>`) also expose the same `type` and `code` —
+branch on `type` (or `code` for finer granularity). `POST /v1/wallet/topup`
+keeps its existing plain-string `detail` envelope, so branch on status there.
+
+| `type` | Status | `code` | Retryable | Meaning |
+|--------|--------|--------|-----------|---------|
+| `token_already_spent` | 400 | `cashu_token_already_spent` | No | The token was already redeemed. |
+| `invalid_token` | 400 | `invalid_cashu_token` | No | The token is malformed or cannot be decoded. |
+| `mint_error` | 422 | `cashu_token_swap_fees_exceed_amount` | No | Token value is too small to cover the mint's swap/melt fees. |
+| `mint_error` | 422 | `cashu_foreign_mint_swap_failed` | No | Swapping the token from a foreign mint to the primary mint failed. |
+| `mint_unreachable` | 503 | `cashu_mint_unreachable` | **Yes** | The mint could not be reached (DNS failure, refused/reset connection, timeout). The token is fine — retry once the mint recovers. |
+| `cashu_error` | 400 | `cashu_token_redemption_failed` | No | The token could not be redeemed for another expected reason. |
+| `cashu_error` | 400 | `cashu_token_zero_value` | No | The token redeemed to zero (empty/dust token, or value fully consumed by fees). |
+| `token_consumed` | 500 | `cashu_token_consumed` | No | The token was **spent** (melted/redeemed) but crediting it then failed. Do not retry — the token is gone; contact support to reconcile. |
+| `api_error` | 500 | `internal_error` | Maybe | Unexpected server-side fault during redemption. |
+
+!!! important "Retry only `mint_unreachable`"
+    Only `mint_unreachable` (503) means the same token will work again later —
+    everything else is a permanent property of the token and must not be
+    blindly retried. Use exponential backoff for the 503. In particular, a
+    `token_consumed` 500 means the mint already spent the token, so a retry
+    would fail as `token_already_spent`.
+
+#### Mint Unreachable (retryable)
 
 ```json
 {
   "error": {
-    "type": "payment_error",
-    "message": "Invalid Cashu token",
-    "code": "invalid_token",
-    "details": {
-      "reason": "Token already spent"
-    }
+    "type": "mint_unreachable",
+    "message": "Cashu mint is unreachable",
+    "code": "cashu_mint_unreachable"
   }
 }
 ```
 
-**Status:** 400  
-**Resolution:** Use a valid, unspent token
+**Status:** 503
 
-#### Mint Unavailable
+**Resolution:** The token is valid — the mint is temporarily down. Retry with
+backoff, or pay with a token from a different mint.
+
+#### Token Already Spent
 
 ```json
 {
   "error": {
-    "type": "payment_error",
-    "message": "Cannot connect to Cashu mint",
-    "code": "mint_unavailable",
-    "details": {
-      "mint_url": "https://mint.example.com",
-      "retry_after": 60
-    }
+    "type": "token_already_spent",
+    "message": "Cashu token already spent",
+    "code": "cashu_token_already_spent"
   }
 }
 ```
 
-**Status:** 503  
-**Resolution:** Try again later or use different mint
+**Status:** 400
+
+**Resolution:** Use a fresh, unspent token. Do not retry with the same token.
+
+#### Response envelope differs by endpoint
+
+The `error` object above is identical everywhere, but the surrounding envelope
+depends on how you paid:
+
+- **`X-Cashu` header payments** (chat + Responses API) return the object at the
+  top level, alongside a `request_id`:
+
+  ```json
+  {
+    "error": { "type": "mint_unreachable", "message": "Cashu mint is unreachable", "code": "cashu_mint_unreachable" },
+    "request_id": "req-abc123"
+  }
+  ```
+
+  The original token is echoed back in the `X-Cashu` **response header only when
+  it is still spendable** (e.g. `mint_unreachable`, `invalid_cashu_token`, fee
+  errors) so you can recover/retry it. It is **not** echoed for spent/consumed
+  tokens (`cashu_token_already_spent`, `cashu_token_consumed`,
+  `cashu_token_zero_value`, `internal_error`) — retrying those can never succeed.
+
+- **`Authorization: Bearer <cashu-token>`** (API key minting) wraps it in
+  FastAPI's `detail` field:
+
+  ```json
+  { "detail": { "error": { "type": "mint_unreachable", "message": "Cashu mint is unreachable", "code": "cashu_mint_unreachable" } } }
+  ```
+
+- **`POST /v1/wallet/topup`** returns a plain string message under `detail` —
+  it carries the shared HTTP **status** and **message** (e.g. `503` for an
+  unreachable mint) but not the structured `type`/`code`, so branch on the
+  status code here:
+
+  ```json
+  { "detail": "Cashu mint is unreachable" }
+  ```
 
 ### Validation Errors
 
@@ -347,7 +414,7 @@ class ErrorHandler:
         'rate_limit',
         'upstream_timeout',
         'model_overloaded',
-        'mint_unavailable'
+        'cashu_mint_unreachable'
     }
     
     # Errors requiring user action

migrations/versions/21c84cd5ad83_add_mint_url_to_lightning_invoices.py

@@ -0,0 +1,23 @@
+"""add mint url to lightning invoices
+
+Revision ID: 21c84cd5ad83
+Revises: c6d7e8f9a0b1
+Create Date: 2026-07-12 15:04:01.675455
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "21c84cd5ad83"
+down_revision = "c6d7e8f9a0b1"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("lightning_invoices", sa.Column("mint_url", sa.String(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("lightning_invoices", "mint_url")

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "routstr"
-version = "0.4.3"
+version = "0.4.4"
 description = "Payment proxy for your LLM endpoint using cashu and nostr."
 readme = "README.md"
 requires-python = ">=3.11"

routstr/algorithm.py

@@ -86,8 +86,8 @@ def get_provider_penalty(provider: "BaseUpstreamProvider") -> float:
 
 def create_model_mappings(
     upstreams: list["BaseUpstreamProvider"],
-    overrides_by_id: dict[str, tuple],
-    disabled_model_ids: set[str],
+    overrides_by_key: dict[tuple[str, int], tuple],
+    disabled_model_keys: set[tuple[str, int]],
 ) -> tuple[
     dict[str, "Model"], dict[str, list["BaseUpstreamProvider"]], dict[str, "Model"]
 ]:
@@ -107,8 +107,9 @@ def create_model_mappings(
 
     Args:
         upstreams: List of all upstream provider instances
-        overrides_by_id: Dict of model overrides from database {model_id: (ModelRow, fee)}
-        disabled_model_ids: Set of model IDs that should be excluded
+        overrides_by_key: Dict of model overrides from database
+            {(model_id_lower, upstream_provider_id): (ModelRow, fee)}
+        disabled_model_keys: Set of provider-scoped model keys that should be excluded
 
     Returns:
         Tuple of (model_instances, provider_map, unique_models)
@@ -179,14 +180,22 @@ def create_model_mappings(
         """Process all models from a given provider."""
         upstream_prefix = getattr(upstream, "upstream_name", None)
         provider_key = get_provider_identity(upstream)
+        upstream_db_id = getattr(upstream, "db_id", None)
 
         for model in upstream.get_cached_models():
-            if not model.enabled or model.id in disabled_model_ids:
+            model_key = (
+                (model.id.lower(), upstream_db_id)
+                if isinstance(upstream_db_id, int)
+                else None
+            )
+            if not model.enabled or (
+                model_key is not None and model_key in disabled_model_keys
+            ):
                 continue
 
-            # Apply overrides if present
-            if model.id in overrides_by_id:
-                override_row, provider_fee = overrides_by_id[model.id]
+            # Apply overrides only for this provider's model row.
+            if model_key is not None and model_key in overrides_by_key:
+                override_row, provider_fee = overrides_by_key[model_key]
                 model_to_use = _row_to_model(
                     override_row, apply_provider_fee=True, provider_fee=provider_fee
                 )
@@ -237,13 +246,10 @@ def create_model_mappings(
 
     # Include enabled DB overrides even when provider discovery misses models.
     # This is important for deployment-based providers like Azure.
-    for model_id, override_data in overrides_by_id.items():
-        if model_id in disabled_model_ids:
+    for (model_id, upstream_provider_id), override_data in overrides_by_key.items():
+        if (model_id, upstream_provider_id) in disabled_model_keys:
             continue
         override_row, provider_fee = override_data
-        upstream_provider_id = getattr(override_row, "upstream_provider_id", None)
-        if not isinstance(upstream_provider_id, int):
-            continue
 
         upstream_for_override = providers_by_db_id.get(upstream_provider_id)
         if upstream_for_override is None:

routstr/auth.py

@@ -20,7 +20,11 @@ from .payment.cost_calculation import (
     MaxCostData,
     calculate_cost,
 )
-from .wallet import credit_balance, deserialize_token_from_string
+from .wallet import (
+    classify_redemption_error,
+    credit_balance,
+    deserialize_token_from_string,
+)
 
 logger = get_logger(__name__)
 payments_logger = get_logger("routstr.payments")
@@ -31,6 +35,25 @@ ROUTSTR_LN_ADDRESS: str = "npub130mznv74rxs032peqym6g3wqavh472623mt3z5w73xq9r6qq
 ROUTSTR_FEE_PAYOUT_INTERVAL_SECONDS: int = 900
 ROUTSTR_FEE_DEFAULT_PAYOUT: int = 200
 
+
+def _format_msat_amount(amount: int) -> str:
+    sats = f"{amount / 1000:.3f}".rstrip("0").rstrip(".")
+    return f"{sats} sats ({amount} msats)"
+
+
+def _model_balance_error(required: int, available: int) -> dict[str, dict[str, str]]:
+    return {
+        "error": {
+            "message": (
+                f"Insufficient balance: {_format_msat_amount(required)} required "
+                f"for this model; {_format_msat_amount(available)} available."
+            ),
+            "type": "insufficient_quota",
+            "code": "insufficient_balance",
+        }
+    }
+
+
 # TODO: implement prepaid api key (not like it was before)
 # PREPAID_API_KEY = os.environ.get("PREPAID_API_KEY", None)
 # PREPAID_BALANCE = int(os.environ.get("PREPAID_BALANCE", "0")) * 1000  # Convert to msats
@@ -78,6 +101,37 @@ async def check_and_reset_limit(key: ApiKey, session: AsyncSession) -> bool:
     return False
 
 
+def redemption_error_to_http_exception(error: Exception) -> HTTPException:
+    """Map a Cashu token redemption failure to a sanitized client-facing error.
+
+    Thin wrapper over the shared :func:`classify_redemption_error` so the bearer
+    path stays identical to the X-Cashu and top-up paths.
+    """
+    classified = classify_redemption_error(error)
+    if classified is None:
+        return HTTPException(
+            status_code=500,
+            detail={
+                "error": {
+                    "message": "Internal error during token redemption",
+                    "type": "api_error",
+                    "code": "internal_error",
+                }
+            },
+        )
+    error_type, status_code, message, error_code = classified
+    return HTTPException(
+        status_code=status_code,
+        detail={
+            "error": {
+                "message": message,
+                "type": error_type,
+                "code": error_code,
+            }
+        },
+    )
+
+
 async def validate_bearer_key(
     bearer_key: str,
     session: AsyncSession,
@@ -171,13 +225,7 @@ async def validate_bearer_key(
                 )
                 raise HTTPException(
                     status_code=402,
-                    detail={
-                        "error": {
-                            "message": f"Insufficient balance: {min_cost} mSats required for this model. {billing_key.total_balance} available.",
-                            "type": "insufficient_quota",
-                            "code": "insufficient_balance",
-                        }
-                    },
+                    detail=_model_balance_error(min_cost, billing_key.total_balance),
                 )
 
             # Early check: Spending limit check (Child key limit)
@@ -216,7 +264,17 @@ async def validate_bearer_key(
 
         try:
             hashed_key = hashlib.sha256(bearer_key.encode()).hexdigest()
-            token_obj = deserialize_token_from_string(bearer_key)
+            try:
+                token_obj = deserialize_token_from_string(bearer_key)
+            except Exception as decode_error:
+                # A malformed token is a bad token (400 invalid_cashu_token via
+                # the shared taxonomy), not an auth failure (401) — otherwise it
+                # would fall through to the generic "Invalid API key" handler.
+                raise redemption_error_to_http_exception(
+                    ValueError(
+                        f"Invalid Cashu token: could not decode token ({decode_error})"
+                    )
+                ) from decode_error
             logger.debug(
                 "Generated token hash", extra={"hash_preview": hashed_key[:16] + "..."}
             )
@@ -257,13 +315,7 @@ async def validate_bearer_key(
                 if min_cost > 0 and existing_key.total_balance < min_cost:
                     raise HTTPException(
                         status_code=402,
-                        detail={
-                            "error": {
-                                "message": f"Insufficient balance: {min_cost} mSats required for this model. {existing_key.total_balance} available.",
-                                "type": "insufficient_quota",
-                                "code": "insufficient_balance",
-                            }
-                        },
+                        detail=_model_balance_error(min_cost, existing_key.total_balance),
                     )
 
                 return existing_key
@@ -334,19 +386,32 @@ async def validate_bearer_key(
                         "error_type": type(credit_error).__name__,
                     },
                 )
-                raise credit_error
+                await session.rollback()
+                raise redemption_error_to_http_exception(credit_error) from credit_error
 
             if msats <= 0:
                 logger.error(
                     "Token redemption returned zero or negative amount",
                     extra={"msats": msats, "key_hash": hashed_key[:8] + "..."},
                 )
-                # Defense-in-depth: credit_balance now refuses to commit on a
-                # zero/negative redemption, but if a row was nonetheless
-                # persisted, drop it so we never leave an orphan zero-balance key.
+                # Defense-in-depth: credit_balance already raises
+                # ValueError("Redeemed token amount must be positive…") before
+                # returning (wallet.py), so this branch is only reachable if a
+                # zero/negative row was somehow persisted; drop it so we never
+                # leave an orphan zero-balance key. Reuse the shared taxonomy
+                # (cashu_error) so the envelope matches the mapper above.
                 await session.delete(new_key)
                 await session.commit()
-                raise Exception("Token redemption failed")
+                raise HTTPException(
+                    status_code=400,
+                    detail={
+                        "error": {
+                            "message": "Failed to redeem Cashu token: token yielded no value",
+                            "type": "cashu_error",
+                            "code": "cashu_token_zero_value",
+                        }
+                    },
+                )
 
             await session.refresh(new_key)
             await session.commit()
@@ -379,7 +444,7 @@ async def validate_bearer_key(
                 status_code=401,
                 detail={
                     "error": {
-                        "message": f"Invalid or expired Cashu key: {str(e)}",
+                        "message": "Invalid or expired Cashu key",
                         "type": "invalid_request_error",
                         "code": "invalid_api_key",
                     }

routstr/balance.py

@@ -20,7 +20,15 @@ from .core.db import (
 from .core.logging import get_logger
 from .core.settings import settings
 from .lightning import lightning_router
-from .wallet import credit_balance, recieve_token, send_to_lnurl, send_token
+from .wallet import (
+    classify_redemption_error,
+    credit_balance,
+    is_mint_connection_error,
+    recieve_token,
+    send_to_lnurl,
+    send_token,
+    token_mint_url,
+)
 
 router = APIRouter()
 balance_router = APIRouter(prefix="/v1/balance")
@@ -137,6 +145,17 @@ class TopupRequest(BaseModel):
     cashu_token: str
 
 
+def _error_chain(error: BaseException) -> list[dict[str, str]]:
+    chain: list[dict[str, str]] = []
+    current: BaseException | None = error
+    seen: set[int] = set()
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        chain.append({"type": type(current).__name__, "message": str(current)})
+        current = current.__cause__ or current.__context__
+    return chain
+
+
 @router.post("/topup")
 async def topup_wallet_endpoint(
     cashu_token: str | None = None,
@@ -154,32 +173,61 @@ async def topup_wallet_endpoint(
     cashu_token = cashu_token.replace("\n", "").replace("\r", "").replace("\t", "")
     if len(cashu_token) < 10 or "cashu" not in cashu_token:
         raise HTTPException(status_code=400, detail="Invalid token format")
+
+    source_mint = token_mint_url(cashu_token, "unknown")
+    logger.warning(
+        "Cashu wallet top-up started",
+        extra={
+            "event": "cashu_topup_started",
+            "source_mint": source_mint,
+            "primary_mint": settings.primary_mint,
+            "trusted_mints": settings.cashu_mints,
+            "key_hash": billing_key.hashed_key[:8],
+        },
+    )
     try:
         amount_msats = await credit_balance(cashu_token, billing_key, session)
-    except ValueError as e:
-        error_msg = str(e)
-        if "already spent" in error_msg.lower():
-            raise HTTPException(status_code=400, detail="Token already spent")
-        elif "invalid" in error_msg.lower() or "decode" in error_msg.lower():
-            raise HTTPException(status_code=400, detail="Invalid token format")
-        elif "insufficient" in error_msg.lower() or "melt fee" in error_msg.lower():
-            raise HTTPException(
-                status_code=400,
-                detail=f"Token value is too small to cover swap fees. {error_msg}",
-            )
-        elif "failed to melt" in error_msg.lower():
-            raise HTTPException(
-                status_code=400,
-                detail=f"Failed to swap foreign mint token. {error_msg}",
-            )
-        else:
-            raise HTTPException(status_code=400, detail=f"Failed to redeem token: {error_msg}")
     except Exception as e:
-        logger.error(
-            "topup_wallet_endpoint: unhandled error",
-            extra={"error": str(e), "error_type": type(e).__name__},
+        # Shared taxonomy so top-up matches the bearer/X-Cashu paths (503 for an
+        # unreachable mint, 422 for fee/swap failures, 400 for token faults).
+        classified = classify_redemption_error(e)
+        if classified is None:
+            logger.error(
+                "Cashu wallet top-up failed with an unhandled error",
+                extra={
+                    "event": "cashu_topup_failed",
+                    "source_mint": source_mint,
+                    "primary_mint": settings.primary_mint,
+                    "trusted_mints": settings.cashu_mints,
+                    "error_chain": _error_chain(e),
+                },
+            )
+            raise HTTPException(status_code=500, detail="Internal server error")
+        error_type, status_code, message, error_code = classified
+        logger.warning(
+            "Cashu wallet top-up failed",
+            extra={
+                "event": "cashu_topup_failed",
+                "source_mint": source_mint,
+                "primary_mint": settings.primary_mint,
+                "trusted_mints": settings.cashu_mints,
+                "status_code": status_code,
+                "error_type": error_type,
+                "error_code": error_code,
+                "error_chain": _error_chain(e),
+            },
         )
-        raise HTTPException(status_code=500, detail="Internal server error")
+        raise HTTPException(status_code=status_code, detail=message)
+
+    logger.warning(
+        "Cashu wallet top-up completed",
+        extra={
+            "event": "cashu_topup_completed",
+            "source_mint": source_mint,
+            "credited_msats": amount_msats,
+            "key_hash": billing_key.hashed_key[:8],
+        },
+    )
     return {"msats": amount_msats}
 
 
@@ -225,7 +273,11 @@ async def _lookup_key_no_create(
 
 
 async def _restore_balance(
-    session: AsyncSession, hashed_key: str, balance: int, reserved_balance: int, mint_url: str
+    session: AsyncSession,
+    hashed_key: str,
+    balance: int,
+    reserved_balance: int,
+    mint_url: str,
 ) -> None:
     """Restore balance after a failed refund mint attempt."""
     restore_stmt = (
@@ -240,7 +292,11 @@ async def _restore_balance(
     await session.commit()
     logger.info(
         "refund_wallet_endpoint: balance restored after mint failure",
-        extra={"hashed_key": hashed_key, "restored_balance": balance, "mint_url": mint_url},
+        extra={
+            "hashed_key": hashed_key,
+            "restored_balance": balance,
+            "mint_url": mint_url,
+        },
     )
 
 
@@ -274,7 +330,20 @@ async def refund_wallet_endpoint(
         )
         out_tx = out_tx_result.first()
         if out_tx is None:
-            raise HTTPException(status_code=404, detail="Refund not found")
+            # The "in" row exists with a request_id, but the "out" (refund)
+            # row hasn't been written yet — the upstream request is still in
+            # flight and the refund will be minted once it completes. Tell the
+            # client to retry instead of 404ing permanently (race condition
+            # where /v1/wallet/refund is polled before the refund exists).
+            logger.debug(
+                "refund_wallet_endpoint: refund pending (in row exists, out row not yet created)",
+                extra={"request_id": in_tx.request_id},
+            )
+            raise HTTPException(
+                status_code=425,
+                detail="Refund is pending; retry shortly.",
+                headers={"Retry-After": "2"},
+            )
         if out_tx.swept:
             raise HTTPException(status_code=410, detail="Refund has been swept")
 
@@ -381,15 +450,14 @@ async def refund_wallet_endpoint(
             detail="Balance changed concurrently. Please retry the refund.",
         )
 
-    # --- 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.
+    # The balance is locked at zero, so it is safe to create the refund token.
     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:
+        refund_currency = key.refund_currency or "sat"
         if key.refund_address:
             await send_to_lnurl(
                 remaining_balance,
@@ -399,10 +467,10 @@ async def refund_wallet_endpoint(
             )
             result = {"recipient": key.refund_address}
         else:
-            refund_currency = key.refund_currency or "sat"
             token = await send_token(
                 remaining_balance, refund_currency, effective_refund_mint
             )
+            effective_refund_mint = token_mint_url(token, effective_refund_mint)
             result = {"token": token}
 
         if key.refund_currency == "sat":
@@ -423,11 +491,23 @@ async def refund_wallet_endpoint(
 
     except HTTPException:
         # Minting failed — restore the debited balance
-        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved, key.refund_mint_url or "")
+        await _restore_balance(
+            session,
+            key.hashed_key,
+            pre_debit_balance,
+            pre_debit_reserved,
+            key.refund_mint_url or "",
+        )
         raise
     except Exception as e:
         # Minting failed — restore the debited balance
-        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved, key.refund_mint_url or "")
+        await _restore_balance(
+            session,
+            key.hashed_key,
+            pre_debit_balance,
+            pre_debit_reserved,
+            key.refund_mint_url or "",
+        )
         error_msg = str(e)
         logger.error(
             "refund_wallet_endpoint: mint/send failed",
@@ -441,14 +521,10 @@ async def refund_wallet_endpoint(
                 "has_refund_address": bool(key.refund_address),
             },
         )
-        if (
-            "mint" in error_msg.lower()
-            or "connection" in error_msg.lower()
-            or "ConnectError" in str(type(e))
-        ):
-            raise HTTPException(status_code=503, detail=f"Mint service unavailable: {error_msg}")
+        if is_mint_connection_error(e):
+            raise HTTPException(status_code=503, detail="Mint service unavailable")
         else:
-            raise HTTPException(status_code=500, detail=f"Refund failed: {error_msg}")
+            raise HTTPException(status_code=500, detail="Refund failed")
 
     await _refund_cache_set(bearer_value, result)
 
@@ -458,7 +534,7 @@ async def refund_wallet_endpoint(
                 token=result["token"],
                 amount=remaining_balance,
                 unit=key.refund_currency or "sat",
-                mint_url=key.refund_mint_url,
+                mint_url=effective_refund_mint,
                 typ="out",
                 collected=False,
                 source="apikey",
@@ -652,7 +728,6 @@ async def reset_child_key_spent(
     return {"success": True, "message": "Child key balance reset successfully."}
 
 
-
 @router.api_route(
     "/{path:path}",
     methods=["GET", "POST", "PUT", "DELETE"],

routstr/core/db.py

@@ -225,6 +225,9 @@ class LightningInvoice(SQLModel, table=True):  # type: ignore
         default=None, description="Associated API key hash for topup operations"
     )
     purpose: str = Field(description="create or topup")
+    mint_url: str | None = Field(
+        default=None, description="Mint URL where the quote was created (fallback tracking)"
+    )
     created_at: int = Field(
         default_factory=lambda: int(time.time()), description="Unix timestamp"
     )
@@ -287,7 +290,7 @@ async def store_cashu_transaction(
     created_at: int | None = None,
     source: str = "x-cashu",
     api_key_hashed_key: str | None = None,
-) -> None:
+) -> bool:
     try:
         async with create_session() as session:
             tx = CashuTransaction(
@@ -304,11 +307,13 @@ async def store_cashu_transaction(
             )
             session.add(tx)
             await session.commit()
+        return True
     except Exception as e:
         logger.warning(
             f"Failed to store cashu transaction: {e} (type={typ})",
             extra={"error": str(e), "type": typ},
         )
+        return False
 
 
 class UpstreamProviderRow(SQLModel, table=True):  # type: ignore

routstr/core/settings.py

@@ -49,6 +49,18 @@ class Settings(BaseSettings):
     payout_interval_seconds: int = Field(
         default=900, gt=0, env="PAYOUT_INTERVAL_SECONDS"
     )
+    # Timeout (seconds) for individual mint API operations (melt, mint, swap,
+    # checkstate). When a mint is slow or rate-limiting, operations are
+    # cancelled after this delay instead of hanging indefinitely.
+    mint_operation_timeout_seconds: int = Field(
+        default=30, gt=0, env="MINT_OPERATION_TIMEOUT_SECONDS"
+    )
+    # Maximum concurrent API operations per mint. Actual mint quotas vary by
+    # endpoint, so 429 responses drive adaptive cooldown instead of fixed RPM
+    # pacing. 0 = unlimited concurrency.
+    mint_max_concurrency: int = Field(default=4, ge=0, env="MINT_MAX_CONCURRENCY")
+    # Max retries when a mint returns 429 or times out (exponential backoff).
+    mint_retry_max_attempts: int = Field(default=3, ge=0, env="MINT_RETRY_MAX_ATTEMPTS")
 
     # Pricing
     # Default behavior: derive pricing from MODELS
@@ -97,7 +109,9 @@ class Settings(BaseSettings):
     enable_pricing_refresh: bool = Field(default=True, env="ENABLE_PRICING_REFRESH")
     enable_models_refresh: bool = Field(default=True, env="ENABLE_MODELS_REFRESH")
     refund_cache_ttl_seconds: int = Field(default=3600, env="REFUND_CACHE_TTL_SECONDS")
-    refund_sweep_ttl_seconds: int = Field(default=604800, env="REFUND_SWEEP_TTL_SECONDS")
+    refund_sweep_ttl_seconds: int = Field(
+        default=604800, env="REFUND_SWEEP_TTL_SECONDS"
+    )
 
     # Logging
     log_level: str = Field(default="INFO", env="LOG_LEVEL")
@@ -116,9 +130,8 @@ class Settings(BaseSettings):
 
     # Discovery
     relays: list[str] = Field(default_factory=list, env="RELAYS")
-    enable_analytics_sharing: bool = Field(
-        default=True, env="ENABLE_ANALYTICS_SHARING"
-    )
+    enable_analytics_sharing: bool = Field(default=True, env="ENABLE_ANALYTICS_SHARING")
+
 
 def _normalize_settings_data(data: dict[str, Any]) -> dict[str, Any]:
     """Discard unknown keys from persisted settings."""
@@ -281,7 +294,11 @@ class SettingsService:
             valid_fields = set(env_resolved.dict().keys())
             merged_dict: dict[str, Any] = dict(env_resolved.dict())
             merged_dict.update(
-                {k: v for k, v in db_json.items() if v not in (None, "", [], {}) and k in valid_fields}
+                {
+                    k: v
+                    for k, v in db_json.items()
+                    if v not in (None, "", [], {}) and k in valid_fields
+                }
             )
             merged_dict = Settings(**merged_dict).dict()
 

routstr/core/version.py

@@ -20,7 +20,7 @@ import subprocess
 from functools import lru_cache
 from pathlib import Path
 
-BASE_VERSION = "0.4.3"
+BASE_VERSION = "0.4.4"
 
 _REPO_ROOT = Path(__file__).resolve().parents[2]
 _GIT_TIMEOUT_SECONDS = 2.0

routstr/lightning.py

@@ -11,7 +11,14 @@ from sqlmodel.ext.asyncio.session import AsyncSession
 from .core.db import ApiKey, LightningInvoice, create_session, get_session
 from .core.logging import get_logger
 from .core.settings import settings
-from .wallet import get_wallet
+from .wallet import (
+    MintConnectionError,
+    _is_mint_rate_limited,
+    _mint_cooldown_remaining,
+    _mint_operation,
+    get_wallet,
+    is_mint_connection_error,
+)
 
 logger = get_logger(__name__)
 
@@ -64,12 +71,80 @@ class InvoiceRecoverRequest(BaseModel):
     bolt11: str = Field(description="BOLT11 invoice string")
 
 
+def _trusted_mint_candidates() -> list[str]:
+    return [
+        mint
+        for mint in dict.fromkeys([settings.primary_mint, *settings.cashu_mints])
+        if mint
+    ]
+
+
+async def _request_mint_with_fallback(
+    amount_sats: int,
+    *,
+    allowed_mints: list[str] | None = None,
+) -> tuple[str, str, str]:
+    """Request a quote, falling back only among the allowed trusted mints.
+
+    Guards against amount_sats <= 0: the cashu library's PostMintQuoteRequest
+    enforces ``amount > 0`` (Pydantic Field(gt=0)), so passing 0 raises a
+    cryptic validation error deep in the stack.  Fail fast with context.
+    """
+    if amount_sats <= 0:
+        raise ValueError(
+            f"generate_lightning_invoice: amount_sats must be > 0, got {amount_sats}."
+        )
+    tried: list[str] = []
+    configured = allowed_mints or [settings.primary_mint, *settings.cashu_mints]
+    candidates = list(dict.fromkeys(configured))
+    for mint_url in candidates:
+        cooldown = _mint_cooldown_remaining(mint_url)
+        if cooldown > 0:
+            tried.append(f"{mint_url}: cooling down")
+            logger.info(
+                "Skipping rate-limited mint",
+                extra={
+                    "mint_url": mint_url,
+                    "cooldown_seconds": round(cooldown, 2),
+                    "op_name": "request_mint_invoice",
+                },
+            )
+            continue
+        try:
+            wallet = await get_wallet(mint_url, "sat", retry_on_rate_limit=False)
+            quote = await _mint_operation(
+                lambda: wallet.request_mint(amount_sats),
+                op_name="request_mint_invoice",
+                mint_url=mint_url,
+                retry_on_rate_limit=False,
+            )
+            return quote.request, quote.quote, mint_url
+        except Exception as e:
+            tried.append(f"{mint_url}: {type(e).__name__}")
+            if not is_mint_connection_error(e) and not _is_mint_rate_limited(e):
+                raise
+            logger.warning(
+                "request_mint failed, trying fallback mint",
+                extra={
+                    "failed_mint": mint_url,
+                    "error": str(e),
+                    "tried": tried,
+                },
+            )
+            continue
+    raise MintConnectionError(f"All mints failed for request_mint: {tried}")
+
+
 async def generate_lightning_invoice(
-    amount_sats: int, description: str
-) -> tuple[str, str]:
-    wallet = await get_wallet(settings.primary_mint, "sat")
-    quote = await wallet.request_mint(amount_sats)
-    return quote.request, quote.quote
+    amount_sats: int,
+    description: str,
+    *,
+    allowed_mints: list[str] | None = None,
+) -> tuple[str, str, str]:
+    bolt11, payment_hash, mint_url = await _request_mint_with_fallback(
+        amount_sats, allowed_mints=allowed_mints
+    )
+    return bolt11, payment_hash, mint_url
 
 
 def generate_invoice_id() -> str:
@@ -83,6 +158,7 @@ async def create_invoice(
     session: AsyncSession = Depends(get_session),
 ) -> InvoiceCreateResponse:
     api_key_token = _extract_bearer_api_key(authorization) or request.api_key
+    topup_api_key: ApiKey | None = None
 
     if request.purpose == "topup":
         if not api_key_token:
@@ -93,14 +169,21 @@ async def create_invoice(
         if not api_key_token.startswith("sk-"):
             raise HTTPException(status_code=400, detail="Invalid API key format")
 
-        api_key = await session.get(ApiKey, api_key_token[3:])
-        if not api_key:
+        topup_api_key = await session.get(ApiKey, api_key_token[3:])
+        if not topup_api_key:
             raise HTTPException(status_code=404, detail="API key not found")
 
     try:
         description = f"Routstr {request.purpose} {request.amount_sats} sats"
-        bolt11, payment_hash = await generate_lightning_invoice(
-            request.amount_sats, description
+        allowed_mints = None
+        if request.purpose == "topup":
+            assert topup_api_key is not None
+            # Top-ups are not pinned to the key's previous/backing mint. Use any
+            # currently available trusted mint so rate limits/cooldowns on one
+            # mint do not block Lightning top-ups.
+            allowed_mints = _trusted_mint_candidates()
+        bolt11, payment_hash, mint_url = await generate_lightning_invoice(
+            request.amount_sats, description, allowed_mints=allowed_mints
         )
 
         invoice_id = generate_invoice_id()
@@ -115,6 +198,7 @@ async def create_invoice(
             status="pending",
             api_key_hash=api_key_token[3:] if api_key_token else None,
             purpose=request.purpose,
+            mint_url=mint_url,
             balance_limit=request.balance_limit,
             balance_limit_reset=request.balance_limit_reset,
             validity_date=request.validity_date,
@@ -223,9 +307,14 @@ async def check_invoice_payment(
     invoice: LightningInvoice, session: AsyncSession
 ) -> None:
     try:
-        wallet = await get_wallet(settings.primary_mint, "sat")
+        mint_url = invoice.mint_url or settings.primary_mint
+        wallet = await get_wallet(mint_url, "sat")
 
-        mint_status = await wallet.get_mint_quote(invoice.payment_hash)
+        mint_status = await _mint_operation(
+            lambda: wallet.get_mint_quote(invoice.payment_hash),
+            op_name="get_mint_quote",
+            mint_url=mint_url,
+        )
 
         if mint_status.paid:
             invoice.status = "paid"
@@ -258,8 +347,14 @@ async def check_invoice_payment(
 async def create_api_key_from_invoice(
     invoice: LightningInvoice, session: AsyncSession
 ) -> ApiKey:
-    wallet = await get_wallet(settings.primary_mint, "sat")
-    await wallet.mint(invoice.amount_sats, quote_id=invoice.payment_hash)
+    mint_url = invoice.mint_url or settings.primary_mint
+    wallet = await get_wallet(mint_url, "sat")
+    await _mint_operation(
+        lambda: wallet.mint(invoice.amount_sats, quote_id=invoice.payment_hash),
+        op_name="invoice_mint_create",
+        mint_url=mint_url,
+        retry_timeouts=False,
+    )
 
     dummy_token = f"invoice-{invoice.id}-{invoice.payment_hash}"
     hashed_key = hashlib.sha256(dummy_token.encode()).hexdigest()
@@ -268,7 +363,7 @@ async def create_api_key_from_invoice(
         hashed_key=hashed_key,
         balance=invoice.amount_sats * 1000,  # Convert to msats
         refund_currency="sat",
-        refund_mint_url=settings.primary_mint,
+        refund_mint_url=mint_url,
         balance_limit=invoice.balance_limit,
         balance_limit_reset=invoice.balance_limit_reset,
         validity_date=invoice.validity_date,
@@ -283,8 +378,14 @@ async def create_api_key_from_invoice(
 async def topup_api_key_from_invoice(
     invoice: LightningInvoice, session: AsyncSession
 ) -> None:
-    wallet = await get_wallet(settings.primary_mint, "sat")
-    await wallet.mint(invoice.amount_sats, quote_id=invoice.payment_hash)
+    mint_url = invoice.mint_url or settings.primary_mint
+    wallet = await get_wallet(mint_url, "sat")
+    await _mint_operation(
+        lambda: wallet.mint(invoice.amount_sats, quote_id=invoice.payment_hash),
+        op_name="invoice_mint_topup",
+        mint_url=mint_url,
+        retry_timeouts=False,
+    )
 
     if not invoice.api_key_hash:
         raise ValueError("No API key associated with topup invoice")
@@ -297,7 +398,9 @@ async def topup_api_key_from_invoice(
     await session.flush()
 
 
-INVOICE_WATCH_INTERVAL_SECONDS = 5
+# Nutshell mints throttle Lightning backend lookups to once per 10s per
+# quote, so polling faster just burns the global request budget for nothing.
+INVOICE_WATCH_INTERVAL_SECONDS = 10
 INVOICE_WATCH_BATCH_LIMIT = 100
 
 

routstr/payment/cost_calculation.py

@@ -157,11 +157,16 @@ async def calculate_cost(
                 },
             )
         try:
+            cost_details = usage_data.get("cost_details", {})
+            if not isinstance(cost_details, dict):
+                cost_details = {}
             input_usd = _coerce_usd(
-                usage_data.get("cost_details", {}).get("input_cost", 0)
+                cost_details.get("input_cost")
+                or cost_details.get("upstream_inference_prompt_cost")
             )
             output_usd = _coerce_usd(
-                usage_data.get("cost_details", {}).get("output_cost", 0)
+                cost_details.get("output_cost")
+                or cost_details.get("upstream_inference_completions_cost")
             )
             return _calculate_from_usd_cost(
                 usd_cost,
@@ -281,54 +286,92 @@ def _resolve_usd_cost(usage_data: dict, response_data: dict) -> float:
 def _get_pricing_rates(
     response_data: dict,
 ) -> tuple[float, float, float, float] | None:
-    """Get model-based pricing rates or None if using fixed pricing.
+    """Get configured rates, falling back to LiteLLM's model cost map.
 
-    Returns: (input_rate, output_rate, cache_read_rate, cache_write_rate)
+    Returns: (input_rate, output_rate, cache_read_rate, cache_write_rate).
+    ``None`` means configured fixed pricing should be used by the caller.
     """
-    if settings.fixed_pricing:
+    if settings.fixed_pricing and (
+        settings.fixed_per_1k_input_tokens
+        or settings.fixed_per_1k_output_tokens
+    ):
         return None
 
     from ..proxy import get_model_instance
+    from .models import litellm_cost_entry
 
     response_model = response_data.get("model", "")
     model_obj = get_model_instance(response_model)
 
-    if not model_obj:
-        logger.error("Invalid model in response", extra={"response_model": response_model})
-        raise ValueError(f"Invalid model: {response_model}")
+    if model_obj and model_obj.sats_pricing:
+        try:
+            mspp = float(model_obj.sats_pricing.prompt)
+            mspc = float(model_obj.sats_pricing.completion)
+            mscr = float(model_obj.sats_pricing.input_cache_read or 0)
+            mscw = float(model_obj.sats_pricing.input_cache_write or 0)
 
-    if not model_obj.sats_pricing:
-        logger.error(
-            "Model pricing not defined",
-            extra={"model": response_model, "model_id": response_model},
+            mspp_1k = mspp * 1_000_000.0
+            mspc_1k = mspc * 1_000_000.0
+            mscr_1k = mscr * 1_000_000.0 if mscr > 0 else mspp_1k
+            mscw_1k = mscw * 1_000_000.0 if mscw > 0 else mspp_1k
+            source = "configured"
+        except Exception as e:
+            logger.error("Invalid pricing data", extra={"error": str(e)})
+            raise ValueError("Invalid pricing data") from e
+    else:
+        pricing_model = (
+            model_obj.forwarded_model_id if model_obj else None
+        ) or response_model
+        pricing = litellm_cost_entry(pricing_model)
+        if pricing is None:
+            logger.error(
+                "Model pricing not found in configured models or LiteLLM",
+                extra={
+                    "response_model": response_model,
+                    "pricing_model": pricing_model,
+                },
+            )
+            raise ValueError(f"Pricing not found for model: {response_model}")
+
+        input_usd = _coerce_usd(pricing.get("input_cost_per_token"))
+        output_usd = _coerce_usd(pricing.get("output_cost_per_token"))
+        if input_usd <= 0 or output_usd <= 0:
+            raise ValueError(f"Incomplete LiteLLM pricing for model: {pricing_model}")
+
+        provider_fee = _resolve_provider_fee(response_model)
+        usd_per_sat = sats_usd_price()
+        mspp_1k = input_usd * provider_fee * 1_000_000.0 / usd_per_sat
+        mspc_1k = output_usd * provider_fee * 1_000_000.0 / usd_per_sat
+        cache_read_usd = _coerce_usd(
+            pricing.get("cache_read_input_token_cost")
         )
-        raise ValueError("Model pricing not defined")
-
-    try:
-        mspp = float(model_obj.sats_pricing.prompt)
-        mspc = float(model_obj.sats_pricing.completion)
-        mscr = float(model_obj.sats_pricing.input_cache_read or 0)
-        mscw = float(model_obj.sats_pricing.input_cache_write or 0)
-
-        mspp_1k = mspp * 1_000_000.0
-        mspc_1k = mspc * 1_000_000.0
-        mscr_1k = mscr * 1_000_000.0 if mscr > 0 else mspp_1k
-        mscw_1k = mscw * 1_000_000.0 if mscw > 0 else mspp_1k
-
-        logger.info(
-            "Applied model-specific pricing",
-            extra={
-                "model": response_model,
-                "input_price_msats_per_1k": mspp_1k,
-                "output_price_msats_per_1k": mspc_1k,
-                "cache_read_price_msats_per_1k": mscr_1k,
-                "cache_write_price_msats_per_1k": mscw_1k,
-            },
+        cache_write_usd = _coerce_usd(
+            pricing.get("cache_creation_input_token_cost")
         )
-        return mspp_1k, mspc_1k, mscr_1k, mscw_1k
-    except Exception as e:
-        logger.error("Invalid pricing data", extra={"error": str(e)})
-        raise ValueError("Invalid pricing data") from e
+        mscr_1k = (
+            cache_read_usd * provider_fee * 1_000_000.0 / usd_per_sat
+            if cache_read_usd > 0
+            else mspp_1k
+        )
+        mscw_1k = (
+            cache_write_usd * provider_fee * 1_000_000.0 / usd_per_sat
+            if cache_write_usd > 0
+            else mspp_1k
+        )
+        source = "litellm"
+
+    logger.info(
+        "Applied model-specific pricing",
+        extra={
+            "model": response_model,
+            "pricing_source": source,
+            "input_price_msats_per_1k": mspp_1k,
+            "output_price_msats_per_1k": mspc_1k,
+            "cache_read_price_msats_per_1k": mscr_1k,
+            "cache_write_price_msats_per_1k": mscw_1k,
+        },
+    )
+    return mspp_1k, mspc_1k, mscr_1k, mscw_1k
 
 
 def _resolve_provider_fee(model_id: str) -> float:
@@ -367,8 +410,12 @@ def _calculate_from_usd_cost(
     cost_in_msats = math.ceil(cost_in_sats * 1000)
 
     if input_usd > 0 or output_usd > 0:
-        input_msats = int((input_usd * sats_per_usd) * 1000)
-        output_msats = int((output_usd * sats_per_usd) * 1000)
+        # The total is the authoritative billed amount. Allocating that integer
+        # total proportionally avoids losing sub-millisatoshi remainders when
+        # input and output components are each truncated independently.
+        component_usd = input_usd + output_usd
+        input_msats = math.floor(cost_in_msats * input_usd / component_usd)
+        output_msats = cost_in_msats - input_msats
     else:
         effective_input_tokens = (
             input_tokens + cache_read_tokens + cache_creation_tokens

routstr/payment/helpers.py

@@ -18,6 +18,14 @@ from ..wallet import deserialize_token_from_string
 
 logger = get_logger(__name__)
 
+_MINT_FEE_ALLOWANCE = 0.10
+
+
+def apply_mint_fee_allowance(cost_msat: int) -> int:
+    """Reduce the admission reservation to account for mint fallback fees."""
+    adjusted = math.ceil(cost_msat * (1 - _MINT_FEE_ALLOWANCE))
+    return max(settings.min_request_msat, adjusted)
+
 
 def check_token_balance(headers: dict, body: dict, max_cost_for_model: int) -> None:
     if x_cashu := headers.get("x-cashu", None):

routstr/payment/lnurl.py

@@ -1,11 +1,18 @@
 from __future__ import annotations
 
+import asyncio
 import math
 from typing import TypedDict
 
 import httpx
 from cashu.wallet.wallet import Proof, Wallet
 
+# The Cashu library issues POST /v1/melt/bolt11 with timeout=None, so a hung or
+# very slow mint can block a melt (and any caller, e.g. the payout loop)
+# indefinitely. _mint_operation (imported lazily in raw_send_to_lnurl to avoid
+# a circular import with wallet.py) bounds it via MINT_OPERATION_TIMEOUT_SECONDS.
+MELT_TIMEOUT_SECONDS = 60
+
 try:
     from bech32 import bech32_decode, convertbits  # type: ignore
 except ModuleNotFoundError:  # pragma: no cover – allow runtime miss
@@ -215,15 +222,34 @@ async def raw_send_to_lnurl(
         lnurl_data["callback_url"], final_amount
     )
 
-    melt_quote_resp = await wallet.melt_quote(invoice=bolt11_invoice)
+    from ..wallet import _mint_operation
+
+    melt_quote_resp = await _mint_operation(
+        lambda: wallet.melt_quote(invoice=bolt11_invoice),
+        op_name="lnurl_melt_quote",
+        mint_url=str(wallet.url),
+    )
 
     if amount:
         proofs, _ = await wallet.select_to_send(proofs, amount, set_reserved=True)
 
-    _ = await wallet.melt(
-        proofs=proofs,
-        invoice=bolt11_invoice,
-        fee_reserve_sat=melt_quote_resp.fee_reserve,
-        quote_id=melt_quote_resp.quote,
-    )
+    try:
+        _ = await asyncio.wait_for(
+            _mint_operation(
+                lambda: wallet.melt(
+                    proofs=proofs,
+                    invoice=bolt11_invoice,
+                    fee_reserve_sat=melt_quote_resp.fee_reserve,
+                    quote_id=melt_quote_resp.quote,
+                ),
+                op_name="lnurl_melt",
+                mint_url=str(wallet.url),
+                retry_timeouts=False,
+            ),
+            timeout=MELT_TIMEOUT_SECONDS,
+        )
+    except (httpx.TimeoutException, asyncio.TimeoutError) as e:
+        raise LNURLError(
+            f"Melt timed out after {MELT_TIMEOUT_SECONDS}s (mint unresponsive)"
+        ) from e
     return final_amount

routstr/payment/models.py

@@ -85,6 +85,30 @@ class Model(BaseModel):
         return hash(self.id)
 
 
+def litellm_cost_entry(model_id: str) -> dict | None:
+    """Look up ``model_id`` in litellm's bundled cost map.
+
+    litellm ships per-model USD rates keyed by the exact OpenRouter id
+    (``deepseek/deepseek-chat``) or the bare model name (``gpt-4o``,
+    ``claude-sonnet-4-5``), so both spellings are tried. Keys are lowercase, so
+    a mixed-case upstream id (``deepseek-ai/DeepSeek-V4-Flash``) is retried via
+    a case-insensitive scan. Returns the matched cost dict, or ``None``.
+    """
+    import litellm
+
+    candidates = (model_id, model_id.split("/", 1)[-1])
+    for key in candidates:
+        info = litellm.model_cost.get(key)
+        if isinstance(info, dict):
+            return info
+
+    lowered = {c.lower() for c in candidates}
+    for key, info in litellm.model_cost.items():
+        if isinstance(key, str) and key.lower() in lowered and isinstance(info, dict):
+            return info
+    return None
+
+
 def backfill_cache_pricing(model_id: str, pricing: Pricing) -> Pricing:
     """Fill missing cache rates from litellm's bundled cost map.
 
@@ -92,12 +116,8 @@ def backfill_cache_pricing(model_id: str, pricing: Pricing) -> Pricing:
     for many models (most DeepSeek entries, openai/gpt-4o, ...). Without a
     cache rate, billing falls back to the full input rate, which overcharges
     cache reads (DeepSeek hits are 10x cheaper) and undercharges Anthropic
-    cache writes (1.25x). litellm ships per-model USD rates keyed by the exact
-    OpenRouter id (deepseek/deepseek-chat) or by the bare model name
-    (gpt-4o, claude-sonnet-4-5), so both spellings are tried. litellm keys are
-    lowercase, but a generic upstream may report a mixed-case id
-    (``deepseek-ai/DeepSeek-V4-Flash``); an exact match is attempted first, then
-    a case-insensitive fallback so such ids still resolve.
+    cache writes (1.25x). The lookup (see ``litellm_cost_entry``) tries both
+    id spellings and a case-insensitive fallback.
 
     Rates already present (e.g. provided by OpenRouter) are authoritative and
     never overwritten. Unknown models are returned unchanged.
@@ -107,28 +127,7 @@ def backfill_cache_pricing(model_id: str, pricing: Pricing) -> Pricing:
     if not (needs_read or needs_write):
         return pricing
 
-    import litellm
-
-    candidates = (model_id, model_id.split("/", 1)[-1])
-    info: dict | None = None
-    for key in candidates:
-        candidate = litellm.model_cost.get(key)
-        if isinstance(candidate, dict):
-            info = candidate
-            break
-    if info is None:
-        # Case-insensitive fallback: a mixed-case upstream id (e.g.
-        # ``deepseek-ai/DeepSeek-V4-Flash``) won't match litellm's lowercase
-        # keys exactly. Build a lowercased index once and retry.
-        lowered = {c.lower() for c in candidates}
-        for key, candidate in litellm.model_cost.items():
-            if (
-                isinstance(key, str)
-                and key.lower() in lowered
-                and isinstance(candidate, dict)
-            ):
-                info = candidate
-                break
+    info = litellm_cost_entry(model_id)
     if info is None:
         return pricing
 

routstr/proxy.py

@@ -19,8 +19,8 @@ from .core.db import (
 )
 from .core.exceptions import UpstreamError
 from .core.not_found import build_not_found_response
-from .core.settings import settings
 from .payment.helpers import (
+    apply_mint_fee_allowance,
     calculate_discounted_max_cost,
     check_token_balance,
     create_error_response,
@@ -118,22 +118,23 @@ async def refresh_model_maps() -> None:
         result = await session.exec(query)
         provider_rows = result.all()
 
-    overrides_by_id: dict[str, tuple[ModelRow, float]] = {}
-    disabled_model_ids: set[str] = set()
+    overrides_by_key: dict[tuple[str, int], tuple[ModelRow, float]] = {}
+    disabled_model_keys: set[tuple[str, int]] = set()
 
     for provider in provider_rows:
         if not provider.enabled:
             continue
         for model in provider.models:
+            model_key = (model.id.lower(), model.upstream_provider_id)
             if model.enabled:
-                overrides_by_id[model.id] = (model, provider.provider_fee)
+                overrides_by_key[model_key] = (model, provider.provider_fee)
             else:
-                disabled_model_ids.add(model.id)
+                disabled_model_keys.add(model_key)
 
     _model_instances, _provider_map, _unique_models = create_model_mappings(
         upstreams=_upstreams,
-        overrides_by_id=overrides_by_id,
-        disabled_model_ids=disabled_model_ids,
+        overrides_by_key=overrides_by_key,
+        disabled_model_keys=disabled_model_keys,
     )
 
 
@@ -249,8 +250,7 @@ async def proxy(
     max_cost_for_model = await calculate_discounted_max_cost(
         _max_cost_for_model, request_body_dict, model_obj=model_obj
     )
-    # Ensure max_cost_for_model is at least the minimum allowed request cost
-    max_cost_for_model = max(max_cost_for_model, settings.min_request_msat)
+    max_cost_for_model = apply_mint_fee_allowance(max_cost_for_model)
 
     check_token_balance(headers, request_body_dict, max_cost_for_model)
 
@@ -605,17 +605,29 @@ async def get_bearer_token_key(
             },
         )
         return key
-    except Exception as e:
-        key_preview = bearer_key[:20] + "..." if len(bearer_key) > 20 else bearer_key
-        logger.error(
-            f"Bearer token validation failed: {type(e).__name__}: {e} path={path} model={model_id!r} min_cost={min_cost} key={key_preview!r}",
+    except HTTPException as error:
+        detail: dict[str, Any] = error.detail if isinstance(error.detail, dict) else {}
+        raw_error = detail.get("error")
+        error_info = raw_error if isinstance(raw_error, dict) else {}
+        logger.warning(
+            "Bearer token rejected",
             extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
+                "status_code": error.status_code,
+                "error_code": error_info.get("code"),
                 "path": path,
                 "model_id": model_id,
-                "min_cost_msat": min_cost,
-                "bearer_key_preview": key_preview,
+                "required_msat": min_cost,
+            },
+        )
+        raise
+    except Exception as error:
+        logger.exception(
+            "Bearer token validation failed",
+            extra={
+                "error_type": type(error).__name__,
+                "path": path,
+                "model_id": model_id,
+                "required_msat": min_cost,
             },
         )
         raise

routstr/upstream/auto_topup.py

@@ -4,8 +4,13 @@ import json
 from sqlmodel import select
 
 from ..core import get_logger
-from ..core.db import UpstreamProviderRow, create_session
-from ..wallet import send_token
+from ..core.db import (
+    CashuTransaction,
+    UpstreamProviderRow,
+    create_session,
+    store_cashu_transaction,
+)
+from ..wallet import release_token_reservation, send_token, token_mint_url
 from .routstr import RoutstrUpstreamProvider
 
 logger = get_logger(__name__)
@@ -123,7 +128,6 @@ async def _check_and_topup(row: UpstreamProviderRow) -> None:
         },
     )
 
-    print(amount, mint_url)
     try:
         token = await send_token(amount, "sat", mint_url)
     except Exception as e:
@@ -138,6 +142,35 @@ async def _check_and_topup(row: UpstreamProviderRow) -> None:
         )
         return
 
+    actual_mint_url = token_mint_url(token, mint_url)
+    stored = await store_cashu_transaction(
+        token=token,
+        amount=amount,
+        unit="sat",
+        mint_url=actual_mint_url,
+        typ="out",
+        collected=False,
+        source="auto_topup",
+    )
+    if not stored:
+        try:
+            await release_token_reservation(token)
+        except Exception as error:
+            logger.critical(
+                "Failed to release untracked auto-topup token",
+                extra={
+                    "provider_id": row.id,
+                    "mint_url": actual_mint_url,
+                    "error": str(error),
+                },
+            )
+        else:
+            logger.warning(
+                "Auto-topup token was released after persistence failed",
+                extra={"provider_id": row.id, "mint_url": actual_mint_url},
+            )
+        return
+
     result = await provider.topup(token)
 
     if "error" in result:
@@ -149,6 +182,26 @@ async def _check_and_topup(row: UpstreamProviderRow) -> None:
             },
         )
     else:
+        async with create_session() as session:
+            transaction = (
+                await session.exec(
+                    select(CashuTransaction).where(
+                        CashuTransaction.token == token,
+                        CashuTransaction.type == "out",
+                        CashuTransaction.source == "auto_topup",
+                    )
+                )
+            ).first()
+            if transaction is None:
+                logger.critical(
+                    "Completed auto top-up transaction is missing from the database",
+                    extra={"provider_id": row.id, "mint_url": mint_url},
+                )
+            else:
+                transaction.collected = True
+                session.add(transaction)
+                await session.commit()
+
         logger.info(
             "Auto top-up completed successfully",
             extra={

routstr/upstream/base.py

@@ -40,7 +40,13 @@ from ..payment.models import (
     list_models,
 )
 from ..payment.price import sats_usd_price
-from ..wallet import recieve_token, send_token
+from ..wallet import (
+    SPENT_TOKEN_CODES,
+    classify_redemption_error,
+    recieve_token,
+    send_token,
+    token_mint_url,
+)
 from . import messages_dispatch
 from .cache_breakpoints import (
     inject_anthropic_cache_breakpoints,
@@ -3285,7 +3291,7 @@ class BaseUpstreamProvider:
                         token=refund_token,
                         amount=amount,
                         unit=unit,
-                        mint_url=mint,
+                        mint_url=token_mint_url(refund_token, mint),
                         typ="out",
                         request_id=request_id,
                     )
@@ -3640,7 +3646,7 @@ class BaseUpstreamProvider:
                     token=refund_token,
                     amount=emergency_refund,
                     unit=unit,
-                    mint_url=mint,
+                    mint_url=token_mint_url(refund_token, mint),
                     typ="out",
                     request_id=request_id,
                 )
@@ -3981,9 +3987,19 @@ class BaseUpstreamProvider:
             },
         )
 
+        redeemed = False
         try:
             headers = dict(request.headers)
             amount, unit, mint = await recieve_token(x_cashu_token)
+            # Reject a zero/negative redemption (empty/dust token, or a value
+            # fully consumed by fees) before marking the token redeemed, so it
+            # classifies as cashu_token_zero_value like the bearer/top-up paths
+            # rather than being forwarded as a free request.
+            if amount <= 0:
+                raise ValueError(
+                    f"Redeemed token amount must be positive, got {amount} {unit}"
+                )
+            redeemed = True
             headers = self.prepare_headers(dict(request.headers))
 
             request_id = getattr(request.state, "request_id", None)
@@ -4027,40 +4043,37 @@ class BaseUpstreamProvider:
                 },
             )
 
-            # Use same error handling as regular X-Cashu
-            if "already spent" in error_message.lower():
+            # Post-redemption the token is spent; a forwarding failure must not
+            # be reported as a retryable redemption error (see handle_x_cashu).
+            if redeemed:
                 return create_error_response(
-                    "token_already_spent",
-                    "The provided CASHU token has already been spent",
-                    400,
+                    "upstream_error",
+                    "Payment succeeded but the upstream request failed",
+                    502,
                     request=request,
-                    token=x_cashu_token,
+                    code="upstream_request_failed",
                 )
 
-            if "invalid token" in error_message.lower():
+            classified = classify_redemption_error(e)
+            if classified is None:
                 return create_error_response(
-                    "invalid_token",
-                    "The provided CASHU token is invalid",
-                    400,
+                    "api_error",
+                    "Internal error during token redemption",
+                    500,
                     request=request,
-                    token=x_cashu_token,
+                    code="internal_error",
                 )
-
-            if "mint error" in error_message.lower():
-                return create_error_response(
-                    "mint_error",
-                    f"CASHU mint error: {error_message}",
-                    422,
-                    request=request,
-                    token=x_cashu_token,
-                )
-
+            error_type, status_code, message, error_code = classified
+            # Echo the token back only when it is still spendable, so clients
+            # can recover it; a spent/consumed token is never re-offered.
+            echo_token = None if error_code in SPENT_TOKEN_CODES else x_cashu_token
             return create_error_response(
-                "cashu_error",
-                f"CASHU token processing failed: {error_message}",
-                400,
+                error_type,
+                message,
+                status_code,
                 request=request,
-                token=x_cashu_token,
+                token=echo_token,
+                code=error_code,
             )
 
     async def forward_x_cashu_responses_request(
@@ -4597,7 +4610,7 @@ class BaseUpstreamProvider:
                     token=refund_token,
                     amount=emergency_refund,
                     unit=unit,
-                    mint_url=mint,
+                    mint_url=token_mint_url(refund_token, mint),
                     typ="out",
                     request_id=request_id,
                 )
@@ -4650,9 +4663,19 @@ class BaseUpstreamProvider:
             },
         )
 
+        redeemed = False
         try:
             headers = dict(request.headers)
             amount, unit, mint = await recieve_token(x_cashu_token)
+            # Reject a zero/negative redemption (empty/dust token, or a value
+            # fully consumed by fees) before marking the token redeemed, so it
+            # classifies as cashu_token_zero_value like the bearer/top-up paths
+            # rather than being forwarded as a free request.
+            if amount <= 0:
+                raise ValueError(
+                    f"Redeemed token amount must be positive, got {amount} {unit}"
+                )
+            redeemed = True
             headers = self.prepare_headers(dict(request.headers))
 
             request_id = getattr(request.state, "request_id", None)
@@ -4696,39 +4719,38 @@ class BaseUpstreamProvider:
                 },
             )
 
-            if "already spent" in error_message.lower():
+            # Once redeemed the token is spent, so a later forwarding failure
+            # must not surface as a retryable mint_unreachable (spent-token retry
+            # bait). Redemption classification only applies while not redeemed.
+            if redeemed:
                 return create_error_response(
-                    "token_already_spent",
-                    "The provided CASHU token has already been spent",
-                    400,
+                    "upstream_error",
+                    "Payment succeeded but the upstream request failed",
+                    502,
                     request=request,
-                    token=x_cashu_token,
+                    code="upstream_request_failed",
                 )
 
-            if "invalid token" in error_message.lower():
+            classified = classify_redemption_error(e)
+            if classified is None:
                 return create_error_response(
-                    "invalid_token",
-                    "The provided CASHU token is invalid",
-                    400,
+                    "api_error",
+                    "Internal error during token redemption",
+                    500,
                     request=request,
-                    token=x_cashu_token,
+                    code="internal_error",
                 )
-
-            if "mint error" in error_message.lower():
-                return create_error_response(
-                    "mint_error",
-                    f"CASHU mint error: {error_message}",
-                    422,
-                    request=request,
-                    token=x_cashu_token,
-                )
-
+            error_type, status_code, message, error_code = classified
+            # Echo the token back only when it is still spendable, so clients
+            # can recover it; a spent/consumed token is never re-offered.
+            echo_token = None if error_code in SPENT_TOKEN_CODES else x_cashu_token
             return create_error_response(
-                "cashu_error",
-                f"CASHU token processing failed: {error_message}",
-                400,
+                error_type,
+                message,
+                status_code,
                 request=request,
-                token=x_cashu_token,
+                token=echo_token,
+                code=error_code,
             )
 
     def _apply_provider_fee_to_model(self, model: Model) -> Model:

routstr/upstream/generic.py

@@ -5,6 +5,12 @@ from typing import TYPE_CHECKING
 import httpx
 
 from .base import BaseUpstreamProvider
+from .pricing_resolver import (
+    FallbackPricingResolver,
+    ResolvedPricing,
+    _as_float,
+    estimate_context_length,
+)
 
 if TYPE_CHECKING:
     from ..core.db import UpstreamProviderRow
@@ -64,6 +70,40 @@ class GenericUpstreamProvider(BaseUpstreamProvider):
             "platform_url": cls.platform_url,
         }
 
+    def _native_pricing(
+        self, model_id: str, model_spec: dict
+    ) -> ResolvedPricing | None:
+        """Read pricing/metadata from Venice's bespoke ``model_spec`` schema.
+
+        Returns ``None`` when the upstream reported no *usable* native price —
+        absent, non-numeric, negative, or both-zero — so the caller falls
+        through to the shared resolution chain instead of fabricating a number
+        or trusting a bogus one. This mirrors the money-safety guards the
+        litellm and OpenRouter rungs already apply: a both-zero price would
+        serve the model free, a negative one would credit the caller, and a
+        non-numeric string would otherwise throw and drop the whole catalog.
+        """
+        pricing_info = model_spec.get("pricing", {})
+        input_usd = _as_float(pricing_info.get("input", {}).get("usd"))
+        output_usd = _as_float(pricing_info.get("output", {}).get("usd"))
+        if input_usd is None or output_usd is None:
+            return None
+        if input_usd < 0 or output_usd < 0 or (input_usd == 0 and output_usd == 0):
+            return None
+
+        capabilities = model_spec.get("capabilities", {})
+        input_modalities = ["text"]
+        if capabilities.get("supportsVision", False):
+            input_modalities.append("image")
+
+        return ResolvedPricing(
+            prompt=input_usd / 1_000_000,
+            completion=output_usd / 1_000_000,
+            context_length=model_spec.get("availableContextTokens"),
+            source="native",
+            input_modalities=input_modalities,
+        )
+
     async def fetch_models(self) -> list[Model]:
         """Fetch models from upstream API using /models endpoint."""
         from ..payment.models import Architecture, Model, Pricing, TopProvider
@@ -78,6 +118,7 @@ class GenericUpstreamProvider(BaseUpstreamProvider):
                 response.raise_for_status()
                 data = response.json()
 
+                resolver = FallbackPricingResolver()
                 models_list = []
                 for model_data in data.get("data", []):
                     model_id = model_data.get("id", "")
@@ -89,41 +130,44 @@ class GenericUpstreamProvider(BaseUpstreamProvider):
                     owned_by = model_data.get("owned_by", "unknown")
                     model_spec = model_data.get("model_spec", {})
 
-                    context_length = 4096
-                    if model_spec.get("availableContextTokens"):
-                        context_length = model_spec["availableContextTokens"]
-                    elif any(
-                        pattern in model_id.lower() for pattern in ["32k", "32000"]
-                    ):
-                        context_length = 32768
-                    elif any(
-                        pattern in model_id.lower() for pattern in ["16k", "16000"]
-                    ):
-                        context_length = 16384
-                    elif any(pattern in model_id.lower() for pattern in ["8k", "8000"]):
-                        context_length = 8192
-                    elif "gpt-4" in model_id.lower():
-                        context_length = 8192
-                    elif "claude" in model_id.lower():
-                        context_length = 200000
+                    resolved = self._native_pricing(model_id, model_spec)
+                    if resolved is None:
+                        resolved = await resolver.resolve(model_id)
 
-                    pricing_info = model_spec.get("pricing", {})
-                    input_pricing = pricing_info.get("input", {})
-                    output_pricing = pricing_info.get("output", {})
+                    if resolved is None:
+                        # Fail closed: never invent a price. Import the model
+                        # disabled with a warning so the operator can price it
+                        # (the admin UI surfaces disabled remote models).
+                        logger.warning(
+                            f"No pricing source resolved for '{model_id}' from "
+                            f"{self.upstream_name}; importing it disabled",
+                            extra={"model_id": model_id, "base_url": self.base_url},
+                        )
+                        resolved = ResolvedPricing(
+                            prompt=0.0,
+                            completion=0.0,
+                            context_length=None,
+                            source="unresolved",
+                        )
+                        enabled = False
+                    else:
+                        enabled = True
 
-                    prompt_price = input_pricing.get("usd", 0.001) / 1000000
-                    completion_price = output_pricing.get("usd", 0.001) / 1000000
+                    # Prefer the source's own modality string (OpenRouter ships
+                    # one, e.g. "text+image->text"); otherwise derive it from the
+                    # captured input/output modalities in the same "in->out" shape
+                    # rather than flattening vision models to "text->text".
+                    modality = resolved.modality or (
+                        f"{'+'.join(resolved.input_modalities)}"
+                        f"->{'+'.join(resolved.output_modalities)}"
+                    )
 
-                    capabilities = model_spec.get("capabilities", {})
-                    input_modalities = ["text"]
-                    output_modalities = ["text"]
-
-                    if capabilities.get("supportsVision", False):
-                        input_modalities.append("image")
-
-                    modality = "text"
-                    if capabilities.get("supportsVision", False):
-                        modality = "text->text"
+                    # A source can carry a price but no context (e.g. a litellm
+                    # entry missing max_input_tokens); fall back to an id-based
+                    # estimate so we never persist a zero-length window.
+                    context_length = resolved.context_length or estimate_context_length(
+                        model_id
+                    )
 
                     spec_name = model_spec.get("name", model_name)
                     description = f"{spec_name}"
@@ -139,30 +183,33 @@ class GenericUpstreamProvider(BaseUpstreamProvider):
                             context_length=context_length,
                             architecture=Architecture(
                                 modality=modality,
-                                input_modalities=input_modalities,
-                                output_modalities=output_modalities,
-                                tokenizer="unknown",
-                                instruct_type=None,
+                                input_modalities=resolved.input_modalities,
+                                output_modalities=resolved.output_modalities,
+                                tokenizer=resolved.tokenizer,
+                                instruct_type=resolved.instruct_type,
                             ),
                             pricing=Pricing(
-                                prompt=prompt_price,
-                                completion=completion_price,
+                                prompt=resolved.prompt,
+                                completion=resolved.completion,
                                 request=0.0,
                                 image=0.0,
                                 web_search=0.0,
                                 internal_reasoning=0.0,
-                                max_prompt_cost=0.001,
-                                max_completion_cost=0.001,
-                                max_cost=0.001,
+                                input_cache_read=resolved.input_cache_read,
+                                input_cache_write=resolved.input_cache_write,
                             ),
                             sats_pricing=None,
                             per_request_limits=None,
                             top_provider=TopProvider(
                                 context_length=context_length,
-                                max_completion_tokens=context_length // 2,
-                                is_moderated=False,
+                                max_completion_tokens=(
+                                    resolved.max_completion_tokens
+                                    if resolved.max_completion_tokens is not None
+                                    else context_length // 2
+                                ),
+                                is_moderated=bool(resolved.is_moderated),
                             ),
-                            enabled=True,
+                            enabled=enabled,
                             upstream_provider_id=None,
                             canonical_slug=None,
                         )

routstr/upstream/helpers.py

@@ -94,12 +94,10 @@ async def get_all_models_with_overrides(
         provider_result = await session.exec(select(UpstreamProviderRow))
         providers_by_id = {p.id: p for p in provider_result.all()}
 
-        overrides_by_id: dict[str, tuple[ModelRow, float]] = {
-            row.id: (
+        overrides_by_key: dict[tuple[str, int], tuple[ModelRow, float]] = {
+            (row.id.lower(), row.upstream_provider_id): (
                 row,
-                providers_by_id[row.upstream_provider_id].provider_fee
-                if row.upstream_provider_id in providers_by_id
-                else 1.01,
+                providers_by_id[row.upstream_provider_id].provider_fee,
             )
             for row in override_rows
             if row.upstream_provider_id is not None
@@ -107,17 +105,28 @@ async def get_all_models_with_overrides(
             and providers_by_id[row.upstream_provider_id].enabled
         }
 
-    all_models: dict[str, Model] = {}
+    all_models: dict[tuple[str, str], Model] = {}
 
     for upstream in upstreams:
+        upstream_db_id = getattr(upstream, "db_id", None)
+        provider_key = (
+            f"db:{upstream_db_id}"
+            if isinstance(upstream_db_id, int)
+            else f"{getattr(upstream, 'provider_type', '')}|{getattr(upstream, 'base_url', '')}"
+        )
         for model in upstream.get_cached_models():
-            if model.id in overrides_by_id:
-                override_row, provider_fee = overrides_by_id[model.id]
-                all_models[model.id] = _row_to_model(
+            model_key = (
+                (model.id.lower(), upstream_db_id)
+                if isinstance(upstream_db_id, int)
+                else None
+            )
+            if model_key is not None and model_key in overrides_by_key:
+                override_row, provider_fee = overrides_by_key[model_key]
+                all_models[(model.id.lower(), provider_key)] = _row_to_model(
                     override_row, apply_provider_fee=True, provider_fee=provider_fee
                 )
             elif model.enabled:
-                all_models[model.id] = model
+                all_models[(model.id.lower(), provider_key)] = model
 
     return list(all_models.values())
 

routstr/upstream/openrouter.py

@@ -1,4 +1,3 @@
-import json
 from typing import TYPE_CHECKING
 
 import httpx
@@ -19,38 +18,6 @@ class OpenRouterUpstreamProvider(BaseUpstreamProvider):
     supports_anthropic_messages = True
     litellm_provider_prefix = "openrouter/"
 
-    def prepare_request_body(
-        self, body: bytes | None, model_obj: Model
-    ) -> bytes | None:
-        """Set provider.require_parameters on tool-use requests.
-
-        Without it OpenRouter can route a tool call to an endpoint that doesn't
-        support function calling and 404 with "No endpoints found that support
-        tool use". We leave a client-supplied value untouched.
-        """
-        body = super().prepare_request_body(body, model_obj)
-        if not body:
-            return body
-
-        try:
-            data = json.loads(body)
-        except json.JSONDecodeError:
-            return body
-
-        if not isinstance(data, dict) or not data.get("tools"):
-            return body
-
-        provider = data.get("provider")
-        if not isinstance(provider, dict):
-            provider = {}
-
-        if "require_parameters" in provider:
-            return body
-
-        provider["require_parameters"] = True
-        data["provider"] = provider
-        return json.dumps(data).encode()
-
     def _apply_provider_field(self, response_json: object) -> None:
         """Stamp the ``provider`` field for OpenRouter responses.
 

routstr/upstream/pricing_resolver.py

@@ -0,0 +1,203 @@
+"""Shared price/metadata resolution chain for upstream model discovery.
+
+Most OpenAI-compatible ``/models`` responses carry no pricing. Rather than let
+a provider fabricate one, this module resolves a model through decreasingly
+trustworthy sources — litellm's bundled cost map (curated list prices, mirrors
+provider docs), then the OpenRouter feed (resale prices, broader coverage) —
+and returns ``None`` when none of them know the model, so the caller can fail
+closed instead of inventing a number.
+
+Provider-native pricing (a gateway's own ``/models`` schema, e.g. Venice's
+``model_spec``) is authoritative and handled by the provider before this chain
+is consulted; only the shared fallback lives here so a later refactor can hoist
+it into the base provider unchanged.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ResolvedPricing:
+    """Per-token pricing plus whatever metadata the answering source carried.
+
+    Prices are USD per token. ``source`` records provenance
+    (``native``/``litellm``/``openrouter``/``unresolved``) so later work can
+    surface where each price came from.
+    """
+
+    prompt: float
+    completion: float
+    context_length: int | None
+    source: str
+    modality: str | None = None
+    max_completion_tokens: int | None = None
+    input_cache_read: float = 0.0
+    input_cache_write: float = 0.0
+    input_modalities: list[str] = field(default_factory=lambda: ["text"])
+    output_modalities: list[str] = field(default_factory=lambda: ["text"])
+    tokenizer: str = "unknown"
+    instruct_type: str | None = None
+    is_moderated: bool | None = None
+
+
+def estimate_context_length(model_id: str) -> int:
+    """Best-effort context window from a model id when no source reports one.
+
+    The last rung of the fallback chain, reached only for a model whose price
+    resolved but whose context did not (or that imported disabled). Context is
+    not a billing input, so a rough id-based guess is acceptable here where a
+    guessed *price* never would be.
+    """
+    lowered = model_id.lower()
+    if any(pattern in lowered for pattern in ["32k", "32000"]):
+        return 32768
+    if any(pattern in lowered for pattern in ["16k", "16000"]):
+        return 16384
+    if any(pattern in lowered for pattern in ["8k", "8000"]):
+        return 8192
+    if "gpt-4" in lowered:
+        return 8192
+    if "claude" in lowered:
+        return 200000
+    return 4096
+
+
+def _as_float(value: object) -> float | None:
+    """OpenRouter reports prices as strings; coerce, ``None`` if unparseable."""
+    try:
+        return float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_int(value: object) -> int | None:
+    """Coerce an already-numeric token count to ``int``, else ``None``."""
+    return int(value) if isinstance(value, (int, float)) else None
+
+
+def _from_litellm(model_id: str) -> ResolvedPricing | None:
+    # Lazy import so the resolver stays import-light and shares the exact
+    # lookup semantics used by cache-rate backfill.
+    from ..payment.models import litellm_cost_entry
+
+    info = litellm_cost_entry(model_id)
+    if info is None:
+        return None
+
+    prompt = info.get("input_cost_per_token")
+    completion = info.get("output_cost_per_token")
+    if not isinstance(prompt, (int, float)) or not isinstance(completion, (int, float)):
+        return None
+    # A both-zero entry is litellm listing a model without a real price (free
+    # moderation/rerank tiers do this) — treating 0/0 as resolved would serve
+    # the model for free. Reject it (and any negative) so the caller falls
+    # through, mirroring async_fetch_openrouter_models' _has_valid_pricing.
+    if prompt < 0 or completion < 0 or (prompt == 0 and completion == 0):
+        return None
+
+    input_modalities = ["text"]
+    if info.get("supports_vision"):
+        input_modalities.append("image")
+
+    return ResolvedPricing(
+        prompt=float(prompt),
+        completion=float(completion),
+        # max_input_tokens is the context window; max_tokens is litellm's
+        # completion cap (it tracks max_output_tokens for ~94% of models), so
+        # it is never a context source. A missing window falls to the id-based
+        # estimate downstream rather than borrowing the output cap.
+        context_length=_as_int(info.get("max_input_tokens")),
+        source="litellm",
+        max_completion_tokens=_as_int(info.get("max_output_tokens")),
+        input_cache_read=float(info.get("cache_read_input_token_cost") or 0.0),
+        input_cache_write=float(info.get("cache_creation_input_token_cost") or 0.0),
+        input_modalities=input_modalities,
+    )
+
+
+def _match_openrouter(model_id: str, feed: list[dict]) -> dict | None:
+    """Find ``model_id`` in the OpenRouter feed, exact id before bare tail.
+
+    Bare-tail matching (``deepseek-chat`` ↔ ``deepseek/deepseek-chat``) is a
+    looser, lower-trust match — OpenRouter fans a model out across resellers —
+    so an exact id match always wins first. When several entries share the bare
+    tail, the one with the highest *combined* (prompt + completion) per-token
+    cost wins: the choice must be deterministic (not feed-order-dependent) and
+    money-safe whichever way traffic leans, since undercharging is the hazard.
+    Ranking on prompt alone could pick an entry that is cheap on input but dear
+    on output. The live feed has no such collisions today; this only governs
+    the latent case.
+    """
+    bare = model_id.split("/", 1)[-1]
+    exact = next((m for m in feed if m.get("id") == model_id), None)
+    if exact is not None:
+        return exact
+    matches = [m for m in feed if m.get("id", "").split("/", 1)[-1] == bare]
+    if not matches:
+        return None
+
+    def _combined_cost(m: dict) -> float:
+        pricing = m.get("pricing", {})
+        return (_as_float(pricing.get("prompt")) or 0.0) + (
+            _as_float(pricing.get("completion")) or 0.0
+        )
+
+    return max(matches, key=_combined_cost)
+
+
+def _from_openrouter(model_id: str, feed: list[dict]) -> ResolvedPricing | None:
+    entry = _match_openrouter(model_id, feed)
+    if entry is None:
+        return None
+
+    pricing = entry.get("pricing", {})
+    prompt = _as_float(pricing.get("prompt"))
+    completion = _as_float(pricing.get("completion"))
+    if prompt is None or completion is None:
+        return None
+
+    architecture = entry.get("architecture", {})
+    top_provider = entry.get("top_provider", {})
+
+    return ResolvedPricing(
+        prompt=prompt,
+        completion=completion,
+        context_length=_as_int(entry.get("context_length")),
+        source="openrouter",
+        modality=architecture.get("modality"),
+        max_completion_tokens=_as_int(top_provider.get("max_completion_tokens")),
+        input_cache_read=_as_float(pricing.get("input_cache_read")) or 0.0,
+        input_cache_write=_as_float(pricing.get("input_cache_write")) or 0.0,
+        input_modalities=architecture.get("input_modalities") or ["text"],
+        output_modalities=architecture.get("output_modalities") or ["text"],
+        tokenizer=architecture.get("tokenizer") or "unknown",
+        instruct_type=architecture.get("instruct_type"),
+        is_moderated=top_provider.get("is_moderated"),
+    )
+
+
+class FallbackPricingResolver:
+    """Resolves models via litellm → OpenRouter for one discovery pass.
+
+    The OpenRouter catalog is fetched at most once and only when a model
+    actually misses litellm, so a provider full of litellm-known models never
+    touches the network. Instantiate one per ``fetch_models`` call.
+    """
+
+    def __init__(self) -> None:
+        self._openrouter_feed: list[dict] | None = None
+
+    async def resolve(self, model_id: str) -> ResolvedPricing | None:
+        """Resolve ``model_id``; ``None`` if no source knows it."""
+        resolved = _from_litellm(model_id)
+        if resolved is not None:
+            return resolved
+
+        if self._openrouter_feed is None:
+            # Lazy import so tests can patch the feed at its source.
+            from ..payment.models import async_fetch_openrouter_models
+
+            self._openrouter_feed = await async_fetch_openrouter_models()
+        return _from_openrouter(model_id, self._openrouter_feed)

tests/integration/test_insufficient_balance.py

@@ -207,8 +207,30 @@ async def test_pay_for_request_succeeds_when_balance_equals_cost(
     assert key.balance == model_cost   # balance unchanged, only reserved goes up
 
 
+@pytest.mark.asyncio
+async def test_ten_percent_mint_fee_shortfall_is_admitted_and_reserved(
+    integration_session: AsyncSession,
+) -> None:
+    from routstr.auth import pay_for_request, validate_bearer_key
+    from routstr.payment.helpers import apply_mint_fee_allowance
+
+    key = _key(balance=90_000)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    admission_cost = apply_mint_fee_allowance(100_000)
+    validated = await validate_bearer_key(
+        f"sk-{key.hashed_key}", integration_session, min_cost=admission_cost
+    )
+    await pay_for_request(validated, admission_cost, integration_session)
+
+    await integration_session.refresh(key)
+    assert admission_cost == 90_000
+    assert key.reserved_balance == 90_000
+
+
 # ---------------------------------------------------------------------------
-# Test 6 — HTTP layer returns 402 JSON with the right shape
+# HTTP layer returns 402 JSON with the right shape
 # ---------------------------------------------------------------------------
 
 @pytest.mark.asyncio
@@ -264,8 +286,8 @@ async def test_http_402_response_shape_on_insufficient_balance(
     error = body["detail"]["error"]
     assert error["code"] == "insufficient_balance"
     assert error["type"] == "insufficient_quota"
-    assert str(model_cost) in error["message"]
-    assert str(user_balance) in error["message"]
+    assert "560.6 sats (560600 msats) required" in error["message"]
+    assert "20.32 sats (20320 msats) available" in error["message"]
 
     # Balance must be completely untouched
     await integration_session.refresh(key)

tests/integration/test_lightning_invoice_rip08.py

@@ -16,6 +16,7 @@ from httpx import AsyncClient
 from sqlmodel.ext.asyncio.session import AsyncSession
 
 from routstr.core.db import ApiKey
+from routstr.core.settings import settings
 
 RIP08_PATH = "/lightning/invoice"
 LEGACY_PATH = "/v1/balance/lightning/invoice"
@@ -26,11 +27,17 @@ async def patch_invoice_generation() -> Any:
     """Stub out `generate_lightning_invoice` so no mint round-trip is needed."""
     counter = {"n": 0}
 
-    async def fake_generate(amount_sats: int, description: str) -> tuple[str, str]:
+    async def fake_generate(
+        amount_sats: int,
+        description: str,
+        *,
+        allowed_mints: list[str] | None = None,
+    ) -> tuple[str, str, str]:
         counter["n"] += 1
         return (
             f"lnbc{amount_sats}n1pfakeinvoice{counter['n']}",
             f"payment_hash_{counter['n']}",
+            "http://localhost:3338",
         )
 
     with patch(
@@ -95,6 +102,10 @@ async def test_topup_with_authorization_header(
     body = resp.json()
     assert body["amount_sats"] == 500
     assert body["bolt11"].startswith("lnbc")
+    expected_mints = [settings.primary_mint, *settings.cashu_mints]
+    allowed_mints = patch_invoice_generation.call_args.kwargs["allowed_mints"]
+    assert allowed_mints == list(dict.fromkeys(mint for mint in expected_mints if mint))
+    assert allowed_mints[0] == settings.primary_mint
 
 
 @pytest.mark.integration

tests/integration/test_swap_fee_retry.py

@@ -89,7 +89,12 @@ def _make_swap_mocks(
 def _wallet_router(primary_wallet: Mock, token_wallet: Mock) -> Callable[..., Mock]:
     """Route get_wallet calls to the primary or foreign wallet mock by URL."""
 
-    def fake_get_wallet(mint_url: str, unit: str = "sat", load: bool = True) -> Mock:
+    def fake_get_wallet(
+        mint_url: str,
+        unit: str = "sat",
+        load: bool = True,
+        **kwargs: object,
+    ) -> Mock:
         return primary_wallet if mint_url == PRIMARY_MINT else token_wallet
 
     return fake_get_wallet
@@ -174,12 +179,12 @@ async def test_topup_retries_when_quote_fee_exceeds_estimate(
 
 @pytest.mark.integration
 @pytest.mark.asyncio
-async def test_topup_returns_400_when_retries_exhausted(
+async def test_topup_returns_422_when_retries_exhausted(
     authenticated_client: AsyncClient,
 ) -> None:
     """A mint that escalates fee_reserve on every re-quote (1 → 10 → 25 → 50)
-    exhausts the retry budget: clean 400 with an actionable message, melt never
-    executed."""
+    exhausts the retry budget: clean 422 mint_error/too-small taxonomy, melt
+    never executed."""
     mock_token, token_wallet, primary_wallet = _make_swap_mocks(
         1000, fee_reserves=[1, 10, 25, 50]
     )
@@ -188,7 +193,7 @@ async def test_topup_returns_400_when_retries_exhausted(
         authenticated_client, mock_token, token_wallet, primary_wallet
     )
 
-    assert response.status_code == 400
+    assert response.status_code == 422
     assert "too small to cover swap fees" in response.json()["detail"]
     assert token_wallet.melt_quote.call_count == 4  # estimation + 3 attempts
     token_wallet.melt.assert_not_called()

tests/integration/test_wallet_authentication.py

@@ -12,10 +12,7 @@ from sqlmodel import select
 
 from routstr.core.db import ApiKey
 
-from .utils import (
-    CashuTokenGenerator,
-    ResponseValidator,
-)
+from .utils import ResponseValidator
 
 
 @pytest.mark.integration
@@ -79,29 +76,31 @@ async def test_api_key_generation_invalid_token(
     # Capture initial state
     await db_snapshot.capture()
 
-    # Test various invalid tokens
-    invalid_tokens = [
-        CashuTokenGenerator.generate_invalid_token(),  # Malformed token
-        "not-a-cashu-token",  # Wrong format
-        "cashuA",  # Empty token
-        "cashuA" + "x" * 1000,  # Invalid base64
+    # Non-Cashu bearer values are invalid API keys (401). Malformed values that
+    # look like Cashu tokens use the shared Cashu taxonomy (400 invalid_token).
+    invalid_tokens: list[tuple[str, int, str | None]] = [
+        ("not-a-cashu-token", 401, None),
+        ("sk-not-a-real-api-key", 401, None),
+        ("cashuA", 400, "invalid_cashu_token"),
+        ("cashuA" + "x" * 1000, 400, "invalid_cashu_token"),
     ]
 
-    for invalid_token in invalid_tokens:
+    for invalid_token, expected_status, expected_code in invalid_tokens:
         integration_client.headers["Authorization"] = f"Bearer {invalid_token}"
         response = await integration_client.get("/v1/wallet/info")
 
-        # Should fail with 401
-        assert response.status_code == 401, (
+        assert response.status_code == expected_status, (
             f"Token {invalid_token[:20]}... should be invalid"
         )
 
         # Validate error response
         validator = ResponseValidator()
         error_validation = validator.validate_error_response(
-            response, expected_status=401, expected_error_key="detail"
+            response, expected_status=expected_status, expected_error_key="detail"
         )
         assert error_validation["valid"]
+        if expected_code is not None:
+            assert response.json()["detail"]["error"]["code"] == expected_code
 
     # Verify no database changes
     diff = await db_snapshot.diff()

tests/integration/test_wallet_refund.py

@@ -14,6 +14,7 @@ from httpx import AsyncClient
 from sqlmodel import select
 
 from routstr.core.db import ApiKey, CashuTransaction
+from routstr.wallet import MintConnectionError
 
 
 @pytest.mark.integration
@@ -503,26 +504,19 @@ async def test_mint_unavailability_handling(
 
     # The global mock in conftest.py is already in place,
     # so we need to temporarily modify it
-    from unittest.mock import patch
+    raw_error = "Mint unavailable: Connection refused"
 
-    # Make the send_token method raise an exception
+    # Make the send_token method raise a typed mint connection exception.
     with patch(
         "routstr.balance.send_token",
-        side_effect=Exception("Mint unavailable: Connection refused"),
+        side_effect=MintConnectionError(raw_error),
     ):
-        # The exception should propagate as a 503 error (Service Unavailable)
-        # But we need to handle it properly
-        try:
-            response = await authenticated_client.post("/v1/wallet/refund")
-            # If we get here, check the status code
-            assert response.status_code == 503
-            assert "Mint service unavailable" in response.json()["detail"]
-        except Exception as e:
-            # If the exception propagates, that's also a failure scenario
-            assert "Mint unavailable" in str(e)
+        response = await authenticated_client.post("/v1/wallet/refund")
+        assert response.status_code == 503
+        assert response.json()["detail"] == "Mint service unavailable"
+        assert raw_error not in response.text
 
         # Balance should remain unchanged (transaction should roll back)
-        # Note: Current implementation might not handle this perfectly
         wallet_response = await authenticated_client.get("/v1/wallet/")
         assert wallet_response.status_code == 200
         assert wallet_response.json()["balance"] == 10_000_000

tests/unit/test_algorithm.py

@@ -137,8 +137,8 @@ def test_create_model_mappings_includes_db_override_for_missing_cached_model(
 
     model_instances, provider_map, unique_models = create_model_mappings(
         upstreams=[provider],
-        overrides_by_id={"azure/gpt-4o": (override_row, 1.01)},
-        disabled_model_ids=set(),
+        overrides_by_key={("azure/gpt-4o", 7): (override_row, 1.01)},
+        disabled_model_keys=set(),
     )
 
     assert "azure/gpt-4o" in model_instances
@@ -182,11 +182,73 @@ def test_create_model_mappings_dedupes_with_provider_identity_not_provider_type(
 
     _, provider_map, _ = create_model_mappings(
         upstreams=[provider_a, provider_b],
-        overrides_by_id={"azure/gpt-4o": (override_row, 1.01)},
-        disabled_model_ids=set(),
+        overrides_by_key={("azure/gpt-4o", 2): (override_row, 1.01)},
+        disabled_model_keys=set(),
     )
 
     providers_for_alias = provider_map["azure/gpt-4o"]
     assert provider_a in providers_for_alias
     assert provider_b in providers_for_alias
     assert len(providers_for_alias) == 2
+
+
+def test_create_model_mappings_applies_override_only_to_matching_provider(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Same-id overrides must not add provider-specific aliases to other providers."""
+    provider_a_model = create_test_model("same-id", prompt_price=0.01)
+    provider_a = create_test_provider(
+        "provider-a",
+        "https://provider-a.example/v1",
+        db_id=1,
+        models=[provider_a_model],
+    )
+    provider_b_model = create_test_model("same-id", prompt_price=0.02)
+    provider_b = create_test_provider(
+        "provider-b",
+        "https://provider-b.example/v1",
+        db_id=2,
+        models=[provider_b_model],
+    )
+
+    override_model = create_test_model("same-id", prompt_price=0.001)
+    override_model.alias_ids = ["provider-b-only"]
+    override_row = SimpleNamespace(id="same-id", upstream_provider_id=2, enabled=True)
+
+    def fake_row_to_model(*args, **kwargs) -> Model:  # type: ignore[no-untyped-def]
+        return override_model
+
+    monkeypatch.setattr("routstr.payment.models._row_to_model", fake_row_to_model)
+
+    _, provider_map, _ = create_model_mappings(
+        upstreams=[provider_a, provider_b],
+        overrides_by_key={("same-id", 2): (override_row, 1.01)},
+        disabled_model_keys=set(),
+    )
+
+    assert provider_map["provider-b-only"] == [provider_b]
+    assert set(provider_map["same-id"]) == {provider_a, provider_b}
+
+
+def test_create_model_mappings_disables_only_matching_provider() -> None:
+    """Disabled overrides are scoped to the provider row, not the shared model id."""
+    provider_a = create_test_provider(
+        "provider-a",
+        "https://provider-a.example/v1",
+        db_id=1,
+        models=[create_test_model("same-id")],
+    )
+    provider_b = create_test_provider(
+        "provider-b",
+        "https://provider-b.example/v1",
+        db_id=2,
+        models=[create_test_model("same-id")],
+    )
+
+    _, provider_map, _ = create_model_mappings(
+        upstreams=[provider_a, provider_b],
+        overrides_by_key={},
+        disabled_model_keys={("same-id", 2)},
+    )
+
+    assert provider_map["same-id"] == [provider_a]

tests/unit/test_auth_cashu.py

@@ -1,8 +1,9 @@
 import hashlib
 from types import SimpleNamespace
-from typing import AsyncGenerator
+from typing import AsyncGenerator, cast
 from unittest.mock import AsyncMock, patch
 
+import httpx
 import pytest
 from fastapi import HTTPException
 from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
@@ -12,6 +13,19 @@ from sqlmodel.ext.asyncio.session import AsyncSession
 
 from routstr.auth import validate_bearer_key
 from routstr.core.db import ApiKey
+from routstr.wallet import MintConnectionError
+
+
+def _value_error_wrapping_transport() -> ValueError:
+    """A ValueError re-raised ``from`` a real httpx transport error, mirroring
+    ``wallet.py`` wrapping a connection failure. The sanitized classifier must
+    still see the mint-unreachable signal through the ``__cause__`` chain."""
+    try:
+        raise httpx.ConnectError("All connection attempts failed")
+    except httpx.ConnectError as exc:
+        err = ValueError("Failed to estimate fees: connection failed")
+        err.__cause__ = exc
+        return err
 
 
 def _make_engine() -> AsyncEngine:
@@ -57,3 +71,223 @@ async def test_failed_first_cashu_redemption_rolls_back_empty_api_key(
             await validate_bearer_key(token, session)
 
     assert await session.get(ApiKey, hashed_key) is None
+
+
+@pytest.mark.parametrize(
+    ("error", "expected_status", "expected_type", "expected_message", "expected_code"),
+    [
+        (
+            ValueError("Mint Error: Token already spent. (Code: 11001)"),
+            400,
+            "token_already_spent",
+            "Cashu token already spent",
+            "cashu_token_already_spent",
+        ),
+        (
+            # Raw httpx transport error propagated unwrapped from cashu.
+            httpx.ConnectError("All connection attempts failed"),
+            503,
+            "mint_unreachable",
+            "Cashu mint is unreachable",
+            "cashu_mint_unreachable",
+        ),
+        (
+            # Typed error raised by wallet.py at a wrap site.
+            MintConnectionError("connect to http://mint:3338 refused"),
+            503,
+            "mint_unreachable",
+            "Cashu mint is unreachable",
+            "cashu_mint_unreachable",
+        ),
+        (
+            # ValueError wrapping the httpx error in its __cause__ chain.
+            _value_error_wrapping_transport(),
+            503,
+            "mint_unreachable",
+            "Cashu mint is unreachable",
+            "cashu_mint_unreachable",
+        ),
+        (
+            # asyncio.TimeoutError is builtin TimeoutError on 3.11+.
+            TimeoutError("Timed out connecting to Cashu mint http://mint:3338"),
+            503,
+            "mint_unreachable",
+            "Cashu mint is unreachable",
+            "cashu_mint_unreachable",
+        ),
+        (
+            ValueError(
+                "Token amount (5 sat) is insufficient to cover melt fees. "
+                "Needed: 7 sat (amount: 5 + fee: 1 + input_fees: 1)"
+            ),
+            422,
+            "mint_error",
+            "Token value is too small to cover swap fees",
+            "cashu_token_swap_fees_exceed_amount",
+        ),
+        (
+            ValueError(
+                "Failed to estimate fees: Fees (7 sat) exceed token amount (5 sat)"
+            ),
+            422,
+            "mint_error",
+            "Token value is too small to cover swap fees",
+            "cashu_token_swap_fees_exceed_amount",
+        ),
+        (
+            ValueError(
+                "Failed to melt token from foreign mint http://foreign:3338: boom"
+            ),
+            422,
+            "mint_error",
+            "Failed to swap token from foreign mint",
+            "cashu_foreign_mint_swap_failed",
+        ),
+        (
+            ValueError("could not decode token"),
+            400,
+            "invalid_token",
+            "Invalid Cashu token",
+            "invalid_cashu_token",
+        ),
+        (
+            ValueError("some unexpected wallet condition"),
+            400,
+            "cashu_error",
+            "Failed to redeem Cashu token",
+            "cashu_token_redemption_failed",
+        ),
+        (
+            ValueError("Redeemed token amount must be positive, got 0 msats"),
+            400,
+            "cashu_error",
+            "Failed to redeem Cashu token: token yielded no value",
+            "cashu_token_zero_value",
+        ),
+    ],
+)
+@pytest.mark.asyncio
+async def test_redemption_failure_returns_sanitized_error(
+    session: AsyncSession,
+    error: Exception,
+    expected_status: int,
+    expected_type: str,
+    expected_message: str,
+    expected_code: str,
+) -> None:
+    """Redemption failures reuse the shared X-Cashu taxonomy (carried in
+    ``type``), expose stable sanitized messages and granular machine-readable
+    ``code`` values, and leave no orphan ApiKey row."""
+    token = "cashuAredemption_fails_with_specific_error"
+    hashed_key = hashlib.sha256(token.encode()).hexdigest()
+    token_obj = SimpleNamespace(mint="http://mint:3338", unit="sat")
+
+    from routstr.core.settings import settings
+
+    with (
+        patch.object(settings, "cashu_mints", ["http://mint:3338"]),
+        patch("routstr.auth.deserialize_token_from_string", return_value=token_obj),
+        patch(
+            "routstr.auth.credit_balance",
+            new=AsyncMock(side_effect=error),
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await validate_bearer_key(token, session)
+
+    assert exc_info.value.status_code == expected_status
+    detail = cast(dict[str, dict[str, object]], exc_info.value.detail)
+    error_detail = detail["error"]
+    assert error_detail["type"] == expected_type
+    assert error_detail["code"] == expected_code
+    assert error_detail["message"] == expected_message
+    assert str(error) not in cast(str, error_detail["message"])
+    assert await session.get(ApiKey, hashed_key) is None
+
+
+@pytest.mark.asyncio
+async def test_unexpected_redemption_error_returns_internal_error(
+    session: AsyncSession,
+) -> None:
+    """Unexpected (non-wallet) failures surface as generic 500s without
+    leaking internal details, instead of masquerading as token errors."""
+    token = "cashuAredemption_fails_with_internal_error"
+    hashed_key = hashlib.sha256(token.encode()).hexdigest()
+    token_obj = SimpleNamespace(mint="http://mint:3338", unit="sat")
+
+    from routstr.core.settings import settings
+
+    with (
+        patch.object(settings, "cashu_mints", ["http://mint:3338"]),
+        patch("routstr.auth.deserialize_token_from_string", return_value=token_obj),
+        patch(
+            "routstr.auth.credit_balance",
+            new=AsyncMock(side_effect=RuntimeError("db exploded at /var/lib/secret")),
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await validate_bearer_key(token, session)
+
+    assert exc_info.value.status_code == 500
+    detail = cast(dict[str, dict[str, str]], exc_info.value.detail)
+    error_detail = detail["error"]
+    assert error_detail["code"] == "internal_error"
+    assert "/var/lib/secret" not in error_detail["message"]
+    assert await session.get(ApiKey, hashed_key) is None
+
+
+@pytest.mark.asyncio
+async def test_internal_error_with_invalid_keyword_does_not_masquerade(
+    session: AsyncSession,
+) -> None:
+    """A non-wallet fault whose text merely contains "invalid" (but not
+    "token") must fall through to a generic 500, not a 401 token error.
+
+    Guards the anchored `"invalid"/"decode"` + `"token"` gate against stdlib/
+    driver strings like "Invalid isoformat string" leaking as token errors."""
+    token = "cashuAinternal_fault_mentions_invalid"
+    hashed_key = hashlib.sha256(token.encode()).hexdigest()
+    token_obj = SimpleNamespace(mint="http://mint:3338", unit="sat")
+
+    from routstr.core.settings import settings
+
+    with (
+        patch.object(settings, "cashu_mints", ["http://mint:3338"]),
+        patch("routstr.auth.deserialize_token_from_string", return_value=token_obj),
+        patch(
+            "routstr.auth.credit_balance",
+            new=AsyncMock(
+                side_effect=RuntimeError("Invalid isoformat string: '2020-13-99'")
+            ),
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await validate_bearer_key(token, session)
+
+    assert exc_info.value.status_code == 500
+    detail = cast(dict[str, dict[str, str]], exc_info.value.detail)
+    assert detail["error"]["code"] == "internal_error"
+    assert await session.get(ApiKey, hashed_key) is None
+
+
+@pytest.mark.asyncio
+async def test_malformed_cashu_token_returns_400_invalid_token(
+    session: AsyncSession,
+) -> None:
+    """A malformed 'cashu...' token that fails to decode maps to 400
+    invalid_cashu_token (shared taxonomy), not the generic 401 invalid_api_key."""
+    token = "cashuAthis_is_not_a_valid_token"
+
+    with patch(
+        "routstr.auth.deserialize_token_from_string",
+        side_effect=ValueError("unable to decode token: bad base64"),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await validate_bearer_key(token, session)
+
+    assert exc_info.value.status_code == 400
+    detail = cast(dict[str, dict[str, str]], exc_info.value.detail)
+    assert detail["error"]["type"] == "invalid_token"
+    assert detail["error"]["code"] == "invalid_cashu_token"
+    # Raw decoder text must not leak to the client.
+    assert "base64" not in detail["error"]["message"]

tests/unit/test_auto_topup.py

@@ -0,0 +1,153 @@
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from routstr.core.db import CashuTransaction
+from routstr.upstream.auto_topup import _check_and_topup
+
+
+def _row() -> MagicMock:
+    row = MagicMock()
+    row.id = "provider-1"
+    row.base_url = "https://provider.test"
+    row.api_key = "secret"
+    row.provider_settings = json.dumps(
+        {
+            "auto_topup": True,
+            "topup_threshold": 100,
+            "topup_amount_limit": 50,
+            "topup_mint_url": "https://mint.test",
+        }
+    )
+    return row
+
+
+class _Session:
+    def __init__(self, transaction: CashuTransaction) -> None:
+        self.transaction = transaction
+        self.commit = AsyncMock()
+
+    async def __aenter__(self) -> "_Session":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        return None
+
+    async def exec(self, query: object) -> MagicMock:
+        result = MagicMock()
+        result.first.return_value = self.transaction
+        return result
+
+    def add(self, transaction: CashuTransaction) -> None:
+        self.transaction = transaction
+
+
+@pytest.mark.asyncio
+async def test_auto_topup_persists_before_sending_and_marks_success_collected() -> None:
+    provider = MagicMock()
+    provider.get_balance = AsyncMock(return_value=0)
+    provider.topup = AsyncMock(return_value={"balance": 50})
+    transaction = CashuTransaction(
+        token="cashu-token", amount=50, unit="sat", source="auto_topup"
+    )
+    session = _Session(transaction)
+
+    with (
+        patch(
+            "routstr.upstream.auto_topup.RoutstrUpstreamProvider.from_db_row",
+            return_value=provider,
+        ),
+        patch(
+            "routstr.upstream.auto_topup.send_token",
+            AsyncMock(return_value="cashu-token"),
+        ),
+        patch(
+            "routstr.upstream.auto_topup.store_cashu_transaction",
+            AsyncMock(return_value=True),
+        ) as store,
+        patch(
+            "routstr.upstream.auto_topup.token_mint_url",
+            return_value="https://fallback-mint.test",
+        ),
+        patch("routstr.upstream.auto_topup.create_session", return_value=session),
+    ):
+        await _check_and_topup(_row())
+
+    store.assert_awaited_once_with(
+        token="cashu-token",
+        amount=50,
+        unit="sat",
+        mint_url="https://fallback-mint.test",
+        typ="out",
+        collected=False,
+        source="auto_topup",
+    )
+    provider.topup.assert_awaited_once_with("cashu-token")
+    assert transaction.collected is True
+    session.commit.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("outcome", [{"error": "rejected"}, RuntimeError("network")])
+async def test_auto_topup_failure_leaves_persisted_token_uncollected(
+    outcome: object,
+) -> None:
+    provider = MagicMock()
+    provider.get_balance = AsyncMock(return_value=0)
+    provider.topup = AsyncMock(
+        side_effect=outcome if isinstance(outcome, Exception) else None,
+        return_value=outcome,
+    )
+
+    with (
+        patch(
+            "routstr.upstream.auto_topup.RoutstrUpstreamProvider.from_db_row",
+            return_value=provider,
+        ),
+        patch(
+            "routstr.upstream.auto_topup.send_token",
+            AsyncMock(return_value="cashu-token"),
+        ),
+        patch(
+            "routstr.upstream.auto_topup.store_cashu_transaction",
+            AsyncMock(return_value=True),
+        ),
+        patch("routstr.upstream.auto_topup.create_session") as create_session,
+    ):
+        if isinstance(outcome, Exception):
+            with pytest.raises(RuntimeError):
+                await _check_and_topup(_row())
+        else:
+            await _check_and_topup(_row())
+
+    create_session.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_auto_topup_does_not_send_untracked_token() -> None:
+    provider = MagicMock()
+    provider.get_balance = AsyncMock(return_value=0)
+    provider.topup = AsyncMock()
+    with (
+        patch(
+            "routstr.upstream.auto_topup.RoutstrUpstreamProvider.from_db_row",
+            return_value=provider,
+        ),
+        patch(
+            "routstr.upstream.auto_topup.send_token",
+            AsyncMock(return_value="cashu-token"),
+        ),
+        patch(
+            "routstr.upstream.auto_topup.store_cashu_transaction",
+            AsyncMock(return_value=False),
+        ),
+        patch(
+            "routstr.upstream.auto_topup.release_token_reservation",
+            AsyncMock(),
+        ) as reclaim,
+    ):
+        await _check_and_topup(_row())
+
+    reclaim.assert_awaited_once_with("cashu-token")
+    provider.topup.assert_not_awaited()

tests/unit/test_balance.py

@@ -1,12 +1,13 @@
 import json
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import httpx
 import pytest
 from fastapi.responses import JSONResponse
 
-from routstr.balance import refund_wallet_endpoint
+from routstr.balance import refund_wallet_endpoint, topup_wallet_endpoint
 from routstr.core.db import ApiKey, CashuTransaction
-from routstr.wallet import credit_balance
+from routstr.wallet import MintConnectionError, credit_balance
 
 
 def _make_cashu_tx(
@@ -103,6 +104,64 @@ async def test_refund_x_cashu_not_found_raises_404() -> None:
     assert exc_info.value.status_code == 404
 
 
+@pytest.mark.asyncio
+async def test_refund_x_cashu_pending_raises_425() -> None:
+    """in row exists with a request_id but out row not yet created → 425.
+
+    This is the race condition where /v1/wallet/refund is polled while the
+    upstream request is still in flight. The endpoint must signal "retry"
+    rather than a permanent 404.
+    """
+    from fastapi import HTTPException
+
+    x_cashu_token = "cashuApending_token"
+    in_tx = _make_cashu_tx(
+        token=x_cashu_token, amount=0, unit="msat", type="in", request_id="req-pending"
+    )
+
+    session = MagicMock()
+    session.exec = AsyncMock(side_effect=[_exec_result(in_tx), _exec_result(None)])
+    session.add = MagicMock()
+    session.commit = AsyncMock()
+
+    with pytest.raises(HTTPException) as exc_info:
+        await refund_wallet_endpoint(
+            authorization="Bearer sk-somekey",
+            x_cashu=x_cashu_token,
+            session=session,
+        )
+
+    assert exc_info.value.status_code == 425
+    assert exc_info.value.headers == {"Retry-After": "2"}
+
+
+@pytest.mark.asyncio
+async def test_refund_x_cashu_in_tx_without_request_id_raises_404() -> None:
+    """in row exists but has no request_id (cannot link to a refund) → 404.
+
+    This is a genuine "no refund will ever exist" case, distinct from the
+    pending 425 path.
+    """
+    from fastapi import HTTPException
+
+    x_cashu_token = "cashuAnoreqid_token"
+    in_tx = _make_cashu_tx(
+        token=x_cashu_token, amount=0, unit="msat", type="in", request_id=None
+    )
+
+    session = MagicMock()
+    session.exec = AsyncMock(side_effect=[_exec_result(in_tx)])
+
+    with pytest.raises(HTTPException) as exc_info:
+        await refund_wallet_endpoint(
+            authorization="Bearer sk-somekey",
+            x_cashu=x_cashu_token,
+            session=session,
+        )
+
+    assert exc_info.value.status_code == 404
+
+
 @pytest.mark.asyncio
 async def test_refund_x_cashu_swept_raises_410() -> None:
     from fastapi import HTTPException
@@ -339,7 +398,10 @@ async def test_apikey_refund_restores_balance_on_mint_failure() -> None:
 
     with (
         patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
-        patch("routstr.balance.send_token", AsyncMock(side_effect=Exception("mint down"))),
+        patch(
+            "routstr.balance.send_token",
+            AsyncMock(side_effect=MintConnectionError("raw mint outage detail")),
+        ),
         patch("routstr.balance.store_cashu_transaction", AsyncMock()),
         patch("routstr.balance._refund_cache_get", AsyncMock(return_value=None)),
         patch("routstr.balance._refund_cache_set", AsyncMock()),
@@ -353,10 +415,46 @@ async def test_apikey_refund_restores_balance_on_mint_failure() -> None:
             )
 
     assert exc_info.value.status_code == 503
+    assert exc_info.value.detail == "Mint service unavailable"
+    assert "raw mint outage detail" not in exc_info.value.detail
     # Verify two exec calls: debit + restore
     assert session.exec.await_count == 2
 
 
+@pytest.mark.asyncio
+async def test_apikey_refund_generic_failure_is_sanitized_500() -> None:
+    """Unexpected send-side failures restore balance without leaking exception text."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=5000, refund_currency="sat")
+    raw_error = "database secret token raw-mint-response"
+
+    session = MagicMock()
+    session.get = AsyncMock(return_value=key)
+    session.exec = AsyncMock(side_effect=[_update_result(1), _update_result(1)])
+    session.commit = AsyncMock()
+
+    with (
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.send_token", AsyncMock(side_effect=RuntimeError(raw_error))),
+        patch("routstr.balance.store_cashu_transaction", AsyncMock()),
+        patch("routstr.balance._refund_cache_get", AsyncMock(return_value=None)),
+        patch("routstr.balance._refund_cache_set", AsyncMock()),
+        patch("routstr.balance.logger"),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await refund_wallet_endpoint(
+                authorization="Bearer sk-testhash",
+                x_cashu=None,
+                session=session,
+            )
+
+    assert exc_info.value.status_code == 500
+    assert exc_info.value.detail == "Refund failed"
+    assert raw_error not in exc_info.value.detail
+    assert session.exec.await_count == 2
+
+
 # ---------------------------------------------------------------------------
 # no-create guarantee: fresh Cashu/unknown sk- tokens must not create API keys
 # ---------------------------------------------------------------------------
@@ -401,3 +499,213 @@ async def test_refund_unknown_sk_bearer_returns_401() -> None:
 
     assert exc_info.value.status_code == 401
     session.get.assert_awaited_once()
+
+
+# --- Topup redemption error taxonomy (POST /v1/wallet/topup) ------------------
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "error",
+    [
+        httpx.ConnectError("All connection attempts failed"),
+        MintConnectionError("connect to mint refused"),
+        TimeoutError("timed out connecting to mint"),
+    ],
+)
+async def test_topup_mint_unreachable_returns_503(error: Exception) -> None:
+    """A down mint must surface 503 (retryable), not 400 or 500 — the token is
+    fine, so the client should retry once the mint recovers."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=1000)
+    session = MagicMock()
+
+    with (
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.credit_balance", AsyncMock(side_effect=error)),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await topup_wallet_endpoint(
+                cashu_token="cashuAtoken", key=key, session=session
+            )
+
+    assert exc_info.value.status_code == 503
+    assert exc_info.value.detail == "Cashu mint is unreachable"
+
+
+@pytest.mark.asyncio
+async def test_topup_unreachable_source_mint_explains_why_fallback_is_impossible() -> None:
+    from fastapi import HTTPException
+
+    from routstr.wallet import SourceMintConnectionError
+
+    key = _make_api_key(balance=1000)
+    session = MagicMock()
+    error = SourceMintConnectionError("Issuing Cashu mint is unreachable")
+
+    with (
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.credit_balance", AsyncMock(side_effect=error)),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await topup_wallet_endpoint(
+                cashu_token="cashuAtoken", key=key, session=session
+            )
+
+    assert exc_info.value.status_code == 503
+    assert "cannot be redeemed at another mint" in exc_info.value.detail
+
+
+@pytest.mark.asyncio
+async def test_topup_already_spent_still_returns_400() -> None:
+    """Regression: the mint-unreachable short-circuit must not swallow the
+    existing ValueError substring buckets."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=1000)
+    session = MagicMock()
+
+    with (
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch(
+            "routstr.balance.credit_balance",
+            AsyncMock(side_effect=ValueError("Token already spent")),
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await topup_wallet_endpoint(
+                cashu_token="cashuAtoken", key=key, session=session
+            )
+
+    assert exc_info.value.status_code == 400
+    assert exc_info.value.detail == "Cashu token already spent"
+
+
+@pytest.mark.asyncio
+async def test_topup_zero_value_returns_400_zero_value_message() -> None:
+    """A dust/zero redemption maps to the documented zero-value message, not the
+    generic redemption-failed one."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=1000)
+    session = MagicMock()
+
+    with (
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch(
+            "routstr.balance.credit_balance",
+            AsyncMock(
+                side_effect=ValueError("Redeemed token amount must be positive, got 0 msats")
+            ),
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await topup_wallet_endpoint(
+                cashu_token="cashuAtoken", key=key, session=session
+            )
+
+    assert exc_info.value.status_code == 400
+    assert exc_info.value.detail == "Failed to redeem Cashu token: token yielded no value"
+
+
+@pytest.mark.asyncio
+async def test_topup_token_consumed_returns_500() -> None:
+    """A post-redemption crediting failure (token spent) is a non-retryable 500,
+    not a 4xx that invites a retry."""
+    from fastapi import HTTPException
+
+    from routstr.wallet import TokenConsumedError
+
+    key = _make_api_key(balance=1000)
+    session = MagicMock()
+
+    with (
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch(
+            "routstr.balance.credit_balance",
+            AsyncMock(side_effect=TokenConsumedError("credit failed")),
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await topup_wallet_endpoint(
+                cashu_token="cashuAtoken", key=key, session=session
+            )
+
+    assert exc_info.value.status_code == 500
+    assert exc_info.value.detail == (
+        "Token was redeemed but could not be credited; do not retry"
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("error", "expected_status", "expected_detail"),
+    [
+        (
+            ValueError(
+                "Failed to estimate fees: Fees (7 sat) exceed token amount (5 sat)"
+            ),
+            422,
+            "Token value is too small to cover swap fees",
+        ),
+        (
+            ValueError(
+                "Token amount (5 sat) is insufficient to cover melt fees."
+            ),
+            422,
+            "Token value is too small to cover swap fees",
+        ),
+        (
+            ValueError("Failed to melt token from foreign mint http://m: boom"),
+            422,
+            "Failed to swap token from foreign mint",
+        ),
+    ],
+)
+async def test_topup_fee_and_swap_failures_return_422(
+    error: Exception, expected_status: int, expected_detail: str
+) -> None:
+    """Fee/swap failures map to 422 (shared taxonomy), matching the bearer and
+    X-Cashu paths — previously top-up flattened these to 400."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=1000)
+    session = MagicMock()
+
+    with (
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.credit_balance", AsyncMock(side_effect=error)),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await topup_wallet_endpoint(
+                cashu_token="cashuAtoken", key=key, session=session
+            )
+
+    assert exc_info.value.status_code == expected_status
+    assert exc_info.value.detail == expected_detail
+
+
+@pytest.mark.asyncio
+async def test_topup_unexpected_non_valueerror_returns_500() -> None:
+    """A non-ValueError, non-transport fault is an internal error (500), not a
+    sanitized 400 — the merged except must preserve this."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=1000)
+    session = MagicMock()
+
+    with (
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch(
+            "routstr.balance.credit_balance",
+            AsyncMock(side_effect=RuntimeError("db exploded")),
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await topup_wallet_endpoint(
+                cashu_token="cashuAtoken", key=key, session=session
+            )
+
+    assert exc_info.value.status_code == 500
+    assert exc_info.value.detail == "Internal server error"

tests/unit/test_cost_calculation_caching.py

@@ -465,9 +465,113 @@ async def test_cache_read_only_usd_cost_response_is_billed(
     assert result.cache_read_input_tokens == 1000
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("total_cost", "input_cost", "output_cost", "expected_msats"),
+    [
+        (0.000471, 0.00023451, 0.00023649, 9420),
+        (0.00000004, 0.00000002, 0.00000002, 1),
+    ],
+)
+async def test_small_usd_cost_components_sum_to_rounded_total(
+    total_cost: float,
+    input_cost: float,
+    output_cost: float,
+    expected_msats: int,
+) -> None:
+    """Small USD component costs must retain every billed millisatoshi."""
+    response = {
+        "model": "gpt-4",
+        "usage": {
+            "prompt_tokens": 1,
+            "completion_tokens": 1,
+            "cost_details": {
+                "total_cost": total_cost,
+                "input_cost": input_cost,
+                "output_cost": output_cost,
+            },
+        },
+    }
+
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.total_msats == expected_msats
+    assert result.input_msats + result.output_msats == result.total_msats
+
+
+@pytest.mark.asyncio
+async def test_openrouter_upstream_inference_cost_components_are_used() -> None:
+    """OpenRouter component aliases must determine the input/output split."""
+    response = {
+        "model": "gpt-4",
+        "usage": {
+            "prompt_tokens": 375,
+            "completion_tokens": 158,
+            "total_tokens": 533,
+            "cost": 0.00022354,
+            "is_byok": False,
+            "prompt_tokens_details": {
+                "cached_tokens": 286,
+                "cache_write_tokens": 0,
+            },
+            "cost_details": {
+                "upstream_inference_cost": 0.00022354,
+                "upstream_inference_prompt_cost": 0.00004974,
+                "upstream_inference_completions_cost": 0.0001738,
+            },
+            "completion_tokens_details": {"reasoning_tokens": 17},
+        },
+    }
+
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.input_msats == 994
+    assert result.output_msats == 3477
+    assert result.input_msats + result.output_msats == result.total_msats == 4471
+
+
 # ============================================================================
 # Test 13: Missing Usage Block
 # ============================================================================
+@pytest.mark.asyncio
+async def test_missing_upstream_cost_uses_litellm_model_pricing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Token usage without an upstream cost is priced from LiteLLM."""
+    monkeypatch.setattr(settings, "fixed_pricing", True)
+    monkeypatch.setattr(settings, "fixed_per_1k_input_tokens", 0)
+    monkeypatch.setattr(settings, "fixed_per_1k_output_tokens", 0)
+    monkeypatch.setattr(
+        "routstr.payment.models.litellm_cost_entry",
+        lambda model: {
+            "input_cost_per_token": 0.000001,
+            "output_cost_per_token": 0.000002,
+        },
+    )
+    response = {
+        "model": "priced-by-litellm",
+        "usage": {
+            "prompt_tokens": 90,
+            "completion_tokens": 80,
+            "total_tokens": 170,
+            "prompt_tokens_details": {"cached_tokens": 0},
+            "completion_tokens_details": {"reasoning_tokens": 74},
+            "prompt_cache_hit_tokens": 0,
+            "prompt_cache_miss_tokens": 90,
+        },
+    }
+
+    result = await calculate_cost(response, max_cost=10000)
+
+    assert isinstance(result, CostData)
+    assert not isinstance(result, MaxCostData)
+    assert result.input_msats == 1800
+    assert result.output_msats == 3200
+    assert result.input_msats + result.output_msats == result.total_msats == 5000
+
+
 @pytest.mark.asyncio
 async def test_missing_usage_block(mock_fixed_pricing: None) -> None:
     """When usage is missing, return MaxCostData with zero tokens."""

tests/unit/test_fetch_all_balances.py

@@ -1,11 +1,28 @@
+from collections.abc import Generator
 from contextlib import asynccontextmanager
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import httpx
 import pytest
 
 from routstr.wallet import fetch_all_balances
 
 
+@pytest.fixture(autouse=True)
+def clear_balance_fetch_state() -> Generator[None, None, None]:
+    from routstr import wallet
+
+    wallet._balance_fetch_failures.clear()
+    wallet._balance_fetch_locks.clear()
+    wallet._mint_supported_units.clear()
+    wallet._MintRateGuard._guards.clear()
+    yield
+    wallet._balance_fetch_failures.clear()
+    wallet._balance_fetch_locks.clear()
+    wallet._mint_supported_units.clear()
+    wallet._MintRateGuard._guards.clear()
+
+
 @asynccontextmanager
 async def _fake_session():  # type: ignore[no-untyped-def]
     yield MagicMock()
@@ -21,7 +38,7 @@ def _patches(proof_amount: int = 1000):  # type: ignore[no-untyped-def]
         ),
         patch(
             "routstr.wallet.slow_filter_spend_proofs",
-            AsyncMock(side_effect=lambda proofs, wallet: proofs),
+            AsyncMock(side_effect=lambda proofs, wallet, **kwargs: proofs),
         ),
         patch(
             "routstr.wallet.db.balances_for_mint_and_unit",
@@ -36,8 +53,9 @@ async def test_fetch_all_balances_falls_back_to_primary_mint() -> None:
     """With empty cashu_mints, balances are still fetched for primary_mint."""
     from routstr.core.settings import settings
 
-    with patch.object(settings, "cashu_mints", []), patch.object(
-        settings, "primary_mint", "http://primary:3338"
+    with (
+        patch.object(settings, "cashu_mints", []),
+        patch.object(settings, "primary_mint", "http://primary:3338"),
     ):
         for p in _patches(proof_amount=1000):
             p.start()
@@ -52,14 +70,170 @@ async def test_fetch_all_balances_falls_back_to_primary_mint() -> None:
     assert total_wallet == 1000
 
 
+@pytest.mark.asyncio
+async def test_fetch_all_balances_uses_units_advertised_by_mint() -> None:
+    from routstr.core.settings import settings
+
+    with (
+        patch.object(settings, "cashu_mints", ["http://mint:3338"]),
+        patch.object(settings, "primary_mint", "http://mint:3338"),
+        patch(
+            "routstr.wallet._get_supported_mint_units",
+            AsyncMock(return_value=["sat"]),
+        ) as supported_units,
+    ):
+        for p in _patches(proof_amount=1000):
+            p.start()
+        try:
+            details, *_ = await fetch_all_balances()
+        finally:
+            patch.stopall()
+
+    supported_units.assert_awaited_once_with("http://mint:3338")
+    assert [detail["unit"] for detail in details] == ["sat"]
+
+
+@pytest.mark.asyncio
+async def test_unit_discovery_failure_returns_structured_balance_error() -> None:
+    from routstr.core.settings import settings
+
+    get_wallet = AsyncMock()
+    with (
+        patch.object(settings, "cashu_mints", ["http://mint:3338"]),
+        patch.object(settings, "primary_mint", "http://mint:3338"),
+        patch(
+            "routstr.wallet._get_supported_mint_units",
+            AsyncMock(side_effect=httpx.ConnectError("mint unavailable")),
+        ),
+        patch("routstr.wallet.get_wallet", get_wallet),
+        patch("routstr.wallet.db.create_session", _fake_session),
+    ):
+        details, *_ = await fetch_all_balances()
+
+    assert details[0]["unit"] == settings.primary_mint_unit
+    assert details[0]["error_code"] == "unreachable"
+    assert details[0]["retry_after_seconds"] > 0
+    get_wallet.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_supported_mint_units_come_from_active_keysets() -> None:
+    from routstr.core.settings import settings
+    from routstr.wallet import _get_supported_mint_units
+
+    # Cashu versions/mints may deserialize keyset units as either strings or
+    # Unit enum-like objects. Both representations must be accepted.
+    sat = MagicMock(active=True, unit="sat")
+    msat = MagicMock(active=False, unit="msat")
+    usd = MagicMock(active=True)
+    usd.unit.name = "usd"
+    wallet = MagicMock()
+    wallet._get_keysets = AsyncMock(return_value=[usd, msat, sat])
+
+    with (
+        patch.object(settings, "primary_mint_unit", "sat"),
+        patch("routstr.wallet.get_wallet", AsyncMock(return_value=wallet)),
+    ):
+        units = await _get_supported_mint_units("http://mint:3338")
+        cached_units = await _get_supported_mint_units("http://mint:3338")
+
+    assert units == ["sat", "usd"]
+    assert cached_units == units
+    wallet._get_keysets.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_fetch_all_balances_backs_off_after_connection_failure() -> None:
+    from routstr.core.settings import settings
+
+    get_wallet = AsyncMock(side_effect=httpx.ConnectError("mint unavailable"))
+    with (
+        patch.object(settings, "cashu_mints", ["http://mint:3338"]),
+        patch.object(settings, "primary_mint", "http://mint:3338"),
+        patch("routstr.wallet.get_wallet", get_wallet),
+        patch("routstr.wallet.db.create_session", _fake_session),
+        patch("routstr.wallet.time.monotonic", return_value=10),
+        patch("routstr.wallet.logger.warning") as warning,
+    ):
+        first = await fetch_all_balances(units=["sat"])
+        second = await fetch_all_balances(units=["sat"])
+
+    assert first[0][0]["error"] == "mint unavailable"
+    assert first[0][0]["error_code"] == "unreachable"
+    assert first[0][0]["retry_after_seconds"] == 60
+    assert second[0][0]["error"] == "mint unavailable"
+    assert second[0][0]["error_code"] == "unreachable"
+    assert get_wallet.await_count == 1
+    warning.assert_called_once()
+
+    with (
+        patch.object(settings, "cashu_mints", ["http://mint:3338"]),
+        patch.object(settings, "primary_mint", "http://mint:3338"),
+        patch("routstr.wallet.get_wallet", get_wallet),
+        patch("routstr.wallet.db.create_session", _fake_session),
+        patch("routstr.wallet.time.monotonic", return_value=71),
+        patch("routstr.wallet.logger.warning"),
+    ):
+        await fetch_all_balances(units=["sat"])
+
+    assert get_wallet.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_fetch_all_balances_reports_rate_limit_status() -> None:
+    from routstr.core.settings import settings
+
+    request = httpx.Request("GET", "http://mint:3338/v1/keysets")
+    response = httpx.Response(429, request=request, headers={"Retry-After": "45"})
+    error = httpx.HTTPStatusError("rate limited", request=request, response=response)
+    with (
+        patch.object(settings, "cashu_mints", ["http://mint:3338"]),
+        patch.object(settings, "primary_mint", "http://mint:3338"),
+        patch("routstr.wallet.get_wallet", AsyncMock(side_effect=error)),
+        patch("routstr.wallet.db.create_session", _fake_session),
+    ):
+        details, *_ = await fetch_all_balances(units=["sat"])
+
+    assert details[0]["error_code"] == "rate_limited"
+    assert details[0]["retry_after_seconds"] == 60
+
+
+@pytest.mark.asyncio
+async def test_balance_failure_applies_mint_cooldown_to_other_units() -> None:
+    from routstr.core.settings import settings
+    from routstr.wallet import _mint_cooldown_remaining
+
+    mint = "http://mint:3338"
+    get_wallet = AsyncMock(side_effect=httpx.ConnectError("mint unavailable"))
+    with (
+        patch.object(settings, "cashu_mints", [mint]),
+        patch.object(settings, "primary_mint", mint),
+        patch("routstr.wallet.get_wallet", get_wallet),
+        patch("routstr.wallet.db.create_session", _fake_session),
+        patch("routstr.wallet.time.monotonic", return_value=10),
+        patch("routstr.wallet.logger.warning") as warning,
+    ):
+        details, *_ = await fetch_all_balances(units=["sat", "msat"])
+        cooldown = _mint_cooldown_remaining(mint)
+
+    assert get_wallet.await_count == 1
+    assert warning.call_count == 1
+    assert cooldown == 60
+    assert details[0]["error"] == "mint unavailable"
+    assert details[0]["error_code"] == "unreachable"
+    assert details[1]["error"] == "Mint is unreachable"
+    assert details[1]["error_code"] == "unreachable"
+
+
 @pytest.mark.asyncio
 async def test_fetch_all_balances_no_duplicate_primary_mint() -> None:
     """primary_mint already in cashu_mints is not inspected twice."""
     from routstr.core.settings import settings
 
-    with patch.object(
-        settings, "cashu_mints", ["http://primary:3338"]
-    ), patch.object(settings, "primary_mint", "http://primary:3338"):
+    with (
+        patch.object(settings, "cashu_mints", ["http://primary:3338"]),
+        patch.object(settings, "primary_mint", "http://primary:3338"),
+    ):
         for p in _patches(proof_amount=1000):
             p.start()
         try:

tests/unit/test_lnurl_melt_timeout.py

@@ -0,0 +1,74 @@
+"""raw_send_to_lnurl() must not hang forever on an unresponsive mint.
+
+The Cashu library issues POST /v1/melt/bolt11 with timeout=None, so a hung
+mint would block the melt (and the payout loop) indefinitely. raw_send_to_lnurl
+now wraps wallet.melt() in asyncio.wait_for(MELT_TIMEOUT_SECONDS) and surfaces a
+timeout as LNURLError instead of hanging.
+"""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from routstr.payment import lnurl
+from routstr.payment.lnurl import LNURLError, raw_send_to_lnurl
+
+
+@pytest.mark.asyncio
+async def test_raw_send_to_lnurl_times_out_on_hung_melt() -> None:
+    proofs = [MagicMock(amount=1000)]
+
+    wallet = MagicMock()
+    wallet.melt_quote = AsyncMock(return_value=MagicMock(fee_reserve=1, quote="q"))
+    wallet.select_to_send = AsyncMock(return_value=(proofs, None))
+
+    async def _hang(**kwargs: object) -> None:
+        await asyncio.sleep(5)  # far longer than the patched timeout
+
+    wallet.melt = AsyncMock(side_effect=_hang)
+
+    lnurl_data = {
+        "callback_url": "https://ln.tld/cb",
+        "min_sendable": 1_000,
+        "max_sendable": 100_000_000,
+    }
+
+    with patch.object(lnurl, "MELT_TIMEOUT_SECONDS", 0.05), patch(
+        "routstr.payment.lnurl.get_lnurl_data", AsyncMock(return_value=lnurl_data)
+    ), patch(
+        "routstr.payment.lnurl.get_lnurl_invoice",
+        AsyncMock(return_value=("lnbc1...", {})),
+    ):
+        with pytest.raises(LNURLError, match="Melt timed out"):
+            await raw_send_to_lnurl(wallet, proofs, "owner@ln.tld", "sat", amount=1000)
+
+
+@pytest.mark.asyncio
+async def test_raw_send_to_lnurl_succeeds_within_timeout() -> None:
+    """A prompt melt still returns the net amount, unaffected by the guard."""
+    proofs = [MagicMock(amount=1000)]
+
+    wallet = MagicMock()
+    wallet.melt_quote = AsyncMock(return_value=MagicMock(fee_reserve=1, quote="q"))
+    wallet.select_to_send = AsyncMock(return_value=(proofs, None))
+    wallet.melt = AsyncMock(return_value=MagicMock())
+
+    lnurl_data = {
+        "callback_url": "https://ln.tld/cb",
+        "min_sendable": 1_000,
+        "max_sendable": 100_000_000,
+    }
+
+    with patch.object(lnurl, "MELT_TIMEOUT_SECONDS", 5), patch(
+        "routstr.payment.lnurl.get_lnurl_data", AsyncMock(return_value=lnurl_data)
+    ), patch(
+        "routstr.payment.lnurl.get_lnurl_invoice",
+        AsyncMock(return_value=("lnbc1...", {})),
+    ):
+        paid = await raw_send_to_lnurl(
+            wallet, proofs, "owner@ln.tld", "sat", amount=1000
+        )
+
+    assert paid > 0
+    wallet.melt.assert_awaited_once()

tests/unit/test_messages_litellm_dispatch.py

@@ -11,6 +11,7 @@ import os
 from typing import Any, AsyncIterator
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import httpx
 import pytest
 from fastapi.responses import Response, StreamingResponse
 
@@ -21,6 +22,7 @@ from routstr.core.db import ApiKey  # noqa: E402
 from routstr.payment.cost_calculation import CostData  # noqa: E402
 from routstr.payment.models import Architecture, Model, Pricing  # noqa: E402
 from routstr.upstream.base import BaseUpstreamProvider  # noqa: E402
+from routstr.wallet import MintConnectionError, TokenConsumedError  # noqa: E402
 
 # ---------------------------------------------------------------------------
 # Fixtures
@@ -1308,3 +1310,320 @@ async def test_dispatch_uses_url_detected_prefix_for_fireworks_custom_row() -> N
         "fireworks_ai/accounts/fireworks/models/glm-5"
     )
     assert captured_kwargs["api_base"] == "https://api.fireworks.ai/inference/v1"
+
+
+# ---------------------------------------------------------------------------
+# X-Cashu redemption error taxonomy (unreachable mint + string codes)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "handler_name",
+    ["handle_x_cashu", "handle_x_cashu_responses"],
+)
+@pytest.mark.parametrize(
+    "error",
+    [
+        httpx.ConnectError("All connection attempts failed"),
+        MintConnectionError("Cashu mint is unreachable"),
+        TimeoutError("timed out connecting to mint"),
+    ],
+)
+async def test_x_cashu_mint_unreachable_returns_503(
+    handler_name: str, error: Exception
+) -> None:
+    """Both X-Cashu entrypoints classify a down mint as 503 mint_unreachable,
+    not a generic 400 cashu_error."""
+    provider = _make_provider()
+    model = _make_model()
+    request = _make_request()
+
+    with patch(
+        "routstr.upstream.base.recieve_token", new=AsyncMock(side_effect=error)
+    ):
+        handler = getattr(provider, handler_name)
+        response = await handler(
+            request=request,
+            x_cashu_token="cashuAtoken",
+            path="v1/chat/completions",
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+
+    assert response.status_code == 503
+    body = json.loads(bytes(response.body))
+    assert body["error"]["type"] == "mint_unreachable"
+    assert body["error"]["message"] == "Cashu mint is unreachable"
+    assert body["error"]["code"] == "cashu_mint_unreachable"
+    if str(error) != body["error"]["message"]:
+        assert str(error) not in body["error"]["message"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "handler_name",
+    ["handle_x_cashu", "handle_x_cashu_responses"],
+)
+@pytest.mark.parametrize(
+    (
+        "error",
+        "expected_status",
+        "expected_type",
+        "expected_message",
+        "expected_code",
+    ),
+    [
+        (
+            ValueError("Mint Error: Token already spent"),
+            400,
+            "token_already_spent",
+            "Cashu token already spent",
+            "cashu_token_already_spent",
+        ),
+        (
+            ValueError("invalid token: could not decode"),
+            400,
+            "invalid_token",
+            "Invalid Cashu token",
+            "invalid_cashu_token",
+        ),
+        (
+            # Fee/swap failures now map to a granular 422 on the X-Cashu path,
+            # matching the bearer path (previously flattened to 400).
+            ValueError(
+                "Failed to estimate fees: Fees (7 sat) exceed token amount (5 sat)"
+            ),
+            422,
+            "mint_error",
+            "Token value is too small to cover swap fees",
+            "cashu_token_swap_fees_exceed_amount",
+        ),
+        (
+            ValueError("Failed to melt token from foreign mint http://m: boom"),
+            422,
+            "mint_error",
+            "Failed to swap token from foreign mint",
+            "cashu_foreign_mint_swap_failed",
+        ),
+        (
+            ValueError("some unexpected wallet condition"),
+            400,
+            "cashu_error",
+            "Failed to redeem Cashu token",
+            "cashu_token_redemption_failed",
+        ),
+        (
+            # Non-ValueError faults are internal errors (500), not token errors.
+            RuntimeError("db exploded"),
+            500,
+            "api_error",
+            "Internal error during token redemption",
+            "internal_error",
+        ),
+    ],
+)
+async def test_x_cashu_error_code_is_stable_string(
+    handler_name: str,
+    error: Exception,
+    expected_status: int,
+    expected_type: str,
+    expected_message: str,
+    expected_code: str,
+) -> None:
+    """X-Cashu emits a stable string ``code`` on every branch, matching the
+    bearer path's taxonomy instead of an int HTTP status."""
+    provider = _make_provider()
+    model = _make_model()
+    request = _make_request()
+
+    with patch(
+        "routstr.upstream.base.recieve_token", new=AsyncMock(side_effect=error)
+    ):
+        handler = getattr(provider, handler_name)
+        response = await handler(
+            request=request,
+            x_cashu_token="cashuAtoken",
+            path="v1/chat/completions",
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+
+    assert response.status_code == expected_status
+    body = json.loads(bytes(response.body))
+    assert body["error"]["type"] == expected_type
+    assert body["error"]["message"] == expected_message
+    assert body["error"]["code"] == expected_code
+    assert isinstance(body["error"]["code"], str)
+    if str(error) != expected_message:
+        assert str(error) not in body["error"]["message"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("handler_name", "forward_attr"),
+    [
+        ("handle_x_cashu", "forward_x_cashu_request"),
+        ("handle_x_cashu_responses", "forward_x_cashu_responses_request"),
+    ],
+)
+async def test_x_cashu_transport_error_after_redemption_is_not_retryable(
+    handler_name: str, forward_attr: str
+) -> None:
+    """A transport failure while forwarding (after the token is spent) maps to
+    502 upstream_error, never a retryable cashu_mint_unreachable."""
+    provider = _make_provider()
+    model = _make_model()
+    request = _make_request()
+
+    with (
+        patch(
+            "routstr.upstream.base.recieve_token",
+            new=AsyncMock(return_value=(5_000, "sat", "https://mint")),
+        ),
+        patch("routstr.upstream.base.store_cashu_transaction", new=AsyncMock()),
+        patch.object(
+            provider,
+            forward_attr,
+            new=AsyncMock(side_effect=httpx.ConnectError("upstream down")),
+        ),
+    ):
+        handler = getattr(provider, handler_name)
+        response = await handler(
+            request=request,
+            x_cashu_token="cashuAtoken",
+            path="v1/chat/completions",
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+
+    assert response.status_code == 502
+    body = json.loads(bytes(response.body))
+    assert body["error"]["type"] == "upstream_error"
+    assert body["error"]["code"] != "cashu_mint_unreachable"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "handler_name",
+    ["handle_x_cashu", "handle_x_cashu_responses"],
+)
+async def test_x_cashu_token_consumed_returns_500_and_no_echo(
+    handler_name: str,
+) -> None:
+    """A post-redemption failure (token spent, crediting/minting failed) is a
+    non-retryable 500 token_consumed and must NOT echo the spent token back."""
+    provider = _make_provider()
+    model = _make_model()
+    request = _make_request()
+
+    with patch(
+        "routstr.upstream.base.recieve_token",
+        new=AsyncMock(side_effect=TokenConsumedError("credit failed")),
+    ):
+        handler = getattr(provider, handler_name)
+        response = await handler(
+            request=request,
+            x_cashu_token="cashuAtoken",
+            path="v1/chat/completions",
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+
+    assert response.status_code == 500
+    body = json.loads(bytes(response.body))
+    assert body["error"]["type"] == "token_consumed"
+    assert body["error"]["code"] == "cashu_token_consumed"
+    assert "X-Cashu" not in response.headers
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("handler_name", "error", "echoed"),
+    [
+        # Spent token: must NOT be echoed.
+        ("handle_x_cashu", ValueError("Token already spent"), False),
+        ("handle_x_cashu_responses", ValueError("Token already spent"), False),
+        # Unspent but unreachable mint: echo so the client can retry the token.
+        ("handle_x_cashu", MintConnectionError("mint down"), True),
+        ("handle_x_cashu_responses", MintConnectionError("mint down"), True),
+        # Consumed token (post-redemption): must NOT be echoed.
+        ("handle_x_cashu", TokenConsumedError("credit failed"), False),
+        ("handle_x_cashu_responses", TokenConsumedError("credit failed"), False),
+    ],
+)
+async def test_x_cashu_echoes_token_only_when_recoverable(
+    handler_name: str, error: Exception, echoed: bool
+) -> None:
+    provider = _make_provider()
+    model = _make_model()
+    request = _make_request()
+
+    with patch(
+        "routstr.upstream.base.recieve_token", new=AsyncMock(side_effect=error)
+    ):
+        handler = getattr(provider, handler_name)
+        response = await handler(
+            request=request,
+            x_cashu_token="cashuAtoken",
+            path="v1/chat/completions",
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+
+    if echoed:
+        assert response.headers.get("X-Cashu") == "cashuAtoken"
+    else:
+        assert "X-Cashu" not in response.headers
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("handler_name", "forward_attr"),
+    [
+        ("handle_x_cashu", "forward_x_cashu_request"),
+        ("handle_x_cashu_responses", "forward_x_cashu_responses_request"),
+    ],
+)
+@pytest.mark.parametrize("amount", [0, -5])
+async def test_x_cashu_zero_value_rejected_not_forwarded(
+    handler_name: str, forward_attr: str, amount: int
+) -> None:
+    """A token that redeems to <= 0 must be rejected as cashu_token_zero_value
+    (400) and NEVER forwarded as a free request — the X-Cashu path lacked the
+    guard that credit_balance has."""
+    provider = _make_provider()
+    model = _make_model()
+    request = _make_request()
+
+    with (
+        patch(
+            "routstr.upstream.base.recieve_token",
+            new=AsyncMock(return_value=(amount, "sat", "https://mint")),
+        ),
+        patch("routstr.upstream.base.store_cashu_transaction", new=AsyncMock()),
+        patch.object(
+            provider,
+            forward_attr,
+            new=AsyncMock(side_effect=AssertionError("must not forward a zero-value token")),
+        ),
+    ):
+        handler = getattr(provider, handler_name)
+        response = await handler(
+            request=request,
+            x_cashu_token="cashuAtoken",
+            path="v1/chat/completions",
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+
+    assert response.status_code == 400
+    body = json.loads(bytes(response.body))
+    assert body["error"]["type"] == "cashu_error"
+    assert (
+        body["error"]["message"]
+        == "Failed to redeem Cashu token: token yielded no value"
+    )
+    assert body["error"]["code"] == "cashu_token_zero_value"
+    # Spent-to-zero token must not be echoed back for retry.
+    assert "X-Cashu" not in response.headers

tests/unit/test_payment_helpers.py

@@ -7,7 +7,19 @@ os.environ["UPSTREAM_BASE_URL"] = "http://test"
 os.environ["UPSTREAM_API_KEY"] = "test"
 
 from routstr.core.settings import settings  # noqa: E402
-from routstr.payment.helpers import get_max_cost_for_model  # noqa: E402
+from routstr.payment.helpers import (  # noqa: E402
+    apply_mint_fee_allowance,
+    get_max_cost_for_model,
+)
+
+
+def test_mint_fee_allowance_reduces_admission_cost_by_ten_percent() -> None:
+    assert apply_mint_fee_allowance(124_886) == 112_398
+
+
+def test_mint_fee_allowance_never_drops_below_minimum() -> None:
+    with patch.object(settings, "min_request_msat", 100):
+        assert apply_mint_fee_allowance(50) == 100
 
 
 async def test_get_max_cost_for_model_known() -> None:

tests/unit/test_periodic_payout.py

@@ -0,0 +1,154 @@
+"""Tests for periodic_payout() resilience fixes.
+
+Covers two regressions from the auto-payout / primary-mint audit
+(docs/auto-payout-primary-mint-failure-report.md):
+
+1. periodic_payout() must include settings.primary_mint even when it is not
+   listed in settings.cashu_mints, matching fetch_all_balances(); otherwise
+   primary-mint funds never auto-payout.
+2. A failure on one mint/unit must not abort payout for the remaining
+   mint/units in the same cycle (the try/except is now per mint/unit).
+"""
+
+from collections.abc import Callable, Coroutine
+from contextlib import asynccontextmanager
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from routstr.wallet import periodic_payout
+
+# Sentinel interval used to break the otherwise-infinite payout loop after
+# exactly one full cycle.
+_INTERVAL = 987
+
+
+class _LoopBreak(Exception):
+    """Raised via the patched sleep to stop periodic_payout after one cycle."""
+
+
+@asynccontextmanager
+async def _fake_session():  # type: ignore[no-untyped-def]
+    yield MagicMock()
+
+
+def _one_cycle_sleep() -> Callable[[float], Coroutine[Any, Any, None]]:
+    """Return an async sleep stub that lets exactly one payout cycle run.
+
+    The top-of-loop sleep uses the sentinel interval; the second time it is
+    seen (start of the second cycle) we raise to break out. The inner
+    ``asyncio.sleep(5)`` pass-through is ignored.
+    """
+    seen = {"interval": 0}
+
+    async def _sleep(seconds: float) -> None:
+        if seconds == _INTERVAL:
+            seen["interval"] += 1
+            if seen["interval"] >= 2:
+                raise _LoopBreak()
+
+    return _sleep
+
+
+@pytest.mark.asyncio
+async def test_periodic_payout_includes_primary_mint_not_in_cashu_mints() -> None:
+    """primary_mint absent from cashu_mints is still paid out."""
+    from routstr.core.settings import settings
+
+    get_wallet = AsyncMock(return_value=MagicMock())
+    raw_send = AsyncMock(return_value=1000)
+
+    with patch.object(settings, "cashu_mints", []), patch.object(
+        settings, "primary_mint", "http://primary:3338"
+    ), patch.object(settings, "receive_ln_address", "owner@ln.tld"), patch.object(
+        settings, "payout_interval_seconds", _INTERVAL
+    ), patch.object(settings, "min_payout_sat", 10), patch(
+        "routstr.wallet.asyncio.sleep", _one_cycle_sleep()
+    ), patch("routstr.wallet.db.create_session", _fake_session), patch(
+        "routstr.wallet.get_wallet", get_wallet
+    ), patch(
+        "routstr.wallet.get_proofs_per_mint_and_unit",
+        MagicMock(return_value=[MagicMock(amount=100_000)]),
+    ), patch(
+        "routstr.wallet.slow_filter_spend_proofs",
+        AsyncMock(side_effect=lambda proofs, wallet: proofs),
+    ), patch(
+        "routstr.wallet.db.balances_for_mint_and_unit", AsyncMock(return_value=0)
+    ), patch("routstr.wallet.raw_send_to_lnurl", raw_send):
+        with pytest.raises(_LoopBreak):
+            await periodic_payout()
+
+    processed = {call.args[0] for call in get_wallet.await_args_list}
+    assert processed == {"http://primary:3338"}
+    assert raw_send.await_count >= 1
+
+
+@pytest.mark.asyncio
+async def test_periodic_payout_isolates_failing_mint() -> None:
+    """A failing mint does not prevent payout for the other mints."""
+    from routstr.core.settings import settings
+
+    async def _get_wallet(mint_url: str, unit: str) -> MagicMock:
+        if mint_url == "http://bad:3338":
+            raise RuntimeError("mint unreachable")
+        return MagicMock()
+
+    get_wallet = AsyncMock(side_effect=_get_wallet)
+    raw_send = AsyncMock(return_value=1000)
+
+    with patch.object(
+        settings, "cashu_mints", ["http://bad:3338", "http://good:3338"]
+    ), patch.object(settings, "primary_mint", "http://good:3338"), patch.object(
+        settings, "receive_ln_address", "owner@ln.tld"
+    ), patch.object(settings, "payout_interval_seconds", _INTERVAL), patch.object(
+        settings, "min_payout_sat", 10
+    ), patch("routstr.wallet.asyncio.sleep", _one_cycle_sleep()), patch(
+        "routstr.wallet.db.create_session", _fake_session
+    ), patch("routstr.wallet.get_wallet", get_wallet), patch(
+        "routstr.wallet.get_proofs_per_mint_and_unit",
+        MagicMock(return_value=[MagicMock(amount=100_000)]),
+    ), patch(
+        "routstr.wallet.slow_filter_spend_proofs",
+        AsyncMock(side_effect=lambda proofs, wallet: proofs),
+    ), patch(
+        "routstr.wallet.db.balances_for_mint_and_unit", AsyncMock(return_value=0)
+    ), patch("routstr.wallet.raw_send_to_lnurl", raw_send):
+        with pytest.raises(_LoopBreak):
+            await periodic_payout()
+
+    # The bad mint raised on get_wallet for both units, yet the good mint was
+    # still reached and paid out for both units — failures are isolated.
+    good_calls = [
+        c for c in get_wallet.await_args_list if c.args[0] == "http://good:3338"
+    ]
+    assert len(good_calls) == 2  # sat + msat
+    assert raw_send.await_count == 2  # good mint paid for both units
+
+
+@pytest.mark.asyncio
+async def test_periodic_payout_handles_session_creation_failure() -> None:
+    """A db.create_session failure is logged and the payout loop continues."""
+    from routstr.core.settings import settings
+
+    create_session = MagicMock(side_effect=RuntimeError("db unavailable"))
+    logger = MagicMock()
+
+    with patch.object(settings, "cashu_mints", ["http://mint:3338"]), patch.object(
+        settings, "primary_mint", "http://mint:3338"
+    ), patch.object(settings, "receive_ln_address", "owner@ln.tld"), patch.object(
+        settings, "payout_interval_seconds", _INTERVAL
+    ), patch(
+        "routstr.wallet.asyncio.sleep", _one_cycle_sleep()
+    ), patch(
+        "routstr.wallet.db.create_session", create_session
+    ), patch("routstr.wallet.logger", logger):
+        with pytest.raises(_LoopBreak):
+            await periodic_payout()
+
+    create_session.assert_called_once()
+    logger.error.assert_called_once()
+    message = logger.error.call_args.args[0]
+    extra = logger.error.call_args.kwargs["extra"]
+    assert message == "Error in periodic payout cycle: RuntimeError"
+    assert extra == {"error": "db unavailable"}

tests/unit/test_require_parameters.py

@@ -1,95 +0,0 @@
-import json
-import os
-
-os.environ.setdefault("UPSTREAM_BASE_URL", "http://test")
-os.environ.setdefault("UPSTREAM_API_KEY", "test")
-os.environ.setdefault("LIGHTNING_ADDRESS", "test@stm.to")
-
-from routstr.upstream import GenericUpstreamProvider
-from routstr.upstream.openrouter import OpenRouterUpstreamProvider
-
-
-def _model(model_id: str = "openai/gpt-4o"):  # type: ignore[no-untyped-def]
-    from routstr.payment.models import Architecture, Model, Pricing
-
-    return Model(
-        id=model_id,
-        name=model_id,
-        created=0,
-        description="",
-        context_length=128000,
-        architecture=Architecture(
-            modality="text->text",
-            input_modalities=["text"],
-            output_modalities=["text"],
-            tokenizer="GPT",
-            instruct_type=None,
-        ),
-        pricing=Pricing(prompt=0.0, completion=0.0),
-    )
-
-
-def _tool_body() -> dict:
-    return {
-        "model": "openai/gpt-4o",
-        "messages": [{"role": "user", "content": "What's the weather?"}],
-        "tools": [
-            {
-                "type": "function",
-                "function": {"name": "get_weather", "parameters": {}},
-            }
-        ],
-    }
-
-
-def _prepare(provider, body: dict) -> dict:  # type: ignore[no-untyped-def]
-    out = provider.prepare_request_body(json.dumps(body).encode(), _model())
-    assert out is not None
-    return json.loads(out)
-
-
-def test_injects_require_parameters_for_tool_request() -> None:
-    data = _prepare(OpenRouterUpstreamProvider(api_key="test"), _tool_body())
-    assert data["provider"]["require_parameters"] is True
-
-
-def test_generic_provider_on_openrouter_url_is_left_alone() -> None:
-    # Only OpenRouterUpstreamProvider injects; a generic provider pointed at the
-    # same base URL doesn't.
-    provider = GenericUpstreamProvider(base_url="https://openrouter.ai/api/v1")
-    data = _prepare(provider, _tool_body())
-    assert "provider" not in data
-
-
-def test_no_injection_without_tools() -> None:
-    body = {"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "hi"}]}
-    data = _prepare(OpenRouterUpstreamProvider(api_key="test"), body)
-    assert "provider" not in data
-
-
-def test_empty_tools_list_does_not_inject() -> None:
-    body = _tool_body()
-    body["tools"] = []
-    data = _prepare(OpenRouterUpstreamProvider(api_key="test"), body)
-    assert "provider" not in data
-
-
-def test_direct_provider_does_not_inject() -> None:
-    provider = GenericUpstreamProvider(base_url="https://api.openai.com/v1")
-    data = _prepare(provider, _tool_body())
-    assert "provider" not in data
-
-
-def test_keeps_client_set_require_parameters() -> None:
-    body = _tool_body()
-    body["provider"] = {"require_parameters": False}
-    data = _prepare(OpenRouterUpstreamProvider(api_key="test"), body)
-    assert data["provider"]["require_parameters"] is False
-
-
-def test_preserves_other_provider_fields() -> None:
-    body = _tool_body()
-    body["provider"] = {"order": ["openai", "azure"]}
-    data = _prepare(OpenRouterUpstreamProvider(api_key="test"), body)
-    assert data["provider"]["order"] == ["openai", "azure"]
-    assert data["provider"]["require_parameters"] is True

tests/unit/test_stale_reservations.py

@@ -375,4 +375,4 @@ async def test_proxy_reverts_reservation_on_client_disconnect() -> None:
         with pytest.raises(asyncio.CancelledError):
             await proxy_module.proxy(request, "v1/chat/completions", session=session)
 
-    revert_mock.assert_awaited_once_with(key, session, 1_000)
+    revert_mock.assert_awaited_once_with(key, session, 900)

tests/unit/test_upstream_generic.py

@@ -0,0 +1,524 @@
+"""Unit tests for ``GenericUpstreamProvider.fetch_models`` price/metadata resolution.
+
+A generic upstream is any OpenAI-compatible API. Most (DeepSeek, OpenAI,
+Groq, ...) answer ``/models`` with bare ``{id, object, owned_by}`` entries that
+carry *no* pricing. The provider must not fabricate a price for those: it
+resolves through native ``model_spec`` (Venice's bespoke schema) → litellm's
+bundled cost map → the OpenRouter feed, and only when every source misses does
+it import the model **disabled** with a warning rather than invent a number.
+
+These tests drive that behaviour through the public ``fetch_models`` API. The
+``/models`` HTTP call is faked at ``httpx.AsyncClient``; the OpenRouter feed is
+patched at its source (``routstr.payment.models.async_fetch_openrouter_models``)
+so the resolver's lazy import picks up the stub. litellm's real bundled cost map
+is used unmocked — the DeepSeek rates it ships are the assertion's ground truth.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from routstr.upstream.generic import GenericUpstreamProvider
+
+
+class _FakeResponse:
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self._payload = payload
+
+    def raise_for_status(self) -> None:
+        return None
+
+    def json(self) -> dict[str, Any]:
+        return self._payload
+
+
+class _FakeAsyncClient:
+    """Stand-in for ``httpx.AsyncClient`` returning a canned ``/models`` body."""
+
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self._payload = payload
+
+    async def __aenter__(self) -> "_FakeAsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: object) -> bool:
+        return False
+
+    async def get(self, url: str, headers: dict[str, str] | None = None) -> _FakeResponse:
+        return _FakeResponse(self._payload)
+
+
+def _patch_models_endpoint(payload: dict[str, Any]) -> Any:
+    """Patch the provider's ``httpx.AsyncClient`` to serve ``payload``."""
+    return patch(
+        "routstr.upstream.generic.httpx.AsyncClient",
+        lambda *args, **kwargs: _FakeAsyncClient(payload),
+    )
+
+
+def _model_by_id(models: list[Any], model_id: str) -> Any:
+    return next(m for m in models if m.id == model_id)
+
+
+# ---------------------------------------------------------------------------
+# native model_spec (Venice) — must keep resolving, and capture its metadata
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_native_model_spec_resolves_and_captures_metadata() -> None:
+    """A Venice-shaped ``model_spec`` is authoritative: prices/context come
+    straight from it and vision capability becomes an image input modality."""
+    payload = {
+        "data": [
+            {
+                "id": "venice-llama",
+                "owned_by": "venice",
+                "model_spec": {
+                    "name": "Venice Llama",
+                    "availableContextTokens": 65536,
+                    "pricing": {
+                        "input": {"usd": 0.5},
+                        "output": {"usd": 1.5},
+                    },
+                    "capabilities": {"supportsVision": True},
+                },
+            }
+        ]
+    }
+
+    with _patch_models_endpoint(payload):
+        or_feed = AsyncMock(return_value=[])
+        with patch(
+            "routstr.payment.models.async_fetch_openrouter_models", or_feed
+        ):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    model = _model_by_id(models, "venice-llama")
+    assert model.enabled is True
+    assert model.pricing.prompt == pytest.approx(0.5 / 1_000_000)
+    assert model.pricing.completion == pytest.approx(1.5 / 1_000_000)
+    assert model.context_length == 65536
+    assert "image" in model.architecture.input_modalities
+    # Vision capability must be reflected in the combined modality string, not
+    # flattened to "text->text".
+    assert model.architecture.modality == "text+image->text"
+    # A native price never needs the OpenRouter feed.
+    or_feed.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# native model_spec validation — a bogus native price is not authoritative
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_native_both_zero_price_falls_through_to_litellm() -> None:
+    """A native ``model_spec`` that prices both tokens at 0 is not a real price
+    (the same free-tier trap the litellm/OpenRouter rungs already reject). It
+    must not be treated as authoritative and served free; the resolver falls
+    through, so a litellm-known model lands on litellm's real rate instead."""
+    payload = {
+        "data": [
+            {
+                "id": "deepseek-chat",
+                "owned_by": "deepseek",
+                "model_spec": {
+                    "pricing": {"input": {"usd": 0}, "output": {"usd": 0}},
+                },
+            }
+        ]
+    }
+
+    with _patch_models_endpoint(payload):
+        or_feed = AsyncMock(return_value=[])
+        with patch("routstr.payment.models.async_fetch_openrouter_models", or_feed):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    model = _model_by_id(models, "deepseek-chat")
+    assert model.enabled is True
+    assert model.pricing.prompt == pytest.approx(2.8e-07)
+    assert model.pricing.completion == pytest.approx(4.2e-07)
+
+
+@pytest.mark.asyncio
+async def test_native_negative_price_falls_through_to_litellm() -> None:
+    """A negative native price would credit the caller's balance on every
+    request (a fund drain, not a discount). Reject it like any other unusable
+    price and fall through to the chain."""
+    payload = {
+        "data": [
+            {
+                "id": "deepseek-chat",
+                "owned_by": "deepseek",
+                "model_spec": {
+                    "pricing": {"input": {"usd": -0.5}, "output": {"usd": -1.5}},
+                },
+            }
+        ]
+    }
+
+    with _patch_models_endpoint(payload):
+        or_feed = AsyncMock(return_value=[])
+        with patch("routstr.payment.models.async_fetch_openrouter_models", or_feed):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    model = _model_by_id(models, "deepseek-chat")
+    assert model.enabled is True
+    assert model.pricing.prompt == pytest.approx(2.8e-07)
+    assert model.pricing.completion == pytest.approx(4.2e-07)
+
+
+@pytest.mark.asyncio
+async def test_native_non_numeric_price_does_not_break_catalog() -> None:
+    """A non-numeric native price (``"free"``) must not raise while parsing —
+    an unguarded ``"free" / 1_000_000`` throws and the outer catch drops the
+    *entire* provider catalog. It has to fail closed for that one model while
+    every other model in the same response still resolves."""
+    payload = {
+        "data": [
+            {
+                "id": "broken-price",
+                "owned_by": "mystery",
+                "model_spec": {
+                    "pricing": {"input": {"usd": "free"}, "output": {"usd": "free"}},
+                },
+            },
+            {"id": "deepseek-chat", "object": "model", "owned_by": "deepseek"},
+        ]
+    }
+
+    with _patch_models_endpoint(payload):
+        or_feed = AsyncMock(return_value=[])
+        with patch("routstr.payment.models.async_fetch_openrouter_models", or_feed):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    # One malformed entry must not empty the catalog.
+    assert {m.id for m in models} == {"broken-price", "deepseek-chat"}
+    broken = _model_by_id(models, "broken-price")
+    assert broken.enabled is False
+    healthy = _model_by_id(models, "deepseek-chat")
+    assert healthy.enabled is True
+    assert healthy.pricing.prompt == pytest.approx(2.8e-07)
+
+
+# ---------------------------------------------------------------------------
+# litellm rescue — the money-critical case (DeepSeek bare /models)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_bare_deepseek_resolves_via_litellm() -> None:
+    """DeepSeek's ``/models`` carries no pricing. The old code fabricated
+    ``$0.001`` + ctx 4096; the resolver must instead pull DeepSeek's real
+    rates from litellm's bundled cost map (``$0.28``/``$0.42`` per 1M, ctx
+    131072) and keep the model enabled."""
+    payload = {
+        "data": [
+            {"id": "deepseek-chat", "object": "model", "owned_by": "deepseek"},
+        ]
+    }
+
+    with _patch_models_endpoint(payload):
+        or_feed = AsyncMock(return_value=[])
+        with patch(
+            "routstr.payment.models.async_fetch_openrouter_models", or_feed
+        ):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    model = _model_by_id(models, "deepseek-chat")
+    assert model.enabled is True
+    assert model.pricing.prompt == pytest.approx(2.8e-07)
+    assert model.pricing.completion == pytest.approx(4.2e-07)
+    assert model.context_length == 131072
+    # Richer metadata than the two base prices is captured too.
+    assert model.pricing.input_cache_read == pytest.approx(2.8e-08)
+    assert model.top_provider is not None
+    assert model.top_provider.max_completion_tokens == 8192
+    # litellm answered, so the OpenRouter feed is never consulted.
+    or_feed.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_litellm_zero_price_entry_fails_closed(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A litellm entry that lists a model but prices it at 0/0 (free-tier
+    moderation/rerank models do this) is not a real price — treating it as one
+    would silently serve the model for free. The resolver must reject a both-zero
+    litellm hit and fall through, so the model imports disabled, not at $0."""
+    payload = {
+        "data": [
+            {"id": "omni-moderation-latest", "object": "model", "owned_by": "openai"},
+        ]
+    }
+
+    gen_logger = logging.getLogger("routstr.upstream.generic")
+    gen_logger.addHandler(caplog.handler)
+    try:
+        with _patch_models_endpoint(payload):
+            or_feed = AsyncMock(return_value=[])
+            with patch(
+                "routstr.payment.models.async_fetch_openrouter_models", or_feed
+            ):
+                models = await GenericUpstreamProvider(
+                    base_url="http://x"
+                ).fetch_models()
+    finally:
+        gen_logger.removeHandler(caplog.handler)
+
+    model = _model_by_id(models, "omni-moderation-latest")
+    assert model.enabled is False
+    assert model.pricing.prompt == 0.0
+    assert model.pricing.completion == 0.0
+    assert any(
+        "omni-moderation-latest" in rec.getMessage()
+        for rec in caplog.records
+        if rec.levelno >= logging.WARNING
+    )
+
+
+@pytest.mark.asyncio
+async def test_litellm_output_cap_not_used_as_context() -> None:
+    """litellm's ``max_tokens`` is the completion cap, not the context window
+    (it tracks ``max_output_tokens`` for ~94% of models). When a model reports
+    no ``max_input_tokens``, the resolver must not smuggle the output cap in as
+    the context window; it falls back to the id-based estimate instead, while
+    ``max_tokens`` still feeds the completion limit."""
+    payload = {
+        "data": [
+            {
+                "id": "gemini/gemini-gemma-2-9b-it",
+                "object": "model",
+                "owned_by": "google",
+            },
+        ]
+    }
+
+    with _patch_models_endpoint(payload):
+        or_feed = AsyncMock(return_value=[])
+        with patch(
+            "routstr.payment.models.async_fetch_openrouter_models", or_feed
+        ):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    model = _model_by_id(models, "gemini/gemini-gemma-2-9b-it")
+    assert model.enabled is True
+    # litellm gives this model max_input_tokens=None, max_tokens=8192 (an output
+    # cap). Context must come from the estimate (4096), never the 8192 cap.
+    assert model.context_length == 4096
+    # The 8192 output cap still lands where it belongs: the completion limit.
+    assert model.top_provider is not None
+    assert model.top_provider.max_completion_tokens == 8192
+
+
+# ---------------------------------------------------------------------------
+# OpenRouter fallback — litellm misses, OR carries a full payload
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_unknown_to_litellm_resolves_via_openrouter() -> None:
+    """A model litellm has never heard of still resolves if the OpenRouter
+    feed lists it, pulling price + context from that entry."""
+    payload = {
+        "data": [
+            {"id": "exotic/model-9000", "object": "model", "owned_by": "exotic"},
+        ]
+    }
+    or_entry = {
+        "id": "exotic/model-9000",
+        "name": "Exotic 9000",
+        "context_length": 65536,
+        "architecture": {
+            "modality": "text+image->text",
+            "input_modalities": ["text", "image"],
+            "output_modalities": ["text"],
+            "tokenizer": "Other",
+            "instruct_type": None,
+        },
+        "pricing": {"prompt": "0.000005", "completion": "0.000010"},
+        "top_provider": {
+            "context_length": 65536,
+            "max_completion_tokens": 4096,
+            "is_moderated": False,
+        },
+    }
+
+    with _patch_models_endpoint(payload):
+        or_feed = AsyncMock(return_value=[or_entry])
+        with patch(
+            "routstr.payment.models.async_fetch_openrouter_models", or_feed
+        ):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    model = _model_by_id(models, "exotic/model-9000")
+    assert model.enabled is True
+    assert model.pricing.prompt == pytest.approx(5e-06)
+    assert model.pricing.completion == pytest.approx(1e-05)
+    assert model.context_length == 65536
+    # The feed's own modality string is carried through verbatim, not recomputed.
+    assert model.architecture.modality == "text+image->text"
+    or_feed.assert_awaited()
+
+
+@pytest.mark.asyncio
+async def test_openrouter_bare_tail_collision_picks_highest_price() -> None:
+    """When a bare model id matches several OpenRouter entries by tail
+    (``model`` ↔ ``a/model``, ``b/model``), the match must be deterministic and
+    money-safe: pick the highest-priced candidate regardless of feed order, so
+    ordering can never leave the node charging below true cost. (The live feed
+    has zero such collisions today; this guards the latent case.)"""
+    payload = {
+        "data": [
+            {"id": "zzz-phantom-model", "object": "model", "owned_by": "mystery"},
+        ]
+    }
+    # Same bare tail, different resellers; the pricier one is listed *second*
+    # so a first-wins match would pick the cheaper (undercharging) entry.
+    or_feed = AsyncMock(
+        return_value=[
+            {
+                "id": "cheapco/zzz-phantom-model",
+                "context_length": 8192,
+                "pricing": {"prompt": "0.000001", "completion": "0.000002"},
+            },
+            {
+                "id": "premiumco/zzz-phantom-model",
+                "context_length": 8192,
+                "pricing": {"prompt": "0.000009", "completion": "0.000010"},
+            },
+        ]
+    )
+
+    with _patch_models_endpoint(payload):
+        with patch("routstr.payment.models.async_fetch_openrouter_models", or_feed):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    model = _model_by_id(models, "zzz-phantom-model")
+    assert model.pricing.prompt == pytest.approx(9e-06)
+    assert model.pricing.completion == pytest.approx(1e-05)
+
+
+@pytest.mark.asyncio
+async def test_openrouter_bare_tail_tie_breaks_on_combined_cost() -> None:
+    """The bare-tail tie-break must weigh *both* rates, not prompt alone.
+    Given two colliding entries where one is cheaper on prompt but far dearer
+    on completion, ranking by prompt would pick the entry that undercharges
+    output-heavy traffic. Pick the highest *combined* per-token cost so the
+    money-safe choice holds whichever way the traffic leans."""
+    payload = {
+        "data": [
+            {"id": "yyy-phantom-model", "object": "model", "owned_by": "mystery"},
+        ]
+    }
+    # dear-overall is listed first with the *lower* prompt, so a prompt-only max
+    # would wrongly pick the second (cheaper-overall) entry.
+    or_feed = AsyncMock(
+        return_value=[
+            {
+                "id": "dearco/yyy-phantom-model",
+                "context_length": 8192,
+                "pricing": {"prompt": "0.000001", "completion": "0.000100"},
+            },
+            {
+                "id": "cheapco/yyy-phantom-model",
+                "context_length": 8192,
+                "pricing": {"prompt": "0.000009", "completion": "0.000002"},
+            },
+        ]
+    )
+
+    with _patch_models_endpoint(payload):
+        with patch("routstr.payment.models.async_fetch_openrouter_models", or_feed):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    model = _model_by_id(models, "yyy-phantom-model")
+    assert model.pricing.prompt == pytest.approx(1e-06)
+    assert model.pricing.completion == pytest.approx(1e-04)
+
+
+@pytest.mark.asyncio
+async def test_openrouter_feed_fetched_once_per_discovery() -> None:
+    """Two models both missing litellm must share a single OpenRouter fetch —
+    the feed is not re-downloaded per model."""
+    payload = {
+        "data": [
+            {"id": "exotic/model-a", "object": "model", "owned_by": "exotic"},
+            {"id": "exotic/model-b", "object": "model", "owned_by": "exotic"},
+        ]
+    }
+    or_feed = AsyncMock(
+        return_value=[
+            {
+                "id": "exotic/model-a",
+                "context_length": 8192,
+                "pricing": {"prompt": "0.000001", "completion": "0.000002"},
+            },
+            {
+                "id": "exotic/model-b",
+                "context_length": 8192,
+                "pricing": {"prompt": "0.000003", "completion": "0.000004"},
+            },
+        ]
+    )
+
+    with _patch_models_endpoint(payload):
+        with patch("routstr.payment.models.async_fetch_openrouter_models", or_feed):
+            models = await GenericUpstreamProvider(base_url="http://x").fetch_models()
+
+    assert {m.id for m in models} == {"exotic/model-a", "exotic/model-b"}
+    assert or_feed.await_count == 1
+
+
+# ---------------------------------------------------------------------------
+# fail closed — no source resolves → disabled + warned, never fabricated
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_unresolvable_model_fails_closed(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """When native, litellm and OpenRouter all miss, the model is imported
+    disabled with a warning naming it — and no price is invented (the old
+    ``$0.001`` placeholder is gone)."""
+    payload = {
+        "data": [
+            {
+                "id": "nobody-has-priced-this-xyz",
+                "object": "model",
+                "owned_by": "mystery",
+            },
+        ]
+    }
+
+    # routstr loggers set propagate=False, so caplog's root handler misses
+    # them; attach its handler to the provider logger directly.
+    gen_logger = logging.getLogger("routstr.upstream.generic")
+    gen_logger.addHandler(caplog.handler)
+    try:
+        with _patch_models_endpoint(payload):
+            or_feed = AsyncMock(return_value=[])
+            with patch(
+                "routstr.payment.models.async_fetch_openrouter_models", or_feed
+            ):
+                models = await GenericUpstreamProvider(
+                    base_url="http://x"
+                ).fetch_models()
+    finally:
+        gen_logger.removeHandler(caplog.handler)
+
+    model = _model_by_id(models, "nobody-has-priced-this-xyz")
+    assert model.enabled is False
+    assert model.pricing.prompt == 0.0
+    assert model.pricing.completion == 0.0
+    assert any(
+        "nobody-has-priced-this-xyz" in rec.getMessage()
+        for rec in caplog.records
+        if rec.levelno >= logging.WARNING
+    )

tests/unit/test_upstream_rate_limit.py

@@ -393,4 +393,4 @@ async def test_proxy_loop_surfaces_rate_limit_and_reverts_once() -> None:
     assert RAW_ORG_ID not in serialized
     assert "org-[REDACTED]" in serialized
     # Single upstream failed -> reservation reverted exactly once (no double-charge).
-    revert_mock.assert_awaited_once_with(key, session, 1_000)
+    revert_mock.assert_awaited_once_with(key, session, 900)

ui/Dockerfile

@@ -4,15 +4,15 @@ FROM base AS deps
 RUN apk add --no-cache libc6-compat
 WORKDIR /app
 
-RUN corepack enable pnpm && corepack prepare pnpm@latest --activate
+RUN corepack enable pnpm && corepack prepare pnpm@10.15.0 --activate
 
-COPY package.json pnpm-lock.yaml* ./
+COPY package.json pnpm-lock.yaml* pnpm-workspace.yaml* ./
 RUN pnpm install --frozen-lockfile
 
 FROM base AS builder
 WORKDIR /app
 
-RUN corepack enable pnpm && corepack prepare pnpm@latest --activate
+RUN corepack enable pnpm && corepack prepare pnpm@10.15.0 --activate
 
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .

ui/Dockerfile.build

@@ -6,14 +6,14 @@ RUN apk add --no-cache libc6-compat
 WORKDIR /app
 
 # Copy package files
-COPY package.json pnpm-lock.yaml* ./
-RUN corepack enable pnpm && corepack prepare pnpm@latest --activate
+COPY package.json pnpm-lock.yaml* pnpm-workspace.yaml* ./
+RUN corepack enable pnpm && corepack prepare pnpm@10.15.0 --activate
 RUN pnpm install --frozen-lockfile
 
 # Build the UI
 FROM base AS builder
 WORKDIR /app
-RUN corepack enable pnpm && corepack prepare pnpm@latest --activate
+RUN corepack enable pnpm && corepack prepare pnpm@10.15.0 --activate
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 

ui/components/detailed-wallet-balance.tsx

@@ -105,6 +105,23 @@ export function DetailedWalletBalance({
   const formatMintLabel = (detail: BalanceDetail) =>
     `${detail.mint_url.replace('https://', '').replace('http://', '')} • ${detail.unit.toUpperCase()}`;
 
+  const formatBalanceError = (detail: BalanceDetail) => {
+    const labels: Record<string, string> = {
+      rate_limited: 'rate limited',
+      unreachable: 'unreachable',
+      cooldown: 'cooling down',
+      mint_error: 'mint error',
+    };
+    const label =
+      (detail.error_code ? labels[detail.error_code] : undefined) ??
+      detail.error ??
+      'error';
+    const retryAfter = detail.retry_after_seconds;
+    return retryAfter && retryAfter > 0
+      ? `${label} (retry in ${Math.ceil(retryAfter)}s)`
+      : label;
+  };
+
   return (
     <>
       <Card>
@@ -262,9 +279,12 @@ export function DetailedWalletBalance({
                               <TableCell className='max-w-md font-mono text-xs break-all whitespace-normal'>
                                 {formatMintLabel(detail)}
                               </TableCell>
-                              <TableCell className='text-right font-mono'>
+                              <TableCell
+                                className='text-right font-mono'
+                                title={detail.error}
+                              >
                                 {detail.error
-                                  ? 'error'
+                                  ? formatBalanceError(detail)
                                   : formatAmount(walletMsat)}
                               </TableCell>
                               <TableCell className='text-right font-mono'>
@@ -306,9 +326,12 @@ export function DetailedWalletBalance({
                               <p className='text-muted-foreground text-xs'>
                                 Wallet
                               </p>
-                              <p className='font-mono text-sm'>
+                              <p
+                                className='font-mono text-sm'
+                                title={detail.error}
+                              >
                                 {detail.error
-                                  ? 'error'
+                                  ? formatBalanceError(detail)
                                   : formatAmount(walletMsat)}
                               </p>
                             </div>

ui/lib/api/services/wallet.ts

@@ -36,6 +36,8 @@ export interface BalanceDetail {
   user_balance: number;
   owner_balance: number;
   error?: string;
+  error_code?: 'rate_limited' | 'unreachable' | 'cooldown' | 'mint_error';
+  retry_after_seconds?: number;
 }
 
 export interface WithdrawResponse {

ui/package.json

@@ -45,7 +45,7 @@
     "@radix-ui/react-tooltip": "^1.2.8",
     "@tanstack/react-query": "^5.90.21",
     "@tanstack/react-table": "^8.21.3",
-    "axios": "^1.13.5",
+    "axios": "^1.16.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
@@ -54,7 +54,7 @@
     "geist": "^1.7.0",
     "input-otp": "^1.4.2",
     "lucide-react": "^0.575.0",
-    "next": "16.1.6",
+    "next": "16.2.6",
     "next-themes": "^0.4.6",
     "qrcode": "^1.5.4",
     "qrcode.react": "^4.2.0",
@@ -81,7 +81,7 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "eslint": "^9.7.0",
-    "eslint-config-next": "16.1.6",
+    "eslint-config-next": "16.2.6",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-react": "^7.37.5",
@@ -89,11 +89,5 @@
     "prettier-plugin-tailwindcss": "^0.7.2",
     "tailwindcss": "^4.2.0",
     "typescript": "^5.9.3"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "sharp",
-      "unrs-resolver"
-    ]
   }
 }

ui/pnpm-lock.yaml

@@ -4,6 +4,20 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+overrides:
+  '@babel/core': 7.29.6
+  flatted: 3.4.2
+  follow-redirects: 1.16.0
+  form-data: 4.0.6
+  ajv@6: 6.14.0
+  brace-expansion@1: 1.1.13
+  brace-expansion@5: 5.0.6
+  js-yaml: 4.2.0
+  minimatch@3: 3.1.4
+  picomatch@2: 2.3.2
+  picomatch@4: 4.0.4
+  postcss: 8.5.10
+
 importers:
 
   .:
@@ -105,8 +119,8 @@ importers:
         specifier: ^8.21.3
         version: 8.21.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       axios:
-        specifier: ^1.13.5
-        version: 1.13.6
+        specifier: ^1.16.0
+        version: 1.18.1
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -124,7 +138,7 @@ importers:
         version: 8.6.0(react@19.2.4)
       geist:
         specifier: ^1.7.0
-        version: 1.7.0(next@16.1.6(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
+        version: 1.7.0(next@16.2.6(@babel/core@7.29.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
       input-otp:
         specifier: ^1.4.2
         version: 1.4.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -132,8 +146,8 @@ importers:
         specifier: ^0.575.0
         version: 0.575.0(react@19.2.4)
       next:
-        specifier: 16.1.6
-        version: 16.1.6(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+        specifier: 16.2.6
+        version: 16.2.6(@babel/core@7.29.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       next-themes:
         specifier: ^0.4.6
         version: 0.4.6(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -208,8 +222,8 @@ importers:
         specifier: ^9.7.0
         version: 9.38.0(jiti@2.6.1)
       eslint-config-next:
-        specifier: 16.1.6
-        version: 16.1.6(@typescript-eslint/parser@8.57.0(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3))(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3)
+        specifier: 16.2.6
+        version: 16.2.6(@typescript-eslint/parser@8.57.0(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3))(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3)
       eslint-config-prettier:
         specifier: ^10.1.8
         version: 10.1.8(eslint@9.38.0(jiti@2.6.1))
@@ -242,16 +256,20 @@ packages:
     resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/code-frame@7.29.7':
+    resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
+    engines: {node: '>=6.9.0'}
+
   '@babel/compat-data@7.29.0':
     resolution: {integrity: sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/core@7.29.0':
-    resolution: {integrity: sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==}
+  '@babel/core@7.29.6':
+    resolution: {integrity: sha512-QdxmAo/ikZqqRGA8s43ww8lcql6naWRvEz0FFrl6MIlc7Gi6TroXnSdWa5U/kq6fzcpqpHesicQxFZIieZbyIA==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/generator@7.29.1':
-    resolution: {integrity: sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==}
+  '@babel/generator@7.29.7':
+    resolution: {integrity: sha512-DkXD5OJQaAQIdZ1bt3UZdEnHAn9Imd3IVBdX03UFe+ony9Ojw5pzr9YVKGDY1jt+Gcn/FnGkNf8r+Vj5NOJWtQ==}
     engines: {node: '>=6.9.0'}
 
   '@babel/helper-compilation-targets@7.28.6':
@@ -270,22 +288,30 @@ packages:
     resolution: {integrity: sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==}
     engines: {node: '>=6.9.0'}
     peerDependencies:
-      '@babel/core': ^7.0.0
+      '@babel/core': 7.29.6
 
   '@babel/helper-string-parser@7.27.1':
     resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/helper-string-parser@7.29.7':
+    resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
+    engines: {node: '>=6.9.0'}
+
   '@babel/helper-validator-identifier@7.28.5':
     resolution: {integrity: sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/helper-validator-identifier@7.29.7':
+    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==}
+    engines: {node: '>=6.9.0'}
+
   '@babel/helper-validator-option@7.27.1':
     resolution: {integrity: sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helpers@7.28.6':
-    resolution: {integrity: sha512-xOBvwq86HHdB7WUDTfKfT/Vuxh7gElQ+Sfti2Cy6yIWNW05P8iUslOVcZ4/sKbE+/jQaukQAdz/gf3724kYdqw==}
+  '@babel/helpers@7.29.7':
+    resolution: {integrity: sha512-1k2lAGRMfHTcwuNYcCNUmaUffmQv8KWMfh2iJUUeRlwlwH4FdNG7mfPI10NPfLHJFThE4Tyr4mv7kTNZOiPuBg==}
     engines: {node: '>=6.9.0'}
 
   '@babel/parser@7.29.0':
@@ -293,6 +319,11 @@ packages:
     engines: {node: '>=6.0.0'}
     hasBin: true
 
+  '@babel/parser@7.29.7':
+    resolution: {integrity: sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
   '@babel/runtime@7.28.6':
     resolution: {integrity: sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==}
     engines: {node: '>=6.9.0'}
@@ -301,6 +332,10 @@ packages:
     resolution: {integrity: sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/template@7.29.7':
+    resolution: {integrity: sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==}
+    engines: {node: '>=6.9.0'}
+
   '@babel/traverse@7.29.0':
     resolution: {integrity: sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==}
     engines: {node: '>=6.9.0'}
@@ -309,6 +344,10 @@ packages:
     resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/types@7.29.7':
+    resolution: {integrity: sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==}
+    engines: {node: '>=6.9.0'}
+
   '@base-ui/react@1.2.0':
     resolution: {integrity: sha512-O6aEQHcm+QyGTFY28xuwRD3SEJGZOBDpyjN2WvpfWYFVhg+3zfXPysAILqtM0C1kWC82MccOE/v1j+GHXE4qIw==}
     engines: {node: '>=14.0.0'}
@@ -600,56 +639,56 @@ packages:
   '@napi-rs/wasm-runtime@0.2.12':
     resolution: {integrity: sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==}
 
-  '@next/env@16.1.6':
-    resolution: {integrity: sha512-N1ySLuZjnAtN3kFnwhAwPvZah8RJxKasD7x1f8shFqhncnWZn4JMfg37diLNuoHsLAlrDfM3g4mawVdtAG8XLQ==}
+  '@next/env@16.2.6':
+    resolution: {integrity: sha512-gd8HoHN4ufj73WmR3JmVolrpJR47ILK6LouP5xElPglaVxir6e1a7VzvTvDWkOoPXT9rkkTzyCxBu4yeZfZwcw==}
 
-  '@next/eslint-plugin-next@16.1.6':
-    resolution: {integrity: sha512-/Qq3PTagA6+nYVfryAtQ7/9FEr/6YVyvOtl6rZnGsbReGLf0jZU6gkpr1FuChAQpvV46a78p4cmHOVP8mbfSMQ==}
+  '@next/eslint-plugin-next@16.2.6':
+    resolution: {integrity: sha512-Z8l6o4JWKUl755x4R+wogD86KPeU+Ckw4K+SYG4kHeOJtRenDeK+OSbGcqZpDtbwn9DsJVdir2UxmwXuinUbUw==}
 
-  '@next/swc-darwin-arm64@16.1.6':
-    resolution: {integrity: sha512-wTzYulosJr/6nFnqGW7FrG3jfUUlEf8UjGA0/pyypJl42ExdVgC6xJgcXQ+V8QFn6niSG2Pb8+MIG1mZr2vczw==}
+  '@next/swc-darwin-arm64@16.2.6':
+    resolution: {integrity: sha512-ZJGkkcNfYgrrMkqOdZ7zoLa1TOy0qpcMfk/z4Mh/FKUz40gVO+HNQWqmLxf67Z5WB64DRp0dhEbyHfel+6sJUg==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [darwin]
 
-  '@next/swc-darwin-x64@16.1.6':
-    resolution: {integrity: sha512-BLFPYPDO+MNJsiDWbeVzqvYd4NyuRrEYVB5k2N3JfWncuHAy2IVwMAOlVQDFjj+krkWzhY2apvmekMkfQR0CUQ==}
+  '@next/swc-darwin-x64@16.2.6':
+    resolution: {integrity: sha512-v/YLBHIY132Ced3puBJ7YJKw1lqsCrgcNo2aRJlCEyQrrCeRJlvGlnmxhPxNQI3KE3N1DN5r9TPNPvka3nq5RQ==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [darwin]
 
-  '@next/swc-linux-arm64-gnu@16.1.6':
-    resolution: {integrity: sha512-OJYkCd5pj/QloBvoEcJ2XiMnlJkRv9idWA/j0ugSuA34gMT6f5b7vOiCQHVRpvStoZUknhl6/UxOXL4OwtdaBw==}
+  '@next/swc-linux-arm64-gnu@16.2.6':
+    resolution: {integrity: sha512-RPOvqlYBbcQjkz9VQQDZ2T2bARIjXZV1KFlt+V2Mr6SW/e4I9fcKsaA0hdyf2FHoTlsV2xnBd5Y912rP/1Ce6w==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
 
-  '@next/swc-linux-arm64-musl@16.1.6':
-    resolution: {integrity: sha512-S4J2v+8tT3NIO9u2q+S0G5KdvNDjXfAv06OhfOzNDaBn5rw84DGXWndOEB7d5/x852A20sW1M56vhC/tRVbccQ==}
+  '@next/swc-linux-arm64-musl@16.2.6':
+    resolution: {integrity: sha512-URUTu1+dMkxJsPFgm+OeEvq9wf5sujw0EvgYy80TDGHTSLTnIHeqb0Eu8A3sC95IRgjejQL+kC4mw+4yPxiAXA==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
 
-  '@next/swc-linux-x64-gnu@16.1.6':
-    resolution: {integrity: sha512-2eEBDkFlMMNQnkTyPBhQOAyn2qMxyG2eE7GPH2WIDGEpEILcBPI/jdSv4t6xupSP+ot/jkfrCShLAa7+ZUPcJQ==}
+  '@next/swc-linux-x64-gnu@16.2.6':
+    resolution: {integrity: sha512-DOj182mPV8G3UkrayLoREM5YEYI+Dk5wv7Ox9xl1fFibAELEsFD0lDPfHIeILlutMMfdyhlzYPELG3peuKaurw==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
 
-  '@next/swc-linux-x64-musl@16.1.6':
-    resolution: {integrity: sha512-oicJwRlyOoZXVlxmIMaTq7f8pN9QNbdes0q2FXfRsPhfCi8n8JmOZJm5oo1pwDaFbnnD421rVU409M3evFbIqg==}
+  '@next/swc-linux-x64-musl@16.2.6':
+    resolution: {integrity: sha512-HKQ5SP/V/ub73UvF7n/zeJlxk2kLmtL7Wzrg4WfmkjmNos5onJ2tKu7yZOPdL18A6Svfn3max29ym+ry7NkK4g==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
 
-  '@next/swc-win32-arm64-msvc@16.1.6':
-    resolution: {integrity: sha512-gQmm8izDTPgs+DCWH22kcDmuUp7NyiJgEl18bcr8irXA5N2m2O+JQIr6f3ct42GOs9c0h8QF3L5SzIxcYAAXXw==}
+  '@next/swc-win32-arm64-msvc@16.2.6':
+    resolution: {integrity: sha512-LZXpTlPyS5v7HhSmnvsLGP3iIYgYOBnc8r8ArlT55sGHV89bR2HlDdBjWQ+PY6SJMmk8TuVGFuxalnP3k/0Dwg==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [win32]
 
-  '@next/swc-win32-x64-msvc@16.1.6':
-    resolution: {integrity: sha512-NRfO39AIrzBnixKbjuo2YiYhB6o9d8v/ymU9m/Xk8cyVk+k7XylniXkHwjs4s70wedVffc6bQNbufk5v0xEm0A==}
+  '@next/swc-win32-x64-msvc@16.2.6':
+    resolution: {integrity: sha512-F0+4i0h9J6C4eE3EAPWsoCk7UW/dbzOjyzxY0qnDUOYFu6FFmdZ6l97/XdV3/Nz3VYyO7UWjyEJUXkGqcoXfMA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [win32]
@@ -1810,8 +1849,12 @@ packages:
     engines: {node: '>=0.4.0'}
     hasBin: true
 
-  ajv@6.12.6:
-    resolution: {integrity: sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==}
+  agent-base@6.0.2:
+    resolution: {integrity: sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==}
+    engines: {node: '>= 6.0.0'}
+
+  ajv@6.14.0:
+    resolution: {integrity: sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==}
 
   ansi-regex@5.0.1:
     resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
@@ -1882,8 +1925,8 @@ packages:
     resolution: {integrity: sha512-BASOg+YwO2C+346x3LZOeoovTIoTrRqEsqMa6fmfAV0P+U9mFr9NsyOEpiYvFjbc64NMrSswhV50WdXzdb/Z5A==}
     engines: {node: '>=4'}
 
-  axios@1.13.6:
-    resolution: {integrity: sha512-ChTCHMouEe2kn713WHbQGcuYrr6fXTBiu460OTwWrWob16g1bXn4vtz07Ope7ewMozJAnEquLk5lWQWtBig9DQ==}
+  axios@1.18.1:
+    resolution: {integrity: sha512-3nTvFlvpn9Zu/RkHUqtc7/+al4UpRW5az71ap5zccp6e8RAYEzhMTecX8Dz1wWDYrPpUoB1HAQEGEAEvUr7S9g==}
 
   axobject-query@4.1.0:
     resolution: {integrity: sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==}
@@ -1901,11 +1944,11 @@ packages:
     engines: {node: '>=6.0.0'}
     hasBin: true
 
-  brace-expansion@1.1.12:
-    resolution: {integrity: sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==}
+  brace-expansion@1.1.13:
+    resolution: {integrity: sha512-9ZLprWS6EENmhEOpjCYW2c8VkmOvckIJZfkr7rBW6dObmfgJ/L1GpSYW5Hpo9lDz4D1+n0Ckz8rU7FwHDQiG/w==}
 
-  brace-expansion@5.0.4:
-    resolution: {integrity: sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg==}
+  brace-expansion@5.0.6:
+    resolution: {integrity: sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==}
     engines: {node: 18 || 20 || >=22}
 
   braces@3.0.3:
@@ -2182,8 +2225,8 @@ packages:
     resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
     engines: {node: '>=10'}
 
-  eslint-config-next@16.1.6:
-    resolution: {integrity: sha512-vKq40io2B0XtkkNDYyleATwblNt8xuh3FWp8SpSz3pt7P01OkBFlKsJZ2mWt5WsCySlDQLckb1zMY9yE9Qy0LA==}
+  eslint-config-next@16.2.6:
+    resolution: {integrity: sha512-z2ELYSkyrrJ6cuunTU8vhsT/RpouPkjaSah06nVW6Rg2Hpg0Vs8s497/e5s8G8qtdp4ccsiovz5P1rv+5VSW2Q==}
     peerDependencies:
       eslint: '>=9.0.0'
       typescript: '>=3.3.1'
@@ -2348,7 +2391,7 @@ packages:
     resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
     engines: {node: '>=12.0.0'}
     peerDependencies:
-      picomatch: ^3 || ^4
+      picomatch: 4.0.4
     peerDependenciesMeta:
       picomatch:
         optional: true
@@ -2373,11 +2416,11 @@ packages:
     resolution: {integrity: sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==}
     engines: {node: '>=16'}
 
-  flatted@3.3.3:
-    resolution: {integrity: sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==}
+  flatted@3.4.2:
+    resolution: {integrity: sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==}
 
-  follow-redirects@1.15.11:
-    resolution: {integrity: sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ==}
+  follow-redirects@1.16.0:
+    resolution: {integrity: sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==}
     engines: {node: '>=4.0'}
     peerDependencies:
       debug: '*'
@@ -2389,8 +2432,8 @@ packages:
     resolution: {integrity: sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==}
     engines: {node: '>= 0.4'}
 
-  form-data@4.0.5:
-    resolution: {integrity: sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==}
+  form-data@4.0.6:
+    resolution: {integrity: sha512-vKatAh4SlVfgbv+YtmhiRjhEMJsYpsG1Y2rMQtR+SVSbytsSD1YGzDIcrAJmdFec88u/+VoGmxnl+80gL1tRCQ==}
     engines: {node: '>= 6'}
 
   function-bind@1.1.2:
@@ -2493,12 +2536,20 @@ packages:
     resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
     engines: {node: '>= 0.4'}
 
+  hasown@2.0.4:
+    resolution: {integrity: sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==}
+    engines: {node: '>= 0.4'}
+
   hermes-estree@0.25.1:
     resolution: {integrity: sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==}
 
   hermes-parser@0.25.1:
     resolution: {integrity: sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==}
 
+  https-proxy-agent@5.0.1:
+    resolution: {integrity: sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==}
+    engines: {node: '>= 6'}
+
   ignore@5.3.2:
     resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
     engines: {node: '>= 4'}
@@ -2659,8 +2710,8 @@ packages:
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
-  js-yaml@4.1.1:
-    resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
+  js-yaml@4.2.0:
+    resolution: {integrity: sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==}
     hasBin: true
 
   jsesc@3.1.0:
@@ -2824,11 +2875,8 @@ packages:
     resolution: {integrity: sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==}
     engines: {node: 18 || 20 || >=22}
 
-  minimatch@3.1.2:
-    resolution: {integrity: sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==}
-
-  minimatch@3.1.5:
-    resolution: {integrity: sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==}
+  minimatch@3.1.4:
+    resolution: {integrity: sha512-twmL+S8+7yIsE9wsqgzU3E8/LumN3M3QELrBZ20OdmQ9jB2JvW5oZtBEmft84k/Gs5CG9mqtWc6Y9vW+JEzGxw==}
 
   minimist@1.2.8:
     resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
@@ -2855,8 +2903,8 @@ packages:
       react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
       react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
 
-  next@16.1.6:
-    resolution: {integrity: sha512-hkyRkcu5x/41KoqnROkfTm2pZVbKxvbZRuNvKXLRXxs3VfyO0WhY50TQS40EuKO9SW3rBj/sF3WbVwDACeMZyw==}
+  next@16.2.6:
+    resolution: {integrity: sha512-qOVgKJg1+At15NpeUP+eJgCHvTCgXsogweq87Ri/Ix7PkqQHg4sdaXmSFqKlgaIXE4kW0g25LE68W87UANlHtw==}
     engines: {node: '>=20.9.0'}
     hasBin: true
     peerDependencies:
@@ -2957,12 +3005,12 @@ packages:
   picocolors@1.1.1:
     resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
 
-  picomatch@2.3.1:
-    resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==}
+  picomatch@2.3.2:
+    resolution: {integrity: sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==}
     engines: {node: '>=8.6'}
 
-  picomatch@4.0.3:
-    resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==}
+  picomatch@4.0.4:
+    resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
     engines: {node: '>=12'}
 
   pngjs@5.0.0:
@@ -2973,12 +3021,8 @@ packages:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
 
-  postcss@8.4.31:
-    resolution: {integrity: sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==}
-    engines: {node: ^10 || ^12 || >=14}
-
-  postcss@8.5.6:
-    resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
+  postcss@8.5.10:
+    resolution: {integrity: sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==}
     engines: {node: ^10 || ^12 || >=14}
 
   prelude-ls@1.2.1:
@@ -3052,8 +3096,9 @@ packages:
   prop-types@15.8.1:
     resolution: {integrity: sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==}
 
-  proxy-from-env@1.1.0:
-    resolution: {integrity: sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==}
+  proxy-from-env@2.1.0:
+    resolution: {integrity: sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA==}
+    engines: {node: '>=10'}
 
   punycode@2.3.1:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
@@ -3580,16 +3625,22 @@ snapshots:
       js-tokens: 4.0.0
       picocolors: 1.1.1
 
+  '@babel/code-frame@7.29.7':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.29.7
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
   '@babel/compat-data@7.29.0': {}
 
-  '@babel/core@7.29.0':
+  '@babel/core@7.29.6':
     dependencies:
       '@babel/code-frame': 7.29.0
-      '@babel/generator': 7.29.1
+      '@babel/generator': 7.29.7
       '@babel/helper-compilation-targets': 7.28.6
-      '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
-      '@babel/helpers': 7.28.6
-      '@babel/parser': 7.29.0
+      '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.6)
+      '@babel/helpers': 7.29.7
+      '@babel/parser': 7.29.7
       '@babel/template': 7.28.6
       '@babel/traverse': 7.29.0
       '@babel/types': 7.29.0
@@ -3602,10 +3653,10 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@babel/generator@7.29.1':
+  '@babel/generator@7.29.7':
     dependencies:
-      '@babel/parser': 7.29.0
-      '@babel/types': 7.29.0
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
       '@jridgewell/gen-mapping': 0.3.13
       '@jridgewell/trace-mapping': 0.3.31
       jsesc: 3.1.0
@@ -3627,9 +3678,9 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@babel/helper-module-transforms@7.28.6(@babel/core@7.29.0)':
+  '@babel/helper-module-transforms@7.28.6(@babel/core@7.29.6)':
     dependencies:
-      '@babel/core': 7.29.0
+      '@babel/core': 7.29.6
       '@babel/helper-module-imports': 7.28.6
       '@babel/helper-validator-identifier': 7.28.5
       '@babel/traverse': 7.29.0
@@ -3638,33 +3689,47 @@ snapshots:
 
   '@babel/helper-string-parser@7.27.1': {}
 
+  '@babel/helper-string-parser@7.29.7': {}
+
   '@babel/helper-validator-identifier@7.28.5': {}
 
+  '@babel/helper-validator-identifier@7.29.7': {}
+
   '@babel/helper-validator-option@7.27.1': {}
 
-  '@babel/helpers@7.28.6':
+  '@babel/helpers@7.29.7':
     dependencies:
-      '@babel/template': 7.28.6
-      '@babel/types': 7.29.0
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
 
   '@babel/parser@7.29.0':
     dependencies:
       '@babel/types': 7.29.0
 
+  '@babel/parser@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
   '@babel/runtime@7.28.6': {}
 
   '@babel/template@7.28.6':
     dependencies:
       '@babel/code-frame': 7.29.0
-      '@babel/parser': 7.29.0
+      '@babel/parser': 7.29.7
       '@babel/types': 7.29.0
 
+  '@babel/template@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+
   '@babel/traverse@7.29.0':
     dependencies:
       '@babel/code-frame': 7.29.0
-      '@babel/generator': 7.29.1
+      '@babel/generator': 7.29.7
       '@babel/helper-globals': 7.28.0
-      '@babel/parser': 7.29.0
+      '@babel/parser': 7.29.7
       '@babel/template': 7.28.6
       '@babel/types': 7.29.0
       debug: 4.4.3
@@ -3676,6 +3741,11 @@ snapshots:
       '@babel/helper-string-parser': 7.27.1
       '@babel/helper-validator-identifier': 7.28.5
 
+  '@babel/types@7.29.7':
+    dependencies:
+      '@babel/helper-string-parser': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+
   '@base-ui/react@1.2.0(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.28.6
@@ -3761,7 +3831,7 @@ snapshots:
     dependencies:
       '@eslint/object-schema': 2.1.7
       debug: 4.4.3
-      minimatch: 3.1.5
+      minimatch: 3.1.4
     transitivePeerDependencies:
       - supports-color
 
@@ -3775,14 +3845,14 @@ snapshots:
 
   '@eslint/eslintrc@3.3.3':
     dependencies:
-      ajv: 6.12.6
+      ajv: 6.14.0
       debug: 4.4.3
       espree: 10.4.0
       globals: 14.0.0
       ignore: 5.3.2
       import-fresh: 3.3.1
-      js-yaml: 4.1.1
-      minimatch: 3.1.2
+      js-yaml: 4.2.0
+      minimatch: 3.1.4
       strip-json-comments: 3.1.1
     transitivePeerDependencies:
       - supports-color
@@ -3952,34 +4022,34 @@ snapshots:
       '@tybys/wasm-util': 0.10.1
     optional: true
 
-  '@next/env@16.1.6': {}
+  '@next/env@16.2.6': {}
 
-  '@next/eslint-plugin-next@16.1.6':
+  '@next/eslint-plugin-next@16.2.6':
     dependencies:
       fast-glob: 3.3.1
 
-  '@next/swc-darwin-arm64@16.1.6':
+  '@next/swc-darwin-arm64@16.2.6':
     optional: true
 
-  '@next/swc-darwin-x64@16.1.6':
+  '@next/swc-darwin-x64@16.2.6':
     optional: true
 
-  '@next/swc-linux-arm64-gnu@16.1.6':
+  '@next/swc-linux-arm64-gnu@16.2.6':
     optional: true
 
-  '@next/swc-linux-arm64-musl@16.1.6':
+  '@next/swc-linux-arm64-musl@16.2.6':
     optional: true
 
-  '@next/swc-linux-x64-gnu@16.1.6':
+  '@next/swc-linux-x64-gnu@16.2.6':
     optional: true
 
-  '@next/swc-linux-x64-musl@16.1.6':
+  '@next/swc-linux-x64-musl@16.2.6':
     optional: true
 
-  '@next/swc-win32-arm64-msvc@16.1.6':
+  '@next/swc-win32-arm64-msvc@16.2.6':
     optional: true
 
-  '@next/swc-win32-x64-msvc@16.1.6':
+  '@next/swc-win32-x64-msvc@16.2.6':
     optional: true
 
   '@nodelib/fs.scandir@2.1.5':
@@ -4898,7 +4968,7 @@ snapshots:
       '@alloc/quick-lru': 5.2.0
       '@tailwindcss/node': 4.2.1
       '@tailwindcss/oxide': 4.2.1
-      postcss: 8.5.6
+      postcss: 8.5.10
       tailwindcss: 4.2.1
 
   '@tanstack/query-core@5.90.20': {}
@@ -5133,7 +5203,13 @@ snapshots:
 
   acorn@8.15.0: {}
 
-  ajv@6.12.6:
+  agent-base@6.0.2:
+    dependencies:
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  ajv@6.14.0:
     dependencies:
       fast-deep-equal: 3.1.3
       fast-json-stable-stringify: 2.1.0
@@ -5233,13 +5309,15 @@ snapshots:
 
   axe-core@4.11.1: {}
 
-  axios@1.13.6:
+  axios@1.18.1:
     dependencies:
-      follow-redirects: 1.15.11
-      form-data: 4.0.5
-      proxy-from-env: 1.1.0
+      follow-redirects: 1.16.0
+      form-data: 4.0.6
+      https-proxy-agent: 5.0.1
+      proxy-from-env: 2.1.0
     transitivePeerDependencies:
       - debug
+      - supports-color
 
   axobject-query@4.1.0: {}
 
@@ -5249,12 +5327,12 @@ snapshots:
 
   baseline-browser-mapping@2.10.0: {}
 
-  brace-expansion@1.1.12:
+  brace-expansion@1.1.13:
     dependencies:
       balanced-match: 1.0.2
       concat-map: 0.0.1
 
-  brace-expansion@5.0.4:
+  brace-expansion@5.0.6:
     dependencies:
       balanced-match: 4.0.4
 
@@ -5639,9 +5717,9 @@ snapshots:
 
   escape-string-regexp@4.0.0: {}
 
-  eslint-config-next@16.1.6(@typescript-eslint/parser@8.57.0(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3))(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3):
+  eslint-config-next@16.2.6(@typescript-eslint/parser@8.57.0(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3))(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3):
     dependencies:
-      '@next/eslint-plugin-next': 16.1.6
+      '@next/eslint-plugin-next': 16.2.6
       eslint: 9.38.0(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.38.0(jiti@2.6.1))
@@ -5712,7 +5790,7 @@ snapshots:
       hasown: 2.0.2
       is-core-module: 2.16.1
       is-glob: 4.0.3
-      minimatch: 3.1.5
+      minimatch: 3.1.4
       object.fromentries: 2.0.8
       object.groupby: 1.0.3
       object.values: 1.2.1
@@ -5740,7 +5818,7 @@ snapshots:
       hasown: 2.0.2
       jsx-ast-utils: 3.3.5
       language-tags: 1.0.9
-      minimatch: 3.1.5
+      minimatch: 3.1.4
       object.fromentries: 2.0.8
       safe-regex-test: 1.1.0
       string.prototype.includes: 2.0.1
@@ -5756,7 +5834,7 @@ snapshots:
 
   eslint-plugin-react-hooks@7.0.1(eslint@9.38.0(jiti@2.6.1)):
     dependencies:
-      '@babel/core': 7.29.0
+      '@babel/core': 7.29.6
       '@babel/parser': 7.29.0
       eslint: 9.38.0(jiti@2.6.1)
       hermes-parser: 0.25.1
@@ -5777,7 +5855,7 @@ snapshots:
       estraverse: 5.3.0
       hasown: 2.0.2
       jsx-ast-utils: 3.3.5
-      minimatch: 3.1.2
+      minimatch: 3.1.4
       object.entries: 1.1.9
       object.fromentries: 2.0.8
       object.values: 1.2.1
@@ -5812,7 +5890,7 @@ snapshots:
       '@humanwhocodes/module-importer': 1.0.1
       '@humanwhocodes/retry': 0.4.3
       '@types/estree': 1.0.8
-      ajv: 6.12.6
+      ajv: 6.14.0
       chalk: 4.1.2
       cross-spawn: 7.0.6
       debug: 4.4.3
@@ -5831,7 +5909,7 @@ snapshots:
       is-glob: 4.0.3
       json-stable-stringify-without-jsonify: 1.0.1
       lodash.merge: 4.6.2
-      minimatch: 3.1.5
+      minimatch: 3.1.4
       natural-compare: 1.4.0
       optionator: 0.9.4
     optionalDependencies:
@@ -5879,9 +5957,9 @@ snapshots:
     dependencies:
       reusify: 1.1.0
 
-  fdir@6.5.0(picomatch@4.0.3):
+  fdir@6.5.0(picomatch@4.0.4):
     optionalDependencies:
-      picomatch: 4.0.3
+      picomatch: 4.0.4
 
   file-entry-cache@8.0.0:
     dependencies:
@@ -5903,23 +5981,23 @@ snapshots:
 
   flat-cache@4.0.1:
     dependencies:
-      flatted: 3.3.3
+      flatted: 3.4.2
       keyv: 4.5.4
 
-  flatted@3.3.3: {}
+  flatted@3.4.2: {}
 
-  follow-redirects@1.15.11: {}
+  follow-redirects@1.16.0: {}
 
   for-each@0.3.5:
     dependencies:
       is-callable: 1.2.7
 
-  form-data@4.0.5:
+  form-data@4.0.6:
     dependencies:
       asynckit: 0.4.0
       combined-stream: 1.0.8
       es-set-tostringtag: 2.1.0
-      hasown: 2.0.2
+      hasown: 2.0.4
       mime-types: 2.1.35
 
   function-bind@1.1.2: {}
@@ -5935,9 +6013,9 @@ snapshots:
 
   functions-have-names@1.2.3: {}
 
-  geist@1.7.0(next@16.1.6(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)):
+  geist@1.7.0(next@16.2.6(@babel/core@7.29.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)):
     dependencies:
-      next: 16.1.6(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      next: 16.2.6(@babel/core@7.29.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
 
   generator-function@2.0.1: {}
 
@@ -6018,12 +6096,23 @@ snapshots:
     dependencies:
       function-bind: 1.1.2
 
+  hasown@2.0.4:
+    dependencies:
+      function-bind: 1.1.2
+
   hermes-estree@0.25.1: {}
 
   hermes-parser@0.25.1:
     dependencies:
       hermes-estree: 0.25.1
 
+  https-proxy-agent@5.0.1:
+    dependencies:
+      agent-base: 6.0.2
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
   ignore@5.3.2: {}
 
   ignore@7.0.5: {}
@@ -6183,7 +6272,7 @@ snapshots:
 
   js-tokens@4.0.0: {}
 
-  js-yaml@4.1.1:
+  js-yaml@4.2.0:
     dependencies:
       argparse: 2.0.1
 
@@ -6305,7 +6394,7 @@ snapshots:
   micromatch@4.0.8:
     dependencies:
       braces: 3.0.3
-      picomatch: 2.3.1
+      picomatch: 2.3.2
 
   mime-db@1.52.0: {}
 
@@ -6315,15 +6404,11 @@ snapshots:
 
   minimatch@10.2.4:
     dependencies:
-      brace-expansion: 5.0.4
+      brace-expansion: 5.0.6
 
-  minimatch@3.1.2:
+  minimatch@3.1.4:
     dependencies:
-      brace-expansion: 1.1.12
-
-  minimatch@3.1.5:
-    dependencies:
-      brace-expansion: 1.1.12
+      brace-expansion: 1.1.13
 
   minimist@1.2.8: {}
 
@@ -6340,25 +6425,25 @@ snapshots:
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
 
-  next@16.1.6(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+  next@16.2.6(@babel/core@7.29.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
-      '@next/env': 16.1.6
+      '@next/env': 16.2.6
       '@swc/helpers': 0.5.15
       baseline-browser-mapping: 2.10.0
       caniuse-lite: 1.0.30001776
-      postcss: 8.4.31
+      postcss: 8.5.10
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
-      styled-jsx: 5.1.6(@babel/core@7.29.0)(react@19.2.4)
+      styled-jsx: 5.1.6(@babel/core@7.29.6)(react@19.2.4)
     optionalDependencies:
-      '@next/swc-darwin-arm64': 16.1.6
-      '@next/swc-darwin-x64': 16.1.6
-      '@next/swc-linux-arm64-gnu': 16.1.6
-      '@next/swc-linux-arm64-musl': 16.1.6
-      '@next/swc-linux-x64-gnu': 16.1.6
-      '@next/swc-linux-x64-musl': 16.1.6
-      '@next/swc-win32-arm64-msvc': 16.1.6
-      '@next/swc-win32-x64-msvc': 16.1.6
+      '@next/swc-darwin-arm64': 16.2.6
+      '@next/swc-darwin-x64': 16.2.6
+      '@next/swc-linux-arm64-gnu': 16.2.6
+      '@next/swc-linux-arm64-musl': 16.2.6
+      '@next/swc-linux-x64-gnu': 16.2.6
+      '@next/swc-linux-x64-musl': 16.2.6
+      '@next/swc-win32-arm64-msvc': 16.2.6
+      '@next/swc-win32-x64-msvc': 16.2.6
       sharp: 0.34.5
     transitivePeerDependencies:
       - '@babel/core'
@@ -6453,21 +6538,15 @@ snapshots:
 
   picocolors@1.1.1: {}
 
-  picomatch@2.3.1: {}
+  picomatch@2.3.2: {}
 
-  picomatch@4.0.3: {}
+  picomatch@4.0.4: {}
 
   pngjs@5.0.0: {}
 
   possible-typed-array-names@1.1.0: {}
 
-  postcss@8.4.31:
-    dependencies:
-      nanoid: 3.3.11
-      picocolors: 1.1.1
-      source-map-js: 1.2.1
-
-  postcss@8.5.6:
+  postcss@8.5.10:
     dependencies:
       nanoid: 3.3.11
       picocolors: 1.1.1
@@ -6491,7 +6570,7 @@ snapshots:
       object-assign: 4.1.1
       react-is: 16.13.1
 
-  proxy-from-env@1.1.0: {}
+  proxy-from-env@2.1.0: {}
 
   punycode@2.3.1: {}
 
@@ -6901,12 +6980,12 @@ snapshots:
 
   strip-json-comments@3.1.1: {}
 
-  styled-jsx@5.1.6(@babel/core@7.29.0)(react@19.2.4):
+  styled-jsx@5.1.6(@babel/core@7.29.6)(react@19.2.4):
     dependencies:
       client-only: 0.0.1
       react: 19.2.4
     optionalDependencies:
-      '@babel/core': 7.29.0
+      '@babel/core': 7.29.6
 
   supports-color@7.2.0:
     dependencies:
@@ -6930,8 +7009,8 @@ snapshots:
 
   tinyglobby@0.2.15:
     dependencies:
-      fdir: 6.5.0(picomatch@4.0.3)
-      picomatch: 4.0.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
 
   to-regex-range@5.0.1:
     dependencies:

ui/pnpm-workspace.yaml

@@ -0,0 +1,17 @@
+overrides:
+  '@babel/core': 7.29.6
+  flatted: 3.4.2
+  follow-redirects: 1.16.0
+  form-data: 4.0.6
+  ajv@6: 6.14.0
+  brace-expansion@1: 1.1.13
+  brace-expansion@5: 5.0.6
+  js-yaml: 4.2.0
+  minimatch@3: 3.1.4
+  picomatch@2: 2.3.2
+  picomatch@4: 4.0.4
+  postcss: 8.5.10
+
+onlyBuiltDependencies:
+  - sharp
+  - unrs-resolver

uv.lock

@@ -2384,7 +2384,7 @@ wheels = [
 
 [[package]]
 name = "routstr"
-version = "0.4.3"
+version = "0.4.4"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },