only activ model should be visible

make cache prices configurable

Makefile

@@ -98,7 +98,7 @@ docker-down:
 lint:
 	@echo "🔍 Running linting checks..."
 	$(RUFF) check .
-	$(MYPY) routstr/ --ignore-missing-imports
+	$(MYPY) .
 
 format:
 	@echo "✨ Formatting code..."
@@ -107,7 +107,7 @@ format:
 
 type-check:
 	@echo "🔎 Running type checks..."
-	$(MYPY) routstr/ --ignore-missing-imports
+	$(MYPY) .
 
 # Development setup
 dev-setup:
@@ -234,7 +234,7 @@ ci-test:
 ci-lint:
 	@echo "🤖 Running CI linting..."
 	$(RUFF) check . --exit-non-zero-on-fix
-	$(MYPY) routstr/ --ignore-missing-imports --no-error-summary
+	$(MYPY) . --no-error-summary
 
 # Debug helpers
 test-debug:

docs/api/endpoints.md

@@ -327,6 +327,58 @@ GET /v1/models
 }
 ```
 
+### List Model Paths
+
+Get the upstream provider paths each advertised model can be reached through.
+This is discovery data only; routing still chooses the provider per request.
+
+```http
+GET /v1/models/paths
+```
+
+**Response:**
+
+```json
+{
+  "data": [
+    {
+      "id": "claude-sonnet-4",
+      "paths": [
+        {"path": "anthropic"},
+        {"path": "openrouter:Anthropic"}
+      ]
+    }
+  ]
+}
+```
+
+### List Paths for One Model
+
+Use a query parameter so model IDs containing `/` are handled safely. Lookup is
+by the public, unqualified model ID: `glm-5v-turbo` resolves
+`z-ai/glm-5v-turbo`, and `deepseek-v4-pro` and `deepseek/deepseek-v4-pro`
+return the same merged path set.
+
+```http
+GET /v1/models/paths/model?model_id=anthropic/claude-sonnet-4
+```
+
+**Response:**
+
+```json
+{
+  "data": [
+    {"path": "anthropic"},
+    {"path": "openrouter:Anthropic"}
+  ]
+}
+```
+
+Model IDs in responses are unqualified display IDs: provider prefixes such as
+`z-ai/` or `openai/` are stripped. Path values match the provider string stamped
+on chat-completion responses, such as `anthropic`, `generic:my-upstream`, or
+`openrouter:Anthropic`.
+
 ## Wallet Management
 
 ### Create Wallet (Coming Soon)

docs/api/overview.md

@@ -100,6 +100,7 @@ All errors follow a consistent format:
 Standard OpenAI-compatible endpoints:
 
 - **Models**: `/v1/models`
+- **Model paths**: `/v1/models/paths`, `/v1/models/paths/model?model_id=...`
 - **Responses**: `/v1/responses`
 - **Chat Completions**: `/v1/chat/completions`
 - **Embeddings**: `/v1/embeddings`
@@ -302,7 +303,7 @@ Get node metadata:
 GET /v1/info
 ```
 
-Supported models and pricing are available at `/v1/models`.
+Supported models and pricing are available at `/v1/models`. Upstream provider path discovery is available at `/v1/models/paths` and `/v1/models/paths/model?model_id=...`.
 
 ## Next Steps
 

docs/provider/configuration.md

@@ -137,6 +137,7 @@ Use environment variables for:
 | `TOR_PROXY_URL`      | SOCKS5 proxy for Tor              | `socks5://127.0.0.1:9050`            |
 | `CORS_ORIGINS`       | Allowed CORS origins              | `*`                                  |
 | `RELAYS`             | Nostr relays (comma-separated)    | (default set)                        |
+| `MODEL_PATHS_REFRESH_INTERVAL_SECONDS` | How often to refresh `/v1/models/paths` discovery data; set `0` to disable | `600` |
 
 ### Priority
 
@@ -156,3 +157,8 @@ Manage which AI models you offer:
    - **Create aliases** — friendly names for models
 
 See [Pricing](pricing.md) for per-model pricing strategies.
+
+Model path discovery is refreshed in the background and exposed through
+`/v1/models/paths`. The response groups each client-visible model ID with the
+provider paths that may appear in chat-completion response metadata. Tune the
+refresh cadence with `MODEL_PATHS_REFRESH_INTERVAL_SECONDS`.

migrations/versions/c6d7e8f9a0b1_add_slug_to_upstream_providers.py

@@ -0,0 +1,88 @@
+"""add slug to upstream_providers
+
+Revision ID: c6d7e8f9a0b1
+Revises: b5e7c9d1f3a2
+Create Date: 2026-06-29 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+from routstr.core.provider_slugs import provider_slug_base, provider_slug_candidate
+
+revision = "c6d7e8f9a0b1"
+down_revision = "b5e7c9d1f3a2"
+branch_labels = None
+depends_on = None
+
+
+def _allocate_backfill_slug(provider_type: str, reserved_slugs: set[str]) -> str:
+    base = provider_slug_base(provider_type)
+    suffix_number = 1
+    while True:
+        candidate = provider_slug_candidate(base, suffix_number)
+        if candidate not in reserved_slugs:
+            reserved_slugs.add(candidate)
+            return candidate
+        suffix_number += 1
+
+
+def _backfill_provider_slugs(conn: sa.Connection) -> None:
+    existing_rows = conn.execute(
+        sa.text(
+            "SELECT slug FROM upstream_providers "
+            "WHERE slug IS NOT NULL AND slug != ''"
+        )
+    )
+    reserved_slugs = {str(row.slug).lower() for row in existing_rows}
+
+    rows_to_backfill = conn.execute(
+        sa.text(
+            "SELECT id, provider_type FROM upstream_providers "
+            "WHERE slug IS NULL OR slug = '' "
+            "ORDER BY id"
+        )
+    )
+    for row in rows_to_backfill:
+        slug = _allocate_backfill_slug(str(row.provider_type), reserved_slugs)
+        conn.execute(
+            sa.text("UPDATE upstream_providers SET slug = :slug WHERE id = :id"),
+            {"slug": slug, "id": row.id},
+        )
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    columns = {c["name"] for c in inspector.get_columns("upstream_providers")}
+
+    if "slug" not in columns:
+        op.add_column(
+            "upstream_providers",
+            sa.Column("slug", sa.String(), nullable=True),
+        )
+
+    _backfill_provider_slugs(conn)
+
+    existing_indexes = {idx["name"] for idx in inspector.get_indexes("upstream_providers")}
+    if "ix_upstream_providers_slug" not in existing_indexes:
+        op.create_index(
+            "ix_upstream_providers_slug",
+            "upstream_providers",
+            ["slug"],
+            unique=True,
+        )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    existing_indexes = {idx["name"] for idx in inspector.get_indexes("upstream_providers")}
+    if "ix_upstream_providers_slug" in existing_indexes:
+        op.drop_index("ix_upstream_providers_slug", table_name="upstream_providers")
+
+    columns = {c["name"] for c in inspector.get_columns("upstream_providers")}
+    if "slug" in columns:
+        op.drop_column("upstream_providers", "slug")

migrations/versions/d7e8f9a0b1c2_add_model_paths_table.py

@@ -0,0 +1,66 @@
+"""add model_paths table
+
+Revision ID: d7e8f9a0b1c2
+Revises: c6d7e8f9a0b1
+Create Date: 2026-07-05 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "d7e8f9a0b1c2"
+down_revision = "c6d7e8f9a0b1"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    if "model_paths" in inspector.get_table_names():
+        return
+
+    op.create_table(
+        "model_paths",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("model_id", sa.String(), nullable=False),
+        sa.Column("path", sa.String(), nullable=False),
+        sa.Column("upstream_provider_id", sa.Integer(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["upstream_provider_id"],
+            ["upstream_providers.id"],
+            ondelete="CASCADE",
+        ),
+        sa.UniqueConstraint(
+            "model_id",
+            "path",
+            "upstream_provider_id",
+            name="uq_model_paths_model_path_provider",
+        ),
+    )
+    op.create_index(
+        "ix_model_paths_model_id",
+        "model_paths",
+        ["model_id"],
+    )
+    op.create_index(
+        "ix_model_paths_upstream_provider_id",
+        "model_paths",
+        ["upstream_provider_id"],
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    if "model_paths" not in inspector.get_table_names():
+        return
+
+    existing_indexes = {idx["name"] for idx in inspector.get_indexes("model_paths")}
+    if "ix_model_paths_upstream_provider_id" in existing_indexes:
+        op.drop_index("ix_model_paths_upstream_provider_id", table_name="model_paths")
+    if "ix_model_paths_model_id" in existing_indexes:
+        op.drop_index("ix_model_paths_model_id", table_name="model_paths")
+    op.drop_table("model_paths")

routstr/auth.py

@@ -709,12 +709,18 @@ async def revert_pay_for_request(
 
 
 async def adjust_payment_for_tokens(
-    key: ApiKey, response_data: dict, session: AsyncSession, deducted_max_cost: int
+    key: ApiKey,
+    response_data: dict,
+    session: AsyncSession,
+    deducted_max_cost: int,
 ) -> dict:
     """
     Adjusts the payment based on token usage in the response.
     This is called after the initial payment and the upstream request is complete.
     Returns cost data to be included in the response.
+
+    The response's usage object is normalized with the default union parser in
+    ``calculate_cost``.
     """
     billing_key = await get_billing_key(key, session)
     model = response_data.get("model", "unknown")
@@ -797,7 +803,7 @@ async def adjust_payment_for_tokens(
                     extra={"error": str(e), "fee_msats": fee_msats},
                 )
 
-    match await calculate_cost(response_data, deducted_max_cost, session):
+    match await calculate_cost(response_data, deducted_max_cost):
         case MaxCostData() as cost:
             logger.debug(
                 "Using max cost data (no token adjustment)",
@@ -1015,32 +1021,37 @@ async def adjust_payment_for_tokens(
             # actual cost exceeded discounted reservation (due to tolerance_percentage)
             if cost_difference > 0:
                 # Always release the reservation and charge min(actual_cost, balance).
-                # Using a CASE expression makes this a single atomic UPDATE — no
-                # multi-level fallback needed and balance can never go negative.
+                # CASE expressions keep this atomic and safe even when the
+                # stale-reservation sweeper has already released the reservation.
                 chargeable = case(
                     (col(ApiKey.balance) >= total_cost_msats, total_cost_msats),
                     else_=col(ApiKey.balance),
                 )
+                overrun_safe_reserved = case(
+                    (
+                        col(ApiKey.reserved_balance) >= deducted_max_cost,
+                        col(ApiKey.reserved_balance) - deducted_max_cost,
+                    ),
+                    else_=0,
+                )
 
                 finalize_stmt = (
                     update(ApiKey)
                     .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
-                    .where(col(ApiKey.reserved_balance) >= deducted_max_cost)
                     .values(
-                        reserved_balance=col(ApiKey.reserved_balance) - deducted_max_cost,
+                        reserved_balance=overrun_safe_reserved,
                         balance=col(ApiKey.balance) - chargeable,
                         total_spent=col(ApiKey.total_spent) + chargeable,
                     )
                 )
-                result = await session.exec(finalize_stmt)  # type: ignore[call-overload]
+                await session.exec(finalize_stmt)  # type: ignore[call-overload]
 
                 if billing_key.hashed_key != key.hashed_key:
                     child_stmt = (
                         update(ApiKey)
                         .where(col(ApiKey.hashed_key) == key.hashed_key)
-                        .where(col(ApiKey.reserved_balance) >= deducted_max_cost)
                         .values(
-                            reserved_balance=col(ApiKey.reserved_balance) - deducted_max_cost,
+                            reserved_balance=overrun_safe_reserved,
                             total_spent=col(ApiKey.total_spent) + min(billing_key.balance, total_cost_msats),
                         )
                     )
@@ -1048,51 +1059,38 @@ async def adjust_payment_for_tokens(
 
                 await session.commit()
 
-                if result.rowcount:
-                    await session.refresh(billing_key)
-                    if billing_key.hashed_key != key.hashed_key:
-                        await session.refresh(key)
-                    cost.total_msats = total_cost_msats
-                    logger.info(
-                        "Finalized payment with additional charge",
-                        extra={
-                            "key_hash": key.hashed_key[:8] + "...",
-                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
-                            "charged_amount": total_cost_msats,
-                            "new_balance": billing_key.balance,
-                            "model": model,
-                        },
-                    )
-                    await _accumulate_fee(total_cost_msats)
-                    payments_logger.info(
-                        "FINALIZE",
-                        extra={
-                            "event": "finalize",
-                            "key_hash": key.hashed_key[:8] + "...",
-                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
-                            "model": model,
-                            "cost_reserved": deducted_max_cost,
-                            "cost_charged": total_cost_msats,
-                            "input_tokens": cost.input_tokens,
-                            "output_tokens": cost.output_tokens,
-                            "balance": billing_key.balance,
-                            "reserved_balance": billing_key.reserved_balance,
-                            "total_spent": billing_key.total_spent,
-                            "finalize_type": "overrun",
-                        },
-                    )
-                else:
-                    # Guard fired: reservation was already released by a concurrent
-                    # finalization for this key. Nothing left to do.
-                    logger.warning(
-                        "Finalization skipped - reservation already released",
-                        extra={
-                            "key_hash": key.hashed_key[:8] + "...",
-                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
-                            "attempted_charge": total_cost_msats,
-                            "model": model,
-                        },
-                    )
+                await session.refresh(billing_key)
+                if billing_key.hashed_key != key.hashed_key:
+                    await session.refresh(key)
+                cost.total_msats = total_cost_msats
+                logger.info(
+                    "Finalized payment with additional charge",
+                    extra={
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                        "charged_amount": total_cost_msats,
+                        "new_balance": billing_key.balance,
+                        "model": model,
+                    },
+                )
+                await _accumulate_fee(total_cost_msats)
+                payments_logger.info(
+                    "FINALIZE",
+                    extra={
+                        "event": "finalize",
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                        "model": model,
+                        "cost_reserved": deducted_max_cost,
+                        "cost_charged": total_cost_msats,
+                        "input_tokens": cost.input_tokens,
+                        "output_tokens": cost.output_tokens,
+                        "balance": billing_key.balance,
+                        "reserved_balance": billing_key.reserved_balance,
+                        "total_spent": billing_key.total_spent,
+                        "finalize_type": "overrun",
+                    },
+                )
             else:
                 # Refund some of the base cost
                 refund = abs(cost_difference)
@@ -1299,6 +1297,35 @@ async def periodic_key_reset() -> None:
             logger.error(f"Error in periodic_key_reset: {e}")
 
 
+async def periodic_dead_key_prune() -> None:
+    """Periodically prune dead API keys. Interval <= 0 disables it.
+
+    See ``prune_dead_api_keys`` for eligibility.
+    """
+    from .core.db import create_session, prune_dead_api_keys
+
+    interval = settings.dead_key_prune_interval_seconds
+    if interval <= 0:
+        logger.info("Dead-key pruning disabled (interval <= 0)")
+        return
+
+    while True:
+        try:
+            await asyncio.sleep(interval)
+        except asyncio.CancelledError:
+            break
+
+        try:
+            async with create_session() as session:
+                await prune_dead_api_keys(
+                    session, settings.dead_key_min_age_seconds
+                )
+        except asyncio.CancelledError:
+            break
+        except Exception as e:
+            logger.error(f"Error in periodic_dead_key_prune: {e}")
+
+
 STALE_RESERVATION_SWEEP_INTERVAL_SECONDS: int = 60
 
 

routstr/core/admin.py

@@ -1,5 +1,6 @@
 import asyncio
 import json
+import re
 import secrets
 from datetime import datetime, timezone
 from pathlib import Path
@@ -8,6 +9,7 @@ from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from pydantic import BaseModel, RootModel
 from pydantic.v1 import ValidationError as PydanticValidationError
 from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
 
 from ..payment.models import _row_to_model, list_models
 from ..proxy import refresh_model_maps, reinitialize_upstreams
@@ -29,6 +31,7 @@ from .db import (
 )
 from .log_manager import log_manager
 from .logging import get_logger
+from .provider_slugs import allocate_unique_provider_slug
 from .settings import SettingsService, settings
 
 logger = get_logger(__name__)
@@ -456,19 +459,18 @@ class ModelCreate(BaseModel):
     dependencies=[Depends(require_admin_api)],
 )
 async def upsert_provider_model(
-    provider_id: int, payload: ModelCreate
+    provider_id: str, payload: ModelCreate
 ) -> dict[str, object]:
     print(payload)
     logger.info(
         f"UPSERT_PROVIDER_MODEL called: provider_id={provider_id}, model_id={payload.id}"
     )
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
 
         # Try to get existing model
-        existing_row = await session.get(ModelRow, (payload.id, provider_id))
+        existing_row = await session.get(ModelRow, (payload.id, provider_pk))
 
         if existing_row:
             # Update existing model
@@ -524,7 +526,7 @@ async def upsert_provider_model(
                 alias_ids=(
                     json.dumps(payload.alias_ids) if payload.alias_ids else None
                 ),
-                upstream_provider_id=provider_id,
+                upstream_provider_id=provider_pk,
                 enabled=payload.enabled,
                 forwarded_model_id=payload.forwarded_model_id or payload.id,
             )
@@ -543,7 +545,7 @@ async def upsert_provider_model(
     dependencies=[Depends(require_admin_api)],
 )
 async def update_provider_model_legacy(
-    provider_id: int, model_id: str, payload: ModelCreate
+    provider_id: str, model_id: str, payload: ModelCreate
 ) -> dict[str, object]:
     """Legacy PATCH endpoint - redirects to upsert POST endpoint for backward compatibility."""
     logger.info(
@@ -556,13 +558,12 @@ async def update_provider_model_legacy(
     "/api/upstream-providers/{provider_id}/models/{model_id:path}",
     dependencies=[Depends(require_admin_api)],
 )
-async def get_provider_model(provider_id: int, model_id: str) -> dict[str, object]:
+async def get_provider_model(provider_id: str, model_id: str) -> dict[str, object]:
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
 
-        row = await session.get(ModelRow, (model_id, provider_id))
+        row = await session.get(ModelRow, (model_id, provider_pk))
         if not row:
             raise HTTPException(
                 status_code=404, detail="Model not found for this provider"
@@ -576,9 +577,11 @@ async def get_provider_model(provider_id: int, model_id: str) -> dict[str, objec
     "/api/upstream-providers/{provider_id}/models/{model_id:path}",
     dependencies=[Depends(require_admin_api)],
 )
-async def delete_provider_model(provider_id: int, model_id: str) -> dict[str, object]:
+async def delete_provider_model(provider_id: str, model_id: str) -> dict[str, object]:
     async with create_session() as session:
-        row = await session.get(ModelRow, (model_id, provider_id))
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
+        row = await session.get(ModelRow, (model_id, provider_pk))
         if not row:
             raise HTTPException(
                 status_code=404, detail="Model not found for this provider"
@@ -593,10 +596,12 @@ async def delete_provider_model(provider_id: int, model_id: str) -> dict[str, ob
     "/api/upstream-providers/{provider_id}/models",
     dependencies=[Depends(require_admin_api)],
 )
-async def delete_all_provider_models(provider_id: int) -> dict[str, object]:
+async def delete_all_provider_models(provider_id: str) -> dict[str, object]:
     async with create_session() as session:
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
         result = await session.exec(
-            select(ModelRow).where(ModelRow.upstream_provider_id == provider_id)
+            select(ModelRow).where(ModelRow.upstream_provider_id == provider_pk)
         )  # type: ignore
         rows = result.all()
         for row in rows:
@@ -615,7 +620,7 @@ class BatchOverrideRequest(BaseModel):
     dependencies=[Depends(require_admin_api)],
 )
 async def batch_override_provider_models(
-    provider_id: int, payload: BatchOverrideRequest
+    provider_id: str, payload: BatchOverrideRequest
 ) -> dict[str, object]:
     """Batch override models for a specific provider."""
     logger.info(
@@ -623,15 +628,14 @@ async def batch_override_provider_models(
     )
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
 
         overridden_count = 0
 
         for model_data in payload.models:
             # Try to get existing model regardless of whether it's enabled or not
-            existing_row = await session.get(ModelRow, (model_data.id, provider_id))
+            existing_row = await session.get(ModelRow, (model_data.id, provider_pk))
 
             if existing_row:
                 # Update existing
@@ -685,7 +689,7 @@ async def batch_override_provider_models(
                         if model_data.alias_ids
                         else None
                     ),
-                    upstream_provider_id=provider_id,
+                    upstream_provider_id=provider_pk,
                     enabled=model_data.enabled,
                 )
                 session.add(row)
@@ -702,6 +706,85 @@ async def batch_override_provider_models(
     }
 
 
+_SLUG_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$")
+
+
+def _validate_slug(value: str) -> str:
+    candidate = value.strip().lower()
+    if not _SLUG_PATTERN.fullmatch(candidate):
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                "slug must be 3-64 chars, lowercase letters/digits/hyphens, "
+                "and may not start or end with a hyphen"
+            ),
+        )
+    if candidate.isdigit():
+        raise HTTPException(
+            status_code=400,
+            detail="slug must not be all digits",
+        )
+    return candidate
+
+
+async def _ensure_unique_slug(
+    session: AsyncSession, slug: str, exclude_id: int | None = None
+) -> None:
+    stmt = select(UpstreamProviderRow).where(UpstreamProviderRow.slug == slug)
+    result = await session.exec(stmt)
+    existing = result.first()
+    if existing and existing.id != exclude_id:
+        raise HTTPException(
+            status_code=409,
+            detail="Provider with this slug already exists",
+        )
+
+
+async def _get_upstream_provider_by_ref(
+    session: AsyncSession, provider_ref: str
+) -> UpstreamProviderRow:
+    if provider_ref.isdigit():
+        provider = await session.get(UpstreamProviderRow, int(provider_ref))
+    else:
+        slug = _validate_slug(provider_ref)
+        result = await session.exec(
+            select(UpstreamProviderRow).where(UpstreamProviderRow.slug == slug)
+        )
+        provider = result.first()
+
+    if not provider:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    return provider
+
+
+def _provider_pk(provider: UpstreamProviderRow) -> int:
+    if provider.id is None:
+        raise HTTPException(status_code=500, detail="Provider has no database id")
+    return provider.id
+
+
+def _serialize_provider(
+    provider: UpstreamProviderRow, redact_api_key: bool = True
+) -> dict[str, object]:
+    return {
+        "id": provider.id,
+        "slug": provider.slug,
+        "provider_type": provider.provider_type,
+        "base_url": provider.base_url,
+        "api_key": "[REDACTED]"
+        if (redact_api_key and provider.api_key)
+        else provider.api_key
+        if not redact_api_key
+        else "",
+        "api_version": provider.api_version,
+        "enabled": provider.enabled,
+        "provider_fee": provider.provider_fee,
+        "provider_settings": json.loads(provider.provider_settings)
+        if provider.provider_settings
+        else None,
+    }
+
+
 class UpstreamProviderCreate(BaseModel):
     provider_type: str
     base_url: str
@@ -710,6 +793,7 @@ class UpstreamProviderCreate(BaseModel):
     enabled: bool = True
     provider_fee: float = 1.01
     provider_settings: dict | None = None
+    slug: str | None = None
 
 
 class UpstreamProviderUpdate(BaseModel):
@@ -720,6 +804,50 @@ class UpstreamProviderUpdate(BaseModel):
     enabled: bool | None = None
     provider_fee: float | None = None
     provider_settings: dict | None = None
+    slug: str | None = None
+
+
+class UpstreamProviderUpdateBySlug(BaseModel):
+    slug: str
+    new_slug: str | None = None
+    provider_type: str | None = None
+    base_url: str | None = None
+    api_key: str | None = None
+    api_version: str | None = None
+    enabled: bool | None = None
+    provider_fee: float | None = None
+    provider_settings: dict | None = None
+
+
+async def _apply_provider_update(
+    session: AsyncSession,
+    provider: UpstreamProviderRow,
+    payload: UpstreamProviderUpdate,
+    new_slug: str | None = None,
+) -> None:
+    if new_slug is not None:
+        validated = _validate_slug(new_slug)
+        await _ensure_unique_slug(session, validated, exclude_id=provider.id)
+        provider.slug = validated
+
+    if payload.provider_type is not None:
+        provider.provider_type = payload.provider_type
+    if payload.base_url is not None:
+        provider.base_url = payload.base_url
+    if payload.api_key is not None:
+        provider.api_key = payload.api_key
+    if payload.api_version is not None:
+        provider.api_version = payload.api_version
+    if payload.enabled is not None:
+        provider.enabled = payload.enabled
+    if payload.provider_fee is not None:
+        provider.provider_fee = payload.provider_fee
+    if payload.provider_settings is not None:
+        provider.provider_settings = json.dumps(payload.provider_settings)
+
+    session.add(provider)
+    await session.commit()
+    await session.refresh(provider)
 
 
 @admin_router.get("/api/upstream-providers", dependencies=[Depends(require_admin_api)])
@@ -727,21 +855,7 @@ async def get_upstream_providers() -> list[dict[str, object]]:
     async with create_session() as session:
         result = await session.exec(select(UpstreamProviderRow))
         providers = result.all()
-        return [
-            {
-                "id": p.id,
-                "provider_type": p.provider_type,
-                "base_url": p.base_url,
-                "api_key": "[REDACTED]" if p.api_key else "",
-                "api_version": p.api_version,
-                "enabled": p.enabled,
-                "provider_fee": p.provider_fee,
-                "provider_settings": json.loads(p.provider_settings)
-                if p.provider_settings
-                else None,
-            }
-            for p in providers
-        ]
+        return [_serialize_provider(p) for p in providers]
 
 
 @admin_router.post("/api/upstream-providers", dependencies=[Depends(require_admin_api)])
@@ -761,7 +875,14 @@ async def create_upstream_provider(
                 detail="Provider with this base URL and API key already exists",
             )
 
+        if payload.slug:
+            slug = _validate_slug(payload.slug)
+            await _ensure_unique_slug(session, slug)
+        else:
+            slug = await allocate_unique_provider_slug(session, payload.provider_type)
+
         provider = UpstreamProviderRow(
+            slug=slug,
             provider_type=payload.provider_type,
             base_url=payload.base_url,
             api_key=payload.api_key,
@@ -778,99 +899,81 @@ async def create_upstream_provider(
 
     await reinitialize_upstreams()
     await refresh_model_maps()
-    return {
-        "id": provider.id,
-        "provider_type": provider.provider_type,
-        "base_url": provider.base_url,
-        "api_key": "[REDACTED]",
-        "api_version": provider.api_version,
-        "enabled": provider.enabled,
-        "provider_fee": provider.provider_fee,
-        "provider_settings": payload.provider_settings,
-    }
+    return _serialize_provider(provider)
 
 
 @admin_router.get(
     "/api/upstream-providers/{provider_id}", dependencies=[Depends(require_admin_api)]
 )
-async def get_upstream_provider(provider_id: int) -> dict[str, object]:
+async def get_upstream_provider(provider_id: str) -> dict[str, object]:
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
-        return {
-            "id": provider.id,
-            "provider_type": provider.provider_type,
-            "base_url": provider.base_url,
-            "api_key": "[REDACTED]" if provider.api_key else "",
-            "api_version": provider.api_version,
-            "enabled": provider.enabled,
-            "provider_fee": provider.provider_fee,
-            "provider_settings": json.loads(provider.provider_settings)
-            if provider.provider_settings
-            else None,
-        }
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        return _serialize_provider(provider)
 
 
 @admin_router.patch(
     "/api/upstream-providers/{provider_id}", dependencies=[Depends(require_admin_api)]
 )
 async def update_upstream_provider(
-    provider_id: int, payload: UpstreamProviderUpdate
+    provider_id: str, payload: UpstreamProviderUpdate
 ) -> dict[str, object]:
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
-        if payload.provider_type is not None:
-            provider.provider_type = payload.provider_type
-        if payload.base_url is not None:
-            provider.base_url = payload.base_url
-        if payload.api_key is not None:
-            provider.api_key = payload.api_key
-        if payload.api_version is not None:
-            provider.api_version = payload.api_version
-        if payload.enabled is not None:
-            provider.enabled = payload.enabled
-        if payload.provider_fee is not None:
-            provider.provider_fee = payload.provider_fee
-        if payload.provider_settings is not None:
-            provider.provider_settings = json.dumps(payload.provider_settings)
-
-        session.add(provider)
-        await session.commit()
-        await session.refresh(provider)
+        await _apply_provider_update(session, provider, payload, new_slug=payload.slug)
 
     await reinitialize_upstreams()
     await refresh_model_maps()
-    return {
-        "id": provider.id,
-        "provider_type": provider.provider_type,
-        "base_url": provider.base_url,
-        "api_key": "[REDACTED]",
-        "api_version": provider.api_version,
-        "enabled": provider.enabled,
-        "provider_fee": provider.provider_fee,
-        "provider_settings": json.loads(provider.provider_settings)
-        if provider.provider_settings
-        else None,
-    }
+    return _serialize_provider(provider)
+
+
+@admin_router.patch(
+    "/api/upstream-providers", dependencies=[Depends(require_admin_api)]
+)
+async def update_upstream_provider_by_slug(
+    payload: UpstreamProviderUpdateBySlug,
+) -> dict[str, object]:
+    lookup = _validate_slug(payload.slug)
+    async with create_session() as session:
+        result = await session.exec(
+            select(UpstreamProviderRow).where(
+                UpstreamProviderRow.slug == lookup
+            )
+        )
+        provider = result.first()
+        if not provider:
+            raise HTTPException(status_code=404, detail="Provider not found")
+
+        update_payload = UpstreamProviderUpdate(
+            provider_type=payload.provider_type,
+            base_url=payload.base_url,
+            api_key=payload.api_key,
+            api_version=payload.api_version,
+            enabled=payload.enabled,
+            provider_fee=payload.provider_fee,
+            provider_settings=payload.provider_settings,
+        )
+        await _apply_provider_update(
+            session, provider, update_payload, new_slug=payload.new_slug
+        )
+
+    await reinitialize_upstreams()
+    await refresh_model_maps()
+    return _serialize_provider(provider)
 
 
 @admin_router.delete(
     "/api/upstream-providers/{provider_id}", dependencies=[Depends(require_admin_api)]
 )
-async def delete_upstream_provider(provider_id: int) -> dict[str, object]:
+async def delete_upstream_provider(provider_id: str) -> dict[str, object]:
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        deleted_id = _provider_pk(provider)
         await session.delete(provider)
         await session.commit()
     await reinitialize_upstreams()
     await refresh_model_maps()
-    return {"ok": True, "deleted_id": provider_id}
+    return {"ok": True, "deleted_id": deleted_id}
 
 
 @admin_router.get("/api/provider-types", dependencies=[Depends(require_admin_api)])
@@ -885,17 +988,16 @@ async def get_provider_types() -> list[dict[str, object]]:
     "/api/upstream-providers/{provider_id}/models",
     dependencies=[Depends(require_admin_api)],
 )
-async def get_provider_models(provider_id: int) -> dict[str, object]:
+async def get_provider_models(provider_id: str) -> dict[str, object]:
     from ..upstream.helpers import _instantiate_provider
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
 
         db_models = await list_models(
             session=session,
-            upstream_id=provider_id,
+            upstream_id=provider_pk,
             include_disabled=True,
             apply_fees=False,
         )
@@ -985,13 +1087,11 @@ class TopupTokenRequest(BaseModel):
     dependencies=[Depends(require_admin_api)],
 )
 async def topup_provider_with_token(
-    provider_id: int, payload: TopupTokenRequest
+    provider_id: str, payload: TopupTokenRequest
 ) -> dict:
     """Redeem a Cashu token for an upstream provider."""
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
         import httpx
 
@@ -1022,15 +1122,13 @@ async def topup_provider_with_token(
     dependencies=[Depends(require_admin_api)],
 )
 async def initiate_provider_topup(
-    provider_id: int, payload: TopupRequest
+    provider_id: str, payload: TopupRequest
 ) -> dict[str, object]:
     """Initiate a Lightning Network top-up for the upstream provider account."""
     from ..upstream.helpers import _instantiate_provider
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
         try:
             logger.info(
@@ -1150,15 +1248,13 @@ async def initiate_provider_topup(
     "/api/upstream-providers/{provider_id}/topup/{invoice_id}/status",
     dependencies=[Depends(require_admin_api)],
 )
-async def check_topup_status(provider_id: int, invoice_id: str) -> dict[str, object]:
+async def check_topup_status(provider_id: str, invoice_id: str) -> dict[str, object]:
     """Check the status of a Lightning Network top-up invoice."""
     from ..upstream.helpers import _instantiate_provider
     from ..upstream.ppqai import PPQAIUpstreamProvider
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
         # For Routstr providers, proxy the status check
         if provider.provider_type == "routstr":
@@ -1205,14 +1301,12 @@ async def check_topup_status(provider_id: int, invoice_id: str) -> dict[str, obj
     "/api/upstream-providers/{provider_id}/balance",
     dependencies=[Depends(require_admin_api)],
 )
-async def get_provider_balance(provider_id: int) -> dict[str, object]:
+async def get_provider_balance(provider_id: str) -> dict[str, object]:
     """Get the current balance for an upstream provider account."""
     from ..upstream.helpers import _instantiate_provider
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
         # For Routstr providers, proxy the balance check
         if provider.provider_type == "routstr":
@@ -1591,15 +1685,13 @@ async def get_lightning_invoices_api(
     "/api/upstream-providers/{provider_id}/routstr/refund",
     dependencies=[Depends(require_admin_api)],
 )
-async def refund_routstr_provider_balance(provider_id: int) -> dict[str, object]:
+async def refund_routstr_provider_balance(provider_id: str) -> dict[str, object]:
     """Refund balance from an upstream Routstr provider back to the local wallet."""
     from ..upstream.helpers import _instantiate_provider
     from ..upstream.routstr import RoutstrUpstreamProvider
 
     async with create_session() as session:
-        provider_row = await session.get(UpstreamProviderRow, provider_id)
-        if not provider_row:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider_row = await _get_upstream_provider_by_ref(session, provider_id)
 
         if provider_row.provider_type != "routstr":
             raise HTTPException(

routstr/core/db.py

@@ -9,9 +9,10 @@ from typing import AsyncGenerator
 from alembic import command
 from alembic.config import Config
 from alembic.util.exc import CommandError
-from sqlalchemy import UniqueConstraint
+from sqlalchemy import UniqueConstraint, delete
 from sqlalchemy.exc import OperationalError
 from sqlalchemy.ext.asyncio.engine import create_async_engine
+from sqlalchemy.orm import aliased
 from sqlmodel import Field, Relationship, SQLModel, col, func, select, update
 from sqlmodel.ext.asyncio.session import AsyncSession
 
@@ -125,6 +126,63 @@ async def release_stale_reservations(
     return released
 
 
+async def prune_dead_api_keys(session: AsyncSession, min_age_seconds: int) -> int:
+    """Delete dead parentless API keys; return the count removed.
+
+    Dead = 0 balance/reservation/spend/requests, older than the grace period,
+    no parent, no children, no pending invoice. Cashu rows are unlinked (not
+    deleted) first to keep the audit trail.
+    """
+    cutoff = int(time.time()) - min_age_seconds
+
+    child = aliased(ApiKey)
+    has_children = (
+        select(child.hashed_key).where(
+            col(child.parent_key_hash) == col(ApiKey.hashed_key)
+        )
+    ).exists()
+    pending_invoice = (
+        select(LightningInvoice.id)
+        .where(col(LightningInvoice.api_key_hash) == col(ApiKey.hashed_key))
+        .where(col(LightningInvoice.status) == "pending")
+    ).exists()
+
+    eligible_hashes = (
+        select(ApiKey.hashed_key)
+        .where(col(ApiKey.balance) == 0)
+        .where(col(ApiKey.reserved_balance) == 0)
+        .where(col(ApiKey.total_spent) == 0)
+        .where(col(ApiKey.total_requests) == 0)
+        .where(col(ApiKey.parent_key_hash).is_(None))
+        .where(
+            (col(ApiKey.created_at).is_(None)) | (col(ApiKey.created_at) < cutoff)
+        )
+        .where(~pending_invoice)
+        .where(~has_children)
+    )
+
+    # Unlink transactions rather than cascade-deleting them, so the financial
+    # audit trail survives. The eligibility predicate is re-evaluated inside both
+    # statements so a key that gained balance mid-run is left untouched.
+    await session.exec(  # type: ignore[call-overload]
+        update(CashuTransaction)
+        .where(col(CashuTransaction.api_key_hashed_key).in_(eligible_hashes))
+        .values(api_key_hashed_key=None)
+    )
+
+    result = await session.exec(  # type: ignore[call-overload]
+        delete(ApiKey).where(col(ApiKey.hashed_key).in_(eligible_hashes))
+    )
+    await session.commit()
+
+    pruned = int(result.rowcount or 0)
+    logger.info(
+        "Pruned dead API keys",
+        extra={"pruned_keys": pruned, "min_age_seconds": min_age_seconds},
+    )
+    return pruned
+
+
 class ModelRow(SQLModel, table=True):  # type: ignore
     __tablename__ = "models"
     id: str = Field(primary_key=True)
@@ -152,6 +210,41 @@ class ModelRow(SQLModel, table=True):  # type: ignore
     upstream_provider: "UpstreamProviderRow" = Relationship(back_populates="models")
 
 
+class ModelPathRow(SQLModel, table=True):  # type: ignore
+    """Upstream provider path a model is reachable through.
+
+    Discovery/visibility data only. ``model_id`` is intentionally NOT globally
+    unique: it is the client-visible ``/v1/models`` id (``forwarded_model_id or
+    id``) grouped across every provider that exposes the model. A single model
+    can therefore have several rows — one per direct provider path plus one per
+    OpenRouter sub-provider endpoint.
+    """
+
+    __tablename__ = "model_paths"
+    __table_args__ = (
+        UniqueConstraint(
+            "model_id",
+            "path",
+            "upstream_provider_id",
+            name="uq_model_paths_model_path_provider",
+        ),
+    )
+    id: int | None = Field(default=None, primary_key=True)
+    model_id: str = Field(
+        index=True, description="Client-visible /v1/models id (forwarded_model_id or id)"
+    )
+    path: str = Field(
+        description="Provider path stamped on chat completion responses, e.g. "
+        "'anthropic' or 'openrouter:Anthropic'"
+    )
+    upstream_provider_id: int = Field(
+        index=True,
+        foreign_key="upstream_providers.id",
+        ondelete="CASCADE",
+        description="upstream_providers.id this path was discovered from",
+    )
+
+
 class LightningInvoice(SQLModel, table=True):  # type: ignore
     __tablename__ = "lightning_invoices"
 
@@ -261,6 +354,12 @@ class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
         ),
     )
     id: int | None = Field(default=None, primary_key=True)
+    slug: str | None = Field(
+        default=None,
+        unique=True,
+        index=True,
+        description="Stable external slug used for updates via API key.",
+    )
     provider_type: str = Field(
         description="Provider type: custom, openai, anthropic, azure, openrouter, etc."
     )

routstr/core/exceptions.py

@@ -7,11 +7,26 @@ logger = get_logger(__name__)
 
 
 class UpstreamError(Exception):
-    """Exception raised when an upstream provider fails."""
+    """Exception raised when an upstream provider fails.
 
-    def __init__(self, message: str, status_code: int = 502):
+    ``code`` carries a stable, machine-readable classification (e.g.
+    ``UPSTREAM_RATE_LIMIT``) so callers can distinguish failure kinds without
+    string-matching the message. ``details`` holds optional structured,
+    redaction-safe context. Both default to ``None`` for backwards
+    compatibility.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 502,
+        code: str | None = None,
+        details: dict[str, object] | None = None,
+    ):
         self.message = message
         self.status_code = status_code
+        self.code = code
+        self.details = details
         super().__init__(message)
 
 

routstr/core/logging.py

@@ -51,6 +51,8 @@ from pythonjsonlogger import jsonlogger
 from rich.console import Console
 from rich.logging import RichHandler
 
+from .redaction import redact_obj, redact_org_ids
+
 # Only use RichHandler when stdout is a real TTY. In non-TTY contexts
 # (docker logs, pipes, CI) Rich pads every line to width and wraps long
 # records, producing visually-empty trailing whitespace and split records.
@@ -180,6 +182,37 @@ class RequestIdFilter(logging.Filter):
         return True
 
 
+# Standard ``LogRecord`` attributes that are never user-supplied ``extra``
+# fields; skipped when redacting structured extras (``msg``/``message`` are
+# handled separately above).
+_NON_EXTRA_RECORD_ATTRS = frozenset(
+    {
+        "name",
+        "msg",
+        "args",
+        "levelname",
+        "levelno",
+        "pathname",
+        "filename",
+        "module",
+        "exc_info",
+        "exc_text",
+        "stack_info",
+        "lineno",
+        "funcName",
+        "created",
+        "msecs",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "processName",
+        "process",
+        "taskName",
+        "message",
+    }
+)
+
+
 class SecurityFilter(logging.Filter):
     """Filter to remove sensitive information from logs."""
 
@@ -203,6 +236,7 @@ class SecurityFilter(logging.Filter):
         """Filter out sensitive information from log records."""
         try:
             message = record.getMessage()
+            message = redact_org_ids(message)
             standalone_patterns = [
                 r"Bearer\s+([a-zA-Z0-9_\-\.]{10,})",  # Bearer token (must be 10 characters or more to reduce false-positives)
                 r"cashu[A-Z]+([a-zA-Z0-9_\-\.=/+]+)",  # Cashu tokens
@@ -224,6 +258,16 @@ class SecurityFilter(logging.Filter):
             record.msg = message
             record.args = ()
 
+            # Structured `extra={...}` fields are emitted by the JSON formatter
+            # straight from the record dict and never pass through the message
+            # formatting above. Redact organization IDs from any string-valued
+            # extra so they cannot leak via structured logs.
+            for attr, value in list(record.__dict__.items()):
+                if attr in _NON_EXTRA_RECORD_ATTRS:
+                    continue
+                if isinstance(value, (str, dict, list, tuple)):
+                    record.__dict__[attr] = redact_obj(value)
+
         except Exception:
             pass
 

routstr/core/main.py

@@ -11,7 +11,11 @@ from starlette.exceptions import HTTPException
 from starlette.responses import Response as StarletteResponse
 from starlette.types import Scope
 
-from ..auth import periodic_key_reset, periodic_stale_reservation_sweep
+from ..auth import (
+    periodic_dead_key_prune,
+    periodic_key_reset,
+    periodic_stale_reservation_sweep,
+)
 from ..balance import balance_router, deprecated_wallet_router
 from ..lightning import lightning_router, periodic_invoice_watcher
 from ..nostr import (
@@ -24,6 +28,7 @@ from ..payment.models import models_router, update_sats_pricing
 from ..payment.price import update_prices_periodically
 from ..proxy import initialize_upstreams, proxy_router, refresh_model_maps_periodically
 from ..upstream.auto_topup import periodic_auto_topup
+from ..upstream.deepseek_v4_pricing_shim import register_deepseek_v4_pricing
 from ..upstream.litellm_routing import configure_litellm
 from ..wallet import periodic_payout, periodic_refund_sweep, periodic_routstr_fee_payout
 from .admin import admin_router
@@ -53,8 +58,10 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
     providers_task = None
     models_refresh_task = None
     model_maps_refresh_task = None
+    model_paths_refresh_task = None
     key_reset_task = None
     stale_reservation_task = None
+    dead_key_prune_task = None
     auto_topup_task = None
     refund_sweep_task = None
     routstr_fee_task = None
@@ -65,6 +72,11 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
         # debug logging) before any upstream provider dispatches a request.
         configure_litellm()
 
+        # TEMPORARY: backfill DeepSeek V4 pricing missing from litellm's cost
+        # map (BerriAI/litellm#30430). Remove this call and
+        # deepseek_v4_pricing_shim.py once litellm ships these models.
+        register_deepseek_v4_pricing()
+
         # Run database migrations on startup
         run_migrations()
 
@@ -116,6 +128,12 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
                 refresh_upstreams_models_periodically(get_upstreams)
             )
         model_maps_refresh_task = asyncio.create_task(refresh_model_maps_periodically())
+        if global_settings.model_paths_refresh_interval_seconds > 0:
+            from ..upstream.model_paths import refresh_model_paths_periodically
+
+            model_paths_refresh_task = asyncio.create_task(
+                refresh_model_paths_periodically(get_upstreams)
+            )
         payout_task = asyncio.create_task(periodic_payout())
         if global_settings.nsec:
             nip91_task = asyncio.create_task(announce_provider())
@@ -126,6 +144,7 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
         stale_reservation_task = asyncio.create_task(
             periodic_stale_reservation_sweep()
         )
+        dead_key_prune_task = asyncio.create_task(periodic_dead_key_prune())
         auto_topup_task = asyncio.create_task(periodic_auto_topup())
         refund_sweep_task = asyncio.create_task(periodic_refund_sweep())
         routstr_fee_task = asyncio.create_task(periodic_routstr_fee_payout())
@@ -161,10 +180,14 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
             models_refresh_task.cancel()
         if model_maps_refresh_task is not None:
             model_maps_refresh_task.cancel()
+        if model_paths_refresh_task is not None:
+            model_paths_refresh_task.cancel()
         if key_reset_task is not None:
             key_reset_task.cancel()
         if stale_reservation_task is not None:
             stale_reservation_task.cancel()
+        if dead_key_prune_task is not None:
+            dead_key_prune_task.cancel()
         if auto_topup_task is not None:
             auto_topup_task.cancel()
         if refund_sweep_task is not None:
@@ -192,10 +215,14 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
                 tasks_to_wait.append(models_refresh_task)
             if model_maps_refresh_task is not None:
                 tasks_to_wait.append(model_maps_refresh_task)
+            if model_paths_refresh_task is not None:
+                tasks_to_wait.append(model_paths_refresh_task)
             if key_reset_task is not None:
                 tasks_to_wait.append(key_reset_task)
             if stale_reservation_task is not None:
                 tasks_to_wait.append(stale_reservation_task)
+            if dead_key_prune_task is not None:
+                tasks_to_wait.append(dead_key_prune_task)
             if auto_topup_task is not None:
                 tasks_to_wait.append(auto_topup_task)
             if refund_sweep_task is not None:
@@ -363,7 +390,10 @@ if UI_DIST_PATH.exists() and UI_DIST_PATH.is_dir():
 
 else:
     logger.warning(
-        f"UI dist directory not found at {UI_DIST_PATH}, skipping static file serving"
+        "UI dist directory not found at %s; serving API only. Run `make ui-build` "
+        "to build the static UI served from here, or `make ui-dev` for the Next.js "
+        "dev server with hot reload on :3000 (it targets this backend on :8000).",
+        UI_DIST_PATH,
     )
 
     @app.get("/", include_in_schema=False)

routstr/core/provider_slugs.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import re
+from itertools import count
+from typing import Collection
+
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from .db import UpstreamProviderRow
+
+_SLUG_BASE_PATTERN = re.compile(r"[^a-z0-9]+")
+_MAX_SLUG_LENGTH = 64
+
+
+def provider_slug_base(provider_type: str) -> str:
+    """Return a deterministic slug base for a provider type."""
+    base = _SLUG_BASE_PATTERN.sub("-", provider_type.lower()).strip("-")
+    if not base:
+        base = "provider"
+    elif base.isdigit():
+        base = f"provider-{base}"
+    elif len(base) < 3:
+        base = f"{base}-provider"
+
+    if len(base) > _MAX_SLUG_LENGTH:
+        base = base[:_MAX_SLUG_LENGTH].rstrip("-") or "provider"
+    return base
+
+
+def provider_slug_candidate(base: str, suffix_number: int) -> str:
+    if suffix_number == 1:
+        return base
+
+    suffix = f"-{suffix_number}"
+    max_base_length = _MAX_SLUG_LENGTH - len(suffix)
+    return f"{base[:max_base_length].rstrip('-')}{suffix}"
+
+
+async def allocate_unique_provider_slug(
+    session: AsyncSession,
+    provider_type: str,
+    reserved_slugs: Collection[str] = (),
+) -> str:
+    """Allocate a stable, deterministic provider slug.
+
+    The first provider of a type gets ``openai``; later collisions get
+    ``openai-2``, ``openai-3``, etc. ``reserved_slugs`` covers rows staged in
+    memory but not flushed yet, such as settings/env seeding.
+    """
+    base = provider_slug_base(provider_type)
+    reserved = {slug.lower() for slug in reserved_slugs}
+
+    for suffix_number in count(1):
+        candidate = provider_slug_candidate(base, suffix_number)
+        if candidate in reserved:
+            continue
+
+        result = await session.exec(
+            select(UpstreamProviderRow).where(UpstreamProviderRow.slug == candidate)
+        )
+        if result.first() is None:
+            return candidate
+
+    raise RuntimeError("unreachable")

routstr/core/redaction.py

@@ -0,0 +1,51 @@
+"""Redaction helpers for sensitive provider identifiers.
+
+Single source of truth for stripping account-scoped identifiers (e.g. OpenAI
+organization IDs) from any text before it is logged, returned to a caller, or
+written to an audit entry.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# OpenAI-style organization identifiers look like ``org-<base62>``. Require at
+# least 6 trailing chars so the already-redacted literal ``org-[REDACTED]`` is
+# never re-matched (``[`` is not in the character class).
+_ORG_ID_PATTERN = re.compile(r"\borg-[A-Za-z0-9]{6,}\b")
+
+ORG_ID_PLACEHOLDER = "org-[REDACTED]"
+
+
+def redact_org_ids(text: str) -> str:
+    """Replace OpenAI-style organization IDs with ``org-[REDACTED]``.
+
+    Args:
+        text: Arbitrary text that may embed an ``org-*`` identifier.
+
+    Returns:
+        The text with every organization ID replaced. Non-string input is
+        returned unchanged after coercion to ``str``.
+    """
+    if not text:
+        return text
+    return _ORG_ID_PATTERN.sub(ORG_ID_PLACEHOLDER, text)
+
+
+def redact_obj(obj: Any) -> Any:
+    """Recursively redact organization IDs in arbitrary nested structures.
+
+    Strings are redacted in place; dicts and lists/tuples are walked so that
+    identifiers nested inside structured payloads (e.g. log ``extra`` fields or
+    error ``details``) are also stripped. Other types are returned unchanged.
+    """
+    if isinstance(obj, str):
+        return redact_org_ids(obj)
+    if isinstance(obj, dict):
+        return {key: redact_obj(value) for key, value in obj.items()}
+    if isinstance(obj, list):
+        return [redact_obj(value) for value in obj]
+    if isinstance(obj, tuple):
+        return tuple(redact_obj(value) for value in obj)
+    return obj

routstr/core/settings.py

@@ -73,6 +73,14 @@ class Settings(BaseSettings):
     stale_reservation_timeout_seconds: int = Field(
         default=300, env="STALE_RESERVATION_TIMEOUT_SECONDS"
     )
+    # Background prune of dead (zero balance, never used) API keys.
+    # Interval 0 disables it; min-age is a grace period (default 1 week).
+    dead_key_prune_interval_seconds: int = Field(
+        default=3600, env="DEAD_KEY_PRUNE_INTERVAL_SECONDS"
+    )
+    dead_key_min_age_seconds: int = Field(
+        default=604_800, env="DEAD_KEY_MIN_AGE_SECONDS"
+    )
 
     # Network
     cors_origins: list[str] = Field(default_factory=lambda: ["*"], env="CORS_ORIGINS")
@@ -86,6 +94,9 @@ class Settings(BaseSettings):
     models_refresh_interval_seconds: int = Field(
         default=360, env="MODELS_REFRESH_INTERVAL_SECONDS"
     )
+    model_paths_refresh_interval_seconds: int = Field(
+        default=600, env="MODEL_PATHS_REFRESH_INTERVAL_SECONDS"
+    )
     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")

routstr/payment/cost_calculation.py

@@ -3,9 +3,17 @@ import math
 from pydantic.v1 import BaseModel
 
 from ..core import get_logger
-from ..core.db import AsyncSession
 from ..core.settings import settings
 from .price import sats_usd_price
+from .usage import normalize_usage, parse_token_count
+
+__all__ = [
+    "CostData",
+    "CostDataError",
+    "MaxCostData",
+    "calculate_cost",
+    "parse_token_count",
+]
 
 logger = get_logger(__name__)
 
@@ -33,8 +41,31 @@ class CostDataError(BaseModel):
     code: str
 
 
+def _empty_cost(cls: type[CostData] = CostData) -> CostData:
+    """Build an all-zero cost object — a full refund for an empty response.
+
+    Shared by the two paths that must not bill: an upstream response with no
+    usage data at all, and one that reports a USD cost but carries zero tokens
+    in every bucket.
+    """
+    return cls(
+        base_msats=0,
+        input_msats=0,
+        output_msats=0,
+        total_msats=0,
+        total_usd=0.0,
+        input_tokens=0,
+        output_tokens=0,
+        cache_read_input_tokens=0,
+        cache_creation_input_tokens=0,
+        cache_read_msats=0,
+        cache_creation_msats=0,
+    )
+
+
 async def calculate_cost(
-    response_data: dict, max_cost: int, session: AsyncSession
+    response_data: dict,
+    max_cost: int,
 ) -> CostData | MaxCostData | CostDataError:
     """Calculate the cost of an API request based on token usage.
 
@@ -44,6 +75,9 @@ async def calculate_cost(
 
     Returns:
         Cost data or error information
+
+    The response's usage object is normalized with the default union parser;
+    this function holds no vendor-dialect knowledge of its own.
     """
     logger.debug(
         "Starting cost calculation",
@@ -54,8 +88,9 @@ async def calculate_cost(
         },
     )
 
-    # Check for usage data
-    if "usage" not in response_data or response_data["usage"] is None:
+    usage = normalize_usage(response_data.get("usage"))
+
+    if usage is None:
         logger.warning(
             "No usage data in response — billing at MaxCostData with zero "
             "tokens. Dashboard will show this request as `(0+0)`. Most "
@@ -70,34 +105,41 @@ async def calculate_cost(
                 else None,
             },
         )
-        return MaxCostData(
-            base_msats=0,
-            input_msats=0,
-            output_msats=0,
-            total_msats=0,
-            total_usd=0.0,
-            input_tokens=0,
-            output_tokens=0,
-            cache_read_input_tokens=0,
-            cache_creation_input_tokens=0,
-            cache_read_msats=0,
-            cache_creation_msats=0,
-        )
+        return _empty_cost(MaxCostData)
 
-    usage_data = response_data["usage"]
+    usage_data = response_data.get("usage") or {}
+    if not isinstance(usage_data, dict):
+        usage_data = {}
 
-    # Extract token counts
-    input_tokens = _extract_token_pair(usage_data, "prompt_tokens", "input_tokens")
-    output_tokens = _extract_token_pair(usage_data, "completion_tokens", "output_tokens")
-
-    # Extract cache tokens (handles OpenAI vs Anthropic formats)
-    cache_read_tokens, cache_creation_tokens, input_tokens = _extract_cache_tokens(
-        usage_data, input_tokens
-    )
+    input_tokens = usage.input_tokens
+    output_tokens = usage.output_tokens
+    cache_read_tokens = usage.cache_read_tokens
+    cache_creation_tokens = usage.cache_write_tokens
 
     # Try USD cost first
     usd_cost = _resolve_usd_cost(usage_data, response_data)
     if usd_cost > 0:
+        truly_empty = (
+            input_tokens == 0
+            and output_tokens == 0
+            and cache_read_tokens == 0
+            and cache_creation_tokens == 0
+        )
+        if truly_empty:
+            logger.warning(
+                "Upstream reported a USD cost but the response carries no "
+                "tokens at all (input, output, cache-read and cache-creation "
+                "are all zero) — refunding in full rather than billing the "
+                "USD-derived cost for an empty response.",
+                extra={
+                    "model": response_data.get("model", "unknown"),
+                    "usd_cost": usd_cost,
+                    "usage_keys": sorted(usage_data.keys())
+                    if isinstance(usage_data, dict)
+                    else None,
+                },
+            )
+            return _empty_cost()
         if input_tokens == 0 and output_tokens == 0:
             logger.warning(
                 "Upstream reported a USD cost but no token counts — "
@@ -202,22 +244,6 @@ async def calculate_cost(
 # ============================================================================
 
 
-def parse_token_count(value: object) -> int:
-    """Parse a token count from various formats (int, float, str, bool)."""
-    if isinstance(value, bool):
-        return 0
-    if isinstance(value, int):
-        return max(0, value)
-    if isinstance(value, float):
-        return max(0, int(value))
-    if isinstance(value, str):
-        try:
-            return max(0, int(float(value)))
-        except ValueError:
-            return 0
-    return 0
-
-
 def _coerce_usd(value: object) -> float:
     """Coerce a value to USD float, handling various formats safely."""
     if value is None or isinstance(value, bool):
@@ -230,37 +256,6 @@ def _coerce_usd(value: object) -> float:
         return 0.0
 
 
-def _extract_token_pair(
-    usage_data: dict, standard_field: str, alt_field: str
-) -> int:
-    """Extract token count trying two field names in order."""
-    value = parse_token_count(usage_data.get(standard_field, 0))
-    if value > 0:
-        return value
-    return parse_token_count(usage_data.get(alt_field, 0))
-
-
-def _extract_cache_tokens(usage_data: dict, input_tokens: int) -> tuple[int, int, int]:
-    """Extract cache tokens, handling OpenAI vs Anthropic formats.
-
-    Returns: (cache_read_tokens, cache_creation_tokens, adjusted_input_tokens)
-    """
-    cache_read = parse_token_count(usage_data.get("cache_read_input_tokens", 0))
-    cache_creation = parse_token_count(
-        usage_data.get("cache_creation_input_tokens", 0)
-    )
-
-    # OpenAI: cache is included in input_tokens, subtract it
-    prompt_details = usage_data.get("prompt_tokens_details")
-    if isinstance(prompt_details, dict) and not cache_read:
-        openai_cached = parse_token_count(prompt_details.get("cached_tokens", 0))
-        if openai_cached:
-            cache_read = openai_cached
-            input_tokens = max(0, input_tokens - cache_read)
-
-    return cache_read, cache_creation, input_tokens
-
-
 def _resolve_usd_cost(usage_data: dict, response_data: dict) -> float:
     """Resolve USD cost with clear priority order.
 
@@ -454,10 +449,21 @@ def _calculate_from_tokens(
         },
     )
 
+    # Fold the cache-read/write cost into the visible ``input_msats`` so a
+    # dashboard that renders I / O / T sees ``input + output == total``
+    # exactly. This mirrors ``_fold_cache_into_input_tokens`` (which rolls the
+    # cache token counts into the visible prompt total). The standalone
+    # ``cache_read_msats`` / ``cache_creation_msats`` fields stay populated for
+    # clients that want the breakdown; nothing sums the components to derive
+    # ``total_msats`` (it is computed independently above), so this is
+    # display-only and does not change what is billed.
+    visible_output_msats = int(calc_output_msats)
+    visible_input_msats = token_based_cost - visible_output_msats
+
     return CostData(
         base_msats=0,
-        input_msats=int(calc_input_msats),
-        output_msats=int(calc_output_msats),
+        input_msats=visible_input_msats,
+        output_msats=visible_output_msats,
         total_msats=token_based_cost,
         total_usd=total_usd,
         input_tokens=input_tokens,

routstr/payment/helpers.py

@@ -11,6 +11,8 @@ from PIL import Image
 from sqlmodel.ext.asyncio.session import AsyncSession
 
 from ..core import get_logger
+from ..core.exceptions import UpstreamError
+from ..core.redaction import redact_org_ids
 from ..core.settings import settings
 from ..wallet import deserialize_token_from_string
 
@@ -418,16 +420,27 @@ def create_error_response(
     status_code: int,
     request: Request,
     token: str | None = None,
+    code: str | int | None = None,
+    details: dict[str, object] | None = None,
 ) -> Response:
-    """Create a standardized error response."""
+    """Create a standardized error response.
+
+    ``code`` is a stable, machine-readable classification (e.g.
+    ``UPSTREAM_RATE_LIMIT``); when omitted it defaults to the HTTP status code
+    for backwards compatibility. ``details`` carries optional structured,
+    redaction-safe context.
+    """
+    error_obj: dict[str, object] = {
+        "message": redact_org_ids(message),
+        "type": error_type,
+        "code": code if code is not None else status_code,
+    }
+    if details is not None:
+        error_obj["details"] = details
     return Response(
         content=json.dumps(
             {
-                "error": {
-                    "message": message,
-                    "type": error_type,
-                    "code": status_code,
-                },
+                "error": error_obj,
                 "request_id": getattr(request.state, "request_id", "unknown"),
             }
         ),
@@ -435,3 +448,20 @@ def create_error_response(
         media_type="application/json",
         headers={"X-Cashu": token} if token else {},
     )
+
+
+def create_upstream_error_response(
+    error: UpstreamError,
+    request: Request,
+    fallback_status: int = 502,
+) -> Response:
+    """Build an error response from an :class:`UpstreamError`, preserving its
+    structured ``code``, ``details``, and original ``status_code``."""
+    return create_error_response(
+        "upstream_error",
+        str(error),
+        error.status_code or fallback_status,
+        request=request,
+        code=getattr(error, "code", None),
+        details=getattr(error, "details", None),
+    )

routstr/payment/models.py

@@ -85,6 +85,65 @@ class Model(BaseModel):
         return hash(self.id)
 
 
+def backfill_cache_pricing(model_id: str, pricing: Pricing) -> Pricing:
+    """Fill missing cache rates from litellm's bundled cost map.
+
+    The OpenRouter model feed omits ``input_cache_read``/``input_cache_write``
+    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.
+
+    Rates already present (e.g. provided by OpenRouter) are authoritative and
+    never overwritten. Unknown models are returned unchanged.
+    """
+    needs_read = (pricing.input_cache_read or 0.0) <= 0.0
+    needs_write = (pricing.input_cache_write or 0.0) <= 0.0
+    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
+    if info is None:
+        return pricing
+
+    updated = Pricing.parse_obj(pricing.dict())
+    if needs_read:
+        read_rate = info.get("cache_read_input_token_cost")
+        if isinstance(read_rate, (int, float)) and read_rate > 0:
+            updated.input_cache_read = float(read_rate)
+    if needs_write:
+        write_rate = info.get("cache_creation_input_token_cost")
+        if isinstance(write_rate, (int, float)) and write_rate > 0:
+            updated.input_cache_write = float(write_rate)
+    return updated
+
+
 def _has_valid_pricing(model: dict) -> bool:
     """Check if model has valid pricing (not free, no negative values)."""
     pricing = model.get("pricing", {})
@@ -173,13 +232,29 @@ def _row_to_model(
     )
     top_provider_dict = json.loads(row.top_provider) if row.top_provider else None
 
-    if apply_provider_fee and isinstance(pricing, dict):
-        pricing = {k: float(v) * provider_fee for k, v in pricing.items()}
-
     if isinstance(pricing, dict) and float(pricing.get("request", 0.0)) <= 0.0:
         pricing["request"] = max(pricing.get("request", 0.0), 0.0)
 
     parsed_pricing = Pricing.parse_obj(pricing)
+
+    # Fill missing cache-read/write rates from litellm's cost map BEFORE applying
+    # the provider fee, so they carry the same markup as every other component.
+    # DB-stored override pricing (e.g. generic providers) omits cache rates;
+    # without this, ``_row_to_model`` bills cache reads at the full input rate —
+    # the ``_apply_provider_fee_to_model`` path backfills, but the override path
+    # used for admin-configured providers did not.
+    #
+    # Key on ``forwarded_model_id`` (the actual upstream model name litellm
+    # prices) when set: an alias row (id="local-alias",
+    # forwarded_model_id="deepseek-v4-flash") would otherwise look up the alias
+    # and miss the cache rate.
+    pricing_model_id = getattr(row, "forwarded_model_id", None) or row.id
+    parsed_pricing = backfill_cache_pricing(pricing_model_id, parsed_pricing)
+
+    if apply_provider_fee:
+        parsed_pricing = Pricing.parse_obj(
+            {k: float(v) * provider_fee for k, v in parsed_pricing.dict().items()}
+        )
     model = Model(
         id=row.id,
         name=row.name,
@@ -521,6 +596,29 @@ async def test_model(
         }
 
 
+@models_router.get("/v1/models/paths")
+@models_router.get("/v1/models/paths/", include_in_schema=False)
+async def model_paths() -> dict:
+    """All models with every upstream provider path they are reachable through."""
+    from ..upstream.model_paths import get_all_model_paths
+
+    return {"data": await get_all_model_paths()}
+
+
+@models_router.get("/v1/models/paths/model")
+@models_router.get("/v1/models/paths/model/", include_in_schema=False)
+async def model_paths_for_model(model_id: str) -> dict:
+    """Paths for a single model.
+
+    Uses a query parameter (``?model_id=...``) under a fully static route so
+    model ids containing ``/`` (e.g. ``anthropic/claude-opus-4.6``) need no URL
+    encoding and there is no dynamic-route ambiguity.
+    """
+    from ..upstream.model_paths import get_paths_for_model
+
+    return {"data": await get_paths_for_model(model_id)}
+
+
 @models_router.get("/v1/models")
 @models_router.get("/v1/models/", include_in_schema=False)
 @models_router.get("/models")

routstr/payment/usage.py

@@ -0,0 +1,131 @@
+"""Vendor-agnostic normalization of upstream usage objects.
+
+Upstream providers report token usage in vendor dialects that differ in field
+names and in whether cached tokens are included in the input count:
+
+* OpenAI / Azure / xAI / Groq / Moonshot / Qwen / Gemini-compat: cache reads in
+  ``prompt_tokens_details.cached_tokens``, included in ``prompt_tokens``.
+* OpenRouter: same as OpenAI plus cache *writes* in
+  ``prompt_tokens_details.cache_write_tokens``, also included in
+  ``prompt_tokens``.
+* litellm-normalized: same nesting, but names the write field
+  ``prompt_tokens_details.cache_creation_tokens`` (and additionally mirrors the
+  Anthropic top-level fields), with ``prompt_tokens`` as the grand total.
+* Anthropic native: ``cache_read_input_tokens`` / ``cache_creation_input_tokens``
+  top-level, additive to (not included in) ``input_tokens``.
+* DeepSeek: ``prompt_cache_hit_tokens`` / ``prompt_cache_miss_tokens``, with
+  ``prompt_tokens = hit + miss``.
+
+What decides whether cached tokens must be subtracted out of the input count is
+**which prompt field the vendor uses**, not which cache field appears:
+
+* ``prompt_tokens`` present -> cached + cache-write tokens are *included* in it
+  (OpenAI family, DeepSeek, OpenRouter, litellm); subtract both so
+  ``input_tokens`` holds only the regular-rate portion.
+* only ``input_tokens`` (Anthropic native) -> cached tokens are *additive*;
+  leave ``input_tokens`` untouched.
+
+``normalize_usage`` maps all of them onto one canonical ``NormalizedUsage``
+shape so billing code needs no vendor knowledge. The known dialects' field
+names do not collide, so a single union parser is safe; a vendor whose fields
+would genuinely conflict needs a dedicated branch here.
+"""
+
+from pydantic.v1 import BaseModel
+
+
+class NormalizedUsage(BaseModel):
+    """Canonical token usage: input_tokens never includes cached tokens."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+
+def parse_token_count(value: object) -> int:
+    """Parse a token count from various formats (int, float, str, bool)."""
+    if isinstance(value, bool):
+        return 0
+    if isinstance(value, int):
+        return max(0, value)
+    if isinstance(value, float):
+        return max(0, int(value))
+    if isinstance(value, str):
+        try:
+            return max(0, int(float(value)))
+        except ValueError:
+            return 0
+    return 0
+
+
+def _first_token_count(usage_data: dict, *fields: str) -> int:
+    """Return the first positive token count among the given fields."""
+    for field in fields:
+        value = parse_token_count(usage_data.get(field, 0))
+        if value > 0:
+            return value
+    return 0
+
+
+def _extract_cache_tokens(usage_data: dict) -> tuple[int, int]:
+    """Pull (cache_read, cache_write) across all known dialects.
+
+    Precedence (highest first), independent for reads and writes:
+
+    * Anthropic top-level: ``cache_read_input_tokens`` /
+      ``cache_creation_input_tokens``.
+    * Nested ``prompt_tokens_details``: ``cached_tokens`` for reads;
+      ``cache_creation_tokens`` (litellm) or ``cache_write_tokens``
+      (OpenRouter) for writes.
+    * DeepSeek: ``prompt_cache_hit_tokens`` for reads (no write concept).
+    """
+    cache_read = parse_token_count(usage_data.get("cache_read_input_tokens", 0))
+    cache_write = parse_token_count(usage_data.get("cache_creation_input_tokens", 0))
+
+    prompt_details = usage_data.get("prompt_tokens_details")
+    if isinstance(prompt_details, dict):
+        if not cache_read:
+            cache_read = parse_token_count(prompt_details.get("cached_tokens", 0))
+        if not cache_write:
+            cache_write = _first_token_count(
+                prompt_details, "cache_creation_tokens", "cache_write_tokens"
+            )
+
+    if not cache_read:
+        # DeepSeek: prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokens
+        cache_read = parse_token_count(usage_data.get("prompt_cache_hit_tokens", 0))
+
+    return cache_read, cache_write
+
+
+def normalize_usage(usage_data: object) -> NormalizedUsage | None:
+    """Map a vendor usage dict onto the canonical shape, or None if absent.
+
+    Cached reads and writes are subtracted from the input count exactly once,
+    only for dialects that report a ``prompt_tokens`` grand total that already
+    includes them (OpenAI family, DeepSeek, OpenRouter, litellm). Anthropic
+    native reports them additively under ``input_tokens`` and is left untouched.
+    """
+    if not isinstance(usage_data, dict):
+        return None
+
+    output_tokens = _first_token_count(
+        usage_data, "completion_tokens", "output_tokens"
+    )
+    cache_read, cache_write = _extract_cache_tokens(usage_data)
+
+    # ``prompt_tokens`` is the inclusive grand total; ``input_tokens`` (Anthropic
+    # native) excludes cached tokens. The field chosen decides whether to subtract.
+    if "prompt_tokens" in usage_data:
+        input_tokens = parse_token_count(usage_data.get("prompt_tokens", 0))
+        input_tokens = max(0, input_tokens - cache_read - cache_write)
+    else:
+        input_tokens = parse_token_count(usage_data.get("input_tokens", 0))
+
+    return NormalizedUsage(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cache_read_tokens=cache_read,
+        cache_write_tokens=cache_write,
+    )

routstr/proxy.py

@@ -24,6 +24,7 @@ from .payment.helpers import (
     calculate_discounted_max_cost,
     check_token_balance,
     create_error_response,
+    create_upstream_error_response,
     get_max_cost_for_model,
 )
 from .payment.models import Model
@@ -211,9 +212,7 @@ async def proxy(
                     e,
                 )
                 if i == len(all_upstreams) - 1:
-                    last_error_response = create_error_response(
-                        "upstream_error", str(e), 502, request=request
-                    )
+                    last_error_response = create_upstream_error_response(e, request)
                 continue
         return last_error_response or create_error_response(
             "upstream_error", "All upstreams failed", 502, request=request
@@ -283,11 +282,10 @@ async def proxy(
                     last_error = e
                 continue
 
+        if last_error is not None:
+            return create_upstream_error_response(last_error, request)
         return create_error_response(
-            "upstream_error",
-            str(last_error) if last_error else "All upstreams failed",
-            502,
-            request=request,
+            "upstream_error", "All upstreams failed", 502, request=request
         )
 
     elif auth := headers.get("authorization", None):
@@ -343,9 +341,7 @@ async def proxy(
             except UpstreamError as e:
                 logger.warning(f"Upstream {upstream.provider_type} failed (GET): {e}")
                 if i == len(upstreams) - 1:
-                    last_error_response = create_error_response(
-                        "upstream_error", str(e), 502, request=request
-                    )
+                    last_error_response = create_upstream_error_response(e, request)
                 continue
         return last_error_response or create_error_response(
             "upstream_error", "All upstreams failed", 502, request=request
@@ -525,9 +521,7 @@ async def proxy(
             # If this was the last provider
             if i == len(upstreams) - 1:
                 await revert_pay_for_request(key, session, max_cost_for_model)
-                return create_error_response(
-                    "upstream_error", str(e), 502, request=request
-                )
+                return create_upstream_error_response(e, request)
 
             # Otherwise loop continues to next provider
             continue

routstr/upstream/anthropic.py

@@ -24,7 +24,7 @@ class AnthropicUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "AnthropicUpstreamProvider":
         return cls(

routstr/upstream/auto_topup.py

@@ -97,6 +97,8 @@ async def _check_and_topup(row: UpstreamProviderRow) -> None:
 
     # Instantiate provider and check balance
     provider = RoutstrUpstreamProvider.from_db_row(row)
+    if provider is None:
+        return
     balance = await provider.get_balance()
 
     if balance is None:

routstr/upstream/azure.py

@@ -38,7 +38,7 @@ class AzureUpstreamProvider(BaseUpstreamProvider):
         self.api_version = api_version
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "AzureUpstreamProvider | None":
         if not provider_row.api_version:

routstr/upstream/base.py

@@ -2,16 +2,16 @@ from __future__ import annotations
 
 import asyncio
 import json
+import math
 import traceback
 import uuid
 from collections.abc import AsyncGenerator, AsyncIterator, Iterator
-from typing import Any, Mapping, cast
+from typing import Any, Mapping, Self, cast
 
 import httpx
 from fastapi import BackgroundTasks, HTTPException, Request
 from fastapi.responses import Response, StreamingResponse
 from pydantic.v1 import BaseModel
-from sqlmodel import select
 
 from ..auth import adjust_payment_for_tokens
 from ..core import get_logger
@@ -23,6 +23,7 @@ from ..core.db import (
     store_cashu_transaction,
 )
 from ..core.exceptions import UpstreamError
+from ..core.redaction import redact_org_ids
 from ..payment.cost_calculation import (
     CostData,
     CostDataError,
@@ -35,13 +36,19 @@ from ..payment.models import (
     Pricing,
     _calculate_usd_max_costs,
     _update_model_sats_pricing,
+    backfill_cache_pricing,
     list_models,
 )
 from ..payment.price import sats_usd_price
 from ..wallet import recieve_token, send_token
 from . import messages_dispatch
+from .cache_breakpoints import (
+    inject_anthropic_cache_breakpoints,
+    is_explicit_cache_model,
+)
 from .count_tokens import count_tokens_locally
 from .litellm_routing import detect_litellm_prefix
+from .rate_limit import UPSTREAM_RATE_LIMIT, classify_rate_limit
 
 logger = get_logger(__name__)
 
@@ -84,6 +91,11 @@ class BaseUpstreamProvider:
     base_url: str
     api_key: str
     provider_fee: float = 1.05
+    # Primary key of the ``upstream_providers`` row this instance was built
+    # from. Set by ``from_db_row`` so a live provider can re-find its own row by
+    # stable identity instead of its rotatable ``api_key``. ``None`` for
+    # instances not sourced from a row.
+    db_id: int | None = None
     _models_cache: list[Model] = []
     _models_by_id: dict[str, Model] = {}
 
@@ -98,6 +110,7 @@ class BaseUpstreamProvider:
         self.base_url = base_url
         self.api_key = api_key
         self.provider_fee = provider_fee
+        self.db_id = None
         self._models_cache = []
         self._models_by_id = {}
 
@@ -115,10 +128,13 @@ class BaseUpstreamProvider:
         return detect_litellm_prefix(self.base_url)
 
     @classmethod
-    def from_db_row(
-        cls, provider_row: "UpstreamProviderRow"
-    ) -> "BaseUpstreamProvider | None":
-        """Factory method to instantiate provider from database row.
+    def from_db_row(cls, provider_row: "UpstreamProviderRow") -> "Self | None":
+        """Instantiate a provider from a database row, carrying its identity.
+
+        Construction itself is delegated to the ``_build_from_row`` hook (which
+        subclasses override to match their constructor); this wrapper stamps the
+        row's primary key onto the instance as ``db_id`` so the provider can
+        later re-find its own row by identity rather than by its ``api_key``.
 
         Args:
             provider_row: Database row containing provider configuration
@@ -126,6 +142,19 @@ class BaseUpstreamProvider:
         Returns:
             Instantiated provider or None if instantiation fails
         """
+        provider = cls._build_from_row(provider_row)
+        if provider is not None:
+            provider.db_id = provider_row.id
+        return provider
+
+    @classmethod
+    def _build_from_row(cls, provider_row: "UpstreamProviderRow") -> "Self | None":
+        """Construct the provider instance from a row (no identity stamping).
+
+        Overridden by subclasses whose constructors differ from the base
+        ``(base_url, api_key, provider_fee)`` shape. Callers should use
+        ``from_db_row`` instead, which also attaches ``db_id``.
+        """
         return cls(
             base_url=provider_row.base_url,
             api_key=provider_row.api_key,
@@ -432,6 +461,19 @@ class BaseUpstreamProvider:
 
         return body
 
+    def _upstream_accepts_cache_control(self) -> bool:
+        """True when this upstream accepts explicit ``cache_control`` markers.
+
+        Only OpenRouter (documents Anthropic + Alibaba explicit caching) and the
+        native Anthropic API accept the markers. Stamping them toward an
+        automatic-cache or non-supporting upstream risks a 400, so injection is
+        confined to these. Base URL is also checked so an OpenRouter endpoint
+        configured through the generic provider is still recognised.
+        """
+        if self.provider_type in ("openrouter", "anthropic"):
+            return True
+        return "openrouter.ai" in (self.base_url or "")
+
     def prepare_request_body(
         self, body: bytes | None, model_obj: Model
     ) -> bytes | None:
@@ -501,6 +543,27 @@ class BaseUpstreamProvider:
                 data["stream_options"] = merged
                 changed = True
 
+        # Explicit-cache models (Anthropic Claude, Alibaba Qwen / deepseek-v3.2)
+        # cache nothing without ``cache_control`` markers in the body. Clients
+        # that don't recognise a routstr URL as one of these never send them, so
+        # caching silently never engages over routstr even though it works
+        # against OpenRouter directly. Stamp the standard breakpoints so caching
+        # works by default, deferring to any client-set markers. Gated to
+        # upstreams that accept the markers (OpenRouter / Anthropic) so they
+        # never leak to an automatic-cache provider that would reject them.
+        if (
+            "messages" in data
+            and isinstance(data.get("messages"), list)
+            and self._upstream_accepts_cache_control()
+            and is_explicit_cache_model(
+                model_obj.id,
+                model_obj.forwarded_model_id,
+                model_obj.canonical_slug,
+            )
+        ):
+            if inject_anthropic_cache_breakpoints(data):
+                changed = True
+
         if changed:
             return json.dumps(data).encode()
         return body
@@ -543,7 +606,7 @@ class BaseUpstreamProvider:
             preview = body_bytes.decode("utf-8", errors="ignore").strip()
             if preview:
                 message = preview[:500]
-        return message, upstream_code
+        return redact_org_ids(message), upstream_code
 
     async def on_upstream_error_redirect(
         self, status_code: int, error_message: str
@@ -586,10 +649,23 @@ class BaseUpstreamProvider:
             body_bytes = b""
             body_read_error = f"{type(exc).__name__}: {exc}"
 
+        # ``message`` is already redacted by ``_extract_upstream_error_message``;
+        # the raw body preview is redacted here before it reaches logs or the
+        # forwarded envelope so provider account identifiers never leak.
         message, upstream_code = self._extract_upstream_error_message(body_bytes)
-        body_preview = body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+        body_preview = redact_org_ids(
+            body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+        )
         is_json_body = _is_json_content_type(content_type)
 
+        # Classify upstream rate-limit failures into a stable, structured error.
+        rate_limit = classify_rate_limit(status_code, message, headers)
+        error_code: str | int = upstream_code or status_code
+        error_details: dict[str, object] | None = None
+        if rate_limit is not None:
+            error_code = UPSTREAM_RATE_LIMIT
+            error_details = rate_limit.as_details()
+
         logger.warning(
             "Upstream %s returned %s for model=%s path=%s: %s",
             self.provider_type,
@@ -603,6 +679,7 @@ class BaseUpstreamProvider:
                 "model": model_id or "unknown",
                 "upstream_status": status_code,
                 "upstream_code": upstream_code,
+                "error_code": error_code,
                 "upstream_content_type": content_type,
                 "upstream_request_id": upstream_request_id,
                 "message_preview": message[:200],
@@ -637,13 +714,41 @@ class BaseUpstreamProvider:
         ):
             headers.pop(header_name, None)
 
+        # Propagate a usable retry hint to the caller when the upstream supplied
+        # one but did not echo a ``Retry-After`` header. RFC 7231 delta-seconds
+        # is an integer, so round sub-second hints up to a usable ``1``.
+        if (
+            rate_limit is not None
+            and rate_limit.retry_after_seconds is not None
+            and "retry-after" not in {k.lower() for k in headers}
+        ):
+            headers["Retry-After"] = str(max(1, math.ceil(rate_limit.retry_after_seconds)))
+
         if is_json_body:
             if not content_type:
                 headers.pop("content-type", None)
                 headers.pop("Content-Type", None)
             media_type = content_type or None
+            # Re-serialise the body with organization IDs stripped. The narrow
+            # ``org-*`` regex preserves the surrounding JSON structure.
+            redacted_text = redact_org_ids(body_bytes.decode("utf-8", errors="ignore"))
+            redacted_body = redacted_text.encode()
+            # Surface the stable rate-limit classification on the forwarded
+            # body so callers can switch on ``error.code`` without parsing the
+            # provider-specific message. Fall back to the redacted bytes if the
+            # body is not a JSON object with an ``error`` mapping.
+            if rate_limit is not None:
+                try:
+                    parsed = json.loads(redacted_text)
+                    err = parsed.get("error") if isinstance(parsed, dict) else None
+                    if isinstance(err, dict):
+                        err["code"] = UPSTREAM_RATE_LIMIT
+                        err["details"] = error_details
+                        redacted_body = json.dumps(parsed).encode()
+                except (ValueError, AttributeError):
+                    pass
             return Response(
-                content=body_bytes,
+                content=redacted_body,
                 status_code=status_code,
                 headers=headers,
                 media_type=media_type,
@@ -654,15 +759,18 @@ class BaseUpstreamProvider:
         for header_name in ("content-type", "Content-Type"):
             headers.pop(header_name, None)
 
+        error_obj: dict[str, object] = {
+            "message": message or "Upstream returned a non-JSON error response",
+            "type": "upstream_error",
+            "code": error_code,
+            "upstream_status": status_code,
+            "upstream_content_type": content_type or None,
+            "upstream_body_preview": body_preview or None,
+        }
+        if error_details is not None:
+            error_obj["details"] = error_details
         envelope = {
-            "error": {
-                "message": message or "Upstream returned a non-JSON error response",
-                "type": "upstream_error",
-                "code": upstream_code or status_code,
-                "upstream_status": status_code,
-                "upstream_content_type": content_type or None,
-                "upstream_body_preview": body_preview or None,
-            },
+            "error": error_obj,
             "request_id": getattr(request.state, "request_id", None),
         }
 
@@ -727,7 +835,9 @@ class BaseUpstreamProvider:
                     except Exception:
                         pass
 
-            def _process_event(raw_event: bytes) -> Iterator[bytes]:
+            def _process_event(
+                raw_event: bytes, final: bool = False
+            ) -> Iterator[bytes]:
                 """Process one complete SSE event block (lines up to a blank line).
 
                 Handles arbitrary upstream framing across every supported
@@ -833,6 +943,12 @@ class BaseUpstreamProvider:
                         return
                     yield prefix + b"data: " + json.dumps(obj).encode() + b"\n\n"
                 else:
+                    if final:
+                        # Final flush of a truncated tail: the upstream closed
+                        # mid-event, so ``data`` is incomplete JSON. Emitting it
+                        # as a ``data:`` frame would hand the client invalid
+                        # JSON (the "unexpected token" parse error). Drop it.
+                        return
                     # Non-JSON data payload (partial fragment already reassembled
                     # by buffering, or a provider control string). Re-prefix each
                     # line so multi-line ``data`` stays valid SSE framing - a bare
@@ -851,7 +967,13 @@ class BaseUpstreamProvider:
                 # boundary-independent for every provider.
                 buffer = b""
                 async for chunk in response.aiter_bytes():
-                    buffer += chunk.replace(b"\r\n", b"\n")
+                    # Normalize the *joined* buffer, not each chunk in
+                    # isolation: a CRLF event delimiter can straddle two
+                    # ``aiter_bytes`` chunks (``...\r`` then ``\n...``). A
+                    # per-chunk replace would leave a stray ``\r`` and the
+                    # ``\n\n`` split would miss the delimiter, merging two
+                    # events into one frame and breaking SSE clients.
+                    buffer = (buffer + chunk).replace(b"\r\n", b"\n")
                     while b"\n\n" in buffer:
                         raw_event, buffer = buffer.split(b"\n\n", 1)
                         for out in _process_event(raw_event):
@@ -859,7 +981,7 @@ class BaseUpstreamProvider:
 
                 # Flush any trailing event that lacked a final blank line.
                 if buffer.strip():
-                    for out in _process_event(buffer):
+                    for out in _process_event(buffer, final=True):
                         yield out
 
                 async with create_session() as session:
@@ -1018,7 +1140,10 @@ class BaseUpstreamProvider:
                 response_json["id"] = f"chatcmpl-{uuid.uuid4()}"
 
             cost_data = await adjust_payment_for_tokens(
-                key, response_json, session, deducted_max_cost
+                key,
+                response_json,
+                session,
+                deducted_max_cost,
             )
 
             await session.refresh(key)
@@ -1162,7 +1287,9 @@ class BaseUpstreamProvider:
                     except Exception:
                         pass
 
-            def _process_event(raw_event: bytes) -> Iterator[bytes]:
+            def _process_event(
+                raw_event: bytes, final: bool = False
+            ) -> Iterator[bytes]:
                 """Process one complete SSE event block for the Responses API.
 
                 Buffers full events (delimited by a blank line) so parsing is
@@ -1232,6 +1359,11 @@ class BaseUpstreamProvider:
 
                     yield prefix + b"data: " + json.dumps(obj).encode() + b"\n\n"
                 else:
+                    if final:
+                        # Final flush of a truncated tail: upstream closed
+                        # mid-event, so ``data`` is incomplete JSON. Dropping it
+                        # avoids handing the client an invalid ``data:`` frame.
+                        return
                     # Re-prefix each line so multi-line ``data`` stays valid SSE
                     # framing for the client.
                     body = b"".join(
@@ -1244,14 +1376,20 @@ class BaseUpstreamProvider:
                 # delimiter so parsing is independent of byte boundaries.
                 buffer = b""
                 async for chunk in response.aiter_bytes():
-                    buffer += chunk.replace(b"\r\n", b"\n")
+                    # Normalize the *joined* buffer, not each chunk in
+                    # isolation: a CRLF event delimiter can straddle two
+                    # ``aiter_bytes`` chunks (``...\r`` then ``\n...``). A
+                    # per-chunk replace would leave a stray ``\r`` and the
+                    # ``\n\n`` split would miss the delimiter, merging two
+                    # events into one frame and breaking SSE clients.
+                    buffer = (buffer + chunk).replace(b"\r\n", b"\n")
                     while b"\n\n" in buffer:
                         raw_event, buffer = buffer.split(b"\n\n", 1)
                         for out in _process_event(raw_event):
                             yield out
 
                 if buffer.strip():
-                    for out in _process_event(buffer):
+                    for out in _process_event(buffer, final=True):
                         yield out
 
                 # Always emit a cost-bearing data chunk
@@ -1436,7 +1574,10 @@ class BaseUpstreamProvider:
                 response_json["id"] = f"chatcmpl-{uuid.uuid4()}"
 
             cost_data = await adjust_payment_for_tokens(
-                key, response_json, session, deducted_max_cost
+                key,
+                response_json,
+                session,
+                deducted_max_cost,
             )
 
             await session.refresh(key)
@@ -1631,7 +1772,10 @@ class BaseUpstreamProvider:
                             "usage": None,
                         }
                         cost_data = await adjust_payment_for_tokens(
-                            fresh_key, fallback, new_session, max_cost_for_model
+                            fresh_key,
+                            fallback,
+                            new_session,
+                            max_cost_for_model,
                         )
                         usage_finalized = True
                         return f"event: cost\ndata: {json.dumps({'cost': cost_data})}\n\n".encode()
@@ -1850,7 +1994,10 @@ class BaseUpstreamProvider:
                 response_json["usage"] = {"input_tokens": input_tokens}
 
             cost_data = await adjust_payment_for_tokens(
-                key, response_json, session, deducted_max_cost
+                key,
+                response_json,
+                session,
+                deducted_max_cost,
             )
 
             self.inject_cost_metadata(response_json, cost_data, key)
@@ -1952,7 +2099,10 @@ class BaseUpstreamProvider:
             response_json["model"] = requested_model
 
         cost_data = await adjust_payment_for_tokens(
-            key, response_json, session, max_cost_for_model
+            key,
+            response_json,
+            session,
+            max_cost_for_model,
         )
         self.inject_cost_metadata(response_json, cost_data, key)
 
@@ -2440,9 +2590,16 @@ class BaseUpstreamProvider:
                         body_bytes = await response.aread()
                     except Exception:
                         body_bytes = b""
-                    body_preview = body_bytes.decode(
-                        "utf-8", errors="ignore"
-                    ).strip()[:500]
+                    # Redact provider account identifiers before the body text
+                    # reaches logs or the raised error.
+                    body_preview = redact_org_ids(
+                        body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+                    )
+                    rate_limit = classify_rate_limit(
+                        response.status_code,
+                        body_preview,
+                        dict(response.headers),
+                    )
                     logger.error(
                         "Upstream %s returned %s for model=%s path=%s: %s",
                         self.provider_type,
@@ -2454,6 +2611,7 @@ class BaseUpstreamProvider:
                             "provider": self.provider_type,
                             "model": original_model_id or "unknown",
                             "status_code": response.status_code,
+                            "error_code": rate_limit.code if rate_limit else None,
                             "reason_phrase": response.reason_phrase,
                             "path": path,
                             "body_preview": body_preview,
@@ -2466,6 +2624,8 @@ class BaseUpstreamProvider:
                         f"for model {original_model_id or 'unknown'}: "
                         f"{body_preview[:200] or '<empty>'}",
                         status_code=response.status_code,
+                        code=rate_limit.code if rate_limit else None,
+                        details=rate_limit.as_details() if rate_limit else None,
                     )
 
                 try:
@@ -2762,9 +2922,16 @@ class BaseUpstreamProvider:
                         body_bytes = await response.aread()
                     except Exception:
                         body_bytes = b""
-                    body_preview = body_bytes.decode(
-                        "utf-8", errors="ignore"
-                    ).strip()[:500]
+                    # Redact provider account identifiers before the body text
+                    # reaches logs or the raised error.
+                    body_preview = redact_org_ids(
+                        body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+                    )
+                    rate_limit = classify_rate_limit(
+                        response.status_code,
+                        body_preview,
+                        dict(response.headers),
+                    )
                     logger.error(
                         "Upstream %s returned %s for model=%s path=%s: %s",
                         self.provider_type,
@@ -2776,6 +2943,7 @@ class BaseUpstreamProvider:
                             "provider": self.provider_type,
                             "model": original_model_id or "unknown",
                             "status_code": response.status_code,
+                            "error_code": rate_limit.code if rate_limit else None,
                             "path": path,
                             "body_preview": body_preview,
                         },
@@ -2787,6 +2955,8 @@ class BaseUpstreamProvider:
                         f"for model {original_model_id or 'unknown'}: "
                         f"{body_preview[:200] or '<empty>'}",
                         status_code=response.status_code,
+                        code=rate_limit.code if rate_limit else None,
+                        details=rate_limit.as_details() if rate_limit else None,
                     )
 
                 try:
@@ -3025,44 +3195,46 @@ class BaseUpstreamProvider:
             extra={"model": model, "has_usage": "usage" in response_data},
         )
 
-        async with create_session() as session:
-            match await calculate_cost(response_data, max_cost_for_model, session):
-                case MaxCostData() as cost:
-                    logger.debug(
-                        "Using max cost pricing",
-                        extra={"model": model, "max_cost_msats": cost.total_msats},
-                    )
-                    return cost
-                case CostData() as cost:
-                    logger.debug(
-                        "Using token-based pricing",
-                        extra={
-                            "model": model,
-                            "total_cost_msats": cost.total_msats,
-                            "input_msats": cost.input_msats,
-                            "output_msats": cost.output_msats,
-                        },
-                    )
-                    return cost
-                case CostDataError() as error:
-                    logger.error(
-                        "Cost calculation error",
-                        extra={
-                            "model": model,
-                            "error_message": error.message,
-                            "error_code": error.code,
-                        },
-                    )
-                    raise HTTPException(
-                        status_code=400,
-                        detail={
-                            "error": {
-                                "message": error.message,
-                                "type": "invalid_request_error",
-                                "code": error.code,
-                            }
-                        },
-                    )
+        match await calculate_cost(
+            response_data,
+            max_cost_for_model,
+        ):
+            case MaxCostData() as cost:
+                logger.debug(
+                    "Using max cost pricing",
+                    extra={"model": model, "max_cost_msats": cost.total_msats},
+                )
+                return cost
+            case CostData() as cost:
+                logger.debug(
+                    "Using token-based pricing",
+                    extra={
+                        "model": model,
+                        "total_cost_msats": cost.total_msats,
+                        "input_msats": cost.input_msats,
+                        "output_msats": cost.output_msats,
+                    },
+                )
+                return cost
+            case CostDataError() as error:
+                logger.error(
+                    "Cost calculation error",
+                    extra={
+                        "model": model,
+                        "error_message": error.message,
+                        "error_code": error.code,
+                    },
+                )
+                raise HTTPException(
+                    status_code=400,
+                    detail={
+                        "error": {
+                            "message": error.message,
+                            "type": "invalid_request_error",
+                            "code": error.code,
+                        }
+                    },
+                )
         return None
 
     async def send_refund(
@@ -4562,14 +4734,19 @@ class BaseUpstreamProvider:
     def _apply_provider_fee_to_model(self, model: Model) -> Model:
         """Apply provider fee to model's USD pricing and calculate max costs.
 
+        Cache rates missing from the upstream pricing feed are backfilled from
+        litellm's cost map first, so they carry the provider fee like every
+        other price component.
+
         Args:
             model: Model object to update
 
         Returns:
             Model with provider fee applied to pricing and max costs calculated
         """
+        base_pricing = backfill_cache_pricing(model.id, model.pricing)
         adjusted_pricing = Pricing.parse_obj(
-            {k: v * self.provider_fee for k, v in model.pricing.dict().items()}
+            {k: v * self.provider_fee for k, v in base_pricing.dict().items()}
         )
 
         temp_model = Model(
@@ -4722,14 +4899,11 @@ class BaseUpstreamProvider:
         """Refresh the in-memory models cache from upstream API."""
         try:
             async with create_session() as session:
-                stmt = select(UpstreamProviderRow).where(
-                    UpstreamProviderRow.base_url == self.base_url,
-                    UpstreamProviderRow.api_key == self.api_key,
+                provider = (
+                    await session.get(UpstreamProviderRow, self.db_id)
+                    if self.db_id is not None
+                    else None
                 )
-                result = await session.exec(stmt)
-
-                # .first() returns the object or None if not found
-                provider = result.first()
                 if not provider or not provider.id:
                     raise HTTPException(status_code=404, detail="Provider not found")
 

routstr/upstream/cache_breakpoints.py

@@ -0,0 +1,157 @@
+"""Inject explicit prompt-cache breakpoints into OpenAI-shaped requests.
+
+Some upstreams cache *explicitly*: the request must carry
+``cache_control: {"type": "ephemeral"}`` markers on the content blocks that
+should be cached. Two model families use this identical wire format:
+
+* **Anthropic Claude** — direct or via OpenRouter's ``anthropic/*`` models.
+* **Alibaba's explicit-cache models on OpenRouter** — ``qwen/qwen3-max``,
+  ``qwen/qwen-plus``, ``qwen/qwen3.6-plus``, ``qwen/qwen3-coder-plus``,
+  ``qwen/qwen3-coder-flash`` and ``deepseek/deepseek-v3.2`` — which OpenRouter
+  documents as using "the same syntax as Anthropic explicit caching".
+
+Every other provider routstr proxies (OpenAI, Azure, xAI/Grok, Groq, Moonshot,
+default DeepSeek, Gemini implicit, Fireworks) caches *automatically* and needs
+no markers — they are left untouched.
+
+A client that doesn't know it is talking to one of these models *through*
+routstr (e.g. an OpenAI-compatible coding agent pointed at a routstr URL) never
+emits the markers — it only adds them when it recognises the provider as
+OpenRouter. So caching silently never engages over routstr even though the same
+client caches fine talking to OpenRouter directly.
+
+This module restores caching by stamping the standard breakpoints onto the
+forwarded body — the system prompt, the last tool, and the last conversation
+message (the format allows up to four; we use three, matching the common
+agent convention) — but only when the client supplied none of its own, so
+explicit client control always wins. The caller is responsible for only
+applying this toward an upstream that accepts the markers (OpenRouter /
+Anthropic), so they never leak to a provider that would reject them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# The single ephemeral marker stamped onto each chosen breakpoint. A 5-minute
+# TTL (the default for ``ephemeral``) — deliberately not the 1h tier, which
+# carries a higher cache-write premium and should stay opt-in.
+EPHEMERAL_CACHE_CONTROL: dict[str, str] = {"type": "ephemeral"}
+
+# Alibaba's explicit-cache models on OpenRouter. Matched as substrings of the
+# model id (any spelling routstr carries). Snapshot endpoints that OpenRouter
+# documents as *not* supporting explicit caching (e.g. ``qwen3.5-plus-02-15``)
+# are different families and deliberately absent from this list.
+_ALIBABA_EXPLICIT_CACHE_SLUGS: tuple[str, ...] = (
+    "qwen3-max",
+    "qwen-plus",
+    "qwen3.6-plus",
+    "qwen3-coder-plus",
+    "qwen3-coder-flash",
+    "deepseek-v3.2",
+)
+
+
+def is_explicit_cache_model(model_id: str | None, *fallbacks: str | None) -> bool:
+    """True when the target model uses the explicit ``cache_control`` dialect.
+
+    Covers the Claude family (broadly — every Claude model supports it) and
+    Alibaba's documented explicit-cache models, across the id spellings routstr
+    carries: the OpenRouter id (``anthropic/claude-...``, ``qwen/qwen3-max``),
+    the bare upstream id, and any forwarded/canonical alias.
+    """
+    for candidate in (model_id, *fallbacks):
+        if not candidate:
+            continue
+        lowered = candidate.lower()
+        if "claude" in lowered or "anthropic/" in lowered:
+            return True
+        if any(slug in lowered for slug in _ALIBABA_EXPLICIT_CACHE_SLUGS):
+            return True
+    return False
+
+
+def _has_cache_control(obj: Any) -> bool:
+    """Recursively detect any client-supplied ``cache_control`` marker."""
+    if isinstance(obj, dict):
+        if "cache_control" in obj:
+            return True
+        return any(_has_cache_control(v) for v in obj.values())
+    if isinstance(obj, list):
+        return any(_has_cache_control(v) for v in obj)
+    return False
+
+
+def body_has_cache_control(data: dict) -> bool:
+    """True when the request already carries cache_control on messages/tools."""
+    return _has_cache_control(data.get("messages")) or _has_cache_control(
+        data.get("tools")
+    )
+
+
+def _stamp_text_content(message: dict) -> bool:
+    """Add the ephemeral marker to a message's last text block.
+
+    A string content is promoted to the array form Anthropic requires for
+    cache markers; an existing array gets the marker on its last text part.
+    Returns True when a marker was placed.
+    """
+    content = message.get("content")
+    if isinstance(content, str):
+        if not content:
+            return False
+        message["content"] = [
+            {
+                "type": "text",
+                "text": content,
+                "cache_control": dict(EPHEMERAL_CACHE_CONTROL),
+            }
+        ]
+        return True
+    if isinstance(content, list):
+        for part in reversed(content):
+            if isinstance(part, dict) and part.get("type") == "text":
+                part["cache_control"] = dict(EPHEMERAL_CACHE_CONTROL)
+                return True
+    return False
+
+
+def _stamp_system_prompt(messages: list) -> None:
+    for message in messages:
+        if isinstance(message, dict) and message.get("role") in (
+            "system",
+            "developer",
+        ):
+            _stamp_text_content(message)
+            return
+
+
+def _stamp_last_tool(tools: Any) -> None:
+    if isinstance(tools, list) and tools and isinstance(tools[-1], dict):
+        tools[-1]["cache_control"] = dict(EPHEMERAL_CACHE_CONTROL)
+
+
+def _stamp_last_conversation_message(messages: list) -> None:
+    for message in reversed(messages):
+        if isinstance(message, dict) and message.get("role") in ("user", "assistant"):
+            if _stamp_text_content(message):
+                return
+
+
+def inject_anthropic_cache_breakpoints(data: dict) -> bool:
+    """Stamp ephemeral cache breakpoints onto an OpenAI-shaped chat body.
+
+    Mutates ``data`` in place (the established convention in
+    ``prepare_request_body``) and returns True when anything changed. No-ops
+    when the body isn't chat-shaped or the client already set cache_control.
+    """
+    messages = data.get("messages")
+    if not isinstance(messages, list) or not messages:
+        return False
+    if body_has_cache_control(data):
+        return False
+
+    _stamp_system_prompt(messages)
+    _stamp_last_tool(data.get("tools"))
+    _stamp_last_conversation_message(messages)
+    return True

routstr/upstream/deepseek_v4_pricing_shim.py

@@ -0,0 +1,73 @@
+"""TEMPORARY: local DeepSeek V4 pricing shim.
+
+litellm's bundled cost map does not yet ship ``deepseek-v4-flash`` /
+``deepseek-v4-pro``. Without an entry, ``backfill_cache_pricing`` cannot find a
+``cache_read_input_token_cost`` and cache reads fall back to the full input
+rate — a large overcharge on cache hits (DeepSeek V4 hits are ~0.008-0.02x
+input, i.e. cached tokens cost 50-120x less than regular input).
+
+This module injects the missing entries into ``litellm.model_cost`` at startup
+so the existing backfill path resolves them. Rates mirror the canonical
+``deepseek`` provider entries now in litellm's ``model_prices`` map
+(``input_cost_per_token`` is the cache-*miss* rate;
+``cache_read_input_token_cost`` is the cache-*hit* rate), sourced from
+https://api-docs.deepseek.com/quick_start/pricing via
+https://github.com/BerriAI/litellm/pull/26380 (issue
+https://github.com/BerriAI/litellm/issues/30430).
+
+=== REMOVAL (once litellm ships these models) ===
+Delete this file and the single ``register_deepseek_v4_pricing()`` call in
+``routstr/core/main.py``. Nothing else depends on it. Entries are only added
+when absent, so a stale shim is harmless after upstream lands — but remove it.
+"""
+
+import litellm
+
+from ..core import get_logger
+
+logger = get_logger(__name__)
+
+# USD per token. Mirrors the canonical ``deepseek`` provider entries in
+# litellm's model_prices map (source: DeepSeek API pricing docs). Keep these in
+# sync with ``litellm.model_cost["deepseek/deepseek-v4-*"]``.
+_DEEPSEEK_V4_RATES: dict[str, dict[str, float]] = {
+    "deepseek-v4-flash": {
+        "input_cost_per_token": 1.4e-07,
+        "output_cost_per_token": 2.8e-07,
+        "cache_read_input_token_cost": 2.8e-09,
+        "cache_creation_input_token_cost": 0.0,
+        "input_cost_per_token_cache_hit": 2.8e-09,
+    },
+    "deepseek-v4-pro": {
+        "input_cost_per_token": 4.35e-07,
+        "output_cost_per_token": 8.7e-07,
+        "cache_read_input_token_cost": 3.625e-09,
+        "cache_creation_input_token_cost": 0.0,
+        "input_cost_per_token_cache_hit": 3.625e-09,
+    },
+}
+
+
+def register_deepseek_v4_pricing() -> None:
+    """Inject DeepSeek V4 pricing into ``litellm.model_cost`` if absent.
+
+    Idempotent and non-destructive: a key already present in the cost map
+    (e.g. once litellm ships it) is left untouched. Registers both the bare
+    (``deepseek-v4-flash``) and prefixed (``deepseek/deepseek-v4-flash``)
+    spellings since ``backfill_cache_pricing`` tries both.
+    """
+    added = []
+    for bare, rates in _DEEPSEEK_V4_RATES.items():
+        for key in (bare, f"deepseek/{bare}"):
+            if key in litellm.model_cost:
+                continue
+            entry: dict[str, object] = dict(rates)
+            entry["litellm_provider"] = "deepseek"
+            entry["mode"] = "chat"
+            litellm.model_cost[key] = entry
+            added.append(key)
+    if added:
+        logger.info(
+            "Registered temporary DeepSeek V4 pricing shim",
+            extra={"models": added},
+        )

routstr/upstream/fireworks.py

@@ -20,7 +20,7 @@ class FireworksUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "FireworksUpstreamProvider":
         return cls(

routstr/upstream/gemini.py

@@ -51,7 +51,7 @@ class GeminiUpstreamProvider(BaseUpstreamProvider):
         return self._client
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "GeminiUpstreamProvider":
         return cls(

routstr/upstream/generic.py

@@ -45,7 +45,7 @@ class GenericUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "GenericUpstreamProvider":
         return cls(

routstr/upstream/groq.py

@@ -20,7 +20,7 @@ class GroqUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(cls, provider_row: "UpstreamProviderRow") -> "GroqUpstreamProvider":
+    def _build_from_row(cls, provider_row: "UpstreamProviderRow") -> "GroqUpstreamProvider":
         return cls(
             api_key=provider_row.api_key,
             provider_fee=provider_row.provider_fee,

routstr/upstream/helpers.py

@@ -12,6 +12,7 @@ from sqlmodel import select
 
 from ..core import get_logger
 from ..core.db import AsyncSession, ModelRow, UpstreamProviderRow, create_session
+from ..core.provider_slugs import allocate_unique_provider_slug
 from ..payment.models import Model
 from .base import BaseUpstreamProvider
 
@@ -215,9 +216,6 @@ async def init_upstreams() -> list[BaseUpstreamProvider]:
 
             provider = _instantiate_provider(provider_row)
             if provider:
-                # Keep provider DB id on runtime instance so model mapping can
-                # bind DB overrides to the correct upstream.
-                setattr(provider, "db_id", provider_row.id)
                 await provider.refresh_models_cache()
                 logger.debug(
                     f"Initialized {provider_row.provider_type} provider",
@@ -250,6 +248,7 @@ async def _seed_providers_from_settings(
 
     providers_to_add: list[UpstreamProviderRow] = []
     seeded_provider_keys: set[tuple[str, str]] = set()
+    reserved_slugs: set[str] = set()
 
     provider_classes_by_type = {
         cls.provider_type: cls
@@ -279,8 +278,13 @@ async def _seed_providers_from_settings(
                     )
                 )
                 if not result.first():
+                    slug = await allocate_unique_provider_slug(
+                        session, provider_type, reserved_slugs
+                    )
+                    reserved_slugs.add(slug)
                     providers_to_add.append(
                         UpstreamProviderRow(
+                            slug=slug,
                             provider_type=provider_type,
                             base_url=base_url,
                             api_key=api_key,
@@ -299,8 +303,13 @@ async def _seed_providers_from_settings(
             )
         )
         if not result.first():
+            slug = await allocate_unique_provider_slug(
+                session, "ollama", reserved_slugs
+            )
+            reserved_slugs.add(slug)
             providers_to_add.append(
                 UpstreamProviderRow(
+                    slug=slug,
                     provider_type="ollama",
                     base_url=ollama_base_url,
                     api_key=ollama_api_key,
@@ -320,8 +329,13 @@ async def _seed_providers_from_settings(
                 )
             )
             if not result.first():
+                slug = await allocate_unique_provider_slug(
+                    session, "azure", reserved_slugs
+                )
+                reserved_slugs.add(slug)
                 providers_to_add.append(
                     UpstreamProviderRow(
+                        slug=slug,
                         provider_type="azure",
                         base_url=base_url,
                         api_key=api_key,
@@ -342,8 +356,13 @@ async def _seed_providers_from_settings(
                 )
             )
             if not result.first():
+                slug = await allocate_unique_provider_slug(
+                    session, "custom", reserved_slugs
+                )
+                reserved_slugs.add(slug)
                 providers_to_add.append(
                     UpstreamProviderRow(
+                        slug=slug,
                         provider_type="custom",
                         base_url=base_url,
                         api_key=api_key,
@@ -356,7 +375,7 @@ async def _seed_providers_from_settings(
         session.add(provider)
         logger.info(
             f"Seeding {provider.provider_type} provider",  # type: ignore[str-format]
-            extra={"base_url": provider.base_url},
+            extra={"base_url": provider.base_url, "slug": provider.slug},
         )
 
 
@@ -391,9 +410,7 @@ def _instantiate_provider(
             return provider
 
         if provider_row.provider_type == "custom":
-            return BaseUpstreamProvider(
-                provider_row.base_url, provider_row.api_key, provider_row.provider_fee
-            )
+            return BaseUpstreamProvider.from_db_row(provider_row)
 
         logger.error(
             f"Unknown provider type: {provider_row.provider_type}",

routstr/upstream/messages_dispatch.py

@@ -29,7 +29,9 @@ import litellm
 
 from ..core import get_logger
 from ..core.exceptions import UpstreamError
+from ..core.redaction import redact_org_ids
 from ..payment.models import Model
+from .rate_limit import classify_rate_limit
 
 logger = get_logger(__name__)
 
@@ -505,23 +507,33 @@ async def dispatch_anthropic_messages(
     try:
         result = await litellm.anthropic.messages.acreate(**kwargs)
     except Exception as exc:
-        exc_message = getattr(exc, "message", None) or str(exc) or repr(exc)
+        raw_message = getattr(exc, "message", None) or str(exc) or repr(exc)
+        # Redact provider account identifiers before the message reaches logs
+        # or the surfaced error.
+        exc_message = redact_org_ids(raw_message)
         exc_status = getattr(exc, "status_code", None)
         exc_response = getattr(exc, "response", None)
         response_text = None
         if exc_response is not None:
             try:
-                response_text = getattr(exc_response, "text", str(exc_response))
+                response_text = redact_org_ids(
+                    getattr(exc_response, "text", str(exc_response))
+                )
             except Exception:
                 response_text = "<unreadable>"
+        status_for_classify = exc_status if isinstance(exc_status, int) else 502
+        rate_limit = classify_rate_limit(
+            status_for_classify, exc_message, getattr(exc, "headers", None)
+        )
         logger.error(
             "litellm dispatch failed",
             extra={
                 "error": exc_message,
                 "error_type": type(exc).__name__,
                 "status_code": exc_status,
+                "error_code": rate_limit.code if rate_limit else None,
                 "llm_provider": getattr(exc, "llm_provider", None),
-                "body": getattr(exc, "body", None),
+                "body": redact_org_ids(str(getattr(exc, "body", "") or "")) or None,
                 "response_text": response_text,
                 "model": litellm_model,
                 "api_base": base_url,
@@ -529,7 +541,9 @@ async def dispatch_anthropic_messages(
         )
         raise UpstreamError(
             f"Upstream error via litellm: {exc_message}",
-            status_code=exc_status if isinstance(exc_status, int) else 502,
+            status_code=status_for_classify,
+            code=rate_limit.code if rate_limit else None,
+            details=rate_limit.as_details() if rate_limit else None,
         ) from exc
 
     if not client_stream and hasattr(result, "__aiter__"):

routstr/upstream/model_paths.py

@@ -0,0 +1,472 @@
+"""Model-path discovery service.
+
+Exposes every upstream provider path a Routstr model is reachable through.
+This is discovery/visibility data only — routing still selects the cheapest or
+best provider separately.
+
+A *path* is the provider string that may appear in Routstr chat completion
+responses (see ``BaseUpstreamProvider._apply_provider_field``):
+
+- Direct upstream -> ``<provider_type>`` e.g. ``anthropic``
+- Generic/custom OpenRouter-compatible upstream -> ``generic:<name>``
+- Native OpenRouter routing to a sub-provider -> ``openrouter:<name>``
+
+Native OpenRouter does not emit a useful bare ``openrouter`` path when no
+sub-provider is present; it reports ``unknown`` instead.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from typing import TYPE_CHECKING, Callable
+
+import httpx
+from sqlalchemy.orm import selectinload
+from sqlmodel import col, delete, select
+
+from ..core.db import ModelPathRow, ModelRow, UpstreamProviderRow, create_session
+from ..core.logging import get_logger
+from .base import BaseUpstreamProvider
+
+if TYPE_CHECKING:
+    from ..payment.models import Model
+
+logger = get_logger(__name__)
+
+# Bound the per-model OpenRouter /endpoints fan-out so a provider with hundreds
+# of models does not open hundreds of concurrent requests every refresh.
+_OPENROUTER_CONCURRENCY = 5
+_OPENROUTER_TIMEOUT_SECONDS = 10.0
+
+
+def is_openrouter_base_url(base_url: str | None) -> bool:
+    """True when ``base_url`` points at OpenRouter.
+
+    Deliberately separate from ``BaseUpstreamProvider._upstream_accepts_cache_control``:
+    that predicate also returns True for native Anthropic (correct for
+    cache-control, wrong for OpenRouter endpoint discovery). This one keys only
+    on the URL so a ``GenericUpstreamProvider`` aimed at OpenRouter is matched
+    while native Anthropic is not.
+    """
+    return "openrouter.ai" in (base_url or "")
+
+
+def exposed_model_id(model: object) -> str:
+    """Client-visible ``/v1/models`` id for a cached model."""
+    forwarded = getattr(model, "forwarded_model_id", None)
+    return forwarded or getattr(model, "id")
+
+
+def public_model_id(model_id: str) -> str:
+    """Model id exposed by model-path API responses.
+
+    Provider-prefixed ids such as ``z-ai/glm-5v-turbo`` are returned as
+    ``glm-5v-turbo`` so clients can search and display the same unqualified id
+    they pass to ``/v1/models/paths/model``.
+    """
+    return model_id.rsplit("/", 1)[-1]
+
+
+def openrouter_author_slug(model: object) -> str | None:
+    """Return a canonical ``author/slug`` for the OpenRouter endpoints API.
+
+    OpenRouter requires the canonical id, never ``forwarded_model_id``. Prefer
+    ``canonical_slug``, then a slash-containing ``id``; otherwise there is no
+    usable form and endpoint discovery is skipped for this model.
+    """
+    canonical = getattr(model, "canonical_slug", None)
+    if canonical and "/" in canonical:
+        return canonical
+    model_id = getattr(model, "id", None)
+    if model_id and "/" in model_id:
+        return model_id
+    return None
+
+
+async def _fetch_openrouter_endpoint_paths(
+    client: httpx.AsyncClient,
+    base_url: str,
+    api_key: str,
+    author_slug: str,
+    path_prefix: str,
+    semaphore: asyncio.Semaphore,
+) -> list[str]:
+    """Return ``<path_prefix>:<provider_name>`` paths for one model, or ``[]``.
+
+    Failures (network, rate limit, bad payload) are logged and swallowed so one
+    model never breaks the whole refresh.
+    """
+    url = f"{base_url.rstrip('/')}/models/{author_slug}/endpoints"
+    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+    async with semaphore:
+        try:
+            resp = await client.get(
+                url, headers=headers, timeout=_OPENROUTER_TIMEOUT_SECONDS
+            )
+        except Exception as e:  # noqa: BLE001 - isolate per-model failures
+            logger.warning(
+                "OpenRouter endpoint discovery request failed",
+                extra={"author_slug": author_slug, "error": str(e)},
+            )
+            return []
+
+    if resp.status_code == 429:
+        logger.warning(
+            "OpenRouter endpoint discovery rate-limited",
+            extra={"author_slug": author_slug},
+        )
+        return []
+    if resp.status_code != 200:
+        logger.warning(
+            "OpenRouter endpoint discovery non-200",
+            extra={"author_slug": author_slug, "status_code": resp.status_code},
+        )
+        return []
+
+    try:
+        endpoints = resp.json().get("data", {}).get("endpoints", [])
+    except Exception as e:  # noqa: BLE001
+        logger.warning(
+            "OpenRouter endpoint discovery bad payload",
+            extra={"author_slug": author_slug, "error": str(e)},
+        )
+        return []
+
+    paths: list[str] = []
+    for endpoint in endpoints:
+        provider_name = (endpoint or {}).get("provider_name")
+        if provider_name:
+            paths.append(f"{path_prefix}:{provider_name}")
+    # De-duplicate while preserving order.
+    return list(dict.fromkeys(paths))
+
+
+async def _load_model_visibility() -> tuple[
+    dict[str, tuple[ModelRow, float]], set[str], set[int]
+]:
+    """Load the same DB model visibility inputs used by routing.
+
+    ``refresh_model_maps`` builds routing from enabled providers, enabled DB
+    override rows, and disabled model ids. Model-path discovery uses the same
+    view so the discovery API does not advertise models routing would hide and
+    reports forwarded aliases from DB overrides consistently with ``/v1/models``.
+    """
+    async with create_session() as session:
+        query = select(UpstreamProviderRow).options(
+            selectinload(UpstreamProviderRow.models)  # type: ignore[arg-type]
+        )
+        provider_rows = (await session.exec(query)).all()
+
+    overrides_by_id: dict[str, tuple[ModelRow, float]] = {}
+    disabled_model_ids: set[str] = set()
+    enabled_provider_ids: set[int] = set()
+
+    for provider in provider_rows:
+        if not provider.enabled:
+            continue
+        if provider.id is not None:
+            enabled_provider_ids.add(provider.id)
+        for model in provider.models:
+            if model.enabled:
+                overrides_by_id[model.id] = (model, provider.provider_fee)
+            else:
+                disabled_model_ids.add(model.id)
+
+    return overrides_by_id, disabled_model_ids, enabled_provider_ids
+
+
+def _row_to_visible_model(
+    model_id: str,
+    row: ModelRow,
+    provider_fee: float,
+) -> Model | None:
+    """Convert an enabled DB override row into a routed model object."""
+    from ..payment.models import _row_to_model
+
+    try:
+        return _row_to_model(row, apply_provider_fee=True, provider_fee=provider_fee)
+    except Exception as exc:  # noqa: BLE001 - skip invalid override row
+        logger.warning(
+            "Skipping invalid model override while collecting model paths",
+            extra={
+                "model_id": model_id,
+                "upstream_provider_id": getattr(row, "upstream_provider_id", None),
+                "error": str(exc),
+                "error_type": type(exc).__name__,
+            },
+        )
+        return None
+
+
+def _apply_model_visibility(
+    upstream: BaseUpstreamProvider,
+    overrides_by_id: dict[str, tuple[ModelRow, float]] | None,
+    disabled_model_ids: set[str] | None,
+) -> list[object]:
+    """Return provider models after DB disabled/override state is applied."""
+    overrides_by_id = overrides_by_id or {}
+    disabled_model_ids = disabled_model_ids or set()
+    visible_models: list[object] = []
+    seen_model_ids: set[str] = set()
+
+    for model in upstream.get_cached_models():
+        model_id = getattr(model, "id", "")
+        if not getattr(model, "enabled", True) or model_id in disabled_model_ids:
+            continue
+
+        if model_id in overrides_by_id:
+            override_row, provider_fee = overrides_by_id[model_id]
+            visible_model = _row_to_visible_model(model_id, override_row, provider_fee)
+            if visible_model is None:
+                continue
+            model = visible_model
+
+        if not getattr(model, "enabled", True):
+            continue
+        visible_models.append(model)
+        seen_model_ids.add(model_id.lower())
+
+    upstream_provider_id = getattr(upstream, "db_id", None)
+    if isinstance(upstream_provider_id, int):
+        for model_id, (override_row, provider_fee) in overrides_by_id.items():
+            if model_id in disabled_model_ids:
+                continue
+            if (
+                getattr(override_row, "upstream_provider_id", None)
+                != upstream_provider_id
+            ):
+                continue
+            if model_id.lower() in seen_model_ids:
+                continue
+            override_model = _row_to_visible_model(model_id, override_row, provider_fee)
+            if override_model is None:
+                continue
+            if getattr(override_model, "enabled", True):
+                visible_models.append(override_model)
+                seen_model_ids.add(model_id.lower())
+
+    return visible_models
+
+
+async def _collect_provider_paths(
+    upstream: BaseUpstreamProvider,
+    overrides_by_id: dict[str, tuple[ModelRow, float]] | None = None,
+    disabled_model_ids: set[str] | None = None,
+) -> list[tuple[str, str]]:
+    """Collect ``(model_id, path)`` pairs for one provider instance.
+
+    Emits the direct ``<provider_type>`` path for normal upstreams. For
+    OpenRouter-compatible providers, emits one path per OpenRouter sub-provider
+    endpoint, prefixed the same way response stamping prefixes it.
+    """
+    provider_type = (upstream.provider_type or "").strip()
+    models = _apply_model_visibility(upstream, overrides_by_id, disabled_model_ids)
+    is_openrouter = is_openrouter_base_url(upstream.base_url)
+
+    pairs: list[tuple[str, str]] = []
+    if not is_openrouter:
+        for model in models:
+            if provider_type:
+                pairs.append((exposed_model_id(model), provider_type))
+        return pairs
+
+    if not provider_type:
+        return pairs
+
+    semaphore = asyncio.Semaphore(_OPENROUTER_CONCURRENCY)
+    async with httpx.AsyncClient() as client:
+
+        async def _for_model(model: object) -> list[tuple[str, str]]:
+            author_slug = openrouter_author_slug(model)
+            if not author_slug:
+                return []
+            paths = await _fetch_openrouter_endpoint_paths(
+                client,
+                upstream.base_url,
+                upstream.api_key,
+                author_slug,
+                provider_type,
+                semaphore,
+            )
+            model_id = exposed_model_id(model)
+            return [(model_id, path) for path in paths]
+
+        results = await asyncio.gather(
+            *(_for_model(m) for m in models), return_exceptions=True
+        )
+
+    for result in results:
+        if isinstance(result, BaseException):
+            logger.warning(
+                "OpenRouter endpoint discovery task errored",
+                extra={"provider": provider_type, "error": str(result)},
+            )
+            continue
+        pairs.extend(result)
+
+    return pairs
+
+
+async def _persist_provider_paths(
+    upstream_provider_id: int, pairs: list[tuple[str, str]]
+) -> None:
+    """Replace all rows for ``upstream_provider_id`` with ``pairs``.
+
+    Replacement (not upsert) so stale paths disappear when provider config or
+    upstream availability changes.
+    """
+    unique_pairs = list(dict.fromkeys(pairs))
+    async with create_session() as session:
+        await session.exec(  # type: ignore[call-overload]
+            delete(ModelPathRow).where(
+                col(ModelPathRow.upstream_provider_id) == upstream_provider_id
+            )
+        )
+        for model_id, path in unique_pairs:
+            session.add(
+                ModelPathRow(
+                    model_id=model_id,
+                    path=path,
+                    upstream_provider_id=upstream_provider_id,
+                )
+            )
+        await session.commit()
+
+
+async def _prune_inactive_provider_paths(active_provider_ids: set[int]) -> None:
+    """Delete paths for providers no longer present in the live upstream set."""
+    async with create_session() as session:
+        stmt = delete(ModelPathRow)
+        if active_provider_ids:
+            stmt = stmt.where(
+                col(ModelPathRow.upstream_provider_id).not_in(active_provider_ids)
+            )
+        await session.exec(stmt)  # type: ignore[call-overload]
+        await session.commit()
+
+
+async def refresh_model_paths(
+    upstreams: list[BaseUpstreamProvider],
+) -> None:
+    """Recompute and persist model paths for every enabled provider.
+
+    One provider's failure is logged and isolated; it must not break the rest.
+    """
+    (
+        overrides_by_id,
+        disabled_model_ids,
+        enabled_provider_ids,
+    ) = await _load_model_visibility()
+    active_provider_ids = {
+        upstream.db_id
+        for upstream in upstreams
+        if upstream.db_id is not None and upstream.db_id in enabled_provider_ids
+    }
+    await _prune_inactive_provider_paths(active_provider_ids)
+
+    for upstream in upstreams:
+        if upstream.db_id is None or upstream.db_id not in enabled_provider_ids:
+            continue
+        try:
+            pairs = await _collect_provider_paths(
+                upstream,
+                overrides_by_id=overrides_by_id,
+                disabled_model_ids=disabled_model_ids,
+            )
+            await _persist_provider_paths(upstream.db_id, pairs)
+        except Exception as e:  # noqa: BLE001 - isolate per-provider failures
+            logger.error(
+                "Failed to refresh model paths for provider",
+                extra={
+                    "provider": upstream.provider_type or upstream.base_url,
+                    "db_id": upstream.db_id,
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                },
+            )
+
+
+async def refresh_model_paths_periodically(
+    upstreams_provider: (
+        Callable[[], list[BaseUpstreamProvider]] | list[BaseUpstreamProvider]
+    ),
+) -> None:
+    """Background task mirroring ``refresh_upstreams_models_periodically``."""
+    from ..core.settings import settings
+
+    interval = getattr(settings, "model_paths_refresh_interval_seconds", 0)
+    if not interval or interval <= 0:
+        logger.info("Model paths refresh disabled (interval <= 0)")
+        return
+
+    def _resolve_upstreams() -> list[BaseUpstreamProvider]:
+        if callable(upstreams_provider):
+            return upstreams_provider()
+        return upstreams_provider
+
+    while True:
+        try:
+            await refresh_model_paths(_resolve_upstreams())
+        except asyncio.CancelledError:
+            break
+        except Exception as e:  # noqa: BLE001
+            logger.error(
+                "Error in model paths refresh loop",
+                extra={"error": str(e), "error_type": type(e).__name__},
+            )
+
+        try:
+            jitter = max(0.0, float(interval) * 0.1)
+            await asyncio.sleep(interval + random.uniform(0, jitter))
+        except asyncio.CancelledError:
+            break
+
+
+async def get_all_model_paths() -> list[dict]:
+    """All models with their paths, shaped for ``GET /v1/models/paths``."""
+    async with create_session() as session:
+        rows = (
+            await session.exec(select(ModelPathRow).order_by(ModelPathRow.model_id))
+        ).all()
+
+    grouped: dict[str, list[dict]] = {}
+    seen_paths: dict[str, set[str]] = {}
+    for row in rows:
+        model_id = public_model_id(row.model_id)
+        if row.path in seen_paths.setdefault(model_id, set()):
+            continue
+        seen_paths[model_id].add(row.path)
+        grouped.setdefault(model_id, []).append({"path": row.path})
+    return [{"id": model_id, "paths": paths} for model_id, paths in grouped.items()]
+
+
+async def get_paths_for_model(model_id: str) -> list[dict]:
+    """Paths for a single model, shaped for ``GET /v1/models/paths/model``.
+
+    Match by the public, unqualified model id, mirroring the model cache alias
+    behavior. Both ``deepseek-v4-pro`` and ``deepseek/deepseek-v4-pro`` resolve
+    every row whose stored id has the same base model id.
+    """
+    requested_id = public_model_id(model_id)
+    async with create_session() as session:
+        rows = (
+            await session.exec(
+                select(ModelPathRow).order_by(
+                    ModelPathRow.path,
+                    col(ModelPathRow.upstream_provider_id),
+                    ModelPathRow.model_id,
+                )
+            )
+        ).all()
+
+    seen: set[str] = set()
+    paths: list[dict] = []
+    for row in rows:
+        if public_model_id(row.model_id) != requested_id:
+            continue
+        if row.path in seen:
+            continue
+        seen.add(row.path)
+        paths.append({"path": row.path})
+    return paths

routstr/upstream/ollama.py

@@ -43,7 +43,7 @@ class OllamaUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "OllamaUpstreamProvider":
         return cls(

routstr/upstream/openai.py

@@ -20,7 +20,7 @@ class OpenAIUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "OpenAIUpstreamProvider":
         return cls(

routstr/upstream/openrouter.py

@@ -1,3 +1,4 @@
+import json
 from typing import TYPE_CHECKING
 
 import httpx
@@ -18,6 +19,38 @@ 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.
 
@@ -57,7 +90,7 @@ class OpenRouterUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "OpenRouterUpstreamProvider":
         return cls(

routstr/upstream/perplexity.py

@@ -23,7 +23,7 @@ class PerplexityUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "PerplexityUpstreamProvider":
         return cls(

routstr/upstream/ppqai.py

@@ -46,7 +46,7 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "PPQAIUpstreamProvider":
         return cls(
@@ -229,17 +229,14 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
                 f"Disabling PPQ.AI provider ({self.base_url}) due to insufficient balance",
                 extra={"error": error_message},
             )
-            from sqlmodel import select
-
             from ..core.db import UpstreamProviderRow, create_session
 
             async with create_session() as session:
-                statement = select(UpstreamProviderRow).where(
-                    UpstreamProviderRow.base_url == self.base_url,
-                    UpstreamProviderRow.api_key == self.api_key,
+                provider = (
+                    await session.get(UpstreamProviderRow, self.db_id)
+                    if self.db_id is not None
+                    else None
                 )
-                result = await session.exec(statement)
-                provider = result.first()
 
                 if provider:
                     provider.enabled = False

routstr/upstream/rate_limit.py

@@ -0,0 +1,136 @@
+"""Detection and parsing of upstream provider rate-limit errors.
+
+Upstream OpenAI-compatible providers signal rate limits via HTTP 429 and/or a
+human-readable message such as::
+
+    Rate limit reached for gpt-5.5-2026-04-23 (for limit gpt-5.5) in organization
+    org-XXXX on tokens per min (TPM): Limit 180000000, Used 180000000,
+    Requested 8929. Please try again in 2ms.
+
+This module classifies those failures into a stable :data:`UPSTREAM_RATE_LIMIT`
+code and extracts useful debugging fields. All retained text is redacted of
+organization IDs first.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+
+from ..core.redaction import redact_org_ids
+
+# Stable error code callers can switch on to distinguish upstream rate limits
+# from generic request failures. The literal value matches the identifier named
+# in issue #555 ("UPSTREAM_RATE_LIMIT") so the public API contract is exact.
+UPSTREAM_RATE_LIMIT = "UPSTREAM_RATE_LIMIT"
+
+# Message fragments that indicate a rate-limit even when the status code is not
+# 429 (some providers wrap it in a 400/500 envelope).
+_RATE_LIMIT_MARKERS = (
+    "rate limit reached",
+    "rate_limit_exceeded",
+    "rate limit exceeded",
+    "too many requests",
+)
+
+_MODEL_RE = re.compile(r"Rate limit reached for ([^\s(]+)", re.IGNORECASE)
+_LIMIT_NAME_RE = re.compile(r"\(for limit ([^)]+)\)", re.IGNORECASE)
+_METRIC_RE = re.compile(r"on ([a-z ]+\((?:TPM|RPM|TPD|RPD|IPM)\))", re.IGNORECASE)
+_LIMIT_RE = re.compile(r"Limit (\d+)", re.IGNORECASE)
+_USED_RE = re.compile(r"Used (\d+)", re.IGNORECASE)
+_REQUESTED_RE = re.compile(r"Requested (\d+)", re.IGNORECASE)
+_RETRY_RE = re.compile(r"try again in ([\d.]+)\s*(ms|s)", re.IGNORECASE)
+
+
+@dataclass
+class RateLimitInfo:
+    """Structured, redaction-safe view of an upstream rate-limit error."""
+
+    code: str
+    message: str
+    model: str | None = None
+    limit_name: str | None = None
+    metric: str | None = None
+    limit: int | None = None
+    used: int | None = None
+    requested: int | None = None
+    retry_after_seconds: float | None = None
+
+    def as_details(self) -> dict[str, object]:
+        """Return a JSON-serialisable dict for embedding in an error envelope."""
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
+def _looks_like_rate_limit(status_code: int, message: str) -> bool:
+    if status_code == 429:
+        return True
+    lowered = message.lower()
+    return any(marker in lowered for marker in _RATE_LIMIT_MARKERS)
+
+
+def _parse_retry_after_header(headers: dict[str, str] | None) -> float | None:
+    """Parse a ``Retry-After`` header (delta-seconds form) into seconds."""
+    if not headers:
+        return None
+    raw = headers.get("retry-after") or headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        return float(str(raw).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def _int_or_none(match: re.Match[str] | None) -> int | None:
+    if match is None:
+        return None
+    try:
+        return int(match.group(1))
+    except (TypeError, ValueError):
+        return None
+
+
+def classify_rate_limit(
+    status_code: int,
+    message: str,
+    headers: dict[str, str] | None = None,
+) -> RateLimitInfo | None:
+    """Classify an upstream error as a rate-limit and extract its fields.
+
+    Args:
+        status_code: HTTP status code from the upstream response.
+        message: Upstream error message (may contain sensitive identifiers).
+        headers: Optional upstream response headers, used for ``Retry-After``.
+
+    Returns:
+        A :class:`RateLimitInfo` when the error is a rate-limit, else ``None``.
+    """
+    message = message or ""
+    if not _looks_like_rate_limit(status_code, message):
+        return None
+
+    redacted = redact_org_ids(message)
+
+    model_match = _MODEL_RE.search(redacted)
+    metric_match = _METRIC_RE.search(redacted)
+
+    retry_after = _parse_retry_after_header(headers)
+    if retry_after is None:
+        retry_match = _RETRY_RE.search(redacted)
+        if retry_match is not None:
+            value = float(retry_match.group(1))
+            retry_after = value / 1000.0 if retry_match.group(2).lower() == "ms" else value
+
+    limit_name_match = _LIMIT_NAME_RE.search(redacted)
+
+    return RateLimitInfo(
+        code=UPSTREAM_RATE_LIMIT,
+        message=redacted,
+        model=model_match.group(1) if model_match else None,
+        limit_name=limit_name_match.group(1).strip() if limit_name_match else None,
+        metric=metric_match.group(1).strip() if metric_match else None,
+        limit=_int_or_none(_LIMIT_RE.search(redacted)),
+        used=_int_or_none(_USED_RE.search(redacted)),
+        requested=_int_or_none(_REQUESTED_RE.search(redacted)),
+        retry_after_seconds=retry_after,
+    )

routstr/upstream/routstr.py

@@ -55,7 +55,7 @@ class RoutstrUpstreamProvider(BaseUpstreamProvider):
         return path.lstrip("/")
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "RoutstrUpstreamProvider":
         import json

routstr/upstream/xai.py

@@ -21,7 +21,7 @@ class XAIUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(cls, provider_row: "UpstreamProviderRow") -> "XAIUpstreamProvider":
+    def _build_from_row(cls, provider_row: "UpstreamProviderRow") -> "XAIUpstreamProvider":
         return cls(
             api_key=provider_row.api_key,
             provider_fee=provider_row.provider_fee,

routstr/wallet.py

@@ -1,4 +1,5 @@
 import asyncio
+import re
 import time
 import typing
 from typing import TypedDict
@@ -129,6 +130,72 @@ async def send_token(amount: int, unit: str, mint_url: str | None = None) -> str
     return token
 
 
+# A foreign mint's fee_reserve is a non-binding estimate (NUT-05): the mint may
+# demand more when re-quoting or at melt execution. Instead of padding the
+# estimate with a safety buffer (which strands the margin at the foreign mint
+# on every swap), the swap retries with the amount recomputed from the fees the
+# mint actually demands, up to this many attempts.
+_MAX_SWAP_ATTEMPTS = 3
+
+_MINT_ERROR_CODE_RE = re.compile(r"\(Code: (\d+)\)")
+_MELT_SHORTFALL_RE = re.compile(r"Provided: (\d+), needed: (\d+)")
+
+# Insufficient-melt-inputs failures differ across mint implementations. 11005 is
+# the registered "Transaction is not balanced" code (cdk), specific enough to
+# trust on the code alone. 11000 is nutshell's generic, unregistered
+# TransactionError covering many unrelated failures, so it only counts as a fee
+# shortfall alongside the "not enough inputs" detail text. With no code suffix at
+# all, that same text is the only signal.
+
+
+def _net_minted_amount(amount_msat: int, token_unit: str, fees: int) -> int:
+    """
+    Convert the token value minus fees (given in the token unit) into an
+    amount in the primary mint's unit.
+    """
+    fee_msat = fees * 1000 if token_unit == "sat" else fees
+    remaining_msat = amount_msat - fee_msat
+    if settings.primary_mint_unit == "sat":
+        return int(remaining_msat // 1000)
+    return int(remaining_msat)
+
+
+def _melt_insufficient_shortfall(error: Exception) -> int | None:
+    """
+    Classify a melt failure: return the observed shortfall (in the token unit)
+    when the mint rejected the inputs as insufficient, or None when the failure
+    is unrelated to fees and must not be retried (e.g. a Lightning payment
+    failure, where a smaller invoice would not help).
+
+    Cashu errors carry no structured amounts (NUT-00 defines only detail/code,
+    flattened to "Mint Error: <detail> (Code: <code>)" by cashu-py), so the
+    classification uses the code and the shortfall must be inferred: the
+    "Provided: X, needed: Y" amounts are nutshell-specific free text and only
+    refine the shortfall when present; otherwise shrink one unit at a time.
+    """
+    message = str(error)
+    code_match = _MINT_ERROR_CODE_RE.search(message)
+    code = code_match.group(1) if code_match is not None else None
+    has_shortfall_text = "not enough inputs" in message.lower()
+
+    match code:
+        case "11005":  # registered TransactionUnbalanced: trust the code
+            pass
+        case "11000" if has_shortfall_text:  # generic nutshell error: needs the text
+            pass
+        case None if has_shortfall_text:  # no code suffix: text is the only signal
+            pass
+        case _:  # other codes, a bare 11000, or no signal: must not retry
+            return None
+
+    amounts = _MELT_SHORTFALL_RE.search(message)
+    if amounts is not None:
+        provided, needed = int(amounts.group(1)), int(amounts.group(2))
+        if needed > provided:
+            return needed - provided
+    return 1
+
+
 async def _calculate_swap_amount(
     amount_msat: int,
     token_unit: str,
@@ -167,26 +234,18 @@ async def _calculate_swap_amount(
 
         fee_reserve = dummy_melt_quote.fee_reserve
         input_fees = token_wallet.get_fees_for_proofs(proofs)
-        if token_unit == "sat":
-            fee_msat = (fee_reserve + input_fees) * 1000
-        else:
-            fee_msat = fee_reserve + input_fees
-
-        amount_msat_after_fee = amount_msat - fee_msat
-
-        if settings.primary_mint_unit == "sat":
-            minted_amount = int(amount_msat_after_fee // 1000)
-        else:
-            minted_amount = int(amount_msat_after_fee)
+        total_fees = fee_reserve + input_fees
+        minted_amount = _net_minted_amount(amount_msat, token_unit, total_fees)
 
         if minted_amount <= 0:
-            raise ValueError(f"Fees ({fee_reserve + input_fees} {token_unit}) exceed token amount")
+            raise ValueError(f"Fees ({total_fees} {token_unit}) exceed token amount")
 
         logger.info(
             "swap_to_primary_mint: fee estimation result",
             extra={
                 "token_amount_sat": amount_msat // 1000,
-                "estimated_fee_sat": fee_msat // 1000,
+                "estimated_fee": total_fees,
+                "estimated_fee_unit": token_unit,
                 "input_fees": input_fees,
                 "minted_amount": minted_amount,
                 "minted_unit": settings.primary_mint_unit,
@@ -251,67 +310,116 @@ async def swap_to_primary_mint(
         token_obj.proofs,
     )
 
-    mint_quote = await primary_wallet.request_mint(minted_amount)
-    logger.info(
-        "swap_to_primary_mint: mint quote received",
-        extra={"mint_quote_id": mint_quote.quote},
-    )
+    # The estimate above is non-binding: the mint may demand a higher fee on the
+    # real quote or reject the melt outright. Retry the quote/melt cycle with the
+    # amount recomputed from the fees the mint actually demands.
+    observed_extra_fee = 0
+    attempt = 0
+    while True:
+        attempt += 1
+        mint_quote = await primary_wallet.request_mint(minted_amount)
+        logger.info(
+            "swap_to_primary_mint: mint quote received",
+            extra={"mint_quote_id": mint_quote.quote, "attempt": attempt},
+        )
 
-    melt_quote = await token_wallet.melt_quote(mint_quote.request)
-    input_fees = token_wallet.get_fees_for_proofs(token_obj.proofs)
-    total_needed = melt_quote.amount + melt_quote.fee_reserve + input_fees
-    logger.info(
-        "swap_to_primary_mint: melt quote received",
-        extra={
-            "melt_quote_id": melt_quote.quote,
-            "melt_amount": melt_quote.amount,
-            "melt_fee_reserve": melt_quote.fee_reserve,
-            "input_fees": input_fees,
-            "total_needed": total_needed,
-            "token_amount": token_amount,
-        },
-    )
-
-    if total_needed > token_amount:
-        logger.warning(
-            "swap_to_primary_mint: insufficient token amount for melt fees",
+        melt_quote = await token_wallet.melt_quote(mint_quote.request)
+        input_fees = token_wallet.get_fees_for_proofs(token_obj.proofs)
+        total_needed = melt_quote.amount + melt_quote.fee_reserve + input_fees
+        logger.info(
+            "swap_to_primary_mint: melt quote received",
             extra={
-                "token_amount": token_amount,
+                "melt_quote_id": melt_quote.quote,
                 "melt_amount": melt_quote.amount,
                 "melt_fee_reserve": melt_quote.fee_reserve,
                 "input_fees": input_fees,
                 "total_needed": total_needed,
-                "shortfall": total_needed - token_amount,
+                "token_amount": token_amount,
+                "attempt": attempt,
             },
         )
-        raise ValueError(
-            f"Token amount ({token_amount} {token_obj.unit}) is insufficient to cover "
-            f"melt fees. Needed: {total_needed} {token_obj.unit} "
-            f"(amount: {melt_quote.amount} + fee: {melt_quote.fee_reserve} + input_fees: {input_fees})"
-        )
 
-    try:
-        _ = await token_wallet.melt(
-            proofs=token_obj.proofs,
-            invoice=mint_quote.request,
-            fee_reserve_sat=melt_quote.fee_reserve,
-            quote_id=melt_quote.quote,
-        )
-    except Exception as e:
-        logger.error(
-            "swap_to_primary_mint: melt failed",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "foreign_mint": token_obj.mint,
-                "token_amount": token_amount,
-                "melt_quote_id": melt_quote.quote,
-                "total_needed": total_needed,
-            },
-        )
-        raise ValueError(
-            f"Failed to melt token from foreign mint {token_obj.mint}: {e}"
-        ) from e
+        if total_needed > token_amount:
+            recomputed = _net_minted_amount(
+                amount_msat,
+                token_obj.unit,
+                melt_quote.fee_reserve + input_fees + observed_extra_fee,
+            )
+            if attempt >= _MAX_SWAP_ATTEMPTS or recomputed <= 0:
+                logger.warning(
+                    "swap_to_primary_mint: insufficient token amount for melt fees",
+                    extra={
+                        "token_amount": token_amount,
+                        "melt_amount": melt_quote.amount,
+                        "melt_fee_reserve": melt_quote.fee_reserve,
+                        "input_fees": input_fees,
+                        "total_needed": total_needed,
+                        "shortfall": total_needed - token_amount,
+                        "attempts": attempt,
+                    },
+                )
+                raise ValueError(
+                    f"Token amount ({token_amount} {token_obj.unit}) is insufficient to cover "
+                    f"melt fees. Needed: {total_needed} {token_obj.unit} "
+                    f"(amount: {melt_quote.amount} + fee: {melt_quote.fee_reserve} + input_fees: {input_fees})"
+                )
+            logger.warning(
+                "swap_to_primary_mint: melt quote exceeds token amount, retrying",
+                extra={
+                    "total_needed": total_needed,
+                    "token_amount": token_amount,
+                    "retry_minted_amount": recomputed,
+                    "attempt": attempt,
+                },
+            )
+            minted_amount = recomputed
+            continue
+
+        try:
+            _ = await token_wallet.melt(
+                proofs=token_obj.proofs,
+                invoice=mint_quote.request,
+                fee_reserve_sat=melt_quote.fee_reserve,
+                quote_id=melt_quote.quote,
+            )
+        except Exception as e:
+            shortfall = _melt_insufficient_shortfall(e)
+            recomputed = 0
+            if shortfall is not None:
+                observed_extra_fee += shortfall
+                recomputed = _net_minted_amount(
+                    amount_msat,
+                    token_obj.unit,
+                    melt_quote.fee_reserve + input_fees + observed_extra_fee,
+                )
+            if shortfall is None or attempt >= _MAX_SWAP_ATTEMPTS or recomputed <= 0:
+                logger.error(
+                    "swap_to_primary_mint: melt failed",
+                    extra={
+                        "error": str(e),
+                        "error_type": type(e).__name__,
+                        "foreign_mint": token_obj.mint,
+                        "token_amount": token_amount,
+                        "melt_quote_id": melt_quote.quote,
+                        "total_needed": total_needed,
+                        "attempts": attempt,
+                    },
+                )
+                raise ValueError(
+                    f"Failed to melt token from foreign mint {token_obj.mint}: {e}"
+                ) from e
+            logger.warning(
+                "swap_to_primary_mint: mint demanded more than quoted at melt, retrying",
+                extra={
+                    "shortfall": shortfall,
+                    "retry_minted_amount": recomputed,
+                    "attempt": attempt,
+                },
+            )
+            minted_amount = recomputed
+            continue
+
+        break
 
     logger.info(
         "swap_to_primary_mint: melt succeeded, minting on primary",
@@ -441,7 +549,11 @@ async def credit_balance(
             .where(col(db.ApiKey.hashed_key) == key.hashed_key)
             .values(balance=(db.ApiKey.balance) + amount)
         )
-        await session.exec(stmt)  # type: ignore[call-overload]
+        result = await session.exec(stmt)  # type: ignore[call-overload]
+        # If pruning removed this key after redemption, do not commit a no-op
+        # balance update and pretend the top-up succeeded.
+        if (getattr(result, "rowcount", 0) or 0) == 0:
+            raise ValueError("API key disappeared before credit could be recorded")
         await session.commit()
         await session.refresh(key)
 

tests/integration/test_admin_model_cache_pricing.py

@@ -0,0 +1,229 @@
+import json
+from datetime import datetime, timedelta, timezone
+from unittest.mock import patch
+
+import pytest
+from httpx import AsyncClient
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.admin import admin_sessions
+from routstr.core.db import ModelRow, UpstreamProviderRow
+from routstr.payment.cost_calculation import CostData, calculate_cost
+from routstr.proxy import get_model_instance, reinitialize_upstreams
+
+
+def _admin_headers() -> dict[str, str]:
+    token = "test-admin-cache-pricing-token"
+    admin_sessions[token] = int(
+        (datetime.now(timezone.utc) + timedelta(minutes=5)).timestamp()
+    )
+    return {"Authorization": f"Bearer {token}"}
+
+
+def _model_payload(
+    provider_id: int,
+    *,
+    cache_read: float,
+    cache_write: float,
+) -> dict[str, object]:
+    return {
+        "id": "custom-cache-model",
+        "name": "Custom Cache Model",
+        "description": "custom model with explicit cache pricing",
+        "created": 0,
+        "context_length": 128000,
+        "architecture": {
+            "modality": "text",
+            "input_modalities": ["text"],
+            "output_modalities": ["text"],
+            "tokenizer": "unknown",
+            "instruct_type": None,
+        },
+        "pricing": {
+            "prompt": 1.4e-7,
+            "completion": 2.8e-7,
+            "input_cache_read": cache_read,
+            "input_cache_write": cache_write,
+            "request": 0.0,
+            "image": 0.0,
+            "web_search": 0.0,
+            "internal_reasoning": 0.0,
+        },
+        "per_request_limits": None,
+        "top_provider": None,
+        "upstream_provider_id": provider_id,
+        "canonical_slug": None,
+        "alias_ids": [],
+        "enabled": True,
+        "forwarded_model_id": "custom-cache-model",
+    }
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_admin_provider_model_api_persists_cache_pricing_on_create_and_update(
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    provider = UpstreamProviderRow(
+        provider_type="generic",
+        base_url="https://custom-upstream.example/v1",
+        api_key="test-key",
+        provider_fee=1.0,
+    )
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+    assert provider.id is not None
+    await reinitialize_upstreams()
+
+    headers = _admin_headers()
+    create_payload = _model_payload(
+        provider.id,
+        cache_read=2.8e-9,
+        cache_write=3.5e-9,
+    )
+
+    with patch("routstr.payment.models.sats_usd_price", return_value=1e-6):
+        create_response = await integration_client.post(
+            f"/admin/api/upstream-providers/{provider.id}/models",
+            headers=headers,
+            json=create_payload,
+        )
+
+    assert create_response.status_code == 200
+    create_body = create_response.json()
+    assert create_body["pricing"]["input_cache_read"] == pytest.approx(2.8e-9)
+    assert create_body["pricing"]["input_cache_write"] == pytest.approx(3.5e-9)
+
+    row = await integration_session.get(ModelRow, ("custom-cache-model", provider.id))
+    assert row is not None
+    stored_pricing = json.loads(row.pricing)
+    assert stored_pricing["input_cache_read"] == pytest.approx(2.8e-9)
+    assert stored_pricing["input_cache_write"] == pytest.approx(3.5e-9)
+
+    update_payload = _model_payload(
+        provider.id,
+        cache_read=1.25e-9,
+        cache_write=4.5e-9,
+    )
+
+    with patch("routstr.payment.models.sats_usd_price", return_value=1e-6):
+        update_response = await integration_client.post(
+            f"/admin/api/upstream-providers/{provider.id}/models",
+            headers=headers,
+            json=update_payload,
+        )
+
+    assert update_response.status_code == 200
+    update_body = update_response.json()
+    assert update_body["pricing"]["input_cache_read"] == pytest.approx(1.25e-9)
+    assert update_body["pricing"]["input_cache_write"] == pytest.approx(4.5e-9)
+
+    await integration_session.refresh(row)
+    updated_pricing = json.loads(row.pricing)
+    assert updated_pricing["input_cache_read"] == pytest.approx(1.25e-9)
+    assert updated_pricing["input_cache_write"] == pytest.approx(4.5e-9)
+
+    model = get_model_instance("custom-cache-model")
+    assert model is not None
+    assert model.sats_pricing is not None
+    assert model.sats_pricing.input_cache_read == pytest.approx(0.00125)
+    assert model.sats_pricing.input_cache_write == pytest.approx(0.0045)
+
+    with patch("routstr.payment.cost_calculation.sats_usd_price", return_value=1e-6):
+        cost = await calculate_cost(
+            {
+                "model": "custom-cache-model",
+                "usage": {
+                    "prompt_tokens": 1000,
+                    "completion_tokens": 100,
+                    "prompt_tokens_details": {"cached_tokens": 800},
+                },
+            },
+            max_cost=1_000_000,
+        )
+
+    assert isinstance(cost, CostData)
+    assert cost.input_tokens == 200
+    assert cost.cache_read_input_tokens == 800
+    assert cost.cache_read_msats == 1000
+    assert cost.output_msats == 28000
+    assert cost.input_msats == 29000
+    assert cost.total_msats == 57000
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_upstream_response_cost_uses_model_cache_pricing(
+    integration_session: AsyncSession,
+    patched_db_engine: None,
+) -> None:
+    """A model's configured cache price must discount upstream cached-token usage."""
+    provider = UpstreamProviderRow(
+        provider_type="generic",
+        base_url="https://cache-priced-upstream.example/v1",
+        api_key="test-key",
+        provider_fee=1.0,
+    )
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+    assert provider.id is not None
+
+    row = ModelRow(
+        id="cache-priced-model",
+        name="Cache Priced Model",
+        description="model seeded with explicit cache pricing",
+        created=0,
+        context_length=128000,
+        architecture=json.dumps(
+            {
+                "modality": "text",
+                "input_modalities": ["text"],
+                "output_modalities": ["text"],
+                "tokenizer": "unknown",
+                "instruct_type": None,
+            }
+        ),
+        pricing=json.dumps(
+            {
+                "prompt": 1.4e-7,
+                "completion": 2.8e-7,
+                "input_cache_read": 1.25e-9,
+                "input_cache_write": 4.5e-9,
+            }
+        ),
+        upstream_provider_id=provider.id,
+        enabled=True,
+        forwarded_model_id="cache-priced-model",
+    )
+    integration_session.add(row)
+    await integration_session.commit()
+
+    with patch("routstr.payment.models.sats_usd_price", return_value=1e-6):
+        await reinitialize_upstreams()
+
+    with patch("routstr.payment.cost_calculation.sats_usd_price", return_value=1e-6):
+        cost = await calculate_cost(
+            {
+                "model": "cache-priced-model",
+                "usage": {
+                    "prompt_tokens": 1000,
+                    "completion_tokens": 100,
+                    "prompt_tokens_details": {"cached_tokens": 800},
+                },
+            },
+            max_cost=1_000_000,
+        )
+
+    assert isinstance(cost, CostData)
+    # prompt 1.4e-7 USD/token -> 0.14 sats/token -> 140 msats/token
+    # cache 1.25e-9 USD/token -> 0.00125 sats/token -> 1.25 msats/token
+    # completion 2.8e-7 USD/token -> 0.28 sats/token -> 280 msats/token
+    assert cost.input_tokens == 200
+    assert cost.cache_read_input_tokens == 800
+    assert cost.cache_read_msats == 1000
+    assert cost.input_msats == 29000
+    assert cost.output_msats == 28000
+    assert cost.total_msats == 57000

tests/integration/test_free_response_stale_reservation.py

@@ -0,0 +1,146 @@
+"""Regression tests for charging after stale reservation cleanup."""
+
+import time
+import uuid
+from unittest.mock import patch
+
+import pytest
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.db import ApiKey
+from routstr.payment.cost_calculation import CostData
+
+
+def _make_key(balance: int, reserved: int) -> ApiKey:
+    return ApiKey(
+        hashed_key=f"test_{uuid.uuid4().hex}",
+        balance=balance,
+        reserved_balance=reserved,
+        total_spent=0,
+        total_requests=1,
+    )
+
+
+def _cost_data(total_msats: int) -> CostData:
+    return CostData(
+        base_msats=0,
+        input_msats=total_msats // 2,
+        output_msats=total_msats - total_msats // 2,
+        total_msats=total_msats,
+        total_usd=0.0,
+        input_tokens=100,
+        output_tokens=100,
+    )
+
+
+@pytest.mark.asyncio
+async def test_overrun_charges_after_reservation_swept(
+    integration_session: AsyncSession,
+) -> None:
+    """Overrun finalize must charge even when the reservation was already released."""
+    from routstr.auth import adjust_payment_for_tokens
+
+    deducted_max_cost = 990  # discounted reservation
+    actual_token_cost = 1000  # actual cost overruns the reservation
+
+    # Sweeper has zeroed reserved_balance but left balance untouched.
+    key = _make_key(balance=1000, reserved=0)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    response_data = {
+        "model": "test-model",
+        "usage": {"prompt_tokens": 100, "completion_tokens": 100},
+    }
+
+    with patch(
+        "routstr.auth.calculate_cost",
+        return_value=_cost_data(actual_token_cost),
+    ):
+        await adjust_payment_for_tokens(
+            key, response_data, integration_session, deducted_max_cost
+        )
+
+    await integration_session.refresh(key)
+
+    assert key.total_spent == actual_token_cost, (
+        f"Request was not billed (total_spent={key.total_spent}) — free response bug"
+    )
+    assert key.balance == 1000 - actual_token_cost, (
+        f"Balance not charged: {key.balance}"
+    )
+    assert key.balance >= 0
+    assert key.reserved_balance == 0
+
+
+@pytest.mark.asyncio
+async def test_free_response_path_closed_end_to_end(
+    integration_session: AsyncSession,
+    patched_db_engine: None,
+) -> None:
+    """A reservation released by the real sweeper must not yield a free response."""
+    from routstr.auth import adjust_payment_for_tokens, pay_for_request
+    from routstr.core.db import create_session, release_stale_reservations
+
+    deducted_max_cost = 990
+    actual_token_cost = 1000
+    key_hash = f"test_sweep_{uuid.uuid4().hex}"
+
+    async with create_session() as session:
+        session.add(
+            ApiKey(
+                hashed_key=key_hash,
+                balance=1000,
+                reserved_balance=0,
+                total_spent=0,
+                total_requests=0,
+            )
+        )
+        await session.commit()
+
+    # Reserve the request, then backdate reserved_at so the sweeper treats it as
+    # stale (simulates a stream that outlived stale_reservation_timeout_seconds).
+    async with create_session() as session:
+        key = await session.get(ApiKey, key_hash)
+        assert key is not None
+        await pay_for_request(key, deducted_max_cost, session)
+        await session.refresh(key)
+        assert key.reserved_balance == deducted_max_cost
+        key.reserved_at = int(time.time()) - 10_000
+        session.add(key)
+        await session.commit()
+
+    # Sweeper releases the stale reservation without charging.
+    async with create_session() as session:
+        released = await release_stale_reservations(session, max_age_seconds=300)
+        assert released == 1
+
+    async with create_session() as session:
+        key = await session.get(ApiKey, key_hash)
+        assert key is not None
+        assert key.reserved_balance == 0, "Precondition: sweeper zeroed the reservation"
+
+        response_data = {
+            "model": "test-model",
+            "usage": {"prompt_tokens": 100, "completion_tokens": 100},
+        }
+        with patch(
+            "routstr.auth.calculate_cost",
+            return_value=_cost_data(actual_token_cost),
+        ):
+            await adjust_payment_for_tokens(
+                key, response_data, session, deducted_max_cost
+            )
+
+    async with create_session() as session:
+        final = await session.get(ApiKey, key_hash)
+        assert final is not None
+
+    assert final.total_spent == actual_token_cost, (
+        f"Free response: total_spent={final.total_spent}, expected {actual_token_cost}"
+    )
+    assert final.balance == 1000 - actual_token_cost, (
+        f"Balance not charged after sweep: {final.balance}"
+    )
+    assert final.balance >= 0
+    assert final.reserved_balance == 0

tests/integration/test_provider_self_lookup.py

@@ -0,0 +1,128 @@
+"""A live upstream provider resolves its OWN database row by stable identity
+(its primary key), not by its mutable/secret ``api_key``.
+
+Today ``from_db_row`` drops ``provider_row.id`` and the two self-referential
+paths — PPQ.AI's insufficient-balance self-disable and the base
+``refresh_models_cache`` — re-find their own row with
+``WHERE base_url == self.base_url AND api_key == self.api_key``. That uses a
+rotatable secret as a self-handle: the moment the row's key changes underneath a
+live object (a rotation racing an in-flight request), the object can no longer
+find itself. These tests pin the invariant that a provider looks itself up by
+identity, so the lookup survives a key change (and, later, key encryption).
+"""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from routstr.core.db import UpstreamProviderRow
+from routstr.upstream.ppqai import PPQAIUpstreamProvider
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_provider_object_carries_its_persistent_identity(
+    integration_session: object,
+    patched_db_engine: None,
+) -> None:
+    """``from_db_row`` gives the in-memory object its row's identity (``db_id``)."""
+    row = UpstreamProviderRow(
+        provider_type="ppqai",
+        base_url="https://api.ppq.ai",
+        api_key="sk-original",
+        enabled=True,
+        provider_fee=1.0,
+    )
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+    await integration_session.refresh(row)  # type: ignore[attr-defined]
+
+    provider = PPQAIUpstreamProvider.from_db_row(row)
+    assert provider is not None
+
+    assert provider.db_id == row.id
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_self_disable_targets_own_row_after_key_rotation(
+    integration_session: object,
+    patched_db_engine: None,
+) -> None:
+    """PPQ.AI self-disable must disable *its* row even after the key rotated.
+
+    RED (current): the object holds the pre-rotation key, so the
+    ``(base_url, api_key)`` lookup misses the row → the provider is never
+    disabled. GREEN: lookup by ``id`` finds it and disables it.
+    """
+    row = UpstreamProviderRow(
+        provider_type="ppqai",
+        base_url="https://api.ppq.ai",
+        api_key="sk-original",
+        enabled=True,
+        provider_fee=1.0,
+    )
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+    await integration_session.refresh(row)  # type: ignore[attr-defined]
+
+    provider = PPQAIUpstreamProvider.from_db_row(row)  # captures sk-original
+    assert provider is not None
+
+    # Key is rotated in the DB while `provider` is still live.
+    row.api_key = "sk-rotated"
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+
+    with patch("routstr.proxy.reinitialize_upstreams", new=AsyncMock()):
+        await provider.on_upstream_error_redirect(402, "Insufficient balance")
+
+    await integration_session.refresh(row)  # type: ignore[attr-defined]
+    assert row.enabled is False
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_refresh_models_cache_finds_own_row_after_key_rotation(
+    integration_session: object,
+    patched_db_engine: None,
+) -> None:
+    """``refresh_models_cache`` must resolve its own row after a key rotation.
+
+    ``refresh_models_cache`` swallows every exception (it only logs), so the
+    observable proof it found its row is that it reaches ``list_models`` — which
+    is called with the row's ``id`` only *after* the row is resolved. RED
+    (current): the stale-key ``(base_url, api_key)`` lookup returns nothing, the
+    method raises ``404`` internally and returns before ``list_models`` is ever
+    called. GREEN: lookup by ``id`` finds the row and ``list_models`` runs for
+    that ``id``.
+    """
+    row = UpstreamProviderRow(
+        provider_type="ppqai",
+        base_url="https://api.ppq.ai",
+        api_key="sk-original",
+        enabled=True,
+        provider_fee=1.0,
+    )
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+    await integration_session.refresh(row)  # type: ignore[attr-defined]
+    row_id = row.id
+
+    provider = PPQAIUpstreamProvider.from_db_row(row)  # captures sk-original
+    assert provider is not None
+
+    row.api_key = "sk-rotated"
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+
+    list_models_mock = AsyncMock(return_value=[])
+    with (
+        patch.object(provider, "fetch_models", new=AsyncMock(return_value=[])),
+        patch("routstr.upstream.base.list_models", new=list_models_mock),
+    ):
+        await provider.refresh_models_cache()
+
+    list_models_mock.assert_awaited_once()
+    assert list_models_mock.await_args is not None
+    assert list_models_mock.await_args.kwargs["upstream_id"] == row_id

tests/integration/test_prune_dead_api_keys.py

@@ -0,0 +1,283 @@
+"""
+Tests for prune_dead_api_keys — the janitor that removes provably-dead 0/0/0
+API keys (funded keys fully refunded/expired without ever being used, plus bare
+orphans), while protecting keys that are still meaningful.
+"""
+
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from typing import Any, cast
+
+import pytest
+from sqlalchemy.sql.dml import Update
+from sqlmodel import col, update
+
+from routstr.core.db import (
+    ApiKey,
+    CashuTransaction,
+    LightningInvoice,
+    create_session,
+    prune_dead_api_keys,
+)
+
+OLD = 100  # min_age_seconds used by the tests
+NOW = int(time.time())
+LONG_AGO = NOW - 10_000  # well past the grace period
+
+
+async def _exists(key_hash: str) -> bool:
+    async with create_session() as session:
+        return (await session.get(ApiKey, key_hash)) is not None
+
+
+def _dead_key(created_at: int | None) -> ApiKey:
+    return ApiKey(
+        hashed_key=f"dead_{uuid.uuid4().hex}",
+        balance=0,
+        reserved_balance=0,
+        total_spent=0,
+        total_requests=0,
+        created_at=created_at,
+    )
+
+
+@pytest.mark.asyncio
+async def test_prunes_old_refunded_zero_key(patched_db_engine: None) -> None:
+    """A funded-then-refunded key (0/0/0, NULL parent, old) is pruned."""
+    key = _dead_key(LONG_AGO)
+    async with create_session() as session:
+        session.add(key)
+        await session.commit()
+
+    async with create_session() as session:
+        pruned = await prune_dead_api_keys(session, OLD)
+
+    assert pruned == 1
+    assert not await _exists(key.hashed_key)
+
+
+@pytest.mark.asyncio
+async def test_grace_period_protects_fresh_key(patched_db_engine: None) -> None:
+    """A dead-looking but recently created key is protected by the grace period."""
+    key = _dead_key(int(time.time()))
+    async with create_session() as session:
+        session.add(key)
+        await session.commit()
+
+    async with create_session() as session:
+        pruned = await prune_dead_api_keys(session, OLD)
+
+    assert pruned == 0
+    assert await _exists(key.hashed_key)
+
+
+@pytest.mark.asyncio
+async def test_used_key_never_pruned(patched_db_engine: None) -> None:
+    """Keys with any spend/requests or live balance are never pruned."""
+    spent = _dead_key(LONG_AGO)
+    spent.total_spent = 1
+    requested = _dead_key(LONG_AGO)
+    requested.total_requests = 1
+    funded = _dead_key(LONG_AGO)
+    funded.balance = 1000
+    reserved = _dead_key(LONG_AGO)
+    reserved.reserved_balance = 500
+
+    async with create_session() as session:
+        for k in (spent, requested, funded, reserved):
+            session.add(k)
+        await session.commit()
+
+    async with create_session() as session:
+        pruned = await prune_dead_api_keys(session, OLD)
+
+    assert pruned == 0
+    for k in (spent, requested, funded, reserved):
+        assert await _exists(k.hashed_key)
+
+
+@pytest.mark.asyncio
+async def test_parent_and_child_keys_are_not_pruned(
+    patched_db_engine: None,
+) -> None:
+    """Pruning must not orphan child keys or delete valid children."""
+    parent = _dead_key(LONG_AGO)
+    child = ApiKey(
+        hashed_key=f"child_{uuid.uuid4().hex}",
+        balance=0,
+        reserved_balance=0,
+        total_spent=0,
+        total_requests=0,
+        created_at=LONG_AGO,
+        parent_key_hash=parent.hashed_key,
+    )
+    async with create_session() as session:
+        session.add(parent)
+        session.add(child)
+        await session.commit()
+
+    async with create_session() as session:
+        pruned = await prune_dead_api_keys(session, OLD)
+
+    assert pruned == 0
+    assert await _exists(parent.hashed_key)
+    assert await _exists(child.hashed_key)
+
+
+@pytest.mark.asyncio
+async def test_pending_invoice_protects_key(patched_db_engine: None) -> None:
+    """A key referenced by a pending topup invoice is never pruned mid-topup."""
+    key = _dead_key(LONG_AGO)
+    invoice = LightningInvoice(
+        id=f"inv_{uuid.uuid4().hex}",
+        bolt11=f"lnbc_{uuid.uuid4().hex}",
+        amount_sats=10,
+        description="topup",
+        payment_hash=uuid.uuid4().hex,
+        status="pending",
+        api_key_hash=key.hashed_key,
+        purpose="topup",
+        expires_at=NOW + 10_000,
+    )
+    async with create_session() as session:
+        session.add(key)
+        session.add(invoice)
+        await session.commit()
+
+    async with create_session() as session:
+        pruned = await prune_dead_api_keys(session, OLD)
+
+    assert pruned == 0
+    assert await _exists(key.hashed_key)
+
+
+@pytest.mark.asyncio
+async def test_paid_invoice_does_not_protect_key(patched_db_engine: None) -> None:
+    """A settled (non-pending) invoice does not keep a dead key alive."""
+    key = _dead_key(LONG_AGO)
+    invoice = LightningInvoice(
+        id=f"inv_{uuid.uuid4().hex}",
+        bolt11=f"lnbc_{uuid.uuid4().hex}",
+        amount_sats=10,
+        description="topup",
+        payment_hash=uuid.uuid4().hex,
+        status="paid",
+        api_key_hash=key.hashed_key,
+        purpose="topup",
+        expires_at=NOW - 1,
+    )
+    async with create_session() as session:
+        session.add(key)
+        session.add(invoice)
+        await session.commit()
+
+    async with create_session() as session:
+        pruned = await prune_dead_api_keys(session, OLD)
+
+    assert pruned == 1
+    assert not await _exists(key.hashed_key)
+
+
+@pytest.mark.asyncio
+async def test_key_that_becomes_meaningful_during_prune_survives(
+    patched_db_engine: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Revalidate before unlink/delete so a late top-up cannot be pruned."""
+    key = _dead_key(LONG_AGO)
+    txn = CashuTransaction(
+        id=uuid.uuid4().hex,
+        token="cashuABC",
+        amount=21,
+        unit="sat",
+        type="in",
+        source="apikey",
+        api_key_hashed_key=key.hashed_key,
+    )
+    async with create_session() as session:
+        session.add(key)
+        session.add(txn)
+        await session.commit()
+
+    async with create_session() as session:
+        original_exec = cast(Callable[..., Awaitable[Any]], session.exec)
+        topped_up = False
+
+        async def exec_with_late_topup(
+            statement: Any, *args: Any, **kwargs: Any
+        ) -> Any:
+            nonlocal topped_up
+            if (
+                not topped_up
+                and isinstance(statement, Update)
+                and getattr(statement.table, "name", None) == "cashu_transactions"
+            ):
+                topped_up = True
+                async with create_session() as topup_session:
+                    await topup_session.exec(  # type: ignore[call-overload]
+                        update(ApiKey)
+                        .where(col(ApiKey.hashed_key) == key.hashed_key)
+                        .values(balance=42)
+                    )
+                    await topup_session.commit()
+            return await original_exec(statement, *args, **kwargs)
+
+        monkeypatch.setattr(session, "exec", exec_with_late_topup)
+        pruned = await prune_dead_api_keys(session, OLD)
+
+    assert pruned == 0
+    assert await _exists(key.hashed_key)
+    async with create_session() as session:
+        surviving = await session.get(CashuTransaction, txn.id)
+        assert surviving is not None
+        assert surviving.api_key_hashed_key == key.hashed_key
+
+
+@pytest.mark.asyncio
+async def test_transaction_audit_trail_preserved(patched_db_engine: None) -> None:
+    """Pruning a refunded key keeps its cashu_transactions, unlinked from the key."""
+    key = _dead_key(LONG_AGO)
+    txn = CashuTransaction(
+        id=uuid.uuid4().hex,
+        token="cashuABC",
+        amount=21,
+        unit="sat",
+        type="in",
+        source="apikey",
+        api_key_hashed_key=key.hashed_key,
+    )
+    async with create_session() as session:
+        session.add(key)
+        session.add(txn)
+        await session.commit()
+
+    async with create_session() as session:
+        pruned = await prune_dead_api_keys(session, OLD)
+
+    assert pruned == 1
+    assert not await _exists(key.hashed_key)
+
+    async with create_session() as session:
+        surviving = await session.get(CashuTransaction, txn.id)
+        assert surviving is not None, "Financial audit row must survive key deletion"
+        assert surviving.api_key_hashed_key is None, "Link must be nulled, not dangling"
+        assert surviving.amount == 21
+
+
+@pytest.mark.asyncio
+async def test_periodic_prune_disabled_returns_immediately(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Non-positive intervals disable the janitor."""
+    from unittest.mock import AsyncMock
+
+    from routstr import auth
+    from routstr.core.settings import settings
+
+    monkeypatch.setattr(settings, "dead_key_prune_interval_seconds", 0)
+    sleep_mock = AsyncMock()
+    monkeypatch.setattr(auth.asyncio, "sleep", sleep_mock)
+
+    await auth.periodic_dead_key_prune()
+
+    sleep_mock.assert_not_called()

tests/integration/test_swap_fee_retry.py

@@ -0,0 +1,194 @@
+"""
+Integration tests for reactive swap fee retries via the wallet topup endpoint.
+
+Foreign-mint tokens are swapped to the primary mint using the foreign mint's
+melt quote, whose fee_reserve is a non-binding estimate (NUT-05): the mint may
+demand more when re-quoting or at melt execution. These tests cover the
+endpoint behaviour in those cases:
+
+1. The mint demands one sat more at melt time than every quote reported
+   (the mint.cubabitcoin.org incident): the swap retries with a smaller
+   invoice and the topup succeeds, crediting the recomputed amount.
+2. The real melt quote reports a higher fee_reserve than the estimate: the
+   swap re-quotes from the observed fee and the topup succeeds.
+3. The mint escalates its fee demands on every attempt: the retry budget is
+   exhausted and the endpoint returns 400 with a clear error (never 500),
+   without ever executing a melt.
+"""
+
+from collections.abc import Callable
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+from httpx import AsyncClient, Response
+
+from routstr.core.settings import settings
+
+# Captured at collection time, before the integration_app fixture replaces it
+# with the testmint stub that bypasses swapping (see conftest.py).
+from routstr.wallet import recieve_token as _real_recieve_token
+
+PRIMARY_MINT = "http://primary:3338"
+
+
+def _make_swap_mocks(
+    token_amount: int,
+    fee_reserves: list[int],
+    input_fees: int = 0,
+    mint_url: str = "http://foreign-mint:3338",
+) -> tuple[Mock, Mock, Mock]:
+    """Return (token, token_wallet, primary_wallet) mocks that act like a mint.
+
+    Mint quotes pass the requested amount through their ``request`` field and
+    melt quotes echo that amount back, so the mocks stay consistent for
+    whatever amounts the implementation requests. ``fee_reserves`` supplies the
+    fee_reserve of each successive melt quote (the first serves the estimation
+    pass); requesting more quotes than provided fails the test.
+    """
+    mock_token = Mock()
+    mock_token.mint = mint_url
+    mock_token.unit = "sat"
+    mock_token.amount = token_amount
+    mock_token.keysets = ["keyset1"]
+    mock_token.proofs = [Mock(amount=token_amount)]
+
+    mock_token_wallet = Mock()
+    mock_token_wallet.load_mint = AsyncMock()
+    mock_token_wallet.load_proofs = AsyncMock()
+    mock_token_wallet.get_fees_for_proofs = Mock(return_value=input_fees)
+
+    mock_primary_wallet = Mock()
+    mock_primary_wallet.load_mint = AsyncMock()
+    mock_primary_wallet.load_proofs = AsyncMock()
+    mock_primary_wallet.available_balance = Mock(amount=0)
+    mock_primary_wallet.mint = AsyncMock(return_value=Mock())
+
+    fees = iter(fee_reserves)
+
+    def _next_fee() -> int:
+        try:
+            return next(fees)
+        except StopIteration:
+            raise AssertionError(
+                "more melt quotes requested than fee_reserves provided"
+            ) from None
+
+    mock_primary_wallet.request_mint = AsyncMock(
+        side_effect=lambda amount: Mock(quote=f"mint_quote_{amount}", request=amount)
+    )
+    mock_token_wallet.melt_quote = AsyncMock(
+        side_effect=lambda invoice: Mock(
+            quote=f"melt_quote_{invoice}", amount=invoice, fee_reserve=_next_fee()
+        )
+    )
+    mock_token_wallet.melt = AsyncMock(return_value=Mock())
+
+    return mock_token, mock_token_wallet, mock_primary_wallet
+
+
+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:
+        return primary_wallet if mint_url == PRIMARY_MINT else token_wallet
+
+    return fake_get_wallet
+
+
+async def _post_topup(
+    client: AsyncClient,
+    mock_token: Mock,
+    token_wallet: Mock,
+    primary_wallet: Mock,
+) -> Response:
+    """POST /v1/wallet/topup with the swap layer mocked at the mint boundary.
+
+    The conftest's testmint stub for recieve_token is swapped back for the
+    real implementation so the request exercises the actual swap path.
+    """
+    with patch("routstr.wallet.recieve_token", _real_recieve_token):
+        with patch(
+            "routstr.wallet.deserialize_token_from_string", return_value=mock_token
+        ):
+            with patch(
+                "routstr.wallet.get_wallet",
+                side_effect=_wallet_router(primary_wallet, token_wallet),
+            ):
+                with patch.object(settings, "primary_mint", PRIMARY_MINT):
+                    with patch.object(settings, "primary_mint_unit", "sat"):
+                        with patch.object(settings, "cashu_mints", [PRIMARY_MINT]):
+                            return await client.post(
+                                "/v1/wallet/topup",
+                                params={"cashu_token": "cashuAtest_foreign_token"},
+                            )
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_topup_retries_when_melt_demands_more_than_quoted(
+    authenticated_client: AsyncClient,
+) -> None:
+    """A 179-sat token where every quote reports fee_reserve=1 but the mint
+    rejects the first melt demanding 180. The retry shrinks the invoice to 177
+    and the topup credits 177 sats (177_000 msats)."""
+    mock_token, token_wallet, primary_wallet = _make_swap_mocks(
+        179, fee_reserves=[1, 1, 1], mint_url="http://mint.cubabitcoin.org"
+    )
+    token_wallet.melt.side_effect = [
+        Exception(
+            "Mint Error: not enough inputs provided for melt. "
+            "Provided: 179, needed: 180 (Code: 11000)"
+        ),
+        Mock(),
+    ]
+
+    response = await _post_topup(
+        authenticated_client, mock_token, token_wallet, primary_wallet
+    )
+
+    assert response.status_code == 200
+    assert response.json()["msats"] == 177_000
+    assert token_wallet.melt.call_count == 2
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_topup_retries_when_quote_fee_exceeds_estimate(
+    authenticated_client: AsyncClient,
+) -> None:
+    """A 1000-sat token estimated at fee 20, but the real quote demands 23.
+    The retry recomputes 1000 - 23 = 977, which fits, and the topup credits
+    977 sats (977_000 msats) with a single melt."""
+    mock_token, token_wallet, primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[20, 23, 23]
+    )
+
+    response = await _post_topup(
+        authenticated_client, mock_token, token_wallet, primary_wallet
+    )
+
+    assert response.status_code == 200
+    assert response.json()["msats"] == 977_000
+    assert token_wallet.melt.call_count == 1
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_topup_returns_400_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."""
+    mock_token, token_wallet, primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[1, 10, 25, 50]
+    )
+
+    response = await _post_topup(
+        authenticated_client, mock_token, token_wallet, primary_wallet
+    )
+
+    assert response.status_code == 400
+    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/unit/test_cache_breakpoints.py

@@ -0,0 +1,189 @@
+"""Tests for Anthropic cache-breakpoint injection on forwarded requests.
+
+Anthropic prompt caching is explicit; a client that doesn't recognise a routstr
+URL as Anthropic-backed never sends ``cache_control`` markers, so caching never
+engages over routstr. ``prepare_request_body`` must stamp the standard
+breakpoints for Anthropic-family models while always deferring to client-set
+markers and never touching automatic-cache providers.
+"""
+
+import json
+import os
+
+import pytest
+
+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.cache_breakpoints import (
+    body_has_cache_control,
+    inject_anthropic_cache_breakpoints,
+    is_explicit_cache_model,
+)
+
+
+def _chat_body() -> dict:
+    return {
+        "model": "anthropic/claude-sonnet-4.5",
+        "stream": True,
+        "messages": [
+            {"role": "system", "content": "You are concise."},
+            {"role": "user", "content": "Hello"},
+        ],
+        "tools": [
+            {"type": "function", "function": {"name": "a"}},
+            {"type": "function", "function": {"name": "b"}},
+        ],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Model detection
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "model_id,expected",
+    [
+        ("anthropic/claude-sonnet-4.5", True),
+        ("claude-haiku-4-5-20251001", True),
+        # Alibaba explicit-cache models share Anthropic's wire format
+        ("qwen/qwen3-max", True),
+        ("qwen/qwen3-coder-plus", True),
+        ("deepseek/deepseek-v3.2", True),
+        # Automatic-cache providers need no markers
+        ("openai/gpt-4o", False),
+        ("google/gemini-2.5-flash", False),
+        ("deepseek/deepseek-chat", False),
+        ("qwen/qwen3.5-plus-02-15", False),  # snapshot, no explicit caching
+        (None, False),
+    ],
+)
+def test_is_explicit_cache_model(model_id: str | None, expected: bool) -> None:
+    assert is_explicit_cache_model(model_id) is expected
+
+
+def test_is_explicit_cache_model_uses_fallbacks() -> None:
+    # routstr id is opaque but a forwarded/canonical alias reveals the family.
+    assert is_explicit_cache_model("model-xyz", None, "anthropic/claude-opus-4.1")
+
+
+# ---------------------------------------------------------------------------
+# Breakpoint placement
+# ---------------------------------------------------------------------------
+
+
+def test_injects_three_breakpoints() -> None:
+    data = _chat_body()
+    assert inject_anthropic_cache_breakpoints(data) is True
+
+    # system prompt promoted to array form with a marker
+    system = data["messages"][0]["content"]
+    assert system == [
+        {
+            "type": "text",
+            "text": "You are concise.",
+            "cache_control": {"type": "ephemeral"},
+        }
+    ]
+    # last tool marked
+    assert data["tools"][-1]["cache_control"] == {"type": "ephemeral"}
+    assert "cache_control" not in data["tools"][0]
+    # last user message marked
+    user = data["messages"][1]["content"]
+    assert user[-1]["cache_control"] == {"type": "ephemeral"}
+
+
+def test_defers_to_client_supplied_cache_control() -> None:
+    data = _chat_body()
+    data["messages"][1]["content"] = [
+        {"type": "text", "text": "Hello", "cache_control": {"type": "ephemeral"}}
+    ]
+    assert body_has_cache_control(data) is True
+    # No additional stamping when the client already controls caching.
+    assert inject_anthropic_cache_breakpoints(data) is False
+    assert "cache_control" not in data["tools"][-1]
+
+
+def test_marks_last_text_part_of_array_content() -> None:
+    data = _chat_body()
+    data["messages"][1]["content"] = [
+        {"type": "text", "text": "first"},
+        {"type": "image_url", "image_url": {"url": "x"}},
+        {"type": "text", "text": "last"},
+    ]
+    inject_anthropic_cache_breakpoints(data)
+    parts = data["messages"][1]["content"]
+    assert parts[2]["cache_control"] == {"type": "ephemeral"}
+    assert "cache_control" not in parts[0]
+
+
+def test_noop_without_messages() -> None:
+    assert inject_anthropic_cache_breakpoints({"prompt": "x"}) is False
+
+
+# ---------------------------------------------------------------------------
+# prepare_request_body integration
+# ---------------------------------------------------------------------------
+
+
+def _model(model_id: str):  # 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=200000,
+        architecture=Architecture(
+            modality="text->text",
+            input_modalities=["text"],
+            output_modalities=["text"],
+            tokenizer="Claude",
+            instruct_type=None,
+        ),
+        pricing=Pricing(prompt=0.0, completion=0.0),
+    )
+
+
+def _openrouter_provider() -> "GenericUpstreamProvider":
+    # OpenRouter endpoint via the generic provider — recognised by base URL.
+    return GenericUpstreamProvider(base_url="https://openrouter.ai/api/v1")
+
+
+@pytest.mark.parametrize(
+    "model_id", ["anthropic/claude-sonnet-4.5", "qwen/qwen3-max", "deepseek/deepseek-v3.2"]
+)
+def test_prepare_request_body_injects_for_explicit_models(model_id: str) -> None:
+    provider = _openrouter_provider()
+    body = json.dumps(_chat_body()).encode()
+    out = provider.prepare_request_body(body, _model(model_id))
+    assert out is not None
+    data = json.loads(out)
+    assert body_has_cache_control(data) is True
+    assert data["tools"][-1]["cache_control"] == {"type": "ephemeral"}
+
+
+def test_prepare_request_body_skips_for_automatic_provider_model() -> None:
+    provider = _openrouter_provider()
+    body = json.dumps(_chat_body()).encode()
+    out = provider.prepare_request_body(body, _model("openai/gpt-4o"))
+    assert out is not None
+    data = json.loads(out)
+    assert body_has_cache_control(data) is False
+
+
+def test_prepare_request_body_skips_when_upstream_rejects_markers() -> None:
+    # Claude id but a non-OpenRouter/Anthropic upstream → must NOT inject,
+    # since the markers could be rejected by an upstream that doesn't accept them.
+    from routstr.upstream import GenericUpstreamProvider
+
+    provider = GenericUpstreamProvider(base_url="https://some-gateway.example/v1")
+    body = json.dumps(_chat_body()).encode()
+    out = provider.prepare_request_body(body, _model("anthropic/claude-sonnet-4.5"))
+    assert out is not None
+    data = json.loads(out)
+    assert body_has_cache_control(data) is False

tests/unit/test_cache_pricing.py

@@ -0,0 +1,347 @@
+"""Tests for cache-aware pricing of cached input tokens.
+
+Specifies two things:
+
+1. ``backfill_cache_pricing`` — when the OpenRouter model feed omits cache
+   rates (it does for most DeepSeek models and e.g. openai/gpt-4o), they are
+   filled from litellm's bundled cost map instead of silently billing cache
+   reads at the full input rate. Existing OpenRouter values are never
+   overwritten, and provider fees apply to backfilled rates like any other.
+2. ``calculate_cost`` — cached tokens are billed at the cache rates from the
+   model's sats_pricing; the full input rate remains only as the documented
+   last resort when no cache rate could be resolved anywhere.
+"""
+
+import os
+from unittest.mock import Mock, patch
+
+import litellm
+import pytest
+
+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.core.settings import settings
+from routstr.payment.cost_calculation import CostData, calculate_cost
+from routstr.payment.models import (
+    Architecture,
+    Model,
+    Pricing,
+    backfill_cache_pricing,
+)
+from routstr.upstream import GenericUpstreamProvider
+
+
+def _make_model(model_id: str, pricing: Pricing) -> Model:
+    return Model(
+        id=model_id,
+        name=model_id,
+        created=0,
+        description="",
+        context_length=64000,
+        architecture=Architecture(
+            modality="text->text",
+            input_modalities=["text"],
+            output_modalities=["text"],
+            tokenizer="Other",
+            instruct_type=None,
+        ),
+        pricing=pricing,
+    )
+
+
+# ============================================================================
+# backfill_cache_pricing — litellm as fallback source for missing cache rates
+# ============================================================================
+
+
+def test_backfill_deepseek_cache_read_from_litellm() -> None:
+    """deepseek/deepseek-chat has no input_cache_read on OpenRouter; litellm
+    knows the real rate (10x cheaper than input)."""
+    pricing = Pricing(prompt=2.8e-07, completion=4.2e-07)
+
+    result = backfill_cache_pricing("deepseek/deepseek-chat", pricing)
+
+    expected = litellm.model_cost["deepseek/deepseek-chat"][
+        "cache_read_input_token_cost"
+    ]
+    assert result.input_cache_read == expected
+    assert result.input_cache_read < pricing.prompt  # sanity: it's a discount
+
+
+def test_backfill_strips_vendor_prefix_for_litellm_lookup() -> None:
+    """OpenRouter ids are vendor-prefixed (openai/gpt-4o); litellm keys most
+    non-DeepSeek models without the prefix (gpt-4o)."""
+    pricing = Pricing(prompt=2.5e-06, completion=1e-05)
+
+    result = backfill_cache_pricing("openai/gpt-4o", pricing)
+
+    expected = litellm.model_cost["gpt-4o"]["cache_read_input_token_cost"]
+    assert result.input_cache_read == expected
+
+
+def test_backfill_case_insensitive_lookup() -> None:
+    """A generic upstream may report a mixed-case id
+    (deepseek-ai/DeepSeek-V4-Flash); litellm keys are lowercase. The
+    case-insensitive fallback still resolves the cache rate."""
+    pricing = Pricing(prompt=1.4e-07, completion=2.8e-07)
+
+    result = backfill_cache_pricing("deepseek-ai/DeepSeek-V4-Flash", pricing)
+
+    expected = litellm.model_cost["deepseek-v4-flash"][
+        "cache_read_input_token_cost"
+    ]
+    assert result.input_cache_read == expected
+    assert result.input_cache_read < pricing.prompt  # sanity: it's a discount
+
+
+def test_backfill_fills_cache_write_rate() -> None:
+    """Anthropic cache writes cost more than input (1.25x); billing them at
+    the input rate undercharges. litellm carries the write rate."""
+    pricing = Pricing(prompt=3e-06, completion=1.5e-05)
+
+    result = backfill_cache_pricing("anthropic/claude-sonnet-4-5", pricing)
+
+    expected = litellm.model_cost["claude-sonnet-4-5"][
+        "cache_creation_input_token_cost"
+    ]
+    assert result.input_cache_write == expected
+    assert result.input_cache_write > pricing.prompt  # sanity: write premium
+
+
+def test_backfill_never_overwrites_openrouter_rates() -> None:
+    """When OpenRouter provides a cache rate, it is authoritative."""
+    pricing = Pricing(
+        prompt=2.1e-07, completion=7.9e-07, input_cache_read=1.3e-07
+    )
+
+    result = backfill_cache_pricing("deepseek/deepseek-chat", pricing)
+
+    assert result.input_cache_read == 1.3e-07
+
+
+def test_backfill_unknown_model_unchanged() -> None:
+    """Models litellm doesn't know stay untouched (last-resort fallback to
+    the input rate happens later, at billing time)."""
+    pricing = Pricing(prompt=1e-06, completion=2e-06)
+
+    result = backfill_cache_pricing("artificial-dumbness/dumb-1", pricing)
+
+    assert result.input_cache_read == 0.0
+    assert result.input_cache_write == 0.0
+
+
+def test_provider_fee_applies_to_backfilled_cache_rates() -> None:
+    """Backfill happens before the provider fee, so cache rates carry the
+    same markup as every other price component."""
+    provider = GenericUpstreamProvider(
+        base_url="http://upstream.example", provider_fee=2.0
+    )
+    model = _make_model(
+        "deepseek/deepseek-chat", Pricing(prompt=2.8e-07, completion=4.2e-07)
+    )
+
+    adjusted = provider._apply_provider_fee_to_model(model)
+
+    litellm_read = litellm.model_cost["deepseek/deepseek-chat"][
+        "cache_read_input_token_cost"
+    ]
+    assert adjusted.pricing.input_cache_read == pytest.approx(litellm_read * 2.0)
+    assert adjusted.pricing.prompt == pytest.approx(2.8e-07 * 2.0)
+
+
+def test_row_to_model_backfills_cache_rate() -> None:
+    """The DB-override path (admin-configured providers, e.g. a generic
+    upstream) stores pricing without cache rates. ``_row_to_model`` must
+    backfill them from litellm just like ``_apply_provider_fee_to_model``,
+    otherwise cache reads bill at the full input rate."""
+    import json
+
+    from routstr.core.db import ModelRow
+    from routstr.payment.models import _row_to_model
+
+    row = ModelRow(
+        id="deepseek-v4-flash",
+        name="deepseek-v4-flash",
+        created=0,
+        description="",
+        context_length=1000000,
+        architecture=json.dumps(
+            {
+                "modality": "text",
+                "input_modalities": ["text"],
+                "output_modalities": ["text"],
+                "tokenizer": "unknown",
+                "instruct_type": None,
+            }
+        ),
+        # Stored pricing omits input_cache_read (generic provider never sets it).
+        pricing=json.dumps({"prompt": 1.4e-07, "completion": 2.8e-07}),
+        enabled=True,
+        upstream_provider_id=1,
+    )
+
+    with patch(
+        "routstr.payment.models.sats_usd_price", return_value=5.0e-5
+    ):
+        model = _row_to_model(row, apply_provider_fee=True, provider_fee=1.0)
+
+    litellm_read = litellm.model_cost["deepseek-v4-flash"][
+        "cache_read_input_token_cost"
+    ]
+    assert model.pricing.input_cache_read == pytest.approx(litellm_read)
+    assert model.pricing.input_cache_read < model.pricing.prompt  # a discount
+    assert model.sats_pricing is not None
+    assert model.sats_pricing.input_cache_read > 0
+
+
+def test_row_to_model_backfills_via_forwarded_model_id() -> None:
+    """An alias row (id != forwarded_model_id) must backfill cache rates from
+    the *forwarded* model name — the real upstream model litellm prices —
+    not the alias id, which litellm doesn't know."""
+    import json
+
+    from routstr.core.db import ModelRow
+    from routstr.payment.models import _row_to_model
+
+    row = ModelRow(
+        id="local-alias",  # litellm has no such key
+        name="local-alias",
+        created=0,
+        description="",
+        context_length=1000000,
+        architecture=json.dumps(
+            {
+                "modality": "text",
+                "input_modalities": ["text"],
+                "output_modalities": ["text"],
+                "tokenizer": "unknown",
+                "instruct_type": None,
+            }
+        ),
+        pricing=json.dumps({"prompt": 1.4e-07, "completion": 2.8e-07}),
+        enabled=True,
+        upstream_provider_id=1,
+        forwarded_model_id="deepseek-v4-flash",
+    )
+
+    with patch(
+        "routstr.payment.models.sats_usd_price", return_value=5.0e-5
+    ):
+        model = _row_to_model(row, apply_provider_fee=True, provider_fee=1.0)
+
+    litellm_read = litellm.model_cost["deepseek-v4-flash"][
+        "cache_read_input_token_cost"
+    ]
+    assert model.pricing.input_cache_read == pytest.approx(litellm_read)
+    assert model.pricing.input_cache_read < model.pricing.prompt
+
+
+# ============================================================================
+# calculate_cost — cached tokens billed at cache rates
+# ============================================================================
+
+
+@pytest.fixture(autouse=True)
+def patch_sats_usd_price() -> None:  # type: ignore[misc]
+    with patch("routstr.payment.cost_calculation.sats_usd_price", return_value=5.0e-5):
+        yield
+
+
+@pytest.fixture
+def model_pricing(monkeypatch: pytest.MonkeyPatch) -> Mock:
+    """Model-based pricing: 1 msat per input token, 2 per output token,
+    0.1 per cache-read token, 1.25 per cache-write token."""
+    monkeypatch.setattr(settings, "fixed_pricing", False)
+    model = Mock()
+    model.sats_pricing = Pricing(
+        prompt=0.001,
+        completion=0.002,
+        input_cache_read=0.0001,
+        input_cache_write=0.00125,
+    )
+    return model
+
+
+@pytest.mark.asyncio
+async def test_deepseek_cache_hits_billed_at_cache_rate(model_pricing: Mock) -> None:
+    """The reported overcharge scenario: a 10k-token prompt with 90% cache
+    hits costs 2900 msats at honest rates, not the 11000 msats that billing
+    every prompt token at the full input rate would charge."""
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 10000,
+            "completion_tokens": 500,
+            "prompt_cache_hit_tokens": 9000,
+            "prompt_cache_miss_tokens": 1000,
+        },
+    }
+
+    with patch("routstr.proxy.get_model_instance", return_value=model_pricing):
+        result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    # 1000 input @ 1 msat + 9000 cache reads @ 0.1 msat + 500 output @ 2 msat.
+    # input_msats folds the cache-read cost in (1000 + 900) so a dashboard
+    # rendering I/O/T sees input + output == total; the cache portion stays
+    # visible in cache_read_msats.
+    assert result.cache_read_msats == 900
+    assert result.output_msats == 1000
+    assert result.input_msats == 1900
+    assert result.input_msats + result.output_msats == result.total_msats
+    assert result.total_msats == 2900
+
+
+@pytest.mark.asyncio
+async def test_anthropic_cache_write_billed_at_write_rate(model_pricing: Mock) -> None:
+    """Cache writes carry their premium rate (1.25x input here), instead of
+    being silently billed at the plain input rate."""
+    response = {
+        "model": "claude-sonnet-4-5",
+        "usage": {
+            "input_tokens": 300,
+            "output_tokens": 100,
+            "cache_read_input_tokens": 500,
+            "cache_creation_input_tokens": 2000,
+        },
+    }
+
+    with patch("routstr.proxy.get_model_instance", return_value=model_pricing):
+        result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    # 300 @ 1 + 500 @ 0.1 + 2000 @ 1.25 + 100 @ 2
+    assert result.cache_read_msats == 50
+    assert result.cache_creation_msats == 2500
+    assert result.total_msats == 3050
+
+
+@pytest.mark.asyncio
+async def test_missing_cache_rate_falls_back_to_input_rate(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Documented last resort: when no cache rate could be resolved anywhere
+    (OpenRouter and litellm both silent), cache reads bill at the input rate —
+    never cheaper, never free."""
+    monkeypatch.setattr(settings, "fixed_pricing", False)
+    model = Mock()
+    model.sats_pricing = Pricing(prompt=0.001, completion=0.002)
+
+    response = {
+        "model": "dumb-1",
+        "usage": {
+            "prompt_tokens": 10000,
+            "completion_tokens": 500,
+            "prompt_cache_hit_tokens": 9000,
+            "prompt_cache_miss_tokens": 1000,
+        },
+    }
+
+    with patch("routstr.proxy.get_model_instance", return_value=model):
+        result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    # 1000 @ 1 + 9000 @ 1 (fallback) + 500 @ 2
+    assert result.total_msats == 11000

tests/unit/test_cost_calculation_caching.py

@@ -1,10 +1,11 @@
 """Tests for cache token handling in cost calculation.
 
-Covers OpenAI vs Anthropic caching formats, edge cases, and billing accuracy.
+Covers OpenAI, Anthropic and DeepSeek caching formats, dialect precedence,
+edge cases, and billing accuracy.
 """
 
 import os
-from unittest.mock import AsyncMock, patch
+from unittest.mock import patch
 
 import pytest
 
@@ -16,12 +17,6 @@ from routstr.core.settings import settings
 from routstr.payment.cost_calculation import CostData, MaxCostData, calculate_cost
 
 
-@pytest.fixture
-def mock_session() -> AsyncMock:
-    """Mock AsyncSession for cost calculation tests."""
-    return AsyncMock()
-
-
 @pytest.fixture(autouse=True)
 def mock_fixed_pricing(monkeypatch: pytest.MonkeyPatch) -> None:
     """Mock settings and price to use fixed pricing."""
@@ -41,7 +36,7 @@ def patch_sats_usd_price() -> None:  # type: ignore[misc]
 # Test 1: OpenAI Cache Format
 # ============================================================================
 @pytest.mark.asyncio
-async def test_openai_cache_subtraction(mock_session: AsyncMock) -> None:
+async def test_openai_cache_subtraction() -> None:
     """OpenAI includes cached_tokens in prompt_tokens, subtract them."""
     response = {
         "model": "gpt-4",
@@ -53,7 +48,7 @@ async def test_openai_cache_subtraction(mock_session: AsyncMock) -> None:
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 1000  # 2000 - 1000
@@ -65,7 +60,7 @@ async def test_openai_cache_subtraction(mock_session: AsyncMock) -> None:
 # Test 2: Anthropic Cache Format
 # ============================================================================
 @pytest.mark.asyncio
-async def test_anthropic_cache_additive(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_anthropic_cache_additive(mock_fixed_pricing: None) -> None:
     """Anthropic cache tokens are separate (additive) from input_tokens."""
     response = {
         "model": "claude-3-5-sonnet",
@@ -76,7 +71,7 @@ async def test_anthropic_cache_additive(mock_session: AsyncMock, mock_fixed_pric
             "cache_read_input_tokens": 0,
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 500
@@ -89,7 +84,7 @@ async def test_anthropic_cache_additive(mock_session: AsyncMock, mock_fixed_pric
 # Test 3: Invalid Cache (Edge Case)
 # ============================================================================
 @pytest.mark.asyncio
-async def test_cache_read_exceeds_prompt_tokens(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_cache_read_exceeds_prompt_tokens(mock_fixed_pricing: None) -> None:
     """Handle buggy upstream reporting cached > prompt_tokens."""
     response = {
         "model": "gpt-4",
@@ -101,7 +96,7 @@ async def test_cache_read_exceeds_prompt_tokens(mock_session: AsyncMock, mock_fi
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     # Should not go negative
     assert isinstance(result, CostData)
@@ -114,7 +109,7 @@ async def test_cache_read_exceeds_prompt_tokens(mock_session: AsyncMock, mock_fi
 # Test 4: Malformed Token Values
 # ============================================================================
 @pytest.mark.asyncio
-async def test_malformed_cache_tokens_coerce_to_zero(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_malformed_cache_tokens_coerce_to_zero(mock_fixed_pricing: None) -> None:
     """Handle non-numeric cache token values."""
     response = {
         "model": "gpt-4",
@@ -127,7 +122,7 @@ async def test_malformed_cache_tokens_coerce_to_zero(mock_session: AsyncMock, mo
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     # Both should coerce to 0
     assert isinstance(result, CostData)
@@ -139,7 +134,7 @@ async def test_malformed_cache_tokens_coerce_to_zero(mock_session: AsyncMock, mo
 # Test 5: Anthropic Cache Not Subtracted
 # ============================================================================
 @pytest.mark.asyncio
-async def test_anthropic_cache_not_subtracted(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_anthropic_cache_not_subtracted(mock_fixed_pricing: None) -> None:
     """Anthropic cache fields should NOT be subtracted from input_tokens."""
     response = {
         "model": "claude-3-5-sonnet",
@@ -149,7 +144,7 @@ async def test_anthropic_cache_not_subtracted(mock_session: AsyncMock, mock_fixe
             "cache_read_input_tokens": 200,  # ← Additive, don't subtract
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     # Anthropic: input_tokens stays as-is
     assert isinstance(result, CostData)
@@ -161,7 +156,7 @@ async def test_anthropic_cache_not_subtracted(mock_session: AsyncMock, mock_fixe
 # Test 6: Only Cache Read, No Regular Input
 # ============================================================================
 @pytest.mark.asyncio
-async def test_only_cache_read_tokens(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_only_cache_read_tokens(mock_fixed_pricing: None) -> None:
     """Handle response with only cache read tokens."""
     response = {
         "model": "gpt-4",
@@ -173,7 +168,7 @@ async def test_only_cache_read_tokens(mock_session: AsyncMock, mock_fixed_pricin
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 0  # max(0, 0 - 1000)
@@ -185,7 +180,7 @@ async def test_only_cache_read_tokens(mock_session: AsyncMock, mock_fixed_pricin
 # Test 7: Only Cache Creation
 # ============================================================================
 @pytest.mark.asyncio
-async def test_only_cache_creation_tokens(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_only_cache_creation_tokens(mock_fixed_pricing: None) -> None:
     """Handle response with only cache creation tokens (Anthropic)."""
     response = {
         "model": "claude-3-5-sonnet",
@@ -196,7 +191,7 @@ async def test_only_cache_creation_tokens(mock_session: AsyncMock, mock_fixed_pr
             "cache_read_input_tokens": 0,
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 500
@@ -209,7 +204,7 @@ async def test_only_cache_creation_tokens(mock_session: AsyncMock, mock_fixed_pr
 # Test 8: Both Cache Read and Creation
 # ============================================================================
 @pytest.mark.asyncio
-async def test_both_cache_read_and_creation(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_both_cache_read_and_creation(mock_fixed_pricing: None) -> None:
     """Handle response with both cache read and creation."""
     response = {
         "model": "claude-3-5-sonnet",
@@ -220,7 +215,7 @@ async def test_both_cache_read_and_creation(mock_session: AsyncMock, mock_fixed_
             "cache_read_input_tokens": 500,
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 300
@@ -233,7 +228,7 @@ async def test_both_cache_read_and_creation(mock_session: AsyncMock, mock_fixed_
 # Test 9: Token Field Fallback
 # ============================================================================
 @pytest.mark.asyncio
-async def test_token_field_fallback_order(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_token_field_fallback_order(mock_fixed_pricing: None) -> None:
     """Verify fallback order for token extraction."""
     # When prompt_tokens is not present, fall back to input_tokens
     response = {
@@ -243,7 +238,7 @@ async def test_token_field_fallback_order(mock_session: AsyncMock, mock_fixed_pr
             "completion_tokens": 50,
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 250
@@ -254,20 +249,21 @@ async def test_token_field_fallback_order(mock_session: AsyncMock, mock_fixed_pr
 # Test 10: Float Token Values
 # ============================================================================
 @pytest.mark.asyncio
-async def test_float_token_values_coerced_to_int(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_float_token_values_coerced_to_int(mock_fixed_pricing: None) -> None:
     """Handle float token values by converting to int."""
     response = {
         "model": "gpt-4",
         "usage": {
             "prompt_tokens": 100.7,  # Float
             "completion_tokens": 50.3,  # Float
-            "cache_read_input_tokens": 25.9,  # Float
+            "prompt_tokens_details": {"cached_tokens": 25.9},  # Float
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
-    assert result.input_tokens == 100  # Floored
+    # cached_tokens are part of prompt_tokens (OpenAI dialect) → subtracted: 100 - 25
+    assert result.input_tokens == 75  # Floored
     assert result.output_tokens == 50  # Floored
     assert result.cache_read_input_tokens == 25  # Floored
 
@@ -276,7 +272,7 @@ async def test_float_token_values_coerced_to_int(mock_session: AsyncMock, mock_f
 # Test 11: Boolean Cache Tokens
 # ============================================================================
 @pytest.mark.asyncio
-async def test_boolean_cache_tokens_coerced_to_zero(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_boolean_cache_tokens_coerced_to_zero(mock_fixed_pricing: None) -> None:
     """Handle boolean cache token values by coercing to zero."""
     response = {
         "model": "gpt-4",
@@ -286,7 +282,7 @@ async def test_boolean_cache_tokens_coerced_to_zero(mock_session: AsyncMock, moc
             "cache_read_input_tokens": True,  # Boolean
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.cache_read_input_tokens == 0  # Boolean coerced to 0
@@ -297,7 +293,7 @@ async def test_boolean_cache_tokens_coerced_to_zero(mock_session: AsyncMock, moc
 # Test 12: Zero Cache Tokens
 # ============================================================================
 @pytest.mark.asyncio
-async def test_zero_cache_tokens(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_zero_cache_tokens(mock_fixed_pricing: None) -> None:
     """Handle explicit zero cache tokens."""
     response = {
         "model": "gpt-4",
@@ -309,21 +305,174 @@ async def test_zero_cache_tokens(mock_session: AsyncMock, mock_fixed_pricing: No
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.cache_read_input_tokens == 0
     assert result.input_tokens == 100
 
 
+# ============================================================================
+# DeepSeek Cache Format
+# DeepSeek emits neither OpenAI's prompt_tokens_details nor Anthropic's
+# cache_read_input_tokens — only prompt_cache_hit_tokens and
+# prompt_cache_miss_tokens, with the documented guarantee
+# prompt_tokens = hit + miss. Hits are ~10x cheaper upstream, so billing
+# them as regular input is a large overcharge.
+# ============================================================================
+@pytest.mark.asyncio
+async def test_deepseek_cache_hit_tokens_extracted() -> None:
+    """DeepSeek cache hits are extracted and removed from regular input.
+
+    Payload shape verbatim from the DeepSeek API reference (usage object).
+    """
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 10000,  # = hit + miss
+            "completion_tokens": 500,
+            "total_tokens": 10500,
+            "prompt_cache_hit_tokens": 9000,
+            "prompt_cache_miss_tokens": 1000,
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.input_tokens == 1000  # only the cache misses
+    assert result.cache_read_input_tokens == 9000
+    assert result.output_tokens == 500
+
+
+@pytest.mark.asyncio
+async def test_deepseek_all_tokens_cached() -> None:
+    """A fully cached DeepSeek prompt bills zero regular input tokens."""
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 5000,
+            "completion_tokens": 100,
+            "prompt_cache_hit_tokens": 5000,
+            "prompt_cache_miss_tokens": 0,
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.input_tokens == 0
+    assert result.cache_read_input_tokens == 5000
+
+
+@pytest.mark.asyncio
+async def test_dialect_precedence_never_double_subtracts() -> None:
+    """If a vendor emits both OpenAI-style and DeepSeek-style cache fields for
+    the same cached tokens, they are counted once, not subtracted twice."""
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 10000,
+            "completion_tokens": 500,
+            "prompt_tokens_details": {"cached_tokens": 9000},
+            "prompt_cache_hit_tokens": 9000,
+            "prompt_cache_miss_tokens": 1000,
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.input_tokens == 1000  # 10000 - 9000, applied exactly once
+    assert result.cache_read_input_tokens == 9000
+
+
+@pytest.mark.asyncio
+async def test_deepseek_malformed_hit_tokens_coerce_to_zero() -> None:
+    """Malformed DeepSeek cache fields degrade to billing all input at full
+    rate instead of crashing or going negative."""
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 1000,
+            "completion_tokens": 50,
+            "prompt_cache_hit_tokens": "garbage",
+            "prompt_cache_miss_tokens": -5,
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.input_tokens == 1000
+    assert result.cache_read_input_tokens == 0
+
+
+# ============================================================================
+# Truly-empty response with a non-zero USD cost → full refund
+#
+# When an upstream reports a USD cost but the response carries NO tokens at all
+# (input, output, cache-read and cache-creation all zero), billing the
+# USD-derived cost charges the user for nothing. Refund in full. The gate is
+# tightened relative to PR #489: a cache-read/-creation-only turn legitimately
+# reports zero prompt/completion tokens with a real cost and must still bill.
+# ============================================================================
+@pytest.mark.asyncio
+async def test_truly_empty_usd_cost_response_is_refunded(
+    mock_fixed_pricing: None,
+) -> None:
+    """0 input + 0 output + 0 cache tokens with a non-zero USD cost → refund."""
+    response = {
+        "model": "gpt-4",
+        "usage": {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_cost": 0.01,  # non-zero USD cost despite no tokens
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.total_msats == 0  # full refund
+    assert result.input_msats == 0
+    assert result.output_msats == 0
+    assert result.total_usd == 0.0
+    assert result.input_tokens == 0
+    assert result.output_tokens == 0
+    assert result.cache_read_input_tokens == 0
+    assert result.cache_creation_input_tokens == 0
+
+
+@pytest.mark.asyncio
+async def test_cache_read_only_usd_cost_response_is_billed(
+    mock_fixed_pricing: None,
+) -> None:
+    """Cache-read-only turn (0 prompt/completion, non-zero cost) still bills."""
+    response = {
+        "model": "claude-3-5-sonnet",
+        "usage": {
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "cache_read_input_tokens": 1000,  # real cached usage
+            "cache_creation_input_tokens": 0,
+            "total_cost": 0.01,  # non-zero USD cost
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    # NOT refunded — the USD cost is billed in full. Pinning the exact value
+    # guards against any future regression that would over-refund a cache-only
+    # turn (the bug in PR #489, which refunded whenever prompt+completion == 0).
+    assert result.total_msats == 200000
+    assert result.total_usd == 0.01
+    assert result.cache_read_input_tokens == 1000
+
+
 # ============================================================================
 # Test 13: Missing Usage Block
 # ============================================================================
 @pytest.mark.asyncio
-async def test_missing_usage_block(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_missing_usage_block(mock_fixed_pricing: None) -> None:
     """When usage is missing, return MaxCostData with zero tokens."""
     response = {"model": "gpt-4", "choices": [{"message": {"content": "test"}}]}
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, MaxCostData)
     assert result.input_tokens == 0
@@ -335,10 +484,10 @@ async def test_missing_usage_block(mock_session: AsyncMock, mock_fixed_pricing:
 # Test 14: Null Usage Block
 # ============================================================================
 @pytest.mark.asyncio
-async def test_null_usage_block(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_null_usage_block(mock_fixed_pricing: None) -> None:
     """When usage is null, return MaxCostData with zero tokens."""
     response = {"model": "gpt-4", "usage": None}
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, MaxCostData)
     assert result.input_tokens == 0

tests/unit/test_messages_litellm_dispatch.py

@@ -500,7 +500,7 @@ async def test_streaming_emits_sse_and_reconciles_cost_at_end() -> None:
     captured_cost_call: dict[str, Any] = {}
 
     async def fake_adjust(
-        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int
+        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int, usage: Any = None
     ) -> dict:
         captured_cost_call["combined_data"] = combined_data
         captured_cost_call["max_cost"] = max_cost
@@ -589,7 +589,7 @@ async def test_streaming_handles_iterator_yielding_raw_sse_bytes() -> None:
     captured: dict[str, Any] = {}
 
     async def fake_adjust(
-        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int
+        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int, usage: Any = None
     ) -> dict:
         captured["combined_data"] = combined_data
         return fake_cost

tests/unit/test_model_paths.py

@@ -0,0 +1,712 @@
+"""Tests for the model-path discovery service and endpoints."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from contextlib import asynccontextmanager
+from types import SimpleNamespace
+from typing import Any, AsyncGenerator
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+from sqlmodel import SQLModel
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+os.environ.setdefault("UPSTREAM_BASE_URL", "http://test")
+os.environ.setdefault("UPSTREAM_API_KEY", "test")
+
+from routstr.core.db import ModelRow, UpstreamProviderRow  # noqa: E402
+from routstr.payment.models import models_router  # noqa: E402
+from routstr.upstream import model_paths as mp  # noqa: E402
+
+# --------------------------------------------------------------------------- #
+# Fakes
+# --------------------------------------------------------------------------- #
+
+
+def _model(
+    id: str,
+    *,
+    forwarded_model_id: str | None = None,
+    canonical_slug: str | None = None,
+    enabled: bool = True,
+) -> SimpleNamespace:
+    return SimpleNamespace(
+        id=id,
+        forwarded_model_id=forwarded_model_id,
+        canonical_slug=canonical_slug,
+        enabled=enabled,
+    )
+
+
+def _model_row(
+    id: str,
+    *,
+    upstream_provider_id: int = 1,
+    forwarded_model_id: str | None = None,
+    canonical_slug: str | None = None,
+    enabled: bool = True,
+) -> ModelRow:
+    return ModelRow(
+        id=id,
+        upstream_provider_id=upstream_provider_id,
+        name=id,
+        created=0,
+        description="test model",
+        context_length=8192,
+        architecture=json.dumps(
+            {
+                "modality": "text",
+                "input_modalities": ["text"],
+                "output_modalities": ["text"],
+                "tokenizer": "test",
+                "instruct_type": None,
+            }
+        ),
+        pricing=json.dumps({"prompt": 0.000001, "completion": 0.000002}),
+        enabled=enabled,
+        forwarded_model_id=forwarded_model_id,
+        canonical_slug=canonical_slug,
+    )
+
+
+class _FakeProvider:
+    def __init__(
+        self,
+        *,
+        provider_type: str,
+        base_url: str,
+        models: list[SimpleNamespace],
+        db_id: int | None = 1,
+        api_key: str = "sk-test",
+    ) -> None:
+        self.provider_type = provider_type
+        self.base_url = base_url
+        self.api_key = api_key
+        self.db_id = db_id
+        self._models = models
+
+    def get_cached_models(self) -> list[SimpleNamespace]:
+        return self._models
+
+
+class _FakeResponse:
+    def __init__(self, status_code: int, payload: Any) -> None:
+        self.status_code = status_code
+        self._payload = payload
+
+    def json(self) -> Any:
+        return self._payload
+
+
+@pytest.fixture
+async def patched_session(
+    monkeypatch: pytest.MonkeyPatch,
+) -> AsyncGenerator[AsyncEngine, None]:
+    """Bind the service's ``create_session`` to a fresh in-memory engine."""
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    # Seed the FK target so ModelPathRow inserts satisfy the constraint.
+    async with AsyncSession(engine) as session:
+        for pid in (1, 2):
+            session.add(
+                UpstreamProviderRow(
+                    id=pid,
+                    slug=f"p{pid}",
+                    provider_type="anthropic" if pid == 1 else "openrouter",
+                    base_url=f"https://provider-{pid}",
+                    api_key=f"k{pid}",
+                )
+            )
+        await session.commit()
+
+    @asynccontextmanager
+    async def _factory() -> AsyncGenerator[AsyncSession, None]:
+        async with AsyncSession(engine, expire_on_commit=False) as session:
+            yield session
+
+    monkeypatch.setattr(mp, "create_session", _factory)
+    yield engine
+    await engine.dispose()
+
+
+# --------------------------------------------------------------------------- #
+# Predicates / pure helpers
+# --------------------------------------------------------------------------- #
+
+
+def test_is_openrouter_base_url() -> None:
+    assert mp.is_openrouter_base_url("https://openrouter.ai/api/v1") is True
+    assert mp.is_openrouter_base_url("https://api.anthropic.com") is False
+    assert mp.is_openrouter_base_url(None) is False
+
+
+def test_native_anthropic_not_openrouter() -> None:
+    """Native Anthropic must not be treated as OpenRouter-compatible even though
+    ``_upstream_accepts_cache_control`` returns True for it."""
+    assert mp.is_openrouter_base_url("https://api.anthropic.com/v1") is False
+
+
+def test_exposed_model_id_prefers_forwarded() -> None:
+    assert (
+        mp.exposed_model_id(_model("claude-x", forwarded_model_id="fwd-claude"))
+        == "fwd-claude"
+    )
+    assert mp.exposed_model_id(_model("claude-x")) == "claude-x"
+
+
+def test_public_model_id_strips_provider_prefix() -> None:
+    assert mp.public_model_id("z-ai/glm-5v-turbo") == "glm-5v-turbo"
+    assert mp.public_model_id("gpt-4o-mini") == "gpt-4o-mini"
+
+
+def test_openrouter_author_slug_uses_canonical_not_forwarded() -> None:
+    m = _model(
+        "claude-opus-4.6",
+        forwarded_model_id="forwarded-only",
+        canonical_slug="anthropic/claude-opus-4.6",
+    )
+    assert mp.openrouter_author_slug(m) == "anthropic/claude-opus-4.6"
+
+
+def test_openrouter_author_slug_falls_back_to_slash_id() -> None:
+    m = _model("anthropic/claude-opus-4.6", canonical_slug="claude-opus-4.6")
+    assert mp.openrouter_author_slug(m) == "anthropic/claude-opus-4.6"
+
+
+def test_openrouter_author_slug_none_when_no_slash() -> None:
+    m = _model("claude-opus-4.6", canonical_slug="claude-opus-4.6")
+    assert mp.openrouter_author_slug(m) is None
+
+
+# --------------------------------------------------------------------------- #
+# Collection
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_direct_provider_single_path_uses_provider_type() -> None:
+    provider = _FakeProvider(
+        provider_type="anthropic",
+        base_url="https://api.anthropic.com/v1",
+        models=[_model("claude-opus-4.6")],
+    )
+    pairs = await mp._collect_provider_paths(provider)  # type: ignore[arg-type]
+    assert pairs == [("claude-opus-4.6", "anthropic")]
+
+
+@pytest.mark.asyncio
+async def test_direct_path_stores_exposed_model_id() -> None:
+    provider = _FakeProvider(
+        provider_type="anthropic",
+        base_url="https://api.anthropic.com/v1",
+        models=[_model("internal-id", forwarded_model_id="claude-opus-4.6")],
+    )
+    pairs = await mp._collect_provider_paths(provider)  # type: ignore[arg-type]
+    assert pairs == [("claude-opus-4.6", "anthropic")]
+
+
+@pytest.mark.asyncio
+async def test_disabled_models_excluded() -> None:
+    provider = _FakeProvider(
+        provider_type="anthropic",
+        base_url="https://api.anthropic.com/v1",
+        models=[
+            _model("enabled-model"),
+            _model("disabled-model", enabled=False),
+        ],
+    )
+    pairs = await mp._collect_provider_paths(provider)  # type: ignore[arg-type]
+    assert pairs == [("enabled-model", "anthropic")]
+
+
+@pytest.mark.asyncio
+async def test_openrouter_provider_adds_endpoint_paths(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    provider = _FakeProvider(
+        provider_type="openrouter",
+        base_url="https://openrouter.ai/api/v1",
+        models=[_model("claude-opus-4.6", canonical_slug="anthropic/claude-opus-4.6")],
+    )
+
+    async def _fake_get(
+        self: object,
+        url: str,
+        headers: object = None,
+        timeout: object = None,
+    ) -> _FakeResponse:
+        return _FakeResponse(
+            200,
+            {
+                "data": {
+                    "endpoints": [
+                        {"provider_name": "Anthropic"},
+                        {"provider_name": "Amazon Bedrock"},
+                    ]
+                }
+            },
+        )
+
+    monkeypatch.setattr("httpx.AsyncClient.get", _fake_get)
+
+    pairs = await mp._collect_provider_paths(provider)  # type: ignore[arg-type]
+    assert ("claude-opus-4.6", "openrouter:Anthropic") in pairs
+    assert ("claude-opus-4.6", "openrouter:Amazon Bedrock") in pairs
+    assert ("claude-opus-4.6", "openrouter") not in pairs
+    assert len(pairs) == 2
+
+
+@pytest.mark.asyncio
+async def test_generic_provider_with_openrouter_base_url_discovers(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A generic provider pointed at OpenRouter exposes the response-stamped
+    ``generic:<upstream>`` path, not a native ``openrouter:`` path."""
+    provider = _FakeProvider(
+        provider_type="generic",
+        base_url="https://openrouter.ai/api/v1",
+        models=[_model("claude-opus-4.6", canonical_slug="anthropic/claude-opus-4.6")],
+    )
+
+    async def _fake_get(
+        self: object,
+        url: str,
+        headers: object = None,
+        timeout: object = None,
+    ) -> _FakeResponse:
+        return _FakeResponse(
+            200, {"data": {"endpoints": [{"provider_name": "Anthropic"}]}}
+        )
+
+    monkeypatch.setattr("httpx.AsyncClient.get", _fake_get)
+
+    pairs = await mp._collect_provider_paths(provider)  # type: ignore[arg-type]
+    assert pairs == [("claude-opus-4.6", "generic:Anthropic")]
+
+
+@pytest.mark.asyncio
+async def test_openrouter_failure_degrades_gracefully(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    provider = _FakeProvider(
+        provider_type="openrouter",
+        base_url="https://openrouter.ai/api/v1",
+        models=[_model("claude-opus-4.6", canonical_slug="anthropic/claude-opus-4.6")],
+    )
+
+    async def _boom(
+        self: object,
+        url: str,
+        headers: object = None,
+        timeout: object = None,
+    ) -> _FakeResponse:
+        raise RuntimeError("network down")
+
+    monkeypatch.setattr("httpx.AsyncClient.get", _boom)
+
+    pairs = await mp._collect_provider_paths(provider)  # type: ignore[arg-type]
+    assert pairs == []
+
+
+@pytest.mark.asyncio
+async def test_openrouter_rate_limit_skips_model(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    provider = _FakeProvider(
+        provider_type="openrouter",
+        base_url="https://openrouter.ai/api/v1",
+        models=[_model("claude-opus-4.6", canonical_slug="anthropic/claude-opus-4.6")],
+    )
+
+    async def _rate_limited(
+        self: object,
+        url: str,
+        headers: object = None,
+        timeout: object = None,
+    ) -> _FakeResponse:
+        return _FakeResponse(429, {})
+
+    monkeypatch.setattr("httpx.AsyncClient.get", _rate_limited)
+
+    pairs = await mp._collect_provider_paths(provider)  # type: ignore[arg-type]
+    assert pairs == []
+
+
+@pytest.mark.asyncio
+async def test_openrouter_fanout_is_bounded(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(mp, "_OPENROUTER_CONCURRENCY", 3)
+    models = [
+        _model(f"m{i}", canonical_slug=f"author/m{i}") for i in range(20)
+    ]
+    provider = _FakeProvider(
+        provider_type="openrouter",
+        base_url="https://openrouter.ai/api/v1",
+        models=models,
+    )
+
+    state = {"current": 0, "max": 0}
+
+    async def _slow_get(
+        self: object,
+        url: str,
+        headers: object = None,
+        timeout: object = None,
+    ) -> _FakeResponse:
+        state["current"] += 1
+        state["max"] = max(state["max"], state["current"])
+        await asyncio.sleep(0.02)
+        state["current"] -= 1
+        return _FakeResponse(200, {"data": {"endpoints": [{"provider_name": "X"}]}})
+
+    monkeypatch.setattr("httpx.AsyncClient.get", _slow_get)
+
+    await mp._collect_provider_paths(provider)  # type: ignore[arg-type]
+    assert state["max"] <= 3, f"concurrency exceeded bound: {state['max']}"
+
+
+# --------------------------------------------------------------------------- #
+# Persistence + query
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_refresh_replaces_stale_rows(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(1, [("m1", "anthropic"), ("m2", "anthropic")])
+    first = await mp.get_all_model_paths()
+    assert {row["id"] for row in first} == {"m1", "m2"}
+
+    # Second refresh with a different set — stale m2 must disappear.
+    await mp._persist_provider_paths(1, [("m1", "anthropic")])
+    second = await mp.get_all_model_paths()
+    assert {row["id"] for row in second} == {"m1"}
+
+
+@pytest.mark.asyncio
+async def test_refresh_model_paths_excludes_db_disabled_override(
+    patched_session: AsyncEngine,
+) -> None:
+    async with AsyncSession(patched_session) as session:
+        session.add(_model_row("disabled-by-db", enabled=False))
+        await session.commit()
+
+    provider = _FakeProvider(
+        provider_type="anthropic",
+        base_url="https://api.anthropic.com/v1",
+        models=[_model("disabled-by-db")],
+        db_id=1,
+    )
+
+    await mp.refresh_model_paths([provider])  # type: ignore[list-item]
+
+    assert await mp.get_all_model_paths() == []
+
+
+@pytest.mark.asyncio
+async def test_refresh_model_paths_uses_db_forwarded_alias(
+    patched_session: AsyncEngine,
+) -> None:
+    async with AsyncSession(patched_session) as session:
+        session.add(_model_row("internal-id", forwarded_model_id="public-alias"))
+        await session.commit()
+
+    provider = _FakeProvider(
+        provider_type="anthropic",
+        base_url="https://api.anthropic.com/v1",
+        models=[_model("internal-id")],
+        db_id=1,
+    )
+
+    await mp.refresh_model_paths([provider])  # type: ignore[list-item]
+
+    assert await mp.get_all_model_paths() == [
+        {"id": "public-alias", "paths": [{"path": "anthropic"}]}
+    ]
+
+
+@pytest.mark.asyncio
+async def test_refresh_model_paths_includes_enabled_db_override_missing_from_cache(
+    patched_session: AsyncEngine,
+) -> None:
+    async with AsyncSession(patched_session) as session:
+        session.add(_model_row("deployment-id", forwarded_model_id="public-deployment"))
+        await session.commit()
+
+    provider = _FakeProvider(
+        provider_type="generic",
+        base_url="https://custom-provider/v1",
+        models=[],
+        db_id=1,
+    )
+
+    await mp.refresh_model_paths([provider])  # type: ignore[list-item]
+
+    assert await mp.get_all_model_paths() == [
+        {"id": "public-deployment", "paths": [{"path": "generic"}]}
+    ]
+
+
+@pytest.mark.asyncio
+async def test_refresh_model_paths_prunes_inactive_provider_rows(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(1, [("m1", "anthropic")])
+    await mp._persist_provider_paths(2, [("m2", "openrouter:Anthropic")])
+
+    provider = _FakeProvider(
+        provider_type="anthropic",
+        base_url="https://api.anthropic.com/v1",
+        models=[_model("m1")],
+        db_id=1,
+    )
+
+    await mp.refresh_model_paths([provider])  # type: ignore[list-item]
+    active_only = await mp.get_all_model_paths()
+    assert active_only == [{"id": "m1", "paths": [{"path": "anthropic"}]}]
+
+    await mp.refresh_model_paths([])
+    assert await mp.get_all_model_paths() == []
+
+
+@pytest.mark.asyncio
+async def test_refresh_model_paths_skips_disabled_db_provider(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(1, [("stale-model", "anthropic")])
+    async with AsyncSession(patched_session) as session:
+        provider_row = await session.get(UpstreamProviderRow, 1)
+        assert provider_row is not None
+        provider_row.enabled = False
+        await session.commit()
+
+    provider = _FakeProvider(
+        provider_type="anthropic",
+        base_url="https://api.anthropic.com/v1",
+        models=[_model("fresh-model")],
+        db_id=1,
+    )
+
+    await mp.refresh_model_paths([provider])  # type: ignore[list-item]
+
+    assert await mp.get_all_model_paths() == []
+
+
+@pytest.mark.asyncio
+async def test_same_model_two_providers_two_paths(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(1, [("claude-opus-4.6", "anthropic")])
+    await mp._persist_provider_paths(2, [("claude-opus-4.6", "openrouter:Anthropic")])
+
+    data = await mp.get_all_model_paths()
+    assert len(data) == 1
+    entry = data[0]
+    assert entry["id"] == "claude-opus-4.6"
+    paths = {p["path"] for p in entry["paths"]}
+    assert paths == {"anthropic", "openrouter:Anthropic"}
+    # No canonical_id anywhere.
+    assert "canonical_id" not in entry
+    assert all("canonical_id" not in p for p in entry["paths"])
+
+
+@pytest.mark.asyncio
+async def test_get_all_model_paths_deduplicates_visible_paths(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(1, [("anthropic/claude-opus-4.6", "anthropic")])
+    await mp._persist_provider_paths(2, [("claude-opus-4.6", "anthropic")])
+
+    assert await mp.get_all_model_paths() == [
+        {"id": "claude-opus-4.6", "paths": [{"path": "anthropic"}]}
+    ]
+
+
+@pytest.mark.asyncio
+async def test_get_all_model_paths_returns_unqualified_model_ids(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(4, [("z-ai/glm-5v-turbo", "openrouter:Z.AI")])
+    await mp._persist_provider_paths(5, [("openai/gpt-4o-mini", "openrouter:OpenAI")])
+
+    data = await mp.get_all_model_paths()
+
+    assert {row["id"] for row in data} == {"glm-5v-turbo", "gpt-4o-mini"}
+
+
+@pytest.mark.asyncio
+async def test_get_paths_for_model_returns_only_paths(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(1, [("claude-opus-4.6", "anthropic")])
+    await mp._persist_provider_paths(2, [("claude-opus-4.6", "openrouter:Anthropic")])
+
+    paths = await mp.get_paths_for_model("claude-opus-4.6")
+    assert {p["path"] for p in paths} == {"anthropic", "openrouter:Anthropic"}
+    assert all(set(p.keys()) == {"path"} for p in paths)
+    assert await mp.get_paths_for_model("does-not-exist") == []
+
+
+@pytest.mark.asyncio
+async def test_get_paths_for_model_falls_back_to_provider_prefixed_id(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(4, [("z-ai/glm-5v-turbo", "openrouter:Z.AI")])
+
+    paths = await mp.get_paths_for_model("glm-5v-turbo")
+
+    assert paths == [{"path": "openrouter:Z.AI"}]
+
+
+@pytest.mark.asyncio
+async def test_get_paths_for_model_deduplicates_visible_paths(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(1, [("anthropic/claude-opus-4.6", "anthropic")])
+    await mp._persist_provider_paths(2, [("claude-opus-4.6", "anthropic")])
+
+    assert await mp.get_paths_for_model("claude-opus-4.6") == [
+        {"path": "anthropic"}
+    ]
+    assert await mp.get_paths_for_model("anthropic/claude-opus-4.6") == [
+        {"path": "anthropic"}
+    ]
+
+
+@pytest.mark.asyncio
+async def test_get_paths_for_model_merges_prefixed_and_unprefixed_aliases(
+    patched_session: AsyncEngine,
+) -> None:
+    await mp._persist_provider_paths(7, [("deepseek-v4-pro", "generic")])
+    await mp._persist_provider_paths(
+        4, [("deepseek/deepseek-v4-pro", "openrouter:DeepSeek")]
+    )
+
+    short_paths = await mp.get_paths_for_model("deepseek-v4-pro")
+    prefixed_paths = await mp.get_paths_for_model("deepseek/deepseek-v4-pro")
+
+    assert short_paths == [
+        {"path": "generic"},
+        {"path": "openrouter:DeepSeek"},
+    ]
+    assert prefixed_paths == short_paths
+
+
+@pytest.mark.asyncio
+async def test_refresh_model_paths_skips_provider_without_db_id(
+    patched_session: AsyncEngine,
+) -> None:
+    provider = _FakeProvider(
+        provider_type="anthropic",
+        base_url="https://api.anthropic.com/v1",
+        models=[_model("claude-opus-4.6")],
+        db_id=None,
+    )
+    await mp.refresh_model_paths([provider])  # type: ignore[list-item]
+    assert await mp.get_all_model_paths() == []
+
+
+@pytest.mark.asyncio
+async def test_refresh_model_paths_isolates_provider_failure(
+    patched_session: AsyncEngine, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    good = _FakeProvider(
+        provider_type="anthropic",
+        base_url="https://api.anthropic.com/v1",
+        models=[_model("claude-opus-4.6")],
+        db_id=1,
+    )
+    bad = _FakeProvider(
+        provider_type="openrouter",
+        base_url="https://openrouter.ai/api/v1",
+        models=[_model("m", canonical_slug="a/m")],
+        db_id=2,
+    )
+
+    original = mp._collect_provider_paths
+
+    async def _maybe_fail(
+        upstream: Any, *args: Any, **kwargs: Any
+    ) -> list[tuple[str, str]]:
+        if upstream is bad:
+            raise RuntimeError("boom")
+        return await original(upstream, *args, **kwargs)  # type: ignore[arg-type]
+
+    monkeypatch.setattr(mp, "_collect_provider_paths", _maybe_fail)
+
+    await mp.refresh_model_paths([good, bad])  # type: ignore[list-item]
+    data = await mp.get_all_model_paths()
+    assert {row["id"] for row in data} == {"claude-opus-4.6"}
+
+
+# --------------------------------------------------------------------------- #
+# Endpoints
+# --------------------------------------------------------------------------- #
+
+
+def _make_model_paths_app() -> FastAPI:
+    app = FastAPI()
+    app.include_router(models_router)
+    return app
+
+
+def test_model_paths_endpoint_returns_all_paths(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def _fake_get_all_model_paths() -> list[dict[str, Any]]:
+        return [
+            {
+                "id": "claude-opus-4.6",
+                "paths": [
+                    {"path": "anthropic"},
+                    {"path": "openrouter:Anthropic"},
+                ],
+            }
+        ]
+
+    monkeypatch.setattr(mp, "get_all_model_paths", _fake_get_all_model_paths)
+
+    response = TestClient(_make_model_paths_app()).get("/v1/models/paths")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "data": [
+            {
+                "id": "claude-opus-4.6",
+                "paths": [
+                    {"path": "anthropic"},
+                    {"path": "openrouter:Anthropic"},
+                ],
+            }
+        ]
+    }
+
+
+def test_model_paths_for_model_endpoint_accepts_slash_model_id(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls: list[str] = []
+
+    async def _fake_get_paths_for_model(model_id: str) -> list[dict[str, Any]]:
+        calls.append(model_id)
+        return [{"path": "generic:Anthropic"}]
+
+    monkeypatch.setattr(mp, "get_paths_for_model", _fake_get_paths_for_model)
+
+    response = TestClient(_make_model_paths_app()).get(
+        "/v1/models/paths/model",
+        params={"model_id": "anthropic/claude-opus-4.6"},
+    )
+
+    assert response.status_code == 200
+    assert response.json() == {"data": [{"path": "generic:Anthropic"}]}
+    assert calls == ["anthropic/claude-opus-4.6"]

tests/unit/test_provider_slug_migration.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import sqlalchemy as sa
+
+_MIGRATION_PATH = (
+    Path(__file__).resolve().parents[2]
+    / "migrations"
+    / "versions"
+    / "c6d7e8f9a0b1_add_slug_to_upstream_providers.py"
+)
+_spec = importlib.util.spec_from_file_location("provider_slug_migration", _MIGRATION_PATH)
+assert _spec is not None and _spec.loader is not None
+migration = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(migration)
+
+
+def test_slug_migration_backfill_uses_api_safe_deterministic_slugs() -> None:
+    engine = sa.create_engine("sqlite:///:memory:")
+    with engine.begin() as conn:
+        conn.execute(
+            sa.text(
+                "CREATE TABLE upstream_providers ("
+                "id INTEGER PRIMARY KEY, "
+                "provider_type VARCHAR NOT NULL, "
+                "slug VARCHAR NULL"
+                ")"
+            )
+        )
+        conn.execute(
+            sa.text(
+                "INSERT INTO upstream_providers (id, provider_type, slug) VALUES "
+                "(1, 'OpenAI Compatible', NULL), "
+                "(2, 'OpenAI Compatible', ''), "
+                "(3, '123', NULL), "
+                "(4, 'x', NULL), "
+                "(5, 'anthropic', 'anthropic')"
+            )
+        )
+
+        migration._backfill_provider_slugs(conn)
+
+        rows = conn.execute(
+            sa.text("SELECT id, slug FROM upstream_providers ORDER BY id")
+        ).all()
+
+    assert rows == [
+        (1, "openai-compatible"),
+        (2, "openai-compatible-2"),
+        (3, "provider-123"),
+        (4, "x-provider"),
+        (5, "anthropic"),
+    ]

tests/unit/test_provider_slugs.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import pytest
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlmodel import SQLModel, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.admin import _get_upstream_provider_by_ref
+from routstr.core.db import UpstreamProviderRow
+from routstr.core.provider_slugs import (
+    allocate_unique_provider_slug,
+    provider_slug_base,
+)
+from routstr.upstream.helpers import _seed_providers_from_settings
+
+
+@pytest.mark.asyncio
+async def test_allocate_unique_provider_slug_is_deterministic_with_suffixes() -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    async with AsyncSession(engine) as session:
+        session.add(
+            UpstreamProviderRow(
+                slug="openai",
+                provider_type="openai",
+                base_url="https://api.openai.com/v1",
+                api_key="key-1",
+            )
+        )
+        await session.commit()
+
+        assert await allocate_unique_provider_slug(session, "openai") == "openai-2"
+        assert (
+            await allocate_unique_provider_slug(session, "openai", {"openai-2"})
+            == "openai-3"
+        )
+
+    await engine.dispose()
+
+
+def test_provider_slug_base_sanitizes_provider_type() -> None:
+    assert provider_slug_base("OpenAI Compatible") == "openai-compatible"
+    assert provider_slug_base("!!!") == "provider"
+    assert provider_slug_base("AI") == "ai-provider"
+    assert provider_slug_base("123") == "provider-123"
+
+
+@pytest.mark.asyncio
+async def test_provider_ref_lookup_accepts_existing_numeric_ids_and_slugs() -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    async with AsyncSession(engine) as session:
+        provider = UpstreamProviderRow(
+            slug="openai",
+            provider_type="openai",
+            base_url="https://api.openai.com/v1",
+            api_key="key-1",
+        )
+        session.add(provider)
+        await session.commit()
+        await session.refresh(provider)
+
+        by_id = await _get_upstream_provider_by_ref(session, str(provider.id))
+        by_slug = await _get_upstream_provider_by_ref(session, "openai")
+
+    assert by_id.id == provider.id
+    assert by_slug.id == provider.id
+
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_seed_providers_from_settings_sets_deterministic_slug(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    monkeypatch.setenv("OPENAI_API_KEY", "seeded-openai-key")
+
+    class SettingsStub:
+        chat_completions_api_version: str | None = None
+        upstream_base_url: str | None = None
+        upstream_api_key: str = ""
+
+    async with AsyncSession(engine) as session:
+        await _seed_providers_from_settings(session, SettingsStub())  # type: ignore[arg-type]
+        await session.commit()
+
+        result = await session.exec(select(UpstreamProviderRow))
+        providers: list[UpstreamProviderRow] = list(result.all())
+
+    assert [(p.provider_type, p.slug) for p in providers] == [("openai", "openai")]
+
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_seed_providers_from_settings_keeps_slug_stable_on_reseed(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    monkeypatch.setenv("OPENAI_API_KEY", "seeded-openai-key")
+
+    class SettingsStub:
+        chat_completions_api_version: str | None = None
+        upstream_base_url: str | None = None
+        upstream_api_key: str = ""
+
+    async with AsyncSession(engine) as session:
+        session.add(
+            UpstreamProviderRow(
+                slug="openai",
+                provider_type="openai",
+                base_url="https://example.invalid/v1",
+                api_key="other-key",
+            )
+        )
+        await session.commit()
+
+        await _seed_providers_from_settings(session, SettingsStub())  # type: ignore[arg-type]
+        await session.commit()
+        await _seed_providers_from_settings(session, SettingsStub())  # type: ignore[arg-type]
+        await session.commit()
+
+        result = await session.exec(
+            select(UpstreamProviderRow).order_by(UpstreamProviderRow.slug)
+        )
+        providers: list[UpstreamProviderRow] = list(result.all())
+
+    assert [(p.provider_type, p.slug) for p in providers] == [
+        ("openai", "openai"),
+        ("openai", "openai-2"),
+    ]
+
+    await engine.dispose()

tests/unit/test_require_parameters.py

@@ -0,0 +1,95 @@
+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_streaming_sse_providers.py

@@ -337,3 +337,75 @@ async def test_multiline_non_json_data_each_line_prefixed() -> None:
             continue
         assert line.startswith(b"data: "), f"bare line leaked to client: {line!r}"
     assert b"data: line one" in blob and b"data: line two" in blob
+
+
+@pytest.mark.asyncio
+async def test_crlf_delimiter_split_across_chunk_boundary() -> None:
+    """CRLF event delimiter straddling two TCP reads must not merge events.
+
+    Regression: a per-chunk ``replace(b"\\r\\n", b"\\n")`` left a stray ``\\r``
+    when a ``\\r\\n`` of the ``\\r\\n\\r\\n`` delimiter landed at the very end of
+    one ``aiter_bytes`` chunk and the matching ``\\n`` opened the next. The
+    ``\\n\\n`` split then missed the boundary, glued two events into one frame
+    with two ``data:`` lines, and the client's ``JSON.parse`` threw on the
+    concatenated payload (the "unexpected token"/"Extra data" crash).
+    """
+    e1 = b'data: {"id":"x","choices":[{"delta":{"content":"a"}}]}'
+    e2 = b'data: {"id":"x","choices":[{"delta":{"content":"b"}}]}'
+    chunks = [
+        e1 + b"\r\n\r",  # delimiter cut mid-CRLF
+        b"\n" + e2 + b"\r\n\r\n",
+        b"data: [DONE]\r\n\r\n",
+    ]
+    out = await _drive(chunks)
+
+    # Client-accurate check: a real SSE client concatenates all ``data:`` lines
+    # *within one event* (events are ``\n\n``-delimited) before parsing. A
+    # merged frame would surface here as two objects glued into one payload,
+    # which ``_assert_clean`` (per-line) would miss.
+    blob = b"".join(out)
+    contents: list[str] = []
+    for event in blob.split(b"\n\n"):
+        datas = [
+            ln[len(b"data: ") :]
+            for ln in event.split(b"\n")
+            if ln.startswith(b"data: ")
+        ]
+        if not datas:
+            continue
+        payload = b"".join(datas)
+        if payload.strip() == b"[DONE]":
+            continue
+        obj = json.loads(payload)  # raises if two events were merged into one
+        for c in obj.get("choices", []):
+            if "delta" in c:
+                contents.append(c["delta"]["content"])
+    assert contents == ["a", "b"]
+
+
+@pytest.mark.asyncio
+async def test_truncated_json_tail_on_connection_close() -> None:
+    """A stream that drops mid-event must not emit the partial JSON downstream.
+
+    Regression: the end-of-stream flush ran ``_process_event`` on the leftover
+    buffer unconditionally. When the upstream connection closed mid-event the
+    leftover was incomplete JSON, which fell through to the raw-forward path and
+    handed the client a ``data: {partial`` frame -> ``Unterminated string`` parse
+    error. The truncated tail must be dropped instead.
+    """
+    chunks = [
+        b'data: {"id":"x","choices":[{"delta":{"content":"ok"}}]}\n\n',
+        b'data: {"id":"x","choices":[{"delta":{"con',  # connection dies here
+    ]
+    out = await _drive(chunks)
+    objs = _assert_clean(out)  # raises if the partial tail leaked as a data frame
+    contents = [
+        c["delta"]["content"]
+        for o in objs
+        for c in o.get("choices", [])
+        if "delta" in c
+    ]
+    # The one complete chunk is delivered; the truncated fragment is dropped
+    # entirely (no second delta), and _assert_clean above guarantees nothing
+    # non-JSON ever reached the client.
+    assert contents == ["ok"]

tests/unit/test_upstream_rate_limit.py

@@ -0,0 +1,396 @@
+"""Tests for upstream rate-limit detection, classification, and org-ID redaction.
+
+Covers issue #555: upstream OpenAI-compatible providers return rate-limit
+errors that embed a sensitive organization ID. The proxy must classify these
+distinctly (``UPSTREAM_RATE_LIMIT``), preserve useful debugging fields, and
+never emit a raw ``org-*`` identifier in logs, errors, or returned bodies.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, Mock, patch
+
+import httpx
+import pytest
+
+from routstr.core.redaction import redact_org_ids
+from routstr.upstream.base import BaseUpstreamProvider
+from routstr.upstream.rate_limit import (
+    UPSTREAM_RATE_LIMIT,
+    RateLimitInfo,
+    classify_rate_limit,
+)
+
+# The exact scenario from the issue, with a realistic (fake) org identifier.
+RAW_ORG_ID = "org-abc123XYZ456def"
+RATE_LIMIT_MESSAGE = (
+    f"Rate limit reached for gpt-5.5-2026-04-23 (for limit gpt-5.5) in "
+    f"organization {RAW_ORG_ID} on tokens per min (TPM): Limit 180000000, "
+    f"Used 180000000, Requested 8929. Please try again in 2ms. Visit "
+    f"https://platform.openai.com/account/rate-limits to learn more."
+)
+
+
+def _make_request(request_id: str = "req-123") -> Mock:
+    request = Mock(spec=["method", "state"])
+    request.method = "POST"
+    request.state = Mock()
+    request.state.request_id = request_id
+    return request
+
+
+def _make_upstream_response(
+    *,
+    body: bytes,
+    status_code: int = 429,
+    content_type: str | None = "application/json",
+    extra_headers: dict[str, str] | None = None,
+) -> httpx.Response:
+    headers: dict[str, str] = {}
+    if content_type is not None:
+        headers["content-type"] = content_type
+    if extra_headers:
+        headers.update(extra_headers)
+    return httpx.Response(status_code=status_code, headers=headers, content=body)
+
+
+@pytest.fixture
+def provider() -> BaseUpstreamProvider:
+    return BaseUpstreamProvider(
+        base_url="https://privateprovider.xyz", api_key="k", provider_fee=1.0
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Redaction
+# --------------------------------------------------------------------------- #
+
+
+def test_redact_org_ids_replaces_identifier() -> None:
+    assert RAW_ORG_ID not in redact_org_ids(RATE_LIMIT_MESSAGE)
+    assert "org-[REDACTED]" in redact_org_ids(RATE_LIMIT_MESSAGE)
+
+
+def test_redact_org_ids_is_idempotent() -> None:
+    once = redact_org_ids(RATE_LIMIT_MESSAGE)
+    assert redact_org_ids(once) == once
+
+
+def test_redact_org_ids_leaves_unrelated_text() -> None:
+    assert redact_org_ids("organize the org-chart") == "organize the org-chart"
+    assert redact_org_ids("") == ""
+
+
+# --------------------------------------------------------------------------- #
+# Classification
+# --------------------------------------------------------------------------- #
+
+
+def test_classify_exact_scenario() -> None:
+    info = classify_rate_limit(429, RATE_LIMIT_MESSAGE)
+    assert isinstance(info, RateLimitInfo)
+    assert info.code == UPSTREAM_RATE_LIMIT
+    assert info.model == "gpt-5.5-2026-04-23"
+    assert info.limit_name == "gpt-5.5"
+    assert info.metric == "tokens per min (TPM)"
+    assert info.limit == 180000000
+    assert info.used == 180000000
+    assert info.requested == 8929
+    assert info.retry_after_seconds == pytest.approx(0.002)
+    # Redaction-safe: no raw org id survives into the structured view.
+    assert RAW_ORG_ID not in info.message
+    assert RAW_ORG_ID not in json.dumps(info.as_details())
+
+
+def test_classify_by_status_code_without_marker() -> None:
+    info = classify_rate_limit(429, "slow down")
+    assert info is not None
+    assert info.code == UPSTREAM_RATE_LIMIT
+
+
+def test_classify_by_message_marker_without_429() -> None:
+    info = classify_rate_limit(400, "rate_limit_exceeded for this key")
+    assert info is not None
+
+
+def test_retry_after_header_takes_precedence() -> None:
+    info = classify_rate_limit(429, RATE_LIMIT_MESSAGE, {"Retry-After": "12"})
+    assert info is not None
+    assert info.retry_after_seconds == pytest.approx(12.0)
+
+
+def test_non_rate_limit_error_is_not_classified() -> None:
+    assert classify_rate_limit(400, "invalid request: missing field 'model'") is None
+    assert classify_rate_limit(500, "internal server error") is None
+
+
+# --------------------------------------------------------------------------- #
+# forward_upstream_error_response integration
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_json_rate_limit_body_is_redacted_and_forwarded(
+    provider: BaseUpstreamProvider,
+) -> None:
+    body = json.dumps(
+        {"error": {"message": RATE_LIMIT_MESSAGE, "type": "rate_limit_exceeded"}}
+    ).encode()
+    upstream = _make_upstream_response(body=body, status_code=429)
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/chat/completions", upstream
+    )
+
+    assert response.status_code == 429
+    raw = bytes(response.body).decode()
+    # No raw organization id may survive in the forwarded body.
+    assert RAW_ORG_ID not in raw
+    assert "org-[REDACTED]" in raw
+    # Body remains valid JSON; the original type is preserved while a stable
+    # rate-limit code is injected so callers can switch on it.
+    payload: dict[str, Any] = json.loads(raw)
+    assert payload["error"]["type"] == "rate_limit_exceeded"
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    assert payload["error"]["details"]["model"] == "gpt-5.5-2026-04-23"
+    # A retry hint extracted from the message is surfaced as a header.
+    assert "retry-after" in {k.lower() for k in response.headers}
+
+
+@pytest.mark.asyncio
+async def test_non_json_rate_limit_envelope_uses_stable_code(
+    provider: BaseUpstreamProvider,
+) -> None:
+    upstream = _make_upstream_response(
+        body=RATE_LIMIT_MESSAGE.encode(),
+        status_code=429,
+        content_type="text/plain",
+    )
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/chat/completions", upstream
+    )
+
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    assert payload["error"]["details"]["model"] == "gpt-5.5-2026-04-23"
+    serialized = json.dumps(payload)
+    assert RAW_ORG_ID not in serialized
+    assert "org-[REDACTED]" in serialized
+
+
+@pytest.mark.asyncio
+async def test_non_rate_limit_json_error_unchanged(
+    provider: BaseUpstreamProvider,
+) -> None:
+    body = json.dumps(
+        {"error": {"message": "missing field 'model'", "type": "invalid_request"}}
+    ).encode()
+    upstream = _make_upstream_response(body=body, status_code=400)
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/chat/completions", upstream
+    )
+
+    assert response.status_code == 400
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "invalid_request"
+    assert "retry-after" not in {k.lower() for k in response.headers}
+
+
+# --------------------------------------------------------------------------- #
+# UpstreamError -> proxy response (preserves code/details/status)
+# --------------------------------------------------------------------------- #
+
+
+def test_create_upstream_error_response_preserves_structure() -> None:
+    from routstr.core.exceptions import UpstreamError
+    from routstr.payment.helpers import create_upstream_error_response
+
+    info = classify_rate_limit(429, RATE_LIMIT_MESSAGE)
+    assert info is not None
+    err = UpstreamError(
+        f"Upstream error via litellm: {RATE_LIMIT_MESSAGE}",
+        status_code=429,
+        code=info.code,
+        details=info.as_details(),
+    )
+
+    response = create_upstream_error_response(err, _make_request())
+
+    # Original upstream status is preserved (not flattened to 502).
+    assert response.status_code == 429
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    assert payload["error"]["details"]["requested"] == 8929
+    serialized = json.dumps(payload)
+    assert RAW_ORG_ID not in serialized
+    assert "org-[REDACTED]" in serialized
+
+
+def test_generic_upstream_error_still_defaults_to_502() -> None:
+    from routstr.core.exceptions import UpstreamError
+    from routstr.payment.helpers import create_upstream_error_response
+
+    err = UpstreamError("connection refused")  # status_code defaults to 502
+
+    response = create_upstream_error_response(err, _make_request())
+
+    assert response.status_code == 502
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["code"] == 502
+    assert "details" not in payload["error"]
+
+
+# --------------------------------------------------------------------------- #
+# Structured log-extra redaction
+# --------------------------------------------------------------------------- #
+
+
+def test_security_filter_redacts_org_id_in_extra() -> None:
+    import logging
+
+    from routstr.core.logging import SecurityFilter
+
+    record = logging.LogRecord(
+        name="test",
+        level=logging.ERROR,
+        pathname=__file__,
+        lineno=1,
+        msg="upstream failed",
+        args=(),
+        exc_info=None,
+    )
+    # Simulate an ``extra={"body_preview": ...}`` field carrying an org id.
+    setattr(record, "body_preview", RATE_LIMIT_MESSAGE)
+
+    assert SecurityFilter().filter(record) is True
+    redacted: str = getattr(record, "body_preview")
+    assert RAW_ORG_ID not in redacted
+    assert "org-[REDACTED]" in redacted
+
+
+def test_security_filter_redacts_org_id_in_nested_extra() -> None:
+    import logging
+
+    from routstr.core.logging import SecurityFilter
+
+    record = logging.LogRecord(
+        name="test",
+        level=logging.ERROR,
+        pathname=__file__,
+        lineno=1,
+        msg="upstream failed",
+        args=(),
+        exc_info=None,
+    )
+    # Nested structures: dict containing a list containing the org id.
+    setattr(record, "body", {"error": {"messages": [RATE_LIMIT_MESSAGE]}})
+
+    assert SecurityFilter().filter(record) is True
+    serialized = json.dumps(getattr(record, "body"))
+    assert RAW_ORG_ID not in serialized
+    assert "org-[REDACTED]" in serialized
+
+
+# --------------------------------------------------------------------------- #
+# 5xx-wrapped rate limit through forward_upstream_error_response
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_5xx_wrapped_rate_limit_is_classified(
+    provider: BaseUpstreamProvider,
+) -> None:
+    # Some providers wrap a rate-limit in a 5xx envelope; classification must
+    # key off the message marker, not only the 429 status.
+    body = json.dumps({"error": {"message": RATE_LIMIT_MESSAGE}}).encode()
+    upstream = _make_upstream_response(body=body, status_code=500)
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/chat/completions", upstream
+    )
+
+    assert response.status_code == 500
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    serialized = json.dumps(payload)
+    assert RAW_ORG_ID not in serialized
+    assert "org-[REDACTED]" in serialized
+
+
+# --------------------------------------------------------------------------- #
+# Real proxy loop: structured error surfaced + reservation reverted once
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_proxy_loop_surfaces_rate_limit_and_reverts_once() -> None:
+    from routstr import proxy as proxy_module
+    from routstr.core.db import ApiKey
+    from routstr.core.exceptions import UpstreamError
+
+    info = classify_rate_limit(429, RATE_LIMIT_MESSAGE)
+    assert info is not None
+
+    key = ApiKey(hashed_key="rlkey", balance=10_000)
+
+    request = MagicMock()
+    request.method = "POST"
+    request.headers = {"authorization": "Bearer sk-rlkey"}
+    request.body = AsyncMock(return_value=b'{"model": "test-model"}')
+    request.state = MagicMock()
+    request.state.request_id = "req-rl"
+
+    upstream = MagicMock()
+    upstream.provider_type = "test"
+    upstream.prepare_headers = MagicMock(side_effect=lambda h: h)
+    upstream.forward_request = AsyncMock(
+        side_effect=UpstreamError(
+            f"Upstream error via litellm: {RATE_LIMIT_MESSAGE}",
+            status_code=429,
+            code=info.code,
+            details=info.as_details(),
+        )
+    )
+
+    session = MagicMock()
+    revert_mock = AsyncMock(return_value=True)
+
+    with (
+        patch.object(proxy_module, "get_model_instance", return_value=MagicMock()),
+        patch.object(proxy_module, "get_provider_for_model", return_value=[upstream]),
+        patch.object(
+            proxy_module, "get_max_cost_for_model", AsyncMock(return_value=1_000)
+        ),
+        patch.object(
+            proxy_module,
+            "calculate_discounted_max_cost",
+            AsyncMock(return_value=1_000),
+        ),
+        patch.object(proxy_module, "check_token_balance", MagicMock()),
+        patch.object(
+            proxy_module, "get_bearer_token_key", AsyncMock(return_value=key)
+        ),
+        patch.object(proxy_module, "pay_for_request", AsyncMock(return_value=1_000)),
+        patch.object(proxy_module, "revert_pay_for_request", revert_mock),
+    ):
+        response = await proxy_module.proxy(
+            request, "v1/chat/completions", session=session
+        )
+
+    # Original 429 status and the stable code/details survive to the client.
+    assert response.status_code == 429
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    assert payload["error"]["details"]["requested"] == 8929
+    serialized = json.dumps(payload)
+    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)

tests/unit/test_usage_normalization.py

@@ -0,0 +1,140 @@
+"""Tests for vendor-agnostic usage normalization.
+
+Specifies the seam that keeps vendor usage dialects out of generic billing
+code: a canonical ``NormalizedUsage`` shape produced by
+``routstr.payment.usage.normalize_usage`` (union parser for the known,
+non-colliding dialects). ``calculate_cost`` normalizes the response's usage
+object with this parser and needs no vendor knowledge of its own.
+"""
+
+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")
+
+import pytest
+
+from routstr.payment.usage import NormalizedUsage, normalize_usage
+
+# ============================================================================
+# The union parser: one canonical shape for all known dialects
+# ============================================================================
+
+
+@pytest.mark.parametrize(
+    "usage,expected",
+    [
+        # OpenAI: cached_tokens included in prompt_tokens → subtracted
+        (
+            {
+                "prompt_tokens": 2000,
+                "completion_tokens": 100,
+                "prompt_tokens_details": {"cached_tokens": 800},
+            },
+            NormalizedUsage(
+                input_tokens=1200,
+                output_tokens=100,
+                cache_read_tokens=800,
+                cache_write_tokens=0,
+            ),
+        ),
+        # DeepSeek: hit/miss fields, prompt_tokens = hit + miss → hit subtracted
+        (
+            {
+                "prompt_tokens": 10000,
+                "completion_tokens": 500,
+                "prompt_cache_hit_tokens": 9000,
+                "prompt_cache_miss_tokens": 1000,
+            },
+            NormalizedUsage(
+                input_tokens=1000,
+                output_tokens=500,
+                cache_read_tokens=9000,
+                cache_write_tokens=0,
+            ),
+        ),
+        # Anthropic: cache fields additive, input_tokens NOT reduced
+        (
+            {
+                "input_tokens": 300,
+                "output_tokens": 100,
+                "cache_read_input_tokens": 500,
+                "cache_creation_input_tokens": 2000,
+            },
+            NormalizedUsage(
+                input_tokens=300,
+                output_tokens=100,
+                cache_read_tokens=500,
+                cache_write_tokens=2000,
+            ),
+        ),
+        # Plain OpenAI without caching
+        (
+            {"prompt_tokens": 100, "completion_tokens": 50},
+            NormalizedUsage(input_tokens=100, output_tokens=50),
+        ),
+        # OpenRouter: cache writes nested as prompt_tokens_details.cache_write_tokens,
+        # both reads and writes included in prompt_tokens → both subtracted
+        (
+            {
+                "prompt_tokens": 10000,
+                "completion_tokens": 60,
+                "prompt_tokens_details": {
+                    "cached_tokens": 5000,
+                    "cache_write_tokens": 2000,
+                },
+            },
+            NormalizedUsage(
+                input_tokens=3000,
+                output_tokens=60,
+                cache_read_tokens=5000,
+                cache_write_tokens=2000,
+            ),
+        ),
+        # litellm-normalized Anthropic: prompt_tokens is the grand total and the
+        # write field is named cache_creation_tokens; top-level fields mirror it.
+        # prompt_tokens present → both subtracted (NOT additive like native).
+        (
+            {
+                "prompt_tokens": 10000,
+                "completion_tokens": 100,
+                "cache_read_input_tokens": 5000,
+                "cache_creation_input_tokens": 2000,
+                "prompt_tokens_details": {
+                    "cached_tokens": 5000,
+                    "cache_creation_tokens": 2000,
+                },
+            },
+            NormalizedUsage(
+                input_tokens=3000,
+                output_tokens=100,
+                cache_read_tokens=5000,
+                cache_write_tokens=2000,
+            ),
+        ),
+    ],
+)
+def test_normalize_usage_dialects(usage: dict, expected: NormalizedUsage) -> None:
+    """Each known vendor dialect maps onto the same canonical shape."""
+    assert normalize_usage(usage) == expected
+
+
+def test_normalize_usage_absent_usage() -> None:
+    """Missing/invalid usage yields None so callers can bill at max cost."""
+    assert normalize_usage(None) is None
+    assert normalize_usage("not a dict") is None  # type: ignore[arg-type]
+
+
+def test_normalize_usage_never_negative() -> None:
+    """Buggy upstreams reporting more cached than prompt tokens clamp to 0."""
+    result = normalize_usage(
+        {
+            "prompt_tokens": 100,
+            "completion_tokens": 50,
+            "prompt_cache_hit_tokens": 150,
+        }
+    )
+    assert result is not None
+    assert result.input_tokens == 0
+    assert result.cache_read_tokens == 150

tests/unit/test_wallet.py

@@ -150,6 +150,7 @@ async def test_credit_balance() -> None:
     mock_key.balance = 5000000
     mock_key.hashed_key = "test_hash"
     mock_session = AsyncMock()
+    mock_session.exec.return_value.rowcount = 1
 
     # Mock session.refresh to update the balance (simulates DB reload)
     async def mock_refresh(key: ApiKey) -> None:
@@ -206,9 +207,43 @@ async def test_credit_balance_rejects_zero_amount() -> None:
     assert not mock_session.commit.called
 
 
+@pytest.mark.asyncio
+async def test_credit_balance_rejects_missing_key() -> None:
+    """A top-up must fail if the key was pruned after redemption."""
+    token_data = {
+        "token": [{"mint": "http://mint:3338", "proofs": [{"amount": 1000}]}],
+        "unit": "sat",
+    }
+    token_json = json.dumps(token_data)
+    token_b64 = base64.urlsafe_b64encode(token_json.encode()).decode()
+    token_str = f"cashuA{token_b64}"
+
+    mock_key = Mock()
+    mock_key.balance = 0
+    mock_key.hashed_key = "test_hash"
+    mock_session = AsyncMock()
+    mock_session.exec.return_value.rowcount = 0
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "cashu_mints", ["http://mint:3338"]):
+        with patch(
+            "routstr.wallet.recieve_token",
+            return_value=(1000, "sat", "http://mint:3338"),
+        ):
+            with pytest.raises(ValueError, match="disappeared"):
+                await credit_balance(token_str, mock_key, mock_session)
+
+    # UPDATE matched nothing; committing would hide the failed credit.
+    assert mock_session.exec.called
+    assert not mock_session.commit.called
+
+
 @pytest.mark.asyncio
 async def test_swap_to_primary_mint_insufficient_for_fees() -> None:
-    """Token amount is less than melt_quote.amount + melt_quote.fee_reserve."""
+    """Token amount is less than melt_quote.amount + melt_quote.fee_reserve.
+    The quote mocks are static, so every retry observes the same shortfall —
+    the swap must still give up and raise."""
     from routstr.wallet import swap_to_primary_mint
 
     mock_token = Mock()
@@ -250,50 +285,6 @@ async def test_swap_to_primary_mint_insufficient_for_fees() -> None:
     mock_token_wallet.melt.assert_not_called()
 
 
-@pytest.mark.asyncio
-async def test_swap_to_primary_mint_melt_error_wrapped() -> None:
-    """Melt failure from cashu lib is wrapped as ValueError."""
-    from routstr.wallet import swap_to_primary_mint
-
-    mock_token = Mock()
-    mock_token.mint = "http://foreign:3338"
-    mock_token.unit = "sat"
-    mock_token.amount = 5000
-    mock_token.keysets = ["keyset1"]
-    mock_token.proofs = [{"amount": 5000}]
-
-    mock_token_wallet = Mock()
-    mock_token_wallet.load_mint = AsyncMock()
-    mock_token_wallet.load_proofs = AsyncMock()
-    mock_token_wallet.get_fees_for_proofs = Mock(return_value=0)
-
-    mock_primary_wallet = Mock()
-    mock_primary_wallet.load_mint = AsyncMock()
-    mock_primary_wallet.load_proofs = AsyncMock()
-
-    mock_mint_quote = Mock()
-    mock_mint_quote.quote = "mint_quote_456"
-    mock_mint_quote.request = "lnbc1..."
-    mock_primary_wallet.request_mint = AsyncMock(return_value=mock_mint_quote)
-
-    mock_melt_quote = Mock()
-    mock_melt_quote.quote = "melt_quote_456"
-    mock_melt_quote.amount = 4940
-    mock_melt_quote.fee_reserve = 50  # total 4990 < 5000, passes fee check
-    mock_token_wallet.melt_quote = AsyncMock(return_value=mock_melt_quote)
-    mock_token_wallet.melt = AsyncMock(
-        side_effect=Exception("Provided: 5000, needed: 5100 (Code: 11000)")
-    )
-
-    from routstr.core.settings import settings
-
-    with patch.object(settings, "primary_mint", "http://primary:3338"):
-        with patch.object(settings, "primary_mint_unit", "sat"):
-            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
-                with pytest.raises(ValueError, match="Failed to melt token"):
-                    await swap_to_primary_mint(mock_token, mock_token_wallet)
-
-
 @pytest.mark.asyncio
 async def test_recieve_token_untrusted_mint() -> None:
     mock_wallet = Mock()
@@ -361,54 +352,80 @@ async def test_swap_to_primary_mint_already_on_primary() -> None:
     mock_token_wallet.melt_quote.assert_not_called()
 
 
-async def test_swap_to_primary_mint_success() -> None:
-    """Test successful swap with dynamic fee calculation."""
-    from routstr.wallet import swap_to_primary_mint
+# ---------------------------------------------------------------------------
+# Swap fee estimation and reactive retry
+#
+# Spec: the estimation pass subtracts only observed fees (no safety buffer).
+# swap_to_primary_mint then runs the mint-quote/melt-quote/melt cycle and, when
+# the foreign mint demands more than estimated (at quote or at melt time),
+# retries with the amount recomputed from the observed fee — at most 3 attempts.
+# Melt failures unrelated to fees are not retried.
+# ---------------------------------------------------------------------------
 
+
+def _make_swap_mocks(
+    token_amount: int,
+    fee_reserves: list[int],
+    input_fees: int = 0,
+    mint_url: str = "http://foreign-mint:3338",
+) -> tuple[Mock, Mock, Mock]:
+    """Return (token, token_wallet, primary_wallet) mocks that act like a mint.
+
+    Mint quotes pass the requested amount through their ``request`` field and
+    melt quotes echo that amount back, so the mocks stay consistent for
+    whatever amounts the implementation requests. ``fee_reserves`` supplies the
+    fee_reserve of each successive melt quote (the first serves the estimation
+    pass); requesting more quotes than provided fails the test.
+    """
     mock_token = Mock()
-    mock_token.mint = "http://foreign:3338"
+    mock_token.mint = mint_url
     mock_token.unit = "sat"
-    mock_token.amount = 1000
+    mock_token.amount = token_amount
     mock_token.keysets = ["keyset1"]
-    mock_token.proofs = [{"amount": 1000}]
+    mock_token.proofs = [Mock(amount=token_amount)]
 
     mock_token_wallet = Mock()
     mock_token_wallet.load_mint = AsyncMock()
     mock_token_wallet.load_proofs = AsyncMock()
-    mock_token_wallet.get_fees_for_proofs = Mock(return_value=0)
+    mock_token_wallet.get_fees_for_proofs = Mock(return_value=input_fees)
 
     mock_primary_wallet = Mock()
     mock_primary_wallet.load_mint = AsyncMock()
     mock_primary_wallet.load_proofs = AsyncMock()
+    mock_primary_wallet.available_balance = Mock(amount=0)
+    mock_primary_wallet.mint = AsyncMock(return_value=Mock())
 
-    # Mocks for the estimation phase
-    # 1. request_mint(dummy_amount=1000) -> invoice_dummy
-    # 2. melt_quote(invoice_dummy) -> fee=10
+    fees = iter(fee_reserves)
 
-    # Mocks for the execution phase
-    # 3. request_mint(minted_amount=990) -> invoice_real
-    # 4. melt_quote(invoice_real) -> amount=990, fee=10
-    # 5. melt() -> success
-    # 6. mint() -> success
+    def _next_fee() -> int:
+        try:
+            return next(fees)
+        except StopIteration:
+            raise AssertionError(
+                "more melt quotes requested than fee_reserves provided"
+            ) from None
 
-    mock_mint_quote_dummy = Mock(quote="dummy_quote", request="lnbc_dummy")
-    mock_mint_quote_real = Mock(quote="real_quote", request="lnbc_real")
-
-    # side_effect for request_mint to return dummy then real
     mock_primary_wallet.request_mint = AsyncMock(
-        side_effect=[mock_mint_quote_dummy, mock_mint_quote_real]
+        side_effect=lambda amount: Mock(quote=f"mint_quote_{amount}", request=amount)
     )
-
-    mock_melt_quote_dummy = Mock(amount=1000, fee_reserve=10)
-    mock_melt_quote_real = Mock(amount=990, fee_reserve=10)
-
-    # side_effect for melt_quote
     mock_token_wallet.melt_quote = AsyncMock(
-        side_effect=[mock_melt_quote_dummy, mock_melt_quote_real]
+        side_effect=lambda invoice: Mock(
+            quote=f"melt_quote_{invoice}", amount=invoice, fee_reserve=_next_fee()
+        )
     )
+    mock_token_wallet.melt = AsyncMock(return_value=Mock())
 
-    mock_token_wallet.melt = AsyncMock(return_value="melted_proofs")
-    mock_primary_wallet.mint = AsyncMock(return_value="minted_proofs")
+    return mock_token, mock_token_wallet, mock_primary_wallet
+
+
+@pytest.mark.asyncio
+async def test_swap_to_primary_mint_success() -> None:
+    """No retry needed: real quote matches the estimate, full net amount minted."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[10, 10]
+    )
 
     from routstr.core.settings import settings
 
@@ -419,17 +436,659 @@ async def test_swap_to_primary_mint_success() -> None:
                     mock_token, mock_token_wallet
                 )
 
-                assert amount == 990  # 1000 - 10
-                assert unit == "sat"
-                assert mint == "http://primary:3338"
+    assert amount == 990  # 1000 - fee_reserve(10), no buffer subtracted
+    assert unit == "sat"
+    assert mint == "http://primary:3338"
+    assert mock_primary_wallet.request_mint.call_count == 2
+    mock_primary_wallet.request_mint.assert_any_call(1000)
+    mock_primary_wallet.request_mint.assert_any_call(990)
+    assert mock_token_wallet.melt_quote.call_count == 2
+    assert mock_token_wallet.melt.call_count == 1
+    assert mock_primary_wallet.mint.called
 
-                # Verify call order/counts
-                assert mock_primary_wallet.request_mint.call_count == 2
-                # First call with full amount for estimation
-                mock_primary_wallet.request_mint.assert_any_call(1000)
-                # Second call with calculated amount
-                mock_primary_wallet.request_mint.assert_any_call(990)
 
-                assert mock_token_wallet.melt_quote.call_count == 2
-                assert mock_token_wallet.melt.called
-                assert mock_primary_wallet.mint.called
+@pytest.mark.asyncio
+@pytest.mark.parametrize("fee_reserve", [1, 10, 100])
+async def test_calculate_swap_amount_subtracts_only_observed_fees(
+    fee_reserve: int,
+) -> None:
+    """Estimation: minted_amount = token - fee_reserve, with no safety buffer."""
+    from routstr.wallet import _calculate_swap_amount
+
+    _, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[fee_reserve]
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            result = await _calculate_swap_amount(
+                amount_msat=1_000_000,
+                token_unit="sat",
+                token_mint_url="http://foreign-mint:3338",
+                token_wallet=mock_token_wallet,
+                primary_wallet=mock_primary_wallet,
+                proofs=[],
+            )
+
+    assert result == 1000 - fee_reserve
+
+
+@pytest.mark.asyncio
+async def test_calculate_swap_amount_includes_input_fees() -> None:
+    """Estimation subtracts NUT-02 input fees alongside the melt fee_reserve."""
+    from routstr.wallet import _calculate_swap_amount
+
+    _, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        500, fee_reserves=[10], input_fees=3
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            result = await _calculate_swap_amount(
+                amount_msat=500_000,
+                token_unit="sat",
+                token_mint_url="http://foreign-mint:3338",
+                token_wallet=mock_token_wallet,
+                primary_wallet=mock_primary_wallet,
+                proofs=[],
+            )
+
+    assert result == 487  # 500 - 10 - 3
+
+
+@pytest.mark.asyncio
+async def test_swap_retries_when_real_quote_exceeds_estimate() -> None:
+    """The real melt quote demands a higher fee than the estimate (20 → 23).
+    Instead of failing, the swap recomputes the amount from the observed fee
+    and re-quotes: 1000 - 23 = 977, which fits (977 + 23 <= 1000)."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[20, 23, 23]
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                amount, unit, mint = await swap_to_primary_mint(
+                    mock_token, mock_token_wallet
+                )
+
+    assert amount == 977
+    assert unit == "sat"
+    mock_primary_wallet.request_mint.assert_any_call(980)
+    mock_primary_wallet.request_mint.assert_any_call(977)
+    assert mock_token_wallet.melt_quote.call_count == 3  # estimation + 2 attempts
+    assert mock_token_wallet.melt.call_count == 1
+
+
+@pytest.mark.asyncio
+async def test_swap_retries_when_melt_demands_more_than_quoted() -> None:
+    """The mint.cubabitcoin.org incident: every quote reports fee_reserve=1,
+    but the mint demands 2 sats at melt time ("Provided: 179, needed: 180").
+    The swap must retry with a smaller invoice (177) so the second melt fits,
+    instead of failing the topup."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        179, fee_reserves=[1, 1, 1], mint_url="http://mint.cubabitcoin.org"
+    )
+    mock_token_wallet.melt.side_effect = [
+        Exception(
+            "Mint Error: not enough inputs provided for melt. "
+            "Provided: 179, needed: 180 (Code: 11000)"
+        ),
+        Mock(),
+    ]
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                amount, unit, mint = await swap_to_primary_mint(
+                    mock_token, mock_token_wallet
+                )
+
+    assert amount == 177  # 179 - 1 (estimate) - 1 (observed melt shortfall)
+    assert mock_token_wallet.melt.call_count == 2
+    mock_primary_wallet.request_mint.assert_any_call(178)
+    mock_primary_wallet.request_mint.assert_any_call(177)
+
+
+@pytest.mark.asyncio
+async def test_swap_retries_on_cdk_unbalanced_error() -> None:
+    """cdk-based mints report insufficient melt inputs as the registered code
+    11005 (TransactionUnbalanced) with their own message wording — no
+    Provided/needed amounts to parse. The retry must classify it by code and
+    fall back to shrinking by 1."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        179, fee_reserves=[1, 1, 1]
+    )
+    mock_token_wallet.melt.side_effect = [
+        Exception("Mint Error: Transaction unbalanced: 179, 178, 2 (Code: 11005)"),
+        Mock(),
+    ]
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                amount, unit, mint = await swap_to_primary_mint(
+                    mock_token, mock_token_wallet
+                )
+
+    assert amount == 177
+    assert mock_token_wallet.melt.call_count == 2
+
+
+@pytest.mark.asyncio
+async def test_swap_quote_retries_exhausted() -> None:
+    """A mint that escalates fee_reserve on every re-quote exhausts the retry
+    budget (3 attempts) and fails cleanly; melt is never executed."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[1, 10, 25, 50]
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                with pytest.raises(ValueError, match="insufficient to cover melt fees"):
+                    await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+    assert mock_token_wallet.melt_quote.call_count == 4  # estimation + 3 attempts
+    mock_token_wallet.melt.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_swap_melt_retries_exhausted() -> None:
+    """A mint that always demands more at melt time than it quoted exhausts
+    the retry budget; the last melt failure is wrapped as ValueError."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        5000, fee_reserves=[50, 50, 50, 50]
+    )
+    mock_token_wallet.melt = AsyncMock(
+        side_effect=Exception(
+            "Mint Error: not enough inputs provided for melt. "
+            "Provided: 5000, needed: 5200 (Code: 11000)"
+        )
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                with pytest.raises(ValueError, match="Failed to melt token"):
+                    await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+    assert mock_token_wallet.melt.call_count == 3
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "primary_unit,token_unit,amount_msat,fees,expected",
+    [
+        ("sat", "sat", 179_000, 2, 177),
+        ("msat", "sat", 179_000, 2, 177_000),
+        ("sat", "msat", 179_000, 2_000, 177),
+    ],
+)
+async def test_net_minted_amount_unit_conversions(
+    primary_unit: str, token_unit: str, amount_msat: int, fees: int, expected: int
+) -> None:
+    """Fee subtraction converts correctly between sat and msat on either side."""
+    from routstr.core.settings import settings
+    from routstr.wallet import _net_minted_amount
+
+    with patch.object(settings, "primary_mint_unit", primary_unit):
+        assert _net_minted_amount(amount_msat, token_unit, fees) == expected
+
+
+@pytest.mark.parametrize(
+    "message,expected",
+    [
+        # nutshell: retryable with exact shortfall from the detail text
+        (
+            "Mint Error: not enough inputs provided for melt. "
+            "Provided: 179, needed: 182 (Code: 11000)",
+            3,
+        ),
+        # verbatim production error from issue #468, including cashu-py's
+        # "could not pay invoice" wrapper around the mint detail
+        (
+            "could not pay invoice: Mint Error: not enough inputs provided "
+            "for melt. Provided: 179, needed: 180 (Code: 11000)",
+            1,
+        ),
+        # cdk: registered TransactionUnbalanced code, no parsable amounts
+        ("Mint Error: Transaction unbalanced: 179, 178, 2 (Code: 11005)", 1),
+        # nutshell wording without a code suffix
+        ("not enough inputs provided for melt", 1),
+        # nonsensical amounts (needed <= provided) fall back to the minimal step
+        (
+            "Mint Error: not enough inputs provided for melt. "
+            "Provided: 180, needed: 179 (Code: 11000)",
+            1,
+        ),
+        # a generic 11000 without the shortfall text is not a fee shortfall:
+        # 11000 is nutshell's catch-all TransactionError, so retrying (shrinking
+        # the invoice) would never help and only masks the real error
+        ("Mint Error: Duplicate inputs provided. (Code: 11000)", None),
+        # spent proofs must never be retried: the funds are gone
+        ("Mint Error: Token already spent. (Code: 11001)", None),
+        # Lightning failures must never be retried: a smaller invoice won't help
+        ("Mint Error: Lightning payment failed. (Code: 20004)", None),
+        # unrecognizable errors (timeouts, bugs) must never be retried
+        ("Connection timeout", None),
+    ],
+)
+def test_melt_shortfall_classifier(message: str, expected: int | None) -> None:
+    """Retry classification across mint implementations and failure classes."""
+    from routstr.wallet import _melt_insufficient_shortfall
+
+    assert _melt_insufficient_shortfall(Exception(message)) == expected
+
+
+@pytest.mark.asyncio
+async def test_calculate_swap_amount_same_mint_short_circuit() -> None:
+    """When the token is already on the primary mint no fees apply and no
+    quotes are requested."""
+    from routstr.wallet import _calculate_swap_amount
+
+    _, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[]
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            result = await _calculate_swap_amount(
+                amount_msat=1_000_000,
+                token_unit="sat",
+                token_mint_url="http://primary:3338",
+                token_wallet=mock_token_wallet,
+                primary_wallet=mock_primary_wallet,
+                proofs=[],
+            )
+
+    assert result == 1000
+    mock_primary_wallet.request_mint.assert_not_called()
+    mock_token_wallet.melt_quote.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_calculate_swap_amount_msat_primary_unit() -> None:
+    """With an msat primary mint the dummy quote and result stay in msats."""
+    from routstr.wallet import _calculate_swap_amount
+
+    _, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        179, fee_reserves=[2]
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "msat"):
+            result = await _calculate_swap_amount(
+                amount_msat=179_000,
+                token_unit="sat",
+                token_mint_url="http://foreign-mint:3338",
+                token_wallet=mock_token_wallet,
+                primary_wallet=mock_primary_wallet,
+                proofs=[],
+            )
+
+    assert result == 177_000  # 179_000 msat - 2 sat fee
+    mock_primary_wallet.request_mint.assert_called_once_with(179_000)
+
+
+@pytest.mark.asyncio
+async def test_calculate_swap_amount_fees_exceed_token() -> None:
+    """Fees larger than the token itself fail fast, before any melt."""
+    from routstr.wallet import _calculate_swap_amount
+
+    _, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        179, fee_reserves=[200]
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with pytest.raises(ValueError, match="exceed token amount"):
+                await _calculate_swap_amount(
+                    amount_msat=179_000,
+                    token_unit="sat",
+                    token_mint_url="http://foreign-mint:3338",
+                    token_wallet=mock_token_wallet,
+                    primary_wallet=mock_primary_wallet,
+                    proofs=[],
+                )
+
+
+@pytest.mark.asyncio
+async def test_calculate_swap_amount_wraps_estimation_failure() -> None:
+    """Estimation infrastructure failures surface as a single clear ValueError."""
+    from routstr.wallet import _calculate_swap_amount
+
+    _, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        179, fee_reserves=[]
+    )
+    mock_primary_wallet.request_mint = AsyncMock(
+        side_effect=Exception("mint offline")
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with pytest.raises(ValueError, match="Failed to estimate fees"):
+                await _calculate_swap_amount(
+                    amount_msat=179_000,
+                    token_unit="sat",
+                    token_mint_url="http://foreign-mint:3338",
+                    token_wallet=mock_token_wallet,
+                    primary_wallet=mock_primary_wallet,
+                    proofs=[],
+                )
+
+
+@pytest.mark.asyncio
+async def test_swap_coerces_non_integer_amount() -> None:
+    """Token amounts arriving as floats are coerced before any arithmetic."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[10, 10]
+    )
+    mock_token.amount = 1000.0
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                amount, unit, mint = await swap_to_primary_mint(
+                    mock_token, mock_token_wallet
+                )
+
+    assert amount == 990
+    assert isinstance(amount, int)
+
+
+@pytest.mark.asyncio
+async def test_swap_rejects_unknown_unit() -> None:
+    """Units other than sat/msat are rejected before any quote is requested."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[]
+    )
+    mock_token.unit = "usd"
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                with pytest.raises(ValueError, match="Invalid unit"):
+                    await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+    mock_primary_wallet.request_mint.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_swap_msat_token_already_on_primary() -> None:
+    """msat-denominated tokens on the primary mint short-circuit unchanged."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, _ = _make_swap_mocks(
+        179_000, fee_reserves=[], mint_url="http://primary:3338"
+    )
+    mock_token.unit = "msat"
+    mock_token_wallet.split = AsyncMock()
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_token_wallet):
+                amount, unit, mint = await swap_to_primary_mint(
+                    mock_token, mock_token_wallet
+                )
+
+    assert (amount, unit, mint) == (179_000, "msat", "http://primary:3338")
+
+
+# ---------------------------------------------------------------------------
+# Mint-on-primary failure handling after a successful melt
+#
+# At this point the foreign proofs are already spent: failures here mean funds
+# are in limbo, so errors must propagate (never be swallowed) and recovery must
+# never credit proofs the wallet does not actually hold.
+# ---------------------------------------------------------------------------
+
+
+def _with_recovery_mocks(
+    mock_primary_wallet: Mock, mint_error: str, balances: list[int]
+) -> None:
+    """Make primary mint() fail and stage available_balance per load_proofs call."""
+    mock_primary_wallet.mint = AsyncMock(side_effect=Exception(mint_error))
+    mock_primary_wallet.keysets = ["keyset_primary"]
+    balance_iter = iter(balances)
+
+    def advance_balance(reload: bool = False) -> None:
+        mock_primary_wallet.available_balance = Mock(amount=next(balance_iter))
+
+    mock_primary_wallet.load_proofs = AsyncMock(side_effect=advance_balance)
+    mock_primary_wallet.restore_tokens_for_keyset = AsyncMock()
+
+
+@pytest.mark.asyncio
+async def test_swap_mint_failure_propagates_unwrapped() -> None:
+    """A non-recoverable mint failure after melt propagates as-is (a 500, not a
+    client error): the melt already spent the foreign proofs."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[10, 10]
+    )
+    _with_recovery_mocks(
+        mock_primary_wallet, "Mint Error: Quote is expired (Code: 20007)", [0]
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                with pytest.raises(Exception, match="Quote is expired") as exc_info:
+                    await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+    assert type(exc_info.value) is Exception  # original error, not wrapped
+    assert mock_token_wallet.melt.call_count == 1
+    mock_primary_wallet.restore_tokens_for_keyset.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_swap_recovers_orphaned_proofs_on_outputs_already_signed() -> None:
+    """11003 (outputs already signed): a recovery scan that restores the full
+    minted amount lets the swap complete normally."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[10, 10]
+    )
+    _with_recovery_mocks(
+        mock_primary_wallet,
+        "Mint Error: outputs already signed (Code: 11003)",
+        [0, 990],  # pre-mint balance, post-recovery balance
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                amount, unit, mint = await swap_to_primary_mint(
+                    mock_token, mock_token_wallet
+                )
+
+    assert amount == 990
+    mock_primary_wallet.restore_tokens_for_keyset.assert_awaited_once_with(
+        "keyset_primary", to=1, batch=25
+    )
+
+
+@pytest.mark.asyncio
+async def test_swap_recovery_shortfall_refuses_credit() -> None:
+    """When the recovery scan restores less than the minted amount, the swap
+    must fail rather than credit proofs the wallet does not hold."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[10, 10]
+    )
+    _with_recovery_mocks(
+        mock_primary_wallet,
+        "Mint Error: outputs already signed (Code: 11003)",
+        [0, 100],  # recovery restores only 100 of the expected 990
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                with pytest.raises(ValueError, match="Swap recovery failed"):
+                    await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+
+@pytest.mark.asyncio
+async def test_swap_recovery_failure_wrapped() -> None:
+    """When the recovery scan itself fails, the error is wrapped and raised —
+    never swallowed."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[10, 10]
+    )
+    _with_recovery_mocks(
+        mock_primary_wallet,
+        "Mint Error: outputs already signed (Code: 11003)",
+        [0],
+    )
+    mock_primary_wallet.restore_tokens_for_keyset = AsyncMock(
+        side_effect=Exception("wallet db locked")
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                with pytest.raises(ValueError, match="recovery unsuccessful"):
+                    await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+
+@pytest.mark.asyncio
+async def test_recieve_token_rejects_multiple_keysets() -> None:
+    """Multi-keyset tokens are rejected before touching any wallet."""
+    with patch("routstr.wallet.deserialize_token_from_string") as mock_deserialize:
+        mock_token = Mock()
+        mock_token.keysets = ["keyset1", "keyset2"]
+        mock_deserialize.return_value = mock_token
+
+        with pytest.raises(ValueError, match="Multiple keysets"):
+            await recieve_token("cashuAmultikeyset")
+
+
+@pytest.mark.asyncio
+async def test_credit_balance_msat_unit_not_converted() -> None:
+    """msat-denominated redemptions are credited as-is, without a 1000x."""
+    mock_key = Mock()
+    mock_key.balance = 0
+    mock_key.hashed_key = "test_hash"
+    mock_session = AsyncMock()
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "cashu_mints", ["http://mint:3338"]):
+        with patch(
+            "routstr.wallet.recieve_token",
+            return_value=(1_000_000, "msat", "http://mint:3338"),
+        ):
+            amount = await credit_balance("cashuAtest", mock_key, mock_session)
+
+    assert amount == 1_000_000
+    assert mock_session.commit.called
+
+
+@pytest.mark.asyncio
+async def test_credit_balance_survives_audit_store_failure() -> None:
+    """A failure writing the CashuTransaction history record must not undo the
+    already-committed balance credit. (The silent swallow is a known
+    audit-trail gap slated for its own fix — this test pins the financial
+    invariant that the user keeps their credit, not the swallow itself.)"""
+    mock_key = Mock()
+    mock_key.balance = 0
+    mock_key.hashed_key = "test_hash"
+    mock_session = AsyncMock()
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "cashu_mints", ["http://mint:3338"]):
+        with patch(
+            "routstr.wallet.recieve_token",
+            return_value=(1000, "sat", "http://mint:3338"),
+        ):
+            with patch(
+                "routstr.wallet.store_cashu_transaction",
+                side_effect=Exception("history table locked"),
+            ):
+                amount = await credit_balance("cashuAtest", mock_key, mock_session)
+
+    assert amount == 1_000_000
+    assert mock_session.commit.called
+
+
+@pytest.mark.asyncio
+async def test_swap_does_not_retry_on_payment_failure() -> None:
+    """Melt failures unrelated to fees (e.g. routing failure) are not retried:
+    a smaller invoice would not help, and the error must surface immediately."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token, mock_token_wallet, mock_primary_wallet = _make_swap_mocks(
+        1000, fee_reserves=[10, 10]
+    )
+    mock_token_wallet.melt = AsyncMock(
+        side_effect=Exception("Mint Error: Lightning payment failed. (Code: 20004)")
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                with pytest.raises(ValueError, match="Failed to melt token"):
+                    await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+    assert mock_token_wallet.melt.call_count == 1
+    assert mock_primary_wallet.request_mint.call_count == 2

ui/README.md

@@ -1,36 +1,44 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Routstr node admin UI
 
-## Getting Started
+A [Next.js](https://nextjs.org) app (App Router, **static export**) that provides the
+admin dashboard for a `routstr-core` node: login, settings, providers, balances,
+transactions, usage, and logs.
 
-First, run the development server:
+There is no separate web server in production. `next build` produces a fully static
+export (`next.config.ts` sets `output: 'export'`), and the FastAPI backend serves it
+directly from `../ui_out/` (see `routstr/core/main.py`). So the UI and the API are
+served from the **same origin** in production.
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
+## Developing the UI (hot reload)
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+The everyday loop runs two processes side by side — you do **not** rebuild the static
+export while developing:
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+1. Start the backend on `:8000` — from the repo root: `make docker-up` (or
+   `uvicorn routstr.core.main:app --reload`).
+2. Start the Next.js dev server on `:3000` — from the repo root: `make ui-dev`
+   (or `cd ui && pnpm dev`). Edits hot-reload instantly.
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+Open http://localhost:3000. With no `NEXT_PUBLIC_API_URL` set, the UI falls back to
+`http://127.0.0.1:8000` in development (see `lib/api/services/configuration.ts`), so it
+talks to the local backend out of the box.
 
-## Learn More
+Because dev is cross-origin (`:3000` → `:8000`), it relies on the backend's CORS
+allowing the UI origin. The default `cors_origins` is `["*"]`; if you tighten CORS,
+keep `http://localhost:3000` allowed for development.
 
-To learn more about Next.js, take a look at the following resources:
+## Building the integrated/static UI (what production serves)
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+To produce the bundle that FastAPI serves from `../ui_out/`:
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+- `make ui-build` — builds with local Node/pnpm (`scripts/build-ui.sh`), then moves
+  `ui/out/*` to `../ui_out/`.
+- `make ui-build-docker` — same, but inside Docker (no local Node needed).
 
-## Deploy on Vercel
+`NEXT_PUBLIC_*` variables are read from the repo-root `.env` at build time and baked in.
+For a same-origin deployment leave `NEXT_PUBLIC_API_URL` empty (relative paths); the UI
+uses `window.location.origin` at runtime. After building, start the backend and open
+http://localhost:8000 — the dashboard is served at `/` and `/admin`.
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+If `../ui_out/` does not exist, the backend logs a warning at startup and serves the API
+only (hitting a UI route returns a small JSON fallback instead of the dashboard).

ui/app/providers/page.tsx

@@ -297,16 +297,13 @@ export default function ProvidersPage() {
   };
 
   const toggleProviderExpansion = (providerId: number) => {
-    const newExpanded = new Set(expandedProviders);
-    if (newExpanded.has(providerId)) {
-      newExpanded.delete(providerId);
-    } else {
-      newExpanded.add(providerId);
-    }
-    setExpandedProviders(newExpanded);
-    if (!newExpanded.has(providerId)) {
+    if (expandedProviders.has(providerId)) {
+      setExpandedProviders(new Set());
       setViewingModels(null);
     } else {
+      // Accordion: only one provider open at a time so switching to another
+      // provider's models auto-collapses the previously expanded one.
+      setExpandedProviders(new Set([providerId]));
       setViewingModels(providerId);
     }
   };

ui/components/add-provider-model-dialog.tsx

@@ -68,6 +68,8 @@ const FormSchema = z.object({
   upstream_provider_id: z.string().default(''),
   input_cost: z.coerce.number().min(0).default(0),
   output_cost: z.coerce.number().min(0).default(0),
+  cache_read_cost: z.coerce.number().min(0).default(0),
+  cache_write_cost: z.coerce.number().min(0).default(0),
   request_cost: z.coerce.number().min(0).default(0),
   image_cost: z.coerce.number().min(0).default(0),
   web_search_cost: z.coerce.number().min(0).default(0),
@@ -125,6 +127,8 @@ export function AddProviderModelDialog({
       upstream_provider_id: '',
       input_cost: 0,
       output_cost: 0,
+      cache_read_cost: 0,
+      cache_write_cost: 0,
       request_cost: 0,
       image_cost: 0,
       web_search_cost: 0,
@@ -190,6 +194,8 @@ export function AddProviderModelDialog({
             : initialData.upstream_provider_id?.toString() || '',
         input_cost: pricing?.prompt ?? 0,
         output_cost: pricing?.completion ?? 0,
+        cache_read_cost: pricing?.input_cache_read ?? 0,
+        cache_write_cost: pricing?.input_cache_write ?? 0,
         request_cost: pricing?.request ?? 0,
         image_cost: pricing?.image ?? 0,
         web_search_cost: pricing?.web_search ?? 0,
@@ -231,6 +237,8 @@ export function AddProviderModelDialog({
         upstream_provider_id: '',
         input_cost: 0,
         output_cost: 0,
+        cache_read_cost: 0,
+        cache_write_cost: 0,
         request_cost: 0,
         image_cost: 0,
         web_search_cost: 0,
@@ -294,6 +302,8 @@ export function AddProviderModelDialog({
     );
     form.setValue('input_cost', pricing?.prompt ?? 0);
     form.setValue('output_cost', pricing?.completion ?? 0);
+    form.setValue('cache_read_cost', pricing?.input_cache_read ?? 0);
+    form.setValue('cache_write_cost', pricing?.input_cache_write ?? 0);
     form.setValue('request_cost', pricing?.request ?? 0);
     form.setValue('image_cost', pricing?.image ?? 0);
     form.setValue('web_search_cost', pricing?.web_search ?? 0);
@@ -365,6 +375,8 @@ export function AddProviderModelDialog({
         pricing: {
           prompt: data.input_cost,
           completion: data.output_cost,
+          input_cache_read: data.cache_read_cost,
+          input_cache_write: data.cache_write_cost,
           request: data.request_cost,
           image: data.image_cost,
           web_search: data.web_search_cost,
@@ -810,6 +822,38 @@ export function AddProviderModelDialog({
                     </FormItem>
                   )}
                 />
+                <FormField
+                  control={form.control}
+                  name='cache_read_cost'
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>Cache Read Cost</FormLabel>
+                      <FormControl>
+                        <Input type='number' step='0.000001' {...field} />
+                      </FormControl>
+                      <FormDescription>
+                        Discounted cached-input read price per 1M tokens.
+                      </FormDescription>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
+                <FormField
+                  control={form.control}
+                  name='cache_write_cost'
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>Cache Write Cost</FormLabel>
+                      <FormControl>
+                        <Input type='number' step='0.000001' {...field} />
+                      </FormControl>
+                      <FormDescription>
+                        Cached-input creation price per 1M tokens.
+                      </FormDescription>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
                 <FormField
                   control={form.control}
                   name='request_cost'

ui/components/provider-form-fields.tsx

@@ -118,6 +118,26 @@ export function ProviderFormFields({
         />
       )}
 
+      <div className='grid gap-2'>
+        <Label htmlFor={`${idPrefix}slug`}>
+          Slug {mode === 'create' ? '(optional, auto-generated)' : ''}
+        </Label>
+        <Input
+          id={`${idPrefix}slug`}
+          value={formData.slug || ''}
+          onChange={(e) =>
+            setFormData((prev) => ({
+              ...prev,
+              slug: e.target.value || undefined,
+            }))
+          }
+          placeholder='e.g. openai-prod'
+        />
+        <p className='text-muted-foreground text-xs'>
+          Stable external key used to update this provider via the admin API.
+        </p>
+      </div>
+
       <div className='grid gap-2'>
         <Label htmlFor={`${idPrefix}base_url`}>Base URL</Label>
         <Input

ui/lib/api/services/admin.ts

@@ -14,6 +14,7 @@ export const ProviderTypeSchema = z.object({
 
 export const UpstreamProviderSchema = z.object({
   id: z.number(),
+  slug: z.string().nullable().optional(),
   provider_type: z.string(),
   base_url: z.string(),
   api_key: z.string().optional(),
@@ -31,6 +32,7 @@ export const CreateUpstreamProviderSchema = z.object({
   enabled: z.boolean().default(true),
   provider_fee: z.number().optional(),
   provider_settings: z.record(z.string(), z.any()).nullable().optional(),
+  slug: z.string().optional(),
 });
 
 export const UpdateUpstreamProviderSchema = z.object({
@@ -41,6 +43,7 @@ export const UpdateUpstreamProviderSchema = z.object({
   enabled: z.boolean().optional(),
   provider_fee: z.number().optional(),
   provider_settings: z.record(z.string(), z.any()).nullable().optional(),
+  slug: z.string().optional(),
 });
 
 export const AdminModelPricingSchema = z.object({
@@ -50,6 +53,8 @@ export const AdminModelPricingSchema = z.object({
   image: z.number().optional(),
   web_search: z.number().optional(),
   internal_reasoning: z.number().optional(),
+  input_cache_read: z.number().optional(),
+  input_cache_write: z.number().optional(),
 });
 
 export const AdminModelArchitectureSchema = z.object({
@@ -146,7 +151,7 @@ export class AdminService {
     if (!pricing) return pricing;
     const result = { ...pricing };
 
-    // Only prompt and completion are per-token and need scaling to per-1M
+    // Token-priced fields are stored per-token by the API and shown per-1M in the UI.
     const convertField = (field: string) => {
       const val = result[field];
       if (val !== undefined && val !== null) {
@@ -161,6 +166,8 @@ export class AdminService {
 
     convertField('prompt');
     convertField('completion');
+    convertField('input_cache_read');
+    convertField('input_cache_write');
 
     // Other fields (request, image, etc.) are already flat fees (per item)
     // so we do NOT scale them.
@@ -174,7 +181,7 @@ export class AdminService {
     if (!pricing) return pricing;
     const result = { ...pricing };
 
-    // Only prompt and completion are per-1M in UI and need scaling down to per-token
+    // Token-priced fields are per-1M in the UI and need scaling down to per-token.
     const convertField = (field: string) => {
       const val = result[field];
       if (val !== undefined && val !== null) {
@@ -187,6 +194,8 @@ export class AdminService {
 
     convertField('prompt');
     convertField('completion');
+    convertField('input_cache_read');
+    convertField('input_cache_write');
 
     // Other fields stay as flat fees