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.

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")

routstr/auth.py

@@ -35,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
@@ -206,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)
@@ -302,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

routstr/balance.py

@@ -27,6 +27,7 @@ from .wallet import (
     recieve_token,
     send_to_lnurl,
     send_token,
+    token_mint_url,
 )
 
 router = APIRouter()
@@ -144,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,
@@ -161,6 +173,18 @@ 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 Exception as e:
@@ -169,12 +193,41 @@ async def topup_wallet_endpoint(
         classified = classify_redemption_error(e)
         if classified is None:
             logger.error(
-                "topup_wallet_endpoint: unhandled error",
-                extra={"error": str(e), "error_type": type(e).__name__},
+                "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")
-        _type, status_code, message, _code = classified
+        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=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}
 
 
@@ -220,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 = (
@@ -235,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,
+        },
     )
 
 
@@ -389,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,
@@ -407,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":
@@ -431,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",
@@ -462,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",
@@ -656,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/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/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

@@ -9,7 +9,8 @@ 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. Bound it here so callers fail instead of hanging forever.
+# 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:
@@ -221,22 +222,33 @@ 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)
 
     try:
         _ = await asyncio.wait_for(
-            wallet.melt(
-                proofs=proofs,
-                invoice=bolt11_invoice,
-                fee_reserve_sat=melt_quote_resp.fee_reserve,
-                quote_id=melt_quote_resp.quote,
+            _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 asyncio.TimeoutError as e:
+    except (httpx.TimeoutException, asyncio.TimeoutError) as e:
         raise LNURLError(
             f"Melt timed out after {MELT_TIMEOUT_SECONDS}s (mint unresponsive)"
         ) from e

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,
@@ -250,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)
 
@@ -606,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

@@ -10,7 +10,7 @@ from ..core.db import (
     create_session,
     store_cashu_transaction,
 )
-from ..wallet import send_token
+from ..wallet import release_token_reservation, send_token, token_mint_url
 from .routstr import RoutstrUpstreamProvider
 
 logger = get_logger(__name__)
@@ -142,20 +142,33 @@ 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=mint_url,
+        mint_url=actual_mint_url,
         typ="out",
         collected=False,
         source="auto_topup",
     )
     if not stored:
-        logger.critical(
-            "Aborting auto top-up because its cashu token could not be persisted",
-            extra={"provider_id": row.id, "mint_url": mint_url},
-        )
+        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)

routstr/upstream/base.py

@@ -45,6 +45,7 @@ from ..wallet import (
     classify_redemption_error,
     recieve_token,
     send_token,
+    token_mint_url,
 )
 from . import messages_dispatch
 from .cache_breakpoints import (
@@ -3290,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,
                     )
@@ -3645,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,
                 )
@@ -4609,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,
                 )

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

tests/unit/test_auto_topup.py

@@ -66,6 +66,10 @@ async def test_auto_topup_persists_before_sending_and_marks_success_collected()
             "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())
@@ -74,7 +78,7 @@ async def test_auto_topup_persists_before_sending_and_marks_success_collected()
         token="cashu-token",
         amount=50,
         unit="sat",
-        mint_url="https://mint.test",
+        mint_url="https://fallback-mint.test",
         typ="out",
         collected=False,
         source="auto_topup",
@@ -138,6 +142,12 @@ async def test_auto_topup_does_not_send_untracked_token() -> None:
             "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

@@ -534,6 +534,29 @@ async def test_topup_mint_unreachable_returns_503(error: Exception) -> None:
     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

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_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_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_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/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 {