Merge branch 'main' into fix/mint-rate-limit-and-fallback

Fix payout safety and proxy session lifecycle

.env.example

@@ -2,21 +2,51 @@
 UPSTREAM_BASE_URL=https://api.openai.com/v1
 UPSTREAM_API_KEY=your-upstream-api-key
 
-# ADMIN_PASSWORD=secure-admin-password
+# Tinfoil (confidential inference enclaves, EHBP)
+# TINFOIL_API_KEY=your-tinfoil-api-key
+
+# Secret key used to encrypt node secrets at rest (optional). If unset, the node
+# generates one on first start, writes it to routstr_secret.key (override the path
+# with ROUTSTR_SECRET_KEY_FILE), and prints it once — back that file up, because
+# losing the key makes previously encrypted secrets unreadable. Set it explicitly
+# to manage the key yourself (recommended in production). Generate one with:
+#   uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+ROUTSTR_SECRET_KEY=
+
+# The admin password and the Nostr identity (nsec) are NOT set here. The admin
+# password is generated and logged once on first start (read it from the logs to
+# sign in); both are managed afterwards from the admin UI and stored encrypted in
+# the database. ADMIN_PASSWORD / NSEC are still read once as a legacy seed for
+# existing deployments, but new nodes should set them in the UI — a value left in
+# .env is ignored once the node has been configured.
 
 # Database
 # DATABASE_URL=sqlite+aiosqlite:///keys.db
+# Pool controls are validated at boot, sourced only from the environment, and
+# logged at startup. Keep total capacity across all workers below the database
+# connection limit. Pre-ping is automatic for networked backends; SQLite may
+# explicitly opt in if desired.
+# DATABASE_POOL_SIZE=5
+# DATABASE_MAX_OVERFLOW=10
+# DATABASE_POOL_TIMEOUT=30
+# DATABASE_POOL_RECYCLE=1800
+# DATABASE_POOL_PRE_PING=false
+# Warn when a checkout is held this many seconds.
+# DATABASE_POOL_HOLD_WARN_SECONDS=10
+# SQLite serialises writes; increasing its pool can trade pool timeouts for
+# "database is locked" errors rather than increasing write throughput.
 
 # Node Information
 # NAME=My Routstr Node
 # DESCRIPTION=Fast AI API access with Bitcoin payments
-# NSEC=nsec1...
 # HTTP_URL=https://api.mynode.com
 # ONION_URL=http://mynode.onion (auto fetched from compose)
 # RELAYS="wss://relay.damus.io,wss://relay.nostr.band,wss://eden.nostr.land,wss://relay.routstr.com"
 # ENABLE_ANALYTICS_SHARING=true
 # CASHU_MINTS="https://mint.minibits.cash/Bitcoin,https://mint.cubabitcoin.org,https://ecashmint.otrta.me"
+# MINT_OPERATION_CONCURRENCY=4
 # RECEIVE_LN_ADDRESS=
+# REFUND_SWEEP_CLAIM_TIMEOUT_SECONDS=900
 
 # Custom Pricing Configuration
 # MODEL_BASED_PRICING=true

.gitignore

@@ -1,6 +1,7 @@
 __pycache__
 .env
 keys.db
+routstr_secret.key
 wallet.sqlite3
 
 # Python build artifacts
@@ -16,6 +17,9 @@ dist/
 *.db-shm
 *.db-wal
 .*wallet.sqlite3
+.wallet/
+AGENTS.md
+TEST_SUITE_OVERVIEW.md
 *models.json
 .cashu
 .relay
@@ -38,3 +42,4 @@ proof_backups
 
 *.todo
 ui_out
+.worktrees

Dockerfile

@@ -1,21 +1,20 @@
-FROM ghcr.io/astral-sh/uv:python3.11-alpine
+FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim
 
-# Install system dependencies required for secp256k1
-RUN apk add --no-cache \
-    pkgconf \
-    build-base \
-    automake \
-    autoconf \
-    libtool \
-    m4 \
-    perl
-RUN apk add git
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        git \
+        build-essential \
+        pkg-config \
+        libsecp256k1-dev \
+        autoconf \
+        automake \
+        libtool \
+    && rm -rf /var/lib/apt/lists/*
 
 COPY uv.lock pyproject.toml ./
 RUN mkdir -p /routstr
 
-RUN uv add git+https://github.com/saschanaz/secp256k1-py.git#branch=upgrade060
-# RUN uv sync
+RUN uv sync --frozen --no-dev --no-install-project
 
 WORKDIR /app
 

Dockerfile.full

@@ -4,10 +4,10 @@ FROM node:23-alpine AS ui-builder
 WORKDIR /app/ui
 
 # Install pnpm
-RUN corepack enable pnpm && corepack prepare pnpm@latest --activate
+RUN corepack enable pnpm && corepack prepare pnpm@10.15.0 --activate
 
 # Copy UI source
-COPY ui/package.json ui/pnpm-lock.yaml* ./
+COPY ui/package.json ui/pnpm-lock.yaml* ui/pnpm-workspace.yaml* ./
 RUN pnpm install --frozen-lockfile
 
 COPY ui/ ./
@@ -16,28 +16,27 @@ ENV NEXT_TELEMETRY_DISABLED=1
 RUN pnpm run build
 
 # Stage 2: Build the Routstr Node
-FROM ghcr.io/astral-sh/uv:python3.11-alpine AS runner
+FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim AS runner
 
-# Install system dependencies
-RUN apk add --no-cache \
-    pkgconf \
-    build-base \
-    automake \
-    autoconf \
-    libtool \
-    m4 \
-    perl \
-    git
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        git \
+        build-essential \
+        pkg-config \
+        libsecp256k1-dev \
+        autoconf \
+        automake \
+        libtool \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY uv.lock pyproject.toml ./
+
+RUN uv sync --no-dev --no-install-project
 
 WORKDIR /app
 
-# Copy the rest of the application (required for uv sync to find the package)
 COPY . .
 
-# Install dependencies including the specific secp256k1 branch
-RUN uv add git+https://github.com/saschanaz/secp256k1-py.git#branch=upgrade060
-RUN uv sync --no-dev
-
 # Copy the built UI from the ui-builder stage
 COPY --from=ui-builder /app/ui/out ./ui_out
 
@@ -51,4 +50,4 @@ ENV PYTHONUNBUFFERED=1
 EXPOSE 8000
 
 # Run the application
-CMD ["/app/.venv/bin/fastapi", "run", "routstr", "--host", "0.0.0.0"]
+CMD ["/.venv/bin/fastapi", "run", "routstr", "--host", "0.0.0.0"]

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:

README.md

@@ -55,19 +55,41 @@ If you are a node runner, start a Routstr Core instance using Docker Compose:
 
 1. **Prepare your `.env`**:
    ```bash
-   ADMIN_PASSWORD=mysecretpassword
+   # Optional: encrypts node secrets at rest. If unset, the node generates a key
+   # on first start, writes it to routstr_secret.key, and prints it once — back
+   # up that file. Set it explicitly to manage the key yourself (recommended in
+   # production).
+   ROUTSTR_SECRET_KEY=<generated-key>
    NAME="My AI Node"
    DESCRIPTION="Fast access to models"
-   NSEC=yournsec
    RECEIVE_LN_ADDRESS=yourname@wallet.com
    ```
 
+   Your Nostr identity (`nsec`) is not set in `.env` — configure it from the admin
+   UI after first start, where it's stored encrypted in the database. (`NSEC` in
+   `.env` is still read once as a legacy seed for existing deployments.)
+
+   If you don't set one, a key is generated and printed on first start — save it
+   somewhere safe (losing it makes previously encrypted secrets unreadable). To
+   supply your own, generate it once and keep it stable:
+   ```bash
+   uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+   ```
+
 2. **Start the services**:
    ```bash
    docker compose up -d
    ```
 
-3. **Configure**:
+3. **Get your admin password**:
+   On first start the node generates an admin password and logs it once with the
+   `/admin` URL. Read it from the logs:
+   ```bash
+   docker compose logs routstr | grep -i admin
+   ```
+   (Lost it? Reset with `docker compose exec routstr /.venv/bin/python scripts/reset_admin_password.py --regenerate`.)
+
+4. **Configure**:
    Open [http://localhost:8000/admin/](http://localhost:8000/admin/) to connect your AI providers and set pricing.
 
 For full instructions, see the **[Provider Quick Start Guide](https://docs.routstr.com/provider/quickstart/)**.

compose.yml

@@ -8,20 +8,22 @@ services:
       args:
         # NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://127.0.0.1:8000}
         NEXT_PUBLIC_ADMIN_API_KEY: ${NEXT_PUBLIC_ADMIN_API_KEY:-}
+    user: root
     volumes:
-      - ./ui_out:/output
+      - ./ui_out:/output:z
     command:
       ["sh", "-c", "mkdir -p /output && cp -r /app/built/. /output/ && echo 'UI build copied to mounted volume' && ls -la /output/ && echo 'UI built and ready' && tail -f /dev/null"]
+    restart: unless-stopped
 
   routstr:
     build: .
     depends_on:
       - ui
     volumes:
-      - .:/app
-      - ./logs:/app/logs
+      - .:/app:z
+      - ./logs:/app/logs:z
       - tor-data:/var/lib/tor:ro
-      - ./ui_out:/app/ui_out:ro
+      - ./ui_out:/app/ui_out:ro,z
     env_file:
       - .env
     environment:
@@ -30,6 +32,7 @@ services:
       - 8000:8000
     extra_hosts: # Needed to access locally running models
       - "host.docker.internal:host-gateway"
+    restart: unless-stopped
 
   tor:
     image: ghcr.io/hundehausen/tor-hidden-service:latest
@@ -40,6 +43,7 @@ services:
       - HS_ROUTER=routstr:8000:80
     depends_on:
       - routstr
+    restart: unless-stopped
 
 volumes:
   tor-data:

docs/api/endpoints.md

@@ -396,6 +396,8 @@ Authorization: Bearer sk-...
 }
 ```
 
+`balance` is the spendable balance used by request admission.
+
 ### Check Balance
 
 Get current wallet balance.

docs/api/errors.md

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

docs/api/overview.md

@@ -155,7 +155,7 @@ The response includes your change in the same header:
 X-Cashu: cashuA7k2mNp4...
 ```
 
-This is fully stateless—no session, no `/v1/balance/refund` call needed. However, **streaming does not work with `X-Cashu`** because the refund can only be calculated after the full response is generated.
+This is fully stateless—no session, no `/v1/balance/refund` call needed. However, **streaming does not work with `X-Cashu`** because the refund can only be calculated after the full response is generated. If you lose the `X-Cashu` response header before claiming your change, you can reclaim the refund via `POST /v1/wallet/refund` by supplying the original payment token in the `x-cashu` header.
 
 ## Response Headers
 

docs/client/payments.md

@@ -53,9 +53,11 @@ If your balance runs low, you don't need a new key. You can top up the existing
 
 ### Via Lightning
 
-`POST /lightning/invoice` with `{"amount_sats": 1000, "purpose": "topup", "api_key": "sk-..."}`.
+`POST /lightning/invoice` with `Authorization: Bearer sk-...` header and body `{"amount_sats": 1000, "purpose": "topup"}`.
 *Once paid, the funds are added to your existing key.*
 
+> Legacy: the endpoint is also exposed at `/v1/balance/lightning/invoice`, and accepts an `api_key` field in the body as a fallback for older clients. New integrations should use the RIP-08 path with the `Authorization` header.
+
 ### Via Cashu
 
 `POST /v1/balance/topup` with `{"cashu_token": "..."}` and `Authorization: Bearer sk-...`.

docs/ehbp-proxy-support.md

@@ -0,0 +1,150 @@
+# EHBP Proxy Support for Tinfoil Models
+
+## Problem
+
+The SDK's `SecureClient.fetch` encrypts request bodies with HPKE (EHBP protocol)
+and sends them to the Routstr provider. The Routstr proxy had no EHBP handling:
+
+1. It tried to `json.loads()` the binary HPKE-sealed body → failed with a 400
+2. The upstream PPQ.AI public endpoint (`/v1/chat/completions`) doesn't speak
+   EHBP, so the response had no `Ehbp-Response-Nonce` header
+3. `SecureClient` threw `Missing Ehbp-Response-Nonce header` because it expects
+   every response from an EHBP-configured `baseURL` to carry that header
+
+## Root cause
+
+PPQ.AI exposes EHBP-aware inference at `/private/`, separate from the public
+`/v1/` endpoint. The Routstr proxy was forwarding to `/v1/` (the public
+endpoint) instead of `/private/` (the enclave endpoint). The public endpoint
+can't decrypt the body, returns a normal HTTP response, and the SDK can't
+decrypt it because there's no nonce header.
+
+The PPQ private-mode proxy (`ppq-private-mode-proxy/lib/proxy.ts`) shows the
+correct pattern: `SecureClient` talks to `api.ppq.ai/private/v1/chat/completions`,
+which decrypts inside the attested enclave and returns an EHBP-encrypted
+response with the `Ehbp-Response-Nonce` header.
+
+## What was changed
+
+### `routstr/proxy.py`
+
+Detects EHBP requests by checking for the `Ehbp-Encapsulated-Key` header (set
+by the EHBP transport on every encrypted request). For EHBP requests:
+
+- Skips JSON body parsing (the body is binary ciphertext, not JSON)
+- Reads the model ID from the `X-Routstr-Model` header (set by the SDK) instead
+  of from `body.model`
+- Routes through new `forward_ehbp_request` (bearer auth) and
+  `forward_ehbp_x_cashu_request` (x-cashu auth) methods
+- Skips reactive 400 param correction (can't parse encrypted response body)
+- Still charges the user via `pay_for_request` (uses `max_cost_for_model` from
+  the model registry, not the body)
+
+### `routstr/upstream/base.py`
+
+Keeps EHBP as an explicit opt-in provider capability instead of making every
+upstream provider appear EHBP-capable:
+
+- `supports_ehbp = False` by default
+- `get_ehbp_forwarding_target(path, model_obj)` raises `NotImplementedError`
+  unless a provider opts in and returns a provider-specific EHBP target
+
+The actual EHBP forwarding logic does **not** live in `base.py`.
+
+### `routstr/upstream/ehbp.py`
+
+Contains the shared opaque EHBP transport and billing helpers:
+
+- `EHBPForwardingTarget` — provider-specific target URL plus extra headers
+- `forward_ehbp_request()` — forwards the encrypted body, captures Tinfoil
+  usage from a response header or streaming HTTP trailer, and finalizes bearer
+  billing at actual cost (falling back to max cost when usage is unavailable)
+- `forward_ehbp_x_cashu_request()` — redeems the Cashu token, refunds the full
+  token on upstream failure, and refunds the difference between the redeemed
+  amount and actual cost (or max cost when usage is unavailable)
+
+### Provider support
+
+EHBP is currently enabled only for `TinfoilUpstreamProvider`. It forwards to
+Tinfoil's attested enclave and requests `X-Tinfoil-Usage-Metrics` for billing.
+PPQ.AI retains its private-target implementation, but `supports_ehbp = False`
+until it has a provider-specific trusted usage/model-binding strategy.
+
+## Why it's done this way
+
+The proxy is a **blind relay** for EHBP requests. It cannot decrypt the body
+(only the attested enclave can), so it must:
+
+1. Get the model ID from a header, not the body
+2. Forward the raw bytes without parsing or transformation
+3. Stream the response back without SSE/cost parsing
+4. Pass through EHBP protocol headers (`Ehbp-Encapsulated-Key` on request,
+   `Ehbp-Response-Nonce` on response)
+
+Cost tracking happens at the proxy level. Routstr reserves or redeems up to
+`max_cost_for_model`, then Tinfoil's out-of-band usage header/trailer allows it
+to finalize at actual token cost. If trusted usage is missing or invalid, the
+proxy safely falls back to max-cost billing.
+
+## End-to-end flow
+
+```
+SDK                                  Routstr Proxy                    PPQ.AI /private/
+  │                                       │                                │
+  │── X-Routstr-Model: tinfoil-kimi-k2-6 ─│                                │
+  │── Ehbp-Encapsulated-Key: <hex> ───────│                                │
+  │── Authorization: Bearer <cashu> ──────│                                │
+  │── body = HPKE-encrypted(kimi-k2-6) ───│                                │
+  │                                       │                                │
+  │                                  detects Ehbp-Encapsulated-Key         │
+  │                                  reads model from X-Routstr-Model      │
+  │                                  does billing/routing                  │
+  │                                       │                                │
+  │                                  adds X-Private-Model: private/kimi-k2-6
+  │                                  forwards raw body to /private/v1/...  │
+  │                                       │──────────────────────────────▶│
+  │                                       │                          enclave decrypts
+  │                                       │                          runs inference
+  │                                       │◀── Ehbp-Response-Nonce ──────│
+  │                                       │◀── encrypted response ────────│
+  │                                       │                                │
+  │                                  streams response back untouched       │
+  │◀── encrypted response ────────────────│                                │
+  │                                        │                                │
+  SecureClient reads nonce, decrypts       │                                │
+  SDK SSE processing sees plaintext        │                                │
+```
+
+## Model ID mapping
+
+Three parties see three different model IDs:
+
+| Party | Header/Body | Value | Source |
+|---|---|---|---|
+| Routstr proxy | `X-Routstr-Model` header | `tinfoil-kimi-k2-6` | SDK sends full caller-facing id |
+| Tinfoil usage metrics | `model` field | `kimi-k2-6` | Enclave reports the model actually served |
+| Tinfoil enclave | `body.model` (encrypted) | `kimi-k2-6` | SDK strips `tinfoil-` prefix before encryption |
+
+## Implementation status
+
+A dedicated `TinfoilUpstreamProvider` (`routstr/upstream/tinfoil.py`) now
+implements the direct blind-upstream pattern described above. The shared EHBP
+helpers in `routstr/upstream/ehbp.py` were extended to:
+
+- Request usage metrics via `X-Tinfoil-Request-Usage-Metrics: true`.
+- Parse `X-Tinfoil-Usage-Metrics` from the response header (non-streaming) or
+  HTTP trailer (streaming).
+- Override the forwarding URL with a validated `X-Tinfoil-Enclave-Url` when the
+  SDK sends it.
+- Finalize bearer billing with the dedicated EHBP actual-cost finalizer.
+- Compute X-Cashu refunds from actual cost instead of max cost.
+
+See `docs/tinfoil-direct-integration.md` for the full implementation notes.
+
+## Verification status
+
+Unit coverage includes usage parsing, target validation, HTTP trailer capture,
+response-size limits, and bearer payment finalization. End-to-end requests have
+verified both non-streaming usage headers and streaming usage trailers against
+Tinfoil. SDK behavior on proxy-generated non-2xx responses without an
+`Ehbp-Response-Nonce` still merits explicit end-to-end coverage.

docs/provider/configuration.md

@@ -13,7 +13,10 @@ Before running your node, you should create a `.env` file in the project root. T
 ### Example .env
 
 ```bash
-ADMIN_PASSWORD=your-secure-password
+# Encrypts node secrets at rest. Optional — if unset, the node generates a key on
+# first start and prints it once (back it up). Set it to manage the key yourself
+# (recommended in production). See "Secrets at Rest" below.
+ROUTSTR_SECRET_KEY=
 
 # Node Identity
 NAME="My AI Node"
@@ -25,10 +28,10 @@ RECEIVE_LN_ADDRESS=yourname@wallet.com
 
 ### Setting the UI Password
 
-There are two ways to set or change your Admin Dashboard password:
+On first start the node generates an admin password and logs it once — read it from the container logs to sign in. You can then change it two ways:
 
-1.  **Via Environment Variable**: Set `ADMIN_PASSWORD` in your `.env` file before starting the container. This will be the password used for the first login.
-2.  **Via Dashboard**: Once logged in, go to **Settings** → **Security** to update your password. Dashboard settings override the `.env` file once saved.
+1.  **Via Dashboard**: Once logged in, go to **Settings** → **Security** to update your password.
+2.  **Via Environment Variable (legacy seed)**: Setting `ADMIN_PASSWORD` in `.env` before the first start seeds the initial password instead of generating one. It's read only once, for existing deployments; a value left in `.env` is ignored after the node has been configured.
 
 ---
 
@@ -78,9 +81,15 @@ Which mints to accept payments from:
 
 Automatic profit withdrawal:
 
-| Setting               | Description                     |
-| --------------------- | ------------------------------- |
-| **Lightning Address** | Your LN address for withdrawals |
+| Setting                              | Description                                                                                                | Default |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------- |
+| **Lightning Address**                | Your LN address for withdrawals                                                                            | —       |
+| **Minimum Payout (sat)**             | Min available balance (in sats) before profit is paid out. Applies to both `sat` and `msat` mints (auto-converted). | `210`   |
+| **Payout Interval (seconds)**        | How often the payout loop wakes up and checks balances                                                     | `900`   |
+
+All payout amounts must be positive. Set the minimums above your wallet's
+minimum-invoice constraint (typically 1 sat) and high enough to amortise
+routing fees.
 
 ### Security
 
@@ -117,15 +126,19 @@ Use environment variables for:
 | -------------------- | --------------------------------- | ------------------------------------ |
 | `UPSTREAM_BASE_URL`  | Upstream API endpoint             | —                                    |
 | `UPSTREAM_API_KEY`   | Upstream API key                  | —                                    |
-| `ADMIN_PASSWORD`     | Dashboard password                | (none)                               |
+| `ADMIN_PASSWORD`     | Legacy seed for the dashboard password (otherwise generated + logged on first start) | (auto-generated) |
+| `ROUTSTR_SECRET_KEY` | Master key encrypting node secrets at rest. Auto-generated to a key file if unset | (auto-generated) |
+| `ROUTSTR_SECRET_KEY_FILE` | Path to the generated key file (used when `ROUTSTR_SECRET_KEY` is unset) | `routstr_secret.key` beside the database |
 | `DATABASE_URL`       | Database connection string        | `sqlite+aiosqlite:///keys.db`        |
 | `NAME`               | Node display name                 | `ARoutstrNode`                       |
 | `DESCRIPTION`        | Node description                  | `A Routstr Node`                     |
 | `NPUB`               | Nostr public key (bech32)         | —                                    |
-| `NSEC`               | Nostr private key                 | —                                    |
+| `NSEC`               | Legacy seed for the Nostr private key (otherwise set from the admin UI) | —                |
 | `ENABLE_ANALYTICS_SHARING` | Enable usage analytics sharing to Nostr | `true`                         |
 | `CASHU_MINTS`        | Comma-separated mint URLs         | `https://mint.minibits.cash/Bitcoin` |
 | `RECEIVE_LN_ADDRESS` | Lightning address for withdrawals | —                                    |
+| `MIN_PAYOUT_SAT`     | Min payout balance in sats (applies to all mints) | `210`                |
+| `PAYOUT_INTERVAL_SECONDS` | Payout loop interval (seconds) | `900`                            |
 | `TOR_PROXY_URL`      | SOCKS5 proxy for Tor              | `socks5://127.0.0.1:9050`            |
 | `CORS_ORIGINS`       | Allowed CORS origins              | `*`                                  |
 | `RELAYS`             | Nostr relays (comma-separated)    | (default set)                        |
@@ -134,6 +147,20 @@ Use environment variables for:
 
 Environment variables are read on startup. Dashboard settings override them and persist in the database. Once you change a setting in the dashboard, the env var is ignored for that setting.
 
+### Secrets at Rest
+
+The node's Nostr private key (`nsec`) is encrypted in the database using
+`ROUTSTR_SECRET_KEY`. You don't have to set it: if it's unset, the node generates a
+key on first start, writes it **beside the database** (the file named by
+`ROUTSTR_SECRET_KEY_FILE`, default `routstr_secret.key`) so it persists on the same
+volume as your data, and prints it once.
+
+**Back up that key** — it lives on the same volume as your database, so include it
+in your backups. If it is lost or changed, previously encrypted secrets can't be
+decrypted and must be re-entered — there is no rotation. To keep the key off the
+data volume, set `ROUTSTR_SECRET_KEY` explicitly (an env value always takes
+precedence over the file). See also [Deployment](deployment.md).
+
 ---
 
 ## Models

docs/provider/deployment.md

@@ -38,7 +38,6 @@ services:
       - routstr-data:/app/data
     environment:
       DATABASE_URL: "sqlite:////app/data/routstr.db"
-      ADMIN_KEY: "your-secure-admin-key"
       LOG_LEVEL: "info"
 
 volumes:
@@ -87,6 +86,8 @@ services:
       - ./logs:/app/logs
     environment:
       - TOR_PROXY_URL=socks5://tor:9050
+      # Keep the database (and the key file generated beside it) on the volume.
+      - DATABASE_URL=sqlite:////app/data/routstr.db
     depends_on:
       - tor
 
@@ -125,8 +126,8 @@ services:
       - UPSTREAM_BASE_URL=https://api.openai.com/v1
       - UPSTREAM_API_KEY=sk-proj-...
       
-      # Secure the dashboard (recommended)
-      - ADMIN_PASSWORD=your-secure-password
+      # The admin password is generated and logged once on first start; set
+      # ADMIN_PASSWORD here only as a legacy seed for an existing deployment.
       
       # Node identity
       - NAME=My Provider Node
@@ -134,6 +135,9 @@ services:
       
       # Lightning withdrawals
       - RECEIVE_LN_ADDRESS=me@walletofsatoshi.com
+
+      # Keep the database (and the key file generated beside it) on the volume.
+      - DATABASE_URL=sqlite:////app/data/routstr.db
     volumes:
       - ./data:/app/data
 ```
@@ -155,22 +159,36 @@ Example `.env`:
 ```bash
 UPSTREAM_BASE_URL=https://api.openai.com/v1
 UPSTREAM_API_KEY=sk-proj-...
-ADMIN_PASSWORD=change-me
+# Keep the database (and the key file generated beside it) on the mounted volume.
+DATABASE_URL=sqlite:////app/data/routstr.db
+# Encrypts node secrets at rest. Optional — if unset, a key is generated next to
+# your database (on the same volume) and its file is named once for backup. Set
+# it explicitly to manage the key yourself.
+ROUTSTR_SECRET_KEY=
 NAME=My Provider Node
 RECEIVE_LN_ADDRESS=me@walletofsatoshi.com
 ```
 
+!!! note "Secret key persistence"
+    If you leave `ROUTSTR_SECRET_KEY` unset, the node generates one and stores it
+    as `routstr_secret.key` **next to your database**, so it persists on the same
+    volume as your data — just include that volume in your backups. For stronger
+    isolation (keeping the key off the data volume), set `ROUTSTR_SECRET_KEY` from
+    a secrets manager instead.
+
 See [Configuration](configuration.md) for all available options.
 
 ---
 
 ## Persistence
 
-Routstr stores all data in `/app/data`:
+Point `DATABASE_URL` inside `/app/data` (as the examples above do) so everything
+Routstr persists lands on the mounted volume:
 
 | Path | Contents |
 |------|----------|
-| `keys.db` | SQLite database (settings, API keys, sessions) |
+| `routstr.db` | SQLite database (settings, API keys, sessions) |
+| `routstr_secret.key` | Auto-generated master key, written beside the database when `ROUTSTR_SECRET_KEY` is unset |
 | `.wallet/` | Cashu wallet data (your Bitcoin!) |
 
 !!! warning "Back Up Your Data"

docs/provider/quickstart.md

@@ -29,19 +29,25 @@ In future versions, you'll be able to run a node that connects to other Routstr
 Create a `.env` file in the root of the project to store your secrets:
 
 ```bash
-# Initial Admin Password
-ADMIN_PASSWORD=mysecretpassword
+# Encrypts node secrets at rest. Optional — if unset, the node generates a key on
+# first start and prints it once (back it up).
+ROUTSTR_SECRET_KEY=
 
 # Node Identity
 NAME="My AI Node"
 DESCRIPTION="Fast access to models"
-NSEC=yournsec
 
 # Lightning Payouts
 RECEIVE_LN_ADDRESS=yourname@wallet.com
 
 ```
 
+The admin password is generated and logged once on first start (read it from the
+logs to sign in), and your Nostr identity (`nsec`) is configured afterwards from
+the admin UI — both are stored encrypted in the database, not in `.env`.
+(`ADMIN_PASSWORD` / `NSEC` are still read once as a legacy seed for existing
+deployments.)
+
 ## 2. Start the Node
 
 The recommended way to run Routstr is using Docker Compose, which handles the node, the UI, and optional services like Tor.
@@ -72,7 +78,7 @@ docker compose up -d
 Open the **Admin Dashboard** at [http://localhost:8000/admin/](http://localhost:8000/admin/).
 
 !!! note "Login"
-Use the `ADMIN_PASSWORD` you defined in your `.env` file to log in. If you didn't set one, the dashboard will prompt you to set one on first visit.
+On first start the node generates an admin password and logs it once — read it from the container logs to sign in. You can change it afterwards from **Settings** → **Security**.
 
 ### Connect Your AI Providers
 

docs/tinfoil-direct-integration.md

@@ -0,0 +1,493 @@
+# Tinfoil / PPQ Private-Mode Integration Notes
+
+This document summarizes the current options for integrating Tinfoil/PPQ private models with Routstr, based on the EHBP work in this branch and local testing against `ppq-private-mode-proxy`.
+
+## Background
+
+PPQ private models run behind a Tinfoil/EHBP flow:
+
+- Request bodies are HPKE-encrypted by a Tinfoil client.
+- The PPQ `/private/` endpoint routes ciphertext to the attested enclave.
+- The enclave decrypts, runs inference, and returns an encrypted response.
+- The caller's Tinfoil client decrypts the response locally.
+
+The PPQ private-mode proxy (`~/projects/ppq-private-mode-proxy`) uses this pattern with the JavaScript `tinfoil` SDK:
+
+```ts
+import { SecureClient } from "tinfoil";
+
+const apiBase = "https://api.ppq.ai";
+
+const client = new SecureClient({
+  baseURL: `${apiBase}/private/`,
+  attestationBundleURL: `${apiBase}/private`,
+  transport: "ehbp",
+});
+
+await client.ready();
+
+const response = await client.fetch(`${apiBase}/private/v1/chat/completions`, {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${process.env.PPQ_API_KEY}`,
+    "X-Private-Model": "private/gpt-oss-120b",
+    "x-query-source": "api",
+  },
+  body: JSON.stringify({
+    model: "gpt-oss-120b", // enclave-internal model id
+    messages: [{ role: "user", content: "Hello" }],
+  }),
+});
+
+const json = await response.json();
+console.log(json.usage);
+```
+
+`X-Private-Model` carries the PPQ-facing private model id, while the encrypted JSON body uses the enclave-internal model id without the `private/` prefix.
+
+## PPQ private model pricing
+
+PPQ exposes private model pricing through:
+
+```text
+GET https://api.ppq.ai/v1/models?type=all
+```
+
+Filter models whose IDs start with `private/`.
+
+Example private pricing observed:
+
+| Model | Input USD / 1M tokens | Output USD / 1M tokens |
+|---|---:|---:|
+| `private/gpt-oss-120b` | `0.79125` | `1.31875` |
+| `private/llama3-3-70b` | `1.84625` | `2.90125` |
+| `private/qwen3-vl-30b` | `1.31875` | `4.22` |
+| `private/glm-5-2` | `1.5825` | `5.53875` |
+| `private/gemma4-31b` | `0.47475` | `1.055` |
+| `private/kimi-k2-6` | `1.5825` | `5.53875` |
+
+The `ppq-private-mode-proxy` commit `ba984214793d3bca0f7d046b6955d42abc1c6843` changed OpenClaw display metadata to align with a 5% API margin. The live PPQ model endpoint returns the more precise rates above, which already include that margin.
+
+Actual PPQ private billing is:
+
+```text
+price_usd =
+  input_tokens  * input_per_1M_tokens  / 1_000_000
++ output_tokens * output_per_1M_tokens / 1_000_000
+```
+
+A test request to `private/gpt-oss-120b` produced:
+
+```json
+{
+  "input_count": 74,
+  "output_count": 3,
+  "price_in_usd": 0.00006250875
+}
+```
+
+which exactly matches:
+
+```text
+74 * 0.79125 / 1_000_000 + 3 * 1.31875 / 1_000_000
+= 0.00006250875 USD
+```
+
+## Integration architectures
+
+There are three materially different ways Routstr could integrate Tinfoil/PPQ private inference.
+
+## Option A: User integrates Tinfoil directly
+
+```text
+User app / SDK
+  -> Tinfoil SecureClient / TinfoilAI
+    -> EHBP-encrypted request
+      -> Tinfoil/PPQ private enclave
+```
+
+Properties:
+
+- Best privacy for the user.
+- Routstr is not in the request path.
+- User's client encrypts requests and decrypts responses.
+- Usage is visible to the user's app after decryption.
+- Billing is handled directly by Tinfoil/PPQ.
+
+Example with Tinfoil's OpenAI-compatible client:
+
+```ts
+import { TinfoilAI } from "tinfoil";
+
+const client = new TinfoilAI({
+  apiKey: process.env.TINFOIL_API_KEY,
+  transport: "ehbp",
+});
+
+const res = await client.chat.completions.create({
+  model: "llama3-3-70b",
+  messages: [{ role: "user", content: "Hello" }],
+});
+
+console.log(res.choices[0].message.content);
+console.log(res.usage);
+```
+
+This is not a Routstr marketplace flow unless Routstr only acts as discovery/UI around direct Tinfoil/PPQ usage.
+
+## Option B: Routstr integrates Tinfoil as an upstream client
+
+```text
+User -> Routstr plaintext request
+  -> Routstr Tinfoil SecureClient encrypts to PPQ/Tinfoil
+    -> PPQ private enclave
+  -> Routstr receives decrypted response
+  -> Routstr bills from decrypted usage
+  -> Routstr returns plaintext response to user
+```
+
+Properties:
+
+- Easier exact billing.
+- Routstr can read the decrypted OpenAI response and `usage` object.
+- Routstr can charge exact PPQ token pricing.
+- Privacy is different: the user sends plaintext to Routstr, and Routstr sees prompts/responses.
+- End-to-end encryption is only Routstr-to-enclave, not user-to-enclave.
+
+This should be considered a separate product/provider mode, not the same as an end-to-end private relay.
+
+Practical implementation options:
+
+1. Run a Node sidecar that uses the `tinfoil` npm package and expose it as a local HTTP upstream to Routstr.
+2. Port EHBP client behavior to Python.
+3. Reuse or adapt `ppq-private-mode-proxy` as a local upstream.
+
+A Node sidecar is probably the quickest implementation path because `ppq-private-mode-proxy` already demonstrates the full flow.
+
+## Option C: Routstr uses Tinfoil as a direct blind upstream
+
+This is the current branch's design intent and is likely the best fit if Tinfoil/PPQ exposes usage metadata headers:
+
+```text
+User Tinfoil SecureClient
+  -> encrypted request body
+    -> Routstr proxy
+      -> Tinfoil/PPQ private API
+         with X-Tinfoil-Request-Usage-Metrics: true
+        -> PPQ private enclave
+      <- encrypted response
+         plus X-Tinfoil-Usage-Metrics / cost headers
+    <- Routstr proxy
+  -> user decrypts response
+```
+
+In this mode Routstr is still a normal upstream proxy from the user's point of view, but the upstream is Tinfoil/PPQ private inference and the body remains opaque to Routstr.
+
+Properties:
+
+- Strongest privacy with Routstr in the path.
+- Routstr never sees plaintext prompt or plaintext response.
+- Routstr can authenticate and route based on plaintext headers.
+- Routstr should request Tinfoil usage metadata by adding `X-Tinfoil-Request-Usage-Metrics: true` to the upstream request.
+- Tinfoil documents `X-Tinfoil-Usage-Metrics` as an upstream response header for non-streaming requests.
+- For streaming requests, Tinfoil documents `X-Tinfoil-Usage-Metrics` as an HTTP trailer available only after the response body completes.
+- If Tinfoil/PPQ returns `X-Tinfoil-Usage-Metrics` or a cost header on the encrypted response, Routstr can bill exactly without decrypting the body.
+- If usage is only present inside the encrypted response body, Routstr still cannot read it and exact billing is not possible without a separate metadata path.
+
+This is the only architecture that preserves end-to-end encryption from the user to the PPQ/Tinfoil enclave while still letting Routstr mediate payment. The key requirement is that usage/cost metadata must be returned outside the encrypted body, ideally as a response header available before body streaming begins.
+
+## Current Routstr problem
+
+The current EHBP implementation charges successful EHBP requests at `max_cost_for_model` because Routstr cannot decrypt the response body:
+
+```text
+successful EHBP request -> charge full reserved max cost
+```
+
+That is incorrect for PPQ private models. Max cost should be only a reservation/solvency ceiling. Final charge should use actual PPQ private token pricing.
+
+Desired behavior:
+
+```text
+reserve max cost
+forward encrypted request
+obtain actual usage/cost metadata
+finalize actual cost
+refund/release the difference
+```
+
+## Usage/cost metadata requirement
+
+For blind-relay exact billing, PPQ should return one of the following outside the encrypted response body:
+
+```http
+X-PPQ-Cost-USD: 0.00006250875
+```
+
+or:
+
+```http
+X-Private-Usage-Metrics: input=74,output=3
+```
+
+or:
+
+```http
+X-Tinfoil-Usage-Metrics: prompt=74,completion=3,total=77
+```
+
+Tinfoil proxy documentation references a usage-metrics flow where a proxy can request usage via:
+
+```http
+X-Tinfoil-Request-Usage-Metrics: true
+```
+
+and read usage from:
+
+```http
+X-Tinfoil-Usage-Metrics
+```
+
+Docs/example references:
+
+- https://docs.tinfoil.sh/guides/proxy-server
+- https://github.com/tinfoilsh/encrypted-request-proxy-example
+
+During local PPQ testing, PPQ responses included this CORS exposure header:
+
+```http
+Access-Control-Expose-Headers: Ehbp-Response-Nonce, X-Private-Usage-Metrics, X-Encrypted-Usage-Metrics, X-Tinfoil-Usage-Metrics
+```
+
+However, the actual tested non-streaming response did not include any of these usage headers, even when `X-Tinfoil-Request-Usage-Metrics: true` was sent.
+
+The decrypted body did include normal OpenAI usage, but only the decrypting Tinfoil client can see that body.
+
+## Query-history fallback
+
+PPQ's query history endpoint exposes actual usage and cost:
+
+```text
+GET https://api.ppq.ai/queries/history?page=1&page_count=...
+```
+
+A record includes:
+
+```json
+{
+  "timestamp": "...",
+  "model": "private/gpt-oss-120b",
+  "input_count": 74,
+  "output_count": 3,
+  "price_in_usd": 0.00006250875,
+  "query_type": "chat_completion",
+  "query_source": "api"
+}
+```
+
+This could be used as a fallback, but it is less robust than response headers/trailers because matching a request to a history row can be race-prone under concurrency. It would need a reliable request identifier or metadata field that PPQ stores in history.
+
+## Recommended Routstr direction
+
+Use Tinfoil/PPQ as a direct blind upstream and have Routstr explicitly request usage metadata:
+
+```text
+User encrypts body
+Routstr reserves max cost
+Routstr forwards encrypted body to Tinfoil/PPQ /private/
+Routstr includes X-Tinfoil-Request-Usage-Metrics: true
+Tinfoil/PPQ returns X-Tinfoil-Usage-Metrics as a response header for non-streaming,
+or as an HTTP trailer after the body completes for streaming
+Routstr finalizes exact charge
+User decrypts encrypted response
+```
+
+This preserves both:
+
+- privacy: Routstr cannot read prompts/responses;
+- exact billing: Routstr can charge actual PPQ private model cost, assuming Tinfoil/PPQ returns usage/cost metadata outside the encrypted body.
+
+Implementation steps:
+
+1. Update PPQ model fetching to include private models:
+
+   ```text
+   GET https://api.ppq.ai/v1/models?type=all
+   ```
+
+2. Register `private/*` models and any Routstr-facing aliases with correct `forwarded_model_id`.
+
+3. Keep max-cost reservation for bearer keys and X-Cashu solvency checks.
+
+4. Add parsing support for possible usage/cost headers:
+
+   ```http
+   X-PPQ-Cost-USD
+   X-Private-Usage-Metrics
+   X-Tinfoil-Usage-Metrics
+   X-Encrypted-Usage-Metrics
+   ```
+
+5. Finalize by actual cost instead of max cost:
+
+   ```text
+   actual_msats = ceil((actual_usd / sats_usd_price()) * 1000)
+   actual_msats = max(actual_msats, settings.min_request_msat)
+   actual_msats = min(actual_msats, reserved_msats)
+   ```
+
+   or, if only token counts are available:
+
+   ```text
+   actual_usd =
+     input_tokens  * input_per_1M_tokens  / 1_000_000
+   + output_tokens * output_per_1M_tokens / 1_000_000
+   ```
+
+6. If usage/cost metadata is missing, choose an explicit policy:
+
+   - fail closed and refund/revert;
+   - query PPQ history as a fallback;
+   - fallback to max-cost billing only if explicitly configured and clearly disclosed.
+
+Silent max-cost billing should not be the default for PPQ private requests.
+
+## X-Cashu consideration
+
+For bearer-auth requests, finalization can happen after the response stream completes if usage is delivered as a trailer.
+
+For `X-Cashu`, Routstr needs to return the refund token in the response headers. If usage/cost is only available after consuming the encrypted response stream, Routstr may need to buffer EHBP responses before sending them to the client so it can compute the refund amount first.
+
+Possible approaches:
+
+1. Prefer a non-trailer response header with actual cost, available before streaming body starts.
+2. Buffer EHBP X-Cashu responses and then return `X-Cashu` refund.
+3. Introduce a later/refund-claim mechanism, which would be a larger protocol change.
+
+## Summary
+
+- PPQ private models are billed per actual input/output tokens.
+- Private model rates are available from `GET /v1/models?type=all`.
+- Current Routstr EHBP billing at max cost is wrong for PPQ private models.
+- Direct Tinfoil integration inside Routstr would enable exact usage billing but would make Routstr see plaintext.
+- A blind EHBP relay preserves privacy but requires PPQ/Tinfoil to expose usage/cost in plaintext headers/trailers.
+- The preferred solution is to keep Routstr blind and have PPQ return billing metadata outside the encrypted body.
+
+## Implementation status
+
+Direct Tinfoil upstream integration is implemented in `routstr/upstream/tinfoil.py`
+and `routstr/upstream/ehbp.py`.
+
+### What was built
+
+- `TinfoilUpstreamProvider` (`provider_type = "tinfoil"`):
+  - Base URL: `https://inference.tinfoil.sh`
+  - Fetches models from the public `GET /v1/models` endpoint (no auth needed).
+  - Parses Tinfoil's pricing (`inputTokenPricePer1M`, `outputTokenPricePer1M`,
+    `requestPrice`) into the standard `Model`/`Pricing` schema.
+  - `supports_ehbp = True` — acts as a blind EHBP relay.
+  - `get_ehbp_forwarding_target()` returns a target that includes
+    `X-Tinfoil-Request-Usage-Metrics: true`.
+  - `forward_get_request()` proxies `/attestation` to `https://atc.tinfoil.sh/attestation`
+    so the SDK can fetch attestation bundles through Routstr.
+  - Registered in `routstr/upstream/__init__.py` and seeded from
+    `TINFOIL_API_KEY` env var.
+
+- `routstr/upstream/ehbp.py`:
+  - `parse_tinfoil_usage_metrics()` parses
+    `prompt=N,completion=N[,total=N][,model=<name>]` into an OpenAI-style
+    usage dict. The `model` field (added in tinfoilsh/confidential-model-router
+    PR #385) is extracted as a string.
+  - `_resolve_ehbp_target_url()` overrides the forwarding URL with
+    `X-Tinfoil-Enclave-Url` when the SDK sends it.
+  - `_strip_proxy_headers()` removes `X-Routstr-Model`,
+    `X-Tinfoil-Enclave-Url`, and `X-Tinfoil-Request-Usage-Metrics` before
+    forwarding to the enclave.
+  - `_compute_ehbp_actual_cost()` converts the usage header into msats via
+    `calculate_cost()`, clamped to `[min_request_msat, max_cost_for_model]`.
+    When the header's `model=<name>` differs from the requested model, the
+    actual served model's pricing is used for cost calculation.
+  - `forward_ehbp_request()` (bearer auth): if `X-Tinfoil-Usage-Metrics` is
+    present in the response header, finalizes with `adjust_payment_for_tokens()`
+    for exact billing; otherwise falls back to max-cost. Billing uses the
+    actual served model when it differs from the requested one.
+  - `forward_ehbp_x_cashu_request()`: if usage is available, computes the
+    refund from actual cost instead of max cost, using the actual served
+    model's pricing when applicable.
+
+- `routstr/proxy.py`: `/attestation` and `/tee/attestation` paths are forwarded
+  to Tinfoil upstreams without model/cost/auth lookups.
+
+### Billing behavior
+
+| Request shape | Usage source | Billing |
+|---|---|---|
+| Bearer, non-streaming | `X-Tinfoil-Usage-Metrics` response header | Exact token cost via `adjust_payment_for_tokens` |
+| Bearer, streaming | `X-Tinfoil-Usage-Metrics` HTTP trailer | Exact token cost (h11 captures trailers) |
+| Bearer, no usage header/trailer | N/A | Max-cost fallback |
+| X-Cashu, non-streaming | `X-Tinfoil-Usage-Metrics` response header | Refund = `redeemed - actual_cost` |
+| X-Cashu, streaming | `X-Tinfoil-Usage-Metrics` HTTP trailer | Refund = `redeemed - actual_cost` (h11 captures trailers) |
+| X-Cashu, no usage header/trailer | N/A | Refund = `redeemed - max_cost` |
+
+### Cost response headers
+
+Since EHBP response bodies are opaque encrypted blobs, per-request cost cannot
+be injected into the JSON body (as done in the normal proxy flow). Instead,
+Routstr returns cost info as response headers:
+
+| Header | Auth | Description |
+|---|---|---|
+| `X-Routstr-Cost-Msats` | Bearer, X-Cashu | Total msats charged for this request |
+| `X-Routstr-Cost-Usd` | Bearer | USD equivalent of the charge |
+| `X-Routstr-Input-Cost-Msats` | Bearer, X-Cashu | msats attributed to input tokens |
+| `X-Routstr-Output-Cost-Msats` | Bearer, X-Cashu | msats attributed to output tokens |
+
+The client/Tinfoil SDK can read these headers from the HTTP response without
+needing to decrypt the body.
+
+### Setup
+
+```bash
+TINFOIL_API_KEY=your-tinfoil-api-key
+```
+
+The provider is auto-seeded on first startup.
+
+### Usage metrics header format
+
+Tinfoil returns usage metrics in the `X-Tinfoil-Usage-Metrics` response header
+(non-streaming) or HTTP trailer (streaming) when `X-Tinfoil-Request-Usage-Metrics:
+true` is sent. As of tinfoilsh/confidential-model-router PR #385, the format is:
+
+```
+prompt=<prompt_tokens>,completion=<completion_tokens>,total=<total_tokens>,model=<served_model>
+```
+
+The `model` field carries the actual model name served by the enclave.
+Routstr uses this to:
+
+- Verify the served model matches the expected upstream model. The comparison
+  uses ``model_obj.forwarded_model_id`` (the actual upstream ID, e.g.
+  ``glm-5-2``) rather than ``model_obj.id`` (the client-facing alias, e.g.
+  ``tinfoil-glm-5-2``), so aliased models don't trigger a spurious mismatch.
+- When they genuinely differ (Tinfoil served a different upstream model than
+  expected), look up the actual served model's pricing and use it for billing.
+  The reverse lookup uses ``get_model_instance``, which resolves
+  ``forwarded_model_id`` values registered as routable aliases.
+- Log the discrepancy for observability.
+
+If the actual model is not found in Routstr's model registry, billing falls
+back to the requested model's pricing.
+
+### What still needs verification
+
+- ~~End-to-end test with a real Tinfoil SDK client against a Routstr node with
+  `TINFOIL_API_KEY` set.~~ Verified: both non-streaming (header) and streaming
+  (trailer) responses include `model=<name>`.
+- Streaming trailer capture is implemented by buffering the encrypted response
+  in `forward_with_trailer()` and then using the dedicated EHBP payment
+  finalizers for bearer and X-Cashu requests. This provides actual-cost billing
+  today, at the cost of full time-to-last-byte latency for streaming responses.
+- Whether Tinfoil's `/v1/responses` endpoint also returns usage metrics
+  headers or trailers.

migrations/versions/7f2843d3f4e4_add_reservation_release_idempotency_.py

@@ -0,0 +1,62 @@
+"""add reservation release idempotency records
+
+Revision ID: 7f2843d3f4e4
+Revises: fc4fa29630d2
+Create Date: 2026-07-24 02:06:06.066726
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "7f2843d3f4e4"
+down_revision = "fc4fa29630d2"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "reservation_releases",
+        sa.Column("id", sa.String(), nullable=False),
+        sa.Column("key_hash", sa.String(), nullable=False),
+        sa.Column("billing_key_hash", sa.String(), nullable=False),
+        sa.Column("reserved_msats", sa.Integer(), nullable=False),
+        sa.Column(
+            "status", sa.String(), nullable=False, server_default="active"
+        ),
+        sa.Column("created_at", sa.Integer(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_reservation_releases_key_hash",
+        "reservation_releases",
+        ["key_hash"],
+    )
+    op.create_index(
+        "ix_reservation_releases_billing_key_hash",
+        "reservation_releases",
+        ["billing_key_hash"],
+    )
+    op.create_index(
+        "ix_reservation_releases_status_created_at",
+        "reservation_releases",
+        ["status", "created_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_reservation_releases_status_created_at",
+        table_name="reservation_releases",
+    )
+    op.drop_index(
+        "ix_reservation_releases_billing_key_hash",
+        table_name="reservation_releases",
+    )
+    op.drop_index(
+        "ix_reservation_releases_key_hash",
+        table_name="reservation_releases",
+    )
+    op.drop_table("reservation_releases")

migrations/versions/9c4d8e2f1a6b_repair_fee_payout_checkpoint_columns.py

@@ -0,0 +1,47 @@
+"""repair missing fee payout checkpoint columns
+
+Revision ID: 9c4d8e2f1a6b
+Revises: 7f2843d3f4e4
+Create Date: 2026-07-25 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "9c4d8e2f1a6b"
+down_revision = "7f2843d3f4e4"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Repair databases stamped past the original checkpoint migration."""
+    conn = op.get_bind()
+    columns = {
+        column["name"] for column in sa.inspect(conn).get_columns("routstr_fees")
+    }
+
+    if "payout_in_progress_msats" not in columns:
+        op.add_column(
+            "routstr_fees",
+            sa.Column(
+                "payout_in_progress_msats",
+                sa.Integer(),
+                nullable=False,
+                server_default="0",
+            ),
+        )
+
+    if "payout_started_at" not in columns:
+        op.add_column(
+            "routstr_fees",
+            sa.Column("payout_started_at", sa.Integer(), nullable=True),
+        )
+
+
+def downgrade() -> None:
+    # The preceding revision already expects both columns. This migration only
+    # repairs schema drift, so downgrading it must preserve the expected schema.
+    pass

migrations/versions/a2b3c4d5e6f7_add_constraints_to_lightning_invoices.py

@@ -0,0 +1,26 @@
+"""Add balance_limit, balance_limit_reset, validity_date to lightning_invoices
+
+Revision ID: a2b3c4d5e6f7
+Revises: f1a2b3c4d5e6
+Create Date: 2026-06-03 00:00:00.000000
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "a2b3c4d5e6f7"
+down_revision = "f1a2b3c4d5e6"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("lightning_invoices", sa.Column("balance_limit", sa.Integer(), nullable=True))
+    op.add_column("lightning_invoices", sa.Column("balance_limit_reset", sa.String(), nullable=True))
+    op.add_column("lightning_invoices", sa.Column("validity_date", sa.Integer(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("lightning_invoices", "validity_date")
+    op.drop_column("lightning_invoices", "balance_limit_reset")
+    op.drop_column("lightning_invoices", "balance_limit")

migrations/versions/aa50fde387a2_add_refund_sweep_claim_lease.py

@@ -0,0 +1,39 @@
+"""add refund sweep claim lease
+
+Revision ID: aa50fde387a2
+Revises: 9c4d8e2f1a6b
+Create Date: 2026-07-26 12:50:10.509217
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "aa50fde387a2"
+down_revision = "9c4d8e2f1a6b"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    columns = {
+        column["name"]
+        for column in sa.inspect(conn).get_columns("cashu_transactions")
+    }
+    if "sweep_started_at" not in columns:
+        op.add_column(
+            "cashu_transactions",
+            sa.Column("sweep_started_at", sa.Integer(), nullable=True),
+        )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    columns = {
+        column["name"]
+        for column in sa.inspect(conn).get_columns("cashu_transactions")
+    }
+    if "sweep_started_at" in columns:
+        op.drop_column("cashu_transactions", "sweep_started_at")

migrations/versions/b5e7c9d1f3a2_add_reserved_at_to_api_keys.py

@@ -0,0 +1,25 @@
+"""add reserved_at to api_keys
+
+Revision ID: b5e7c9d1f3a2
+Revises: a2b3c4d5e6f7
+Create Date: 2026-06-12 00:00:00.000000
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "b5e7c9d1f3a2"
+down_revision = "a2b3c4d5e6f7"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # existing keys keep NULL
+    # New reservations populate it via pay_for_request.
+    op.add_column("api_keys", sa.Column("reserved_at", sa.Integer(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("api_keys", "reserved_at")

migrations/versions/bf76270b66c4_add_mint_url_to_lightning_invoices.py

@@ -0,0 +1,25 @@
+"""add mint url to lightning invoices
+
+Revision ID: bf76270b66c4
+Revises: aa50fde387a2
+Create Date: 2026-07-30 00:54:30.306876
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "bf76270b66c4"
+down_revision = "aa50fde387a2"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "lightning_invoices", sa.Column("mint_url", sa.String(), nullable=True)
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("lightning_invoices", "mint_url")

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_fee_payout_checkpoint.py

@@ -0,0 +1,37 @@
+"""add fee payout checkpoint
+
+Revision ID: d7e8f9a0b1c2
+Revises: c6d7e8f9a0b1
+Create Date: 2026-07-18 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:
+    op.add_column(
+        "routstr_fees",
+        sa.Column(
+            "payout_in_progress_msats",
+            sa.Integer(),
+            nullable=False,
+            server_default="0",
+        ),
+    )
+    op.add_column(
+        "routstr_fees",
+        sa.Column("payout_started_at", sa.Integer(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("routstr_fees", "payout_started_at")
+    op.drop_column("routstr_fees", "payout_in_progress_msats")

migrations/versions/f1a2b3c4d5e6_add_created_at_to_api_keys.py

@@ -0,0 +1,25 @@
+"""add created_at to api_keys
+
+Revision ID: f1a2b3c4d5e6
+Revises: cli_tokens_001
+Create Date: 2026-06-01 00:00:00.000000
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "f1a2b3c4d5e6"
+down_revision = "cli_tokens_001"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Nullable on purpose: existing keys keep NULL (unknown creation time) and
+    # sort last; new keys get populated by the model's default_factory.
+    op.add_column("api_keys", sa.Column("created_at", sa.Integer(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("api_keys", "created_at")

migrations/versions/fc4fa29630d2_add_secrets_table.py

@@ -0,0 +1,51 @@
+"""add secrets table
+
+Revision ID: fc4fa29630d2
+Revises: d7e8f9a0b1c2
+Create Date: 2026-07-23 00:00:00.000000
+
+Creates the node-level singleton secret store (issue #553). Schema only; moving
+any legacy plaintext into the encrypted/hashed columns happens at bootstrap,
+where the live ROUTSTR_SECRET_KEY is available. ``nsec_state`` records the vault's
+ownership of the nsec (legacy | encrypted | cleared), so a cleared identity is
+never resurrected from a stale legacy ``NSEC`` env var / settings blob on the next
+boot.
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+revision = "fc4fa29630d2"
+down_revision = "d7e8f9a0b1c2"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "secrets",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column(
+            "admin_password_hash",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=True,
+        ),
+        sa.Column(
+            "encrypted_nsec",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=True,
+        ),
+        sa.Column(
+            "nsec_state",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=False,
+            server_default="legacy",
+        ),
+        sa.Column("updated_at", sa.Integer(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("secrets")

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "routstr"
-version = "0.4.3"
+version = "0.4.4"
 description = "Payment proxy for your LLM endpoint using cashu and nostr."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,11 +10,11 @@ dependencies = [
     "aiosqlite>=0.20",
     "sqlmodel>=0.0.24",
     "httpx[socks]>=0.25.2",
+    "h11>=0.14",
     "greenlet>=3.2.1",
     "alembic>=1.13",
     "python-json-logger>=2.0.0",
     "cashu>=0.20",
-    "secp256k1",
     "marshmallow>=3.13,<4.0",
     "websockets>=12.0",
     "nostr>=0.0.2",
@@ -87,4 +87,3 @@ disallow_untyped_decorators = true
 
 [tool.uv.sources]
 routstr = { workspace = true }
-secp256k1 = { git = "https://github.com/saschanaz/secp256k1-py", branch = "upgrade060" }

routstr/algorithm.py

@@ -86,10 +86,12 @@ def get_provider_penalty(provider: "BaseUpstreamProvider") -> float:
 
 def create_model_mappings(
     upstreams: list["BaseUpstreamProvider"],
-    overrides_by_id: dict[str, tuple],
-    disabled_model_ids: set[str],
+    overrides_by_key: dict[tuple[str, int], tuple],
+    disabled_model_keys: set[tuple[str, int]],
 ) -> tuple[
-    dict[str, "Model"], dict[str, list["BaseUpstreamProvider"]], dict[str, "Model"]
+    dict[str, "Model"],
+    dict[str, list[tuple["Model", "BaseUpstreamProvider"]]],
+    dict[str, "Model"],
 ]:
     """Create optimal model mappings based on cost and provider preferences.
 
@@ -97,7 +99,9 @@ def create_model_mappings(
     and creates three mappings based on cost optimization:
 
     1. model_instances: alias -> Model (all model aliases mapped to their Model objects)
-    2. provider_map: alias -> List[UpstreamProvider] (sorted list of providers for each alias)
+    2. provider_map: alias -> List[(Model, UpstreamProvider)] (sorted candidate
+       list for each alias; each provider is paired with ITS OWN model so
+       failover can forward and bill the candidate that actually serves)
     3. unique_models: base_id -> Model (unique models without provider prefixes)
 
     The algorithm:
@@ -107,8 +111,9 @@ def create_model_mappings(
 
     Args:
         upstreams: List of all upstream provider instances
-        overrides_by_id: Dict of model overrides from database {model_id: (ModelRow, fee)}
-        disabled_model_ids: Set of model IDs that should be excluded
+        overrides_by_key: Dict of model overrides from database
+            {(model_id_lower, upstream_provider_id): (ModelRow, fee)}
+        disabled_model_keys: Set of provider-scoped model keys that should be excluded
 
     Returns:
         Tuple of (model_instances, provider_map, unique_models)
@@ -179,14 +184,22 @@ def create_model_mappings(
         """Process all models from a given provider."""
         upstream_prefix = getattr(upstream, "upstream_name", None)
         provider_key = get_provider_identity(upstream)
+        upstream_db_id = getattr(upstream, "db_id", None)
 
         for model in upstream.get_cached_models():
-            if not model.enabled or model.id in disabled_model_ids:
+            model_key = (
+                (model.id.lower(), upstream_db_id)
+                if isinstance(upstream_db_id, int)
+                else None
+            )
+            if not model.enabled or (
+                model_key is not None and model_key in disabled_model_keys
+            ):
                 continue
 
-            # Apply overrides if present
-            if model.id in overrides_by_id:
-                override_row, provider_fee = overrides_by_id[model.id]
+            # Apply overrides only for this provider's model row.
+            if model_key is not None and model_key in overrides_by_key:
+                override_row, provider_fee = overrides_by_key[model_key]
                 model_to_use = _row_to_model(
                     override_row, apply_provider_fee=True, provider_fee=provider_fee
                 )
@@ -195,14 +208,15 @@ def create_model_mappings(
 
             # Add to unique models
             base_id = get_base_model_id(model_to_use.id)
-            if not is_openrouter or base_id not in unique_models:
+            unique_key = model_to_use.forwarded_model_id or base_id
+            if not is_openrouter or unique_key not in unique_models:
                 unique_model = model_to_use.copy(
                     update={
                         "id": base_id,
                         "upstream_provider_id": upstream.provider_type,
                     }
                 )
-                unique_models[base_id] = unique_model
+                unique_models[unique_key] = unique_model
 
             # Get all aliases for this model
             aliases = resolve_model_alias(
@@ -236,13 +250,10 @@ def create_model_mappings(
 
     # Include enabled DB overrides even when provider discovery misses models.
     # This is important for deployment-based providers like Azure.
-    for model_id, override_data in overrides_by_id.items():
-        if model_id in disabled_model_ids:
+    for (model_id, upstream_provider_id), override_data in overrides_by_key.items():
+        if (model_id, upstream_provider_id) in disabled_model_keys:
             continue
         override_row, provider_fee = override_data
-        upstream_provider_id = getattr(override_row, "upstream_provider_id", None)
-        if not isinstance(upstream_provider_id, int):
-            continue
 
         upstream_for_override = providers_by_db_id.get(upstream_provider_id)
         if upstream_for_override is None:
@@ -272,18 +283,19 @@ def create_model_mappings(
             continue
 
         base_id = get_base_model_id(model_to_use.id)
+        unique_key = model_to_use.forwarded_model_id or base_id
         is_openrouter = (
             getattr(upstream_for_override, "base_url", "")
             == "https://openrouter.ai/api/v1"
         )
-        if not is_openrouter or base_id not in unique_models:
+        if not is_openrouter or unique_key not in unique_models:
             unique_model = model_to_use.copy(
                 update={
                     "id": base_id,
                     "upstream_provider_id": upstream_for_override.provider_type,
                 }
             )
-            unique_models[base_id] = unique_model
+            unique_models[unique_key] = unique_model
 
         try:
             aliases = resolve_model_alias(
@@ -319,10 +331,29 @@ def create_model_mappings(
 
     # Sort candidates and build final maps
     model_instances: dict[str, "Model"] = {}
-    provider_map: dict[str, list["BaseUpstreamProvider"]] = {}
+    provider_map: dict[str, list[tuple["Model", "BaseUpstreamProvider"]]] = {}
 
     def alias_priority(model: "Model", alias: str) -> int:
-        """Rank how strong the mapping of alias->model is."""
+        """Rank how strong the mapping of alias->model is.
+
+        forwarded_model_id is the most specific identifier (set per-provider
+        instance), so a match there should beat a model_id match. This way,
+        when multiple providers have the same model_id but different
+        forwarded_model_ids, the one whose forwarded_model_id equals the
+        requested alias wins.
+        """
+        if (
+            model.forwarded_model_id
+            and model.forwarded_model_id.lower() == alias
+        ):
+            return 5
+
+        if (
+            model.id
+            and model.id.lower() == alias
+        ):
+            return 4
+
         model_base = get_base_model_id(model.id)
         if model_base == alias:
             return 3
@@ -347,13 +378,13 @@ def create_model_mappings(
 
         best_model, best_provider = items[0]
         model_instances[alias] = best_model
-        provider_map[alias] = [p for _, p in items]
+        provider_map[alias] = list(items)
 
     # Log provider distribution (using top provider for stats)
     provider_counts: dict[str, int] = {}
-    for providers in provider_map.values():
-        if providers:
-            provider = providers[0]
+    for candidate_list in provider_map.values():
+        if candidate_list:
+            provider = candidate_list[0][1]
             provider_name = getattr(provider, "upstream_name", "unknown")
             provider_counts[provider_name] = provider_counts.get(provider_name, 0) + 1
 

routstr/balance.py

@@ -15,12 +15,23 @@ from .core.db import (
     AsyncSession,
     CashuTransaction,
     get_session,
-    store_cashu_transaction,
+    release_stale_reservations,
+)
+from .core.db import (
+    store_cashu_transaction_with_retry as store_cashu_transaction,
 )
 from .core.logging import get_logger
 from .core.settings import settings
 from .lightning import lightning_router
-from .wallet import credit_balance, recieve_token, send_to_lnurl, send_token
+from .wallet import (
+    classify_redemption_error,
+    credit_balance,
+    is_mint_connection_error,
+    recieve_token,
+    send_to_lnurl,
+    send_token,
+    token_mint_url,
+)
 
 router = APIRouter()
 balance_router = APIRouter(prefix="/v1/balance")
@@ -45,10 +56,9 @@ async def get_balance_info(key: ApiKey, session: AsyncSession) -> dict:
     billing_key = await get_billing_key(key, session)
     info = {
         "api_key": "sk-" + key.hashed_key,
-        "balance": billing_key.balance,
+        "balance": billing_key.total_balance,
         "reserved": billing_key.reserved_balance,
         "is_child": key.parent_key_hash is not None,
-        "parent_key": "sk-" + key.parent_key_hash if key.parent_key_hash else None,
         "total_requests": key.total_requests,
         "total_spent": key.total_spent,
         "balance_limit": key.balance_limit,
@@ -56,7 +66,9 @@ async def get_balance_info(key: ApiKey, session: AsyncSession) -> dict:
         "validity_date": key.validity_date,
     }
 
-    if not key.parent_key_hash:
+    if key.parent_key_hash:
+        info["parent_key_preview"] = key.parent_key_hash[:8] + "..."
+    else:
         # Fetch child keys if this is a parent key
         statement = select(ApiKey).where(ApiKey.parent_key_hash == key.hashed_key)
         results = await session.exec(statement)
@@ -98,13 +110,19 @@ async def account_info(
 # Note: validate_bearer_key already supports refund_address and key_expiry_time params
 
 
-@router.get("/create")
-async def create_balance(
+class BalanceCreateRequest(BaseModel):
+    initial_balance_token: str
+    balance_limit: int | None = None
+    balance_limit_reset: str | None = None
+    validity_date: int | None = None
+
+
+async def _create_balance(
     initial_balance_token: str,
-    balance_limit: int | None = None,
-    balance_limit_reset: str | None = None,
-    validity_date: int | None = None,
-    session: AsyncSession = Depends(get_session),
+    balance_limit: int | None,
+    balance_limit_reset: str | None,
+    validity_date: int | None,
+    session: AsyncSession,
 ) -> dict:
     key = await validate_bearer_key(initial_balance_token, session)
 
@@ -124,6 +142,37 @@ async def create_balance(
     }
 
 
+@router.post("/create")
+async def create_balance_from_body(
+    payload: BalanceCreateRequest,
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    return await _create_balance(
+        payload.initial_balance_token,
+        payload.balance_limit,
+        payload.balance_limit_reset,
+        payload.validity_date,
+        session,
+    )
+
+
+@router.get("/create")
+async def create_balance(
+    initial_balance_token: str,
+    balance_limit: int | None = None,
+    balance_limit_reset: str | None = None,
+    validity_date: int | None = None,
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    return await _create_balance(
+        initial_balance_token,
+        balance_limit,
+        balance_limit_reset,
+        validity_date,
+        session,
+    )
+
+
 @router.get("/info")
 async def wallet_info(
     key: ApiKey = Depends(get_key_from_header),
@@ -136,6 +185,17 @@ class TopupRequest(BaseModel):
     cashu_token: str
 
 
+def _error_chain(error: BaseException) -> list[dict[str, str]]:
+    chain: list[dict[str, str]] = []
+    current: BaseException | None = error
+    seen: set[int] = set()
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        chain.append({"type": type(current).__name__, "message": str(current)})
+        current = current.__cause__ or current.__context__
+    return chain
+
+
 @router.post("/topup")
 async def topup_wallet_endpoint(
     cashu_token: str | None = None,
@@ -153,32 +213,61 @@ async def topup_wallet_endpoint(
     cashu_token = cashu_token.replace("\n", "").replace("\r", "").replace("\t", "")
     if len(cashu_token) < 10 or "cashu" not in cashu_token:
         raise HTTPException(status_code=400, detail="Invalid token format")
+
+    source_mint = token_mint_url(cashu_token, "unknown")
+    logger.warning(
+        "Cashu wallet top-up started",
+        extra={
+            "event": "cashu_topup_started",
+            "source_mint": source_mint,
+            "primary_mint": settings.primary_mint,
+            "trusted_mints": settings.cashu_mints,
+            "key_hash": billing_key.hashed_key[:8],
+        },
+    )
     try:
         amount_msats = await credit_balance(cashu_token, billing_key, session)
-    except ValueError as e:
-        error_msg = str(e)
-        if "already spent" in error_msg.lower():
-            raise HTTPException(status_code=400, detail="Token already spent")
-        elif "invalid" in error_msg.lower() or "decode" in error_msg.lower():
-            raise HTTPException(status_code=400, detail="Invalid token format")
-        elif "insufficient" in error_msg.lower() or "melt fee" in error_msg.lower():
-            raise HTTPException(
-                status_code=400,
-                detail=f"Token value is too small to cover swap fees. {error_msg}",
-            )
-        elif "failed to melt" in error_msg.lower():
-            raise HTTPException(
-                status_code=400,
-                detail=f"Failed to swap foreign mint token. {error_msg}",
-            )
-        else:
-            raise HTTPException(status_code=400, detail=f"Failed to redeem token: {error_msg}")
     except Exception as e:
-        logger.error(
-            "topup_wallet_endpoint: unhandled error",
-            extra={"error": str(e), "error_type": type(e).__name__},
+        # Shared taxonomy so top-up matches the bearer/X-Cashu paths (503 for an
+        # unreachable mint, 422 for fee/swap failures, 400 for token faults).
+        classified = classify_redemption_error(e)
+        if classified is None:
+            logger.error(
+                "Cashu wallet top-up failed with an unhandled error",
+                extra={
+                    "event": "cashu_topup_failed",
+                    "source_mint": source_mint,
+                    "primary_mint": settings.primary_mint,
+                    "trusted_mints": settings.cashu_mints,
+                    "error_chain": _error_chain(e),
+                },
+            )
+            raise HTTPException(status_code=500, detail="Internal server error")
+        error_type, status_code, message, error_code = classified
+        logger.warning(
+            "Cashu wallet top-up failed",
+            extra={
+                "event": "cashu_topup_failed",
+                "source_mint": source_mint,
+                "primary_mint": settings.primary_mint,
+                "trusted_mints": settings.cashu_mints,
+                "status_code": status_code,
+                "error_type": error_type,
+                "error_code": error_code,
+                "error_chain": _error_chain(e),
+            },
         )
-        raise HTTPException(status_code=500, detail="Internal server error")
+        raise HTTPException(status_code=status_code, detail=message)
+
+    logger.warning(
+        "Cashu wallet top-up completed",
+        extra={
+            "event": "cashu_topup_completed",
+            "source_mint": source_mint,
+            "credited_msats": amount_msats,
+            "key_hash": billing_key.hashed_key[:8],
+        },
+    )
     return {"msats": amount_msats}
 
 
@@ -211,8 +300,24 @@ async def _refund_cache_set(authorization: str, value: dict[str, str]) -> None:
         _refund_cache[key] = (expiry, value)
 
 
+async def _lookup_key_no_create(
+    bearer_value: str, session: AsyncSession
+) -> ApiKey | None:
+    """Look up an existing API key without creating one Used by the refund endpoint"""
+    if bearer_value.startswith("sk-"):
+        return await session.get(ApiKey, bearer_value[3:])
+    if bearer_value.startswith("cashu"):
+        hashed = hashlib.sha256(bearer_value.encode()).hexdigest()
+        return await session.get(ApiKey, hashed)
+    return None
+
+
 async def _restore_balance(
-    session: AsyncSession, hashed_key: str, balance: int, reserved_balance: int
+    session: AsyncSession,
+    hashed_key: str,
+    balance: int,
+    reserved_balance: int,
+    mint_url: str,
 ) -> None:
     """Restore balance after a failed refund mint attempt."""
     restore_stmt = (
@@ -227,7 +332,11 @@ async def _restore_balance(
     await session.commit()
     logger.info(
         "refund_wallet_endpoint: balance restored after mint failure",
-        extra={"hashed_key": hashed_key, "restored_balance": balance},
+        extra={
+            "hashed_key": hashed_key,
+            "restored_balance": balance,
+            "mint_url": mint_url,
+        },
     )
 
 
@@ -261,7 +370,20 @@ async def refund_wallet_endpoint(
         )
         out_tx = out_tx_result.first()
         if out_tx is None:
-            raise HTTPException(status_code=404, detail="Refund not found")
+            # The "in" row exists with a request_id, but the "out" (refund)
+            # row hasn't been written yet — the upstream request is still in
+            # flight and the refund will be minted once it completes. Tell the
+            # client to retry instead of 404ing permanently (race condition
+            # where /v1/wallet/refund is polled before the refund exists).
+            logger.debug(
+                "refund_wallet_endpoint: refund pending (in row exists, out row not yet created)",
+                extra={"request_id": in_tx.request_id},
+            )
+            raise HTTPException(
+                status_code=425,
+                detail="Refund is pending; retry shortly.",
+                headers={"Retry-After": "2"},
+            )
         if out_tx.swept:
             raise HTTPException(status_code=410, detail="Refund has been swept")
 
@@ -282,7 +404,12 @@ async def refund_wallet_endpoint(
         )
 
     bearer_value: str = authorization[7:]
-    key: ApiKey = await validate_bearer_key(bearer_value, session)
+    key: ApiKey | None = await _lookup_key_no_create(bearer_value, session)
+    if key is None:
+        raise HTTPException(
+            status_code=401,
+            detail="Key not found. Deposit first via /v1/wallet/create before requesting a refund.",
+        )
 
     if key.total_balance <= 0:
         if cached := await _refund_cache_get(bearer_value):
@@ -295,9 +422,25 @@ async def refund_wallet_endpoint(
         )
 
     if key.reserved_balance > 0:
-        raise HTTPException(
-            status_code=400,
-            detail="Cannot refund key. There are ongoing requests for this api key.",
+        # Release only durable reservations old enough to be stale. A newer
+        # request on the same aggregate balance must remain reserved.
+        await release_stale_reservations(
+            session,
+            settings.stale_reservation_timeout_seconds,
+            key_hash=key.hashed_key,
+        )
+        await session.refresh(key)
+        if key.reserved_balance > 0:
+            raise HTTPException(
+                status_code=400,
+                detail="Cannot refund key. There are ongoing requests for this api key.",
+            )
+        logger.warning(
+            "refund_wallet_endpoint: released stale reservation before refund",
+            extra={
+                "hashed_key": key.hashed_key,
+                "stale_timeout_seconds": settings.stale_reservation_timeout_seconds,
+            },
         )
 
     remaining_balance_msats: int = key.total_balance
@@ -324,7 +467,7 @@ async def refund_wallet_endpoint(
         .where(col(ApiKey.hashed_key) == key.hashed_key)
         .where(col(ApiKey.balance) == pre_debit_balance)
         .where(col(ApiKey.reserved_balance) == pre_debit_reserved)
-        .values(balance=0, reserved_balance=0)
+        .values(balance=0, reserved_balance=0, reserved_at=None)
     )
     debit_result = await session.exec(debit_stmt)  # type: ignore[call-overload]
     await session.commit()
@@ -336,23 +479,27 @@ async def refund_wallet_endpoint(
             detail="Balance changed concurrently. Please retry the refund.",
         )
 
-    # --- MINT: balance is locked at zero, safe to create the refund token ---
+    # The balance is locked at zero, so it is safe to create the refund token.
+    effective_refund_mint = (
+        key.refund_mint_url
+        if key.refund_mint_url and key.refund_mint_url in settings.cashu_mints
+        else settings.primary_mint
+    )
     try:
+        refund_currency = key.refund_currency or "sat"
         if key.refund_address:
-            from .core.settings import settings as global_settings
-
             await send_to_lnurl(
                 remaining_balance,
                 key.refund_currency or "sat",
-                key.refund_mint_url or global_settings.primary_mint,
+                effective_refund_mint,
                 key.refund_address,
             )
             result = {"recipient": key.refund_address}
         else:
-            refund_currency = key.refund_currency or "sat"
             token = await send_token(
-                remaining_balance, refund_currency, key.refund_mint_url
+                remaining_balance, refund_currency, effective_refund_mint
             )
+            effective_refund_mint = token_mint_url(token, effective_refund_mint)
             result = {"token": token}
 
         if key.refund_currency == "sat":
@@ -373,18 +520,37 @@ async def refund_wallet_endpoint(
 
     except HTTPException:
         # Minting failed — restore the debited balance
-        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved)
+        await _restore_balance(
+            session,
+            key.hashed_key,
+            pre_debit_balance,
+            pre_debit_reserved,
+            key.refund_mint_url or "",
+        )
         raise
     except Exception as e:
         # Minting failed — restore the debited balance
-        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved)
+        await _restore_balance(
+            session,
+            key.hashed_key,
+            pre_debit_balance,
+            pre_debit_reserved,
+            key.refund_mint_url or "",
+        )
         error_msg = str(e)
-        if (
-            "mint" in error_msg.lower()
-            or "connection" in error_msg.lower()
-            or isinstance(e, Exception)
-            and "ConnectError" in str(type(e))
-        ):
+        logger.error(
+            "refund_wallet_endpoint: mint/send failed",
+            extra={
+                "error": error_msg,
+                "error_type": type(e).__name__,
+                "hashed_key": key.hashed_key,
+                "remaining_balance": remaining_balance,
+                "refund_currency": key.refund_currency,
+                "refund_mint_url": key.refund_mint_url,
+                "has_refund_address": bool(key.refund_address),
+            },
+        )
+        if is_mint_connection_error(e):
             raise HTTPException(status_code=503, detail="Mint service unavailable")
         else:
             raise HTTPException(status_code=500, detail="Refund failed")
@@ -397,7 +563,7 @@ async def refund_wallet_endpoint(
                 token=result["token"],
                 amount=remaining_balance,
                 unit=key.refund_currency or "sat",
-                mint_url=key.refund_mint_url,
+                mint_url=effective_refund_mint,
                 typ="out",
                 collected=False,
                 source="apikey",
@@ -502,10 +668,24 @@ async def create_child_key(
             detail=f"Insufficient balance to create {count} child keys. {total_cost} mSats required.",
         )
 
-    # Deduct cost from parent
-    key.balance -= total_cost
-    key.total_spent += total_cost
-    session.add(key)
+    # Deduct cost from parent atomically — guards against concurrent requests
+    # that both pass the balance check above on stale in-memory state.
+    deduct_stmt = (
+        update(ApiKey)
+        .where(col(ApiKey.hashed_key) == key.hashed_key)
+        .where(col(ApiKey.balance) - col(ApiKey.reserved_balance) >= total_cost)
+        .values(
+            balance=col(ApiKey.balance) - total_cost,
+            total_spent=col(ApiKey.total_spent) + total_cost,
+        )
+    )
+    result = await session.exec(deduct_stmt)  # type: ignore[call-overload]
+
+    if result.rowcount == 0:
+        raise HTTPException(
+            status_code=402,
+            detail=f"Insufficient balance to create {count} child keys. {total_cost} mSats required.",
+        )
 
     # Generate new keys
     import secrets
@@ -530,6 +710,7 @@ async def create_child_key(
         new_keys.append("sk-" + new_key_hash)
 
     await session.commit()
+    await session.refresh(key)
 
     response_data = {
         "api_keys": new_keys,
@@ -576,27 +757,6 @@ async def reset_child_key_spent(
     return {"success": True, "message": "Child key balance reset successfully."}
 
 
-@router.get("/cashu-refund/{payment_token_hash}")
-async def get_cashu_refund(
-    payment_token_hash: str,
-    session: AsyncSession = Depends(get_session),
-) -> dict:
-    """Retrieve a stored Cashu refund token by the hash of the original payment token."""
-    result = await session.get(CashuTransaction, payment_token_hash)
-    if result is None:
-        raise HTTPException(status_code=404, detail="Refund not found")
-    if result.swept:
-        raise HTTPException(status_code=410, detail="Refund has been swept")
-    result.collected = True
-    session.add(result)
-    await session.commit()
-    return {
-        "refund_token": result.token,
-        "amount": result.amount,
-        "unit": result.unit,
-    }
-
-
 @router.api_route(
     "/{path:path}",
     methods=["GET", "POST", "PUT", "DELETE"],
@@ -609,7 +769,7 @@ async def wallet_catch_all(path: str) -> NoReturn:
     )
 
 
-balance_router.include_router(lightning_router)
+balance_router.include_router(lightning_router, include_in_schema=False)
 balance_router.include_router(router)
 
 deprecated_wallet_router = APIRouter(prefix="/v1/wallet", include_in_schema=False)

routstr/core/admin.py

@@ -1,12 +1,15 @@
 import asyncio
 import json
+import re
 import secrets
 from datetime import datetime, timezone
 from pathlib import Path
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from pydantic import BaseModel, RootModel
+from pydantic.v1 import ValidationError as PydanticValidationError
 from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
 
 from ..payment.models import _row_to_model, list_models
 from ..proxy import refresh_model_maps, reinitialize_upstreams
@@ -17,17 +20,26 @@ from ..wallet import (
     send_token,
     slow_filter_spend_proofs,
 )
+from . import vault
 from .db import (
     ApiKey,
     CashuTransaction,
     CliToken,
+    LightningInvoice,
     ModelRow,
     UpstreamProviderRow,
     create_session,
+    get_secret,
+    set_admin_password,
+    set_nsec,
+)
+from .db import (
+    store_cashu_transaction_with_retry as store_cashu_transaction,
 )
 from .log_manager import log_manager
 from .logging import get_logger
-from .settings import SettingsService, settings
+from .provider_slugs import allocate_unique_provider_slug
+from .settings import SettingsService, derive_npub_from_nsec, settings
 
 logger = get_logger(__name__)
 
@@ -66,26 +78,89 @@ async def require_admin_api(request: Request) -> None:
 
 
 @admin_router.get("/api/temporary-balances", dependencies=[Depends(require_admin_api)])
-async def get_temporary_balances_api(request: Request) -> list[dict[str, object]]:
+async def get_temporary_balances_api(
+    request: Request,
+    search: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> dict[str, object]:
+    from sqlalchemy import case
+    from sqlmodel import col, func
+
+    filters = []
+    if search:
+        pattern = f"%{search}%"
+        filters.append(
+            col(ApiKey.hashed_key).like(pattern)
+            | col(ApiKey.refund_address).like(pattern)
+        )
+
     async with create_session() as session:
-        result = await session.exec(select(ApiKey))
+        base = select(ApiKey).where(*filters)
+
+        count_result = await session.exec(
+            select(func.count()).select_from(base.subquery())
+        )
+        total = count_result.one()
+
+        # Aggregate totals across the whole (search-filtered) set, not just the
+        # current page. Balance counts only parent (non-child) keys to avoid
+        # double-counting, since child keys draw from their parent's balance.
+        totals_result = await session.exec(
+            select(
+                func.coalesce(
+                    func.sum(
+                        case(
+                            (col(ApiKey.parent_key_hash).is_(None), ApiKey.balance),
+                            else_=0,
+                        )
+                    ),
+                    0,
+                ),
+                func.coalesce(func.sum(ApiKey.total_spent), 0),
+                func.coalesce(func.sum(ApiKey.total_requests), 0),
+            ).where(*filters)
+        )
+        total_balance, total_spent, total_requests = totals_result.one()
+
+        # Latest created first; keys with no created_at (legacy rows) sort last.
+        # Use an explicit CASE rather than relying on dialect NULL-ordering so
+        # the behaviour is identical on SQLite and Postgres.
+        stmt = (
+            base.order_by(
+                case((col(ApiKey.created_at).is_(None), 1), else_=0),
+                col(ApiKey.created_at).desc(),
+            )
+            .offset(offset)
+            .limit(limit)
+        )
+        result = await session.exec(stmt)
         api_keys = result.all()
 
-    return [
-        {
-            "hashed_key": key.hashed_key,
-            "balance": key.balance,
-            "total_spent": key.total_spent,
-            "total_requests": key.total_requests,
-            "refund_address": key.refund_address,
-            "key_expiry_time": key.key_expiry_time,
-            "parent_key_hash": key.parent_key_hash,
-            "balance_limit": key.balance_limit,
-            "balance_limit_reset": key.balance_limit_reset,
-            "validity_date": key.validity_date,
-        }
-        for key in api_keys
-    ]
+    return {
+        "balances": [
+            {
+                "hashed_key": key.hashed_key,
+                "balance": key.balance,
+                "total_spent": key.total_spent,
+                "total_requests": key.total_requests,
+                "refund_address": key.refund_address,
+                "key_expiry_time": key.key_expiry_time,
+                "parent_key_hash": key.parent_key_hash,
+                "balance_limit": key.balance_limit,
+                "balance_limit_reset": key.balance_limit_reset,
+                "validity_date": key.validity_date,
+                "created_at": key.created_at,
+            }
+            for key in api_keys
+        ],
+        "total": total,
+        "totals": {
+            "total_balance": total_balance,
+            "total_spent": total_spent,
+            "total_requests": total_requests,
+        },
+    }
 
 
 class ApiKeyUpdate(BaseModel):
@@ -135,8 +210,6 @@ async def get_settings(request: Request) -> dict:
     data = settings.dict()
     if "upstream_api_key" in data:
         data["upstream_api_key"] = "[REDACTED]" if data["upstream_api_key"] else ""
-    if "admin_password" in data:
-        data["admin_password"] = "[REDACTED]" if data["admin_password"] else ""
     if "nsec" in data:
         data["nsec"] = "[REDACTED]" if data["nsec"] else ""
     return data
@@ -153,20 +226,24 @@ class PasswordUpdate(BaseModel):
 
 @admin_router.patch("/api/settings", dependencies=[Depends(require_admin_api)])
 async def update_settings(request: Request, update: SettingsUpdate) -> dict:
-    # Remove sensitive fields from general settings update
+    # Secrets are not editable through the general settings endpoint; they have
+    # dedicated rotation paths and never reach the settings blob.
     settings_data = update.root.copy()
-    sensitive_fields = ["admin_password", "upstream_api_key", "nsec"]
+    sensitive_fields = ["upstream_api_key", "nsec"]
     for field in sensitive_fields:
         if field in settings_data:
             del settings_data[field]
 
-    async with create_session() as session:
-        new_settings = await SettingsService.update(settings_data, session)
+    try:
+        async with create_session() as session:
+            new_settings = await SettingsService.update(settings_data, session)
+    except PydanticValidationError as e:
+        # Surface validation issues (e.g. non-positive payout amounts)
+        # as a clean 400 instead of a 500.
+        raise HTTPException(status_code=400, detail=e.errors()) from e
     data = new_settings.dict()
     if "upstream_api_key" in data:
         data["upstream_api_key"] = "[REDACTED]" if data["upstream_api_key"] else ""
-    if "admin_password" in data:
-        data["admin_password"] = "[REDACTED]" if data["admin_password"] else ""
     if "nsec" in data:
         data["nsec"] = "[REDACTED]" if data["nsec"] else ""
     return data
@@ -174,44 +251,63 @@ async def update_settings(request: Request, update: SettingsUpdate) -> dict:
 
 @admin_router.patch("/api/password", dependencies=[Depends(require_admin_api)])
 async def update_password(request: Request, password_update: PasswordUpdate) -> dict:
-    current_password = settings.admin_password
-
-    if not current_password:
-        raise HTTPException(status_code=500, detail="Admin password not configured")
-
-    if password_update.current_password != current_password:
-        raise HTTPException(status_code=401, detail="Current password is incorrect")
-
-    # Validate new password
-    new_password = password_update.new_password.strip()
-    if len(new_password) < 6:
-        raise HTTPException(
-            status_code=400, detail="New password must be at least 6 characters"
-        )
-
-    # Update password
     async with create_session() as session:
-        await SettingsService.update({"admin_password": new_password}, session)
+        secret = await get_secret(session)
+
+        if not secret.admin_password_hash:
+            raise HTTPException(
+                status_code=500, detail="Admin password not configured"
+            )
+
+        if not vault.verify_password(
+            password_update.current_password, secret.admin_password_hash
+        ):
+            raise HTTPException(
+                status_code=401, detail="Current password is incorrect"
+            )
+
+        # Validate new password
+        new_password = password_update.new_password.strip()
+        if len(new_password) < vault.MIN_PASSWORD_LENGTH:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    "New password must be at least "
+                    f"{vault.MIN_PASSWORD_LENGTH} characters"
+                ),
+            )
+
+        await set_admin_password(session, new_password)
 
     return {"ok": True, "message": "Password updated successfully"}
 
 
-class SetupRequest(BaseModel):
-    password: str
+class NsecUpdate(BaseModel):
+    nsec: str
 
 
-@admin_router.post("/api/setup")
-async def initial_setup(request: Request, payload: SetupRequest) -> dict[str, object]:
-    if settings.admin_password:
-        raise HTTPException(status_code=409, detail="Admin password already set")
-    pw = (payload.password or "").strip()
-    if len(pw) < 8:
-        raise HTTPException(
-            status_code=400, detail="Password must be at least 8 characters"
-        )
+@admin_router.patch("/api/nsec", dependencies=[Depends(require_admin_api)])
+async def update_nsec(request: Request, payload: NsecUpdate) -> dict[str, object]:
+    # The node's Nostr identity is a secret: it is stored encrypted in the
+    # Secret store, never in the settings blob, so it gets its own endpoint
+    # rather than riding the general settings PATCH (which strips it). An empty
+    # nsec clears the identity.
+    nsec = payload.nsec.strip()
+    npub = ""
+    if nsec:
+        derived = derive_npub_from_nsec(nsec)
+        if not derived:
+            raise HTTPException(status_code=400, detail="Invalid nsec")
+        npub = derived
+
     async with create_session() as session:
-        await SettingsService.update({"admin_password": pw}, session)
-    return {"ok": True}
+        await set_nsec(session, nsec)
+
+    # Reflect the change in the live runtime so Nostr signing/announcements pick
+    # it up without a restart (mirrors what bootstrap_secrets sets at boot).
+    settings.nsec = nsec
+    settings.npub = npub
+    return {"ok": True, "npub": npub}
 
 
 class AdminLoginRequest(BaseModel):
@@ -222,12 +318,16 @@ class AdminLoginRequest(BaseModel):
 async def admin_login(
     request: Request, payload: AdminLoginRequest
 ) -> dict[str, object]:
-    admin_pw = settings.admin_password
+    async with create_session() as session:
+        secret = await get_secret(session)
+        # Read the hash while the session is open; the ORM object is detached
+        # once the context exits and its attributes can no longer be loaded.
+        password_hash = secret.admin_password_hash
 
-    if not admin_pw:
+    if not password_hash:
         raise HTTPException(status_code=500, detail="Admin password not configured")
 
-    if payload.password != admin_pw:
+    if not vault.verify_password(payload.password, password_hash):
         raise HTTPException(status_code=401, detail="Invalid password")
 
     token = secrets.token_urlsafe(32)
@@ -338,12 +438,11 @@ async def withdraw(
     # Get wallet and check balance
     from .settings import settings as global_settings
 
-    wallet = await get_wallet(
-        withdraw_request.mint_url or global_settings.primary_mint, withdraw_request.unit
-    )
+    effective_mint = withdraw_request.mint_url or global_settings.primary_mint
+    wallet = await get_wallet(effective_mint, withdraw_request.unit)
     proofs = get_proofs_per_mint_and_unit(
         wallet,
-        withdraw_request.mint_url or global_settings.primary_mint,
+        effective_mint,
         withdraw_request.unit,
         not_reserved=True,
     )
@@ -359,8 +458,27 @@ async def withdraw(
         raise HTTPException(status_code=400, detail="Insufficient wallet balance")
 
     token = await send_token(
-        withdraw_request.amount, withdraw_request.unit, withdraw_request.mint_url
+        withdraw_request.amount, withdraw_request.unit, effective_mint
     )
+    try:
+        await store_cashu_transaction(
+            token=token,
+            amount=withdraw_request.amount,
+            unit=withdraw_request.unit,
+            mint_url=effective_mint,
+            typ="out",
+            collected=False,
+            source="admin",
+        )
+    except Exception:
+        logger.critical(
+            "Admin withdrawal token issued without a persisted audit record",
+            extra={
+                "amount": withdraw_request.amount,
+                "unit": withdraw_request.unit,
+                "mint_url": effective_mint,
+            },
+        )
     return {"token": token}
 
 
@@ -386,19 +504,17 @@ 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
@@ -454,7 +570,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,
             )
@@ -473,7 +589,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(
@@ -486,13 +602,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"
@@ -506,9 +621,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"
@@ -523,10 +640,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:
@@ -545,7 +664,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(
@@ -553,15 +672,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
@@ -615,7 +733,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)
@@ -632,6 +750,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
@@ -640,6 +837,7 @@ class UpstreamProviderCreate(BaseModel):
     enabled: bool = True
     provider_fee: float = 1.01
     provider_settings: dict | None = None
+    slug: str | None = None
 
 
 class UpstreamProviderUpdate(BaseModel):
@@ -650,6 +848,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)])
@@ -657,21 +899,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)])
@@ -691,7 +919,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,
@@ -708,99 +943,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)])
@@ -815,17 +1032,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,
         )
@@ -915,13 +1131,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
 
@@ -952,15 +1166,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(
@@ -1080,15 +1292,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":
@@ -1135,14 +1345,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":
@@ -1461,12 +1669,64 @@ async def get_transactions_api(
         )
         total = count_result.one()
 
-        stmt = base.order_by(col(CashuTransaction.created_at).desc()).offset(offset).limit(limit)
+        stmt = (
+            base.order_by(col(CashuTransaction.created_at).desc())
+            .offset(offset)
+            .limit(limit)
+        )
         results = await session.exec(stmt)
         transactions = results.all()
 
         return {
-            "transactions": [tx.dict() for tx in transactions],
+            "transactions": [
+                tx.dict(exclude={"sweep_started_at"}) for tx in transactions
+            ],
+            "total": total,
+        }
+
+
+@admin_router.get(
+    "/api/lightning-invoices", dependencies=[Depends(require_admin_api)]
+)
+async def get_lightning_invoices_api(
+    status: str | None = None,
+    purpose: str | None = None,
+    search: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> dict:
+    async with create_session() as session:
+        from sqlmodel import col, func
+
+        base = select(LightningInvoice)
+        if status:
+            base = base.where(LightningInvoice.status == status)
+        if purpose:
+            base = base.where(LightningInvoice.purpose == purpose)
+        if search:
+            pattern = f"%{search}%"
+            base = base.where(
+                (col(LightningInvoice.id).like(pattern))
+                | (col(LightningInvoice.bolt11).like(pattern))
+                | (col(LightningInvoice.payment_hash).like(pattern))
+                | (col(LightningInvoice.api_key_hash).like(pattern))
+            )
+
+        count_result = await session.exec(
+            select(func.count()).select_from(base.subquery())
+        )
+        total = count_result.one()
+
+        stmt = (
+            base.order_by(col(LightningInvoice.created_at).desc())
+            .offset(offset)
+            .limit(limit)
+        )
+        results = await session.exec(stmt)
+        invoices = results.all()
+
+        return {
+            "invoices": [inv.dict() for inv in invoices],
             "total": total,
         }
 
@@ -1475,15 +1735,13 @@ async def get_transactions_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

@@ -1,28 +1,91 @@
+import asyncio
+import hashlib
 import os
 import pathlib
 import sqlite3
 import time
 import uuid
 from contextlib import asynccontextmanager
+from enum import Enum
 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.exc import OperationalError
+from sqlalchemy import Index, UniqueConstraint, case, delete, event, or_
+from sqlalchemy.engine import make_url
+from sqlalchemy.exc import IntegrityError, OperationalError
+from sqlalchemy.ext.asyncio import AsyncEngine
 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
 
 from .logging import get_logger
+from .settings import settings
 
 logger = get_logger(__name__)
 
 DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite+aiosqlite:///keys.db")
 
 
-engine = create_async_engine(DATABASE_URL, echo=False)  # echo=True for debugging SQL
+def create_db_engine(database_url: str = DATABASE_URL) -> AsyncEngine:
+    """Build and instrument an async engine from environment-only settings."""
+    url = make_url(database_url)
+    backend = url.get_backend_name()
+    is_sqlite = backend == "sqlite"
+    is_memory_sqlite = is_sqlite and url.database in {None, "", ":memory:"}
+    pool_pre_ping = settings.database_pool_pre_ping or not is_sqlite
+    options: dict[str, int | float | bool] = {"pool_pre_ping": pool_pre_ping}
+    if not is_memory_sqlite:
+        options.update(
+            pool_size=settings.database_pool_size,
+            max_overflow=settings.database_max_overflow,
+            pool_timeout=settings.database_pool_timeout,
+            pool_recycle=settings.database_pool_recycle,
+        )
+
+    logger.info(
+        "Database pool configured",
+        extra={
+            "database_url_backend": backend,
+            "in_memory_sqlite": is_memory_sqlite,
+            **options,
+        },
+    )
+    created_engine = create_async_engine(database_url, echo=False, **options)
+    hold_warn_seconds = settings.database_pool_hold_warn_seconds
+
+    def record_pool_checkout(
+        dbapi_connection: object, connection_record: object, proxy: object
+    ) -> None:
+        connection_record.info["routstr_checked_out_at"] = time.monotonic()  # type: ignore[attr-defined]
+
+    def record_pool_checkin(
+        dbapi_connection: object, connection_record: object
+    ) -> None:
+        checked_out_at = connection_record.info.pop(  # type: ignore[attr-defined]
+            "routstr_checked_out_at", None
+        )
+        if checked_out_at is None:
+            return
+        held_seconds = time.monotonic() - checked_out_at
+        if held_seconds >= hold_warn_seconds:
+            logger.warning(
+                "Database connection held longer than threshold",
+                extra={
+                    "held_seconds": round(held_seconds, 3),
+                    "threshold_seconds": hold_warn_seconds,
+                    "pool_status": created_engine.pool.status(),
+                },
+            )
+
+    event.listen(created_engine.sync_engine, "checkout", record_pool_checkout)
+    event.listen(created_engine.sync_engine, "checkin", record_pool_checkin)
+    return created_engine
+
+
+engine = create_db_engine()
 
 
 class ApiKey(SQLModel, table=True):  # type: ignore
@@ -33,6 +96,14 @@ class ApiKey(SQLModel, table=True):  # type: ignore
     reserved_balance: int = Field(
         default=0, description="Reserved balance in millisatoshis (msats)"
     )
+    reserved_at: int | None = Field(
+        default=None,
+        description=(
+            "Unix timestamp of the most recent balance reservation. Used to "
+            "detect and release stale reservations (e.g. after client "
+            "disconnects). NULL when no reservation has been made yet."
+        ),
+    )
     refund_address: str | None = Field(
         default=None,
         description="Lightning address to refund remaining balance after key expires",
@@ -45,6 +116,14 @@ class ApiKey(SQLModel, table=True):  # type: ignore
         default=0, description="Total spent in millisatoshis (msats)"
     )
     total_requests: int = Field(default=0)
+    created_at: int | None = Field(
+        default_factory=lambda: int(time.time()),
+        nullable=True,
+        description=(
+            "Unix timestamp when the key was created. Nullable: keys created "
+            "before this column existed have no value and sort last."
+        ),
+    )
     refund_mint_url: str | None = Field(
         default=None,
         description="URL of the mint used to create the cashu-token",
@@ -79,12 +158,194 @@ class ApiKey(SQLModel, table=True):  # type: ignore
 
 
 async def reset_all_reserved_balances(session: AsyncSession) -> None:
-    stmt = update(ApiKey).values(reserved_balance=0)
-    await session.exec(stmt)  # type: ignore[call-overload]
+    """Release every active durable reservation during explicit startup reset."""
+    await session.exec(  # type: ignore[call-overload]
+        update(ReservationRelease)
+        .where(col(ReservationRelease.status) == "active")
+        .values(status="released")
+    )
+    await session.exec(  # type: ignore[call-overload]
+        update(ApiKey).values(reserved_balance=0, reserved_at=None)
+    )
     await session.commit()
     logger.info("Reset reserved balances on startup")
 
 
+async def release_stale_reservations(
+    session: AsyncSession,
+    max_age_seconds: int,
+    *,
+    key_hash: str | None = None,
+) -> int:
+    """Release stale durable reservations without touching newer reservations."""
+    cutoff = int(time.time()) - max_age_seconds
+    query = (
+        select(ReservationRelease)
+        .where(col(ReservationRelease.status) == "active")
+        .where(col(ReservationRelease.created_at) < cutoff)
+    )
+    if key_hash is not None:
+        query = query.where(
+            or_(
+                col(ReservationRelease.key_hash) == key_hash,
+                col(ReservationRelease.billing_key_hash) == key_hash,
+            )
+        )
+    reservations = (await session.exec(query)).all()
+    released = 0
+
+    for reservation in reservations:
+        transition = await session.exec(  # type: ignore[call-overload]
+            update(ReservationRelease)
+            .where(col(ReservationRelease.id) == reservation.id)
+            .where(col(ReservationRelease.status) == "active")
+            .values(status="released")
+        )
+        if transition.rowcount != 1:
+            continue
+
+        values = {
+            "reserved_balance": col(ApiKey.reserved_balance)
+            - reservation.reserved_msats,
+            "reserved_at": case(
+                (
+                    col(ApiKey.reserved_balance) - reservation.reserved_msats > 0,
+                    col(ApiKey.reserved_at),
+                ),
+                else_=None,
+            ),
+        }
+        parent_result = await session.exec(  # type: ignore[call-overload]
+            update(ApiKey)
+            .where(col(ApiKey.hashed_key) == reservation.billing_key_hash)
+            .where(col(ApiKey.reserved_balance) >= reservation.reserved_msats)
+            .values(**values)
+        )
+        if parent_result.rowcount != 1:
+            await session.rollback()
+            return 0
+
+        if reservation.billing_key_hash != reservation.key_hash:
+            child_result = await session.exec(  # type: ignore[call-overload]
+                update(ApiKey)
+                .where(col(ApiKey.hashed_key) == reservation.key_hash)
+                .where(col(ApiKey.reserved_balance) >= reservation.reserved_msats)
+                .values(**values)
+            )
+            if child_result.rowcount != 1:
+                await session.rollback()
+                return 0
+        released += 1
+
+    # Rolling upgrades can leave aggregate reservations created before durable
+    # reservation rows existed. Release only stale aggregates that have no active
+    # durable owner; targeted refund cleanup also heals legacy NULL timestamps.
+    legacy_query = select(ApiKey).where(col(ApiKey.reserved_balance) > 0)
+    if key_hash is None:
+        legacy_query = legacy_query.where(col(ApiKey.reserved_at).is_not(None)).where(
+            col(ApiKey.reserved_at) < cutoff
+        )
+    else:
+        legacy_query = legacy_query.where(
+            or_(
+                col(ApiKey.hashed_key) == key_hash,
+                col(ApiKey.parent_key_hash) == key_hash,
+            )
+        ).where(
+            or_(col(ApiKey.reserved_at).is_(None), col(ApiKey.reserved_at) < cutoff)
+        )
+
+    for legacy_key in (await session.exec(legacy_query)).all():
+        active_owner = (
+            await session.exec(
+                select(ReservationRelease.id)
+                .where(col(ReservationRelease.status) == "active")
+                .where(
+                    or_(
+                        col(ReservationRelease.key_hash) == legacy_key.hashed_key,
+                        col(ReservationRelease.billing_key_hash)
+                        == legacy_key.hashed_key,
+                    )
+                )
+                .limit(1)
+            )
+        ).first()
+        if active_owner is not None:
+            continue
+        legacy_key.reserved_balance = 0
+        legacy_key.reserved_at = None
+        session.add(legacy_key)
+        released += 1
+
+    await session.commit()
+    if released:
+        logger.warning(
+            "Released stale reservations",
+            extra={
+                "released_reservations": released,
+                "max_age_seconds": max_age_seconds,
+            },
+        )
+    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)
@@ -121,17 +382,33 @@ class LightningInvoice(SQLModel, table=True):  # type: ignore
     description: str = Field(description="Invoice description")
     payment_hash: str = Field(description="Payment hash for tracking", unique=True)
     status: str = Field(
-        default="pending", description="pending, paid, expired, cancelled"
+        default="pending",
+        description="pending, paid, expired, cancelled, reconciliation_required",
     )
     api_key_hash: str | None = Field(
         default=None, description="Associated API key hash for topup operations"
     )
     purpose: str = Field(description="create or topup")
+    mint_url: str | None = Field(
+        default=None, description="Mint URL where the quote was created (fallback tracking)"
+    )
     created_at: int = Field(
         default_factory=lambda: int(time.time()), description="Unix timestamp"
     )
     expires_at: int = Field(description="Unix timestamp when invoice expires")
     paid_at: int | None = Field(default=None, description="Unix timestamp when paid")
+    balance_limit: int | None = Field(
+        default=None,
+        description="Max spendable msats for the created key",
+    )
+    balance_limit_reset: str | None = Field(
+        default=None,
+        description="Reset policy for balance limit (daily, weekly, monthly)",
+    )
+    validity_date: int | None = Field(
+        default=None,
+        description="Unix timestamp after which the created key expires",
+    )
 
 
 class CashuTransaction(SQLModel, table=True):  # type: ignore
@@ -154,6 +431,10 @@ class CashuTransaction(SQLModel, table=True):  # type: ignore
     )
     collected: bool = Field(default=False)
     swept: bool = Field(default=False)
+    sweep_started_at: int | None = Field(
+        default=None,
+        description="Unix timestamp for a recoverable refund-sweep claim",
+    )
     source: str = Field(
         default="x-cashu",
         description="Payment source: x-cashu or apikey",
@@ -177,10 +458,13 @@ async def store_cashu_transaction(
     created_at: int | None = None,
     source: str = "x-cashu",
     api_key_hashed_key: str | None = None,
-) -> None:
+    transaction_id: str | None = None,
+    log_failure: bool = True,
+) -> bool:
     try:
         async with create_session() as session:
             tx = CashuTransaction(
+                id=transaction_id or uuid.uuid4().hex,
                 token=token,
                 amount=amount,
                 unit=unit,
@@ -194,11 +478,93 @@ async def store_cashu_transaction(
             )
             session.add(tx)
             await session.commit()
-    except Exception as e:
-        logger.warning(
-            f"Failed to store cashu transaction: {e} (type={typ})",
-            extra={"error": str(e), "type": typ},
-        )
+    except Exception:
+        if log_failure:
+            logger.critical(
+                "Failed to store Cashu transaction",
+                extra={"type": typ, "request_id": request_id, "source": source},
+                exc_info=True,
+            )
+        raise
+    return True
+
+
+async def _cashu_transaction_exists(transaction_id: str) -> bool:
+    async with create_session() as session:
+        return await session.get(CashuTransaction, transaction_id) is not None
+
+
+async def store_cashu_transaction_with_retry(
+    token: str,
+    amount: int,
+    unit: str,
+    mint_url: str | None = None,
+    typ: str = "out",
+    request_id: str | None = None,
+    collected: bool = False,
+    created_at: int | None = None,
+    source: str = "x-cashu",
+    api_key_hashed_key: str | None = None,
+    max_attempts: int = 3,
+) -> bool:
+    """Retry a critical Cashu transaction write with bounded backoff."""
+    transaction_id = hashlib.sha256(f"{typ}\0{token}".encode()).hexdigest()
+    last_error: Exception | None = None
+    for attempt in range(1, max_attempts + 1):
+        try:
+            return await store_cashu_transaction(
+                token=token,
+                amount=amount,
+                unit=unit,
+                mint_url=mint_url,
+                typ=typ,
+                request_id=request_id,
+                collected=collected,
+                created_at=created_at,
+                source=source,
+                api_key_hashed_key=api_key_hashed_key,
+                transaction_id=transaction_id,
+                log_failure=False,
+            )
+        except IntegrityError as error:
+            try:
+                if await _cashu_transaction_exists(transaction_id):
+                    return True
+            except Exception as lookup_error:
+                last_error = lookup_error
+            else:
+                last_error = error
+        except Exception as error:
+            last_error = error
+
+        if last_error is not None:
+            if attempt == max_attempts:
+                break
+            delay = 0.25 * (2 ** (attempt - 1))
+            logger.warning(
+                "Cashu transaction storage failed; retrying",
+                extra={
+                    "type": typ,
+                    "request_id": request_id,
+                    "attempt": attempt,
+                    "max_attempts": max_attempts,
+                    "retry_delay_seconds": delay,
+                },
+            )
+            await asyncio.sleep(delay)
+
+    logger.critical(
+        "Cashu transaction storage failed after bounded retries",
+        extra={
+            "type": typ,
+            "request_id": request_id,
+            "attempts": max_attempts,
+            "error": str(last_error),
+        },
+    )
+    if last_error is None:
+        raise RuntimeError("Cashu transaction storage failed without an exception")
+    raise last_error
 
 
 class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
@@ -209,6 +575,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."
     )
@@ -230,12 +602,64 @@ class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
     )
 
 
+class ReservationRelease(SQLModel, table=True):  # type: ignore
+    __tablename__ = "reservation_releases"
+    __table_args__ = (
+        Index("ix_reservation_releases_status_created_at", "status", "created_at"),
+    )
+
+    id: str = Field(primary_key=True)
+    key_hash: str = Field(index=True)
+    billing_key_hash: str = Field(index=True)
+    reserved_msats: int
+    status: str = Field(default="active")
+    created_at: int = Field(default_factory=lambda: int(time.time()))
+
+
 class RoutstrFee(SQLModel, table=True):  # type: ignore
     __tablename__ = "routstr_fees"
     id: int = Field(default=1, primary_key=True)
     accumulated_msats: int = Field(default=0)
     total_paid_msats: int = Field(default=0)
     last_paid_at: int | None = Field(default=None)
+    payout_in_progress_msats: int = Field(default=0)
+    payout_started_at: int | None = Field(default=None)
+
+
+class NsecState(str, Enum):
+    """Ownership state of the node's nsec — an explicit 3-state machine.
+
+    The single ``encrypted_nsec`` column cannot distinguish "never migrated" from
+    "intentionally cleared" (both leave it empty), which let a cleared identity be
+    resurrected from a stale legacy ``NSEC``. This names the three states so the
+    bootstrap branches on ownership rather than inferring it:
+
+    * ``legacy`` — the vault has not taken ownership; a plaintext ``NSEC`` (env or
+      old settings blob) may still exist and should be migrated in once.
+    * ``encrypted`` — the vault owns a ciphertext; decrypt it, never re-read env.
+    * ``cleared`` — the vault owns it but the operator emptied it; stay empty,
+      never re-import from a stale legacy copy.
+    """
+
+    legacy = "legacy"
+    encrypted = "encrypted"
+    cleared = "cleared"
+
+
+class Secret(SQLModel, table=True):  # type: ignore
+    """Node-level secrets, stored encrypted/hashed at rest (singleton, id=1).
+
+    The asymmetric column names document the encoding: ``_hash`` is one-way
+    (scrypt, verify only) while ``encrypted_`` is reversible (Fernet). Per-provider
+    upstream keys live on ``upstream_providers``, not here. See ``routstr.core.vault``.
+    """
+
+    __tablename__ = "secrets"
+    id: int = Field(default=1, primary_key=True)
+    admin_password_hash: str | None = Field(default=None)
+    encrypted_nsec: str | None = Field(default=None)
+    nsec_state: NsecState = Field(default=NsecState.legacy)
+    updated_at: int | None = Field(default=None)
 
 
 class CliToken(SQLModel, table=True):  # type: ignore
@@ -276,28 +700,136 @@ async def get_routstr_fee(session: AsyncSession) -> RoutstrFee:
     return fee
 
 
-async def reset_routstr_fee(session: AsyncSession, paid_msats: int) -> None:
+async def get_secret(session: AsyncSession) -> Secret:
+    secret = await session.get(Secret, 1)
+    if secret is None:
+        secret = Secret(id=1)
+        session.add(secret)
+        try:
+            await session.commit()
+        except IntegrityError:
+            # Another worker created the singleton row between our read and
+            # insert (multiple workers booting against one shared DB). Roll back
+            # and read the row they committed instead of failing startup.
+            await session.rollback()
+            secret = await session.get(Secret, 1)
+            if secret is None:
+                raise
+            return secret
+        await session.refresh(secret)
+    return secret
+
+
+async def set_admin_password(session: AsyncSession, password: str) -> None:
+    """Store the admin password as a one-way hash on the Secret singleton."""
+    from .vault import hash_password
+
+    secret = await get_secret(session)
+    secret.admin_password_hash = hash_password(password)
+    secret.updated_at = int(time.time())
+    session.add(secret)
+    await session.commit()
+
+
+async def set_nsec(session: AsyncSession, nsec: str) -> None:
+    """Store the node's nsec, Fernet-encrypted, on the Secret singleton.
+
+    An empty string clears it (the node then holds no Nostr identity and signs
+    no events). Either way the vault now owns the nsec, so the state moves off
+    ``legacy``: a cleared identity (``cleared``) must not be resurrected from a
+    stale legacy ``NSEC`` on the next boot.
+    """
+    from .vault import encrypt
+
+    secret = await get_secret(session)
+    secret.encrypted_nsec = encrypt(nsec) if nsec else None
+    secret.nsec_state = NsecState.encrypted if nsec else NsecState.cleared
+    secret.updated_at = int(time.time())
+    session.add(secret)
+    await session.commit()
+
+
+async def reset_routstr_fee(session: AsyncSession, paid_msats: int) -> bool:
+    """Checkpoint a fee payout before making the external payment."""
     stmt = (
         update(RoutstrFee)
         .where(col(RoutstrFee.id) == 1)
+        .where(col(RoutstrFee.payout_in_progress_msats) == 0)
+        .where(col(RoutstrFee.accumulated_msats) >= paid_msats)
         .values(
             accumulated_msats=RoutstrFee.accumulated_msats - paid_msats,
+            payout_in_progress_msats=paid_msats,
+            payout_started_at=int(time.time()),
+        )
+    )
+    result = await session.exec(stmt)  # type: ignore[call-overload]
+    await session.commit()
+    return result.rowcount == 1
+
+
+async def complete_routstr_fee_payout(
+    session: AsyncSession, paid_msats: int
+) -> bool:
+    """Mark a checkpointed payout complete after the external payment succeeds."""
+    stmt = (
+        update(RoutstrFee)
+        .where(col(RoutstrFee.id) == 1)
+        .where(col(RoutstrFee.payout_in_progress_msats) == paid_msats)
+        .values(
+            payout_in_progress_msats=0,
+            payout_started_at=None,
             total_paid_msats=RoutstrFee.total_paid_msats + paid_msats,
             last_paid_at=int(time.time()),
         )
     )
-    await session.exec(stmt)  # type: ignore[call-overload]
+    result = await session.exec(stmt)  # type: ignore[call-overload]
     await session.commit()
+    return result.rowcount == 1
 
 
-async def balances_for_mint_and_unit(
+async def total_user_liability(db_session: AsyncSession) -> int:
+    """Return all outstanding API-key balances in millisatoshis."""
+    result = await db_session.exec(select(func.sum(ApiKey.balance)))
+    return int(result.one() or 0)
+
+
+async def balance_for_mint_and_unit(
     db_session: AsyncSession, mint_url: str, unit: str
 ) -> int:
-    query = select(func.sum(ApiKey.balance)).where(
-        ApiKey.refund_mint_url == mint_url, ApiKey.refund_currency == unit
+    """Return the user liability for one mint and unit in millisatoshis."""
+    result = await db_session.exec(
+        select(func.sum(ApiKey.balance)).where(
+            col(ApiKey.refund_mint_url) == mint_url,
+            col(ApiKey.refund_currency) == unit,
+        )
+    )
+    return int(result.one() or 0)
+
+
+async def balances_by_mint_and_unit(
+    db_session: AsyncSession, mint_urls: list[str], units: list[str]
+) -> dict[tuple[str, str], int]:
+    """Return requested user liabilities grouped by mint and unit."""
+    if not mint_urls or not units:
+        return {}
+    query = (
+        select(
+            col(ApiKey.refund_mint_url),
+            col(ApiKey.refund_currency),
+            func.sum(ApiKey.balance),
+        )
+        .where(
+            col(ApiKey.refund_mint_url).in_(mint_urls),
+            col(ApiKey.refund_currency).in_(units),
+        )
+        .group_by(col(ApiKey.refund_mint_url), col(ApiKey.refund_currency))
     )
     result = await db_session.exec(query)
-    return result.one() or 0
+    return {
+        (mint_url, unit): int(balance or 0)
+        for mint_url, unit, balance in result.all()
+        if mint_url is not None and unit is not None
+    }
 
 
 async def init_db() -> None:

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,8 +11,13 @@ from starlette.exceptions import HTTPException
 from starlette.responses import Response as StarletteResponse
 from starlette.types import Scope
 
-from ..auth import periodic_key_reset
+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 (
     announce_provider,
     providers_cache_refresher,
@@ -23,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
@@ -30,7 +36,8 @@ from .db import create_session, init_db, run_migrations
 from .exceptions import general_exception_handler, http_exception_handler
 from .logging import get_logger, setup_logging
 from .middleware import LoggingMiddleware
-from .settings import SettingsService
+from .not_found import _NOT_FOUND_HTML, not_found_catch_all  # noqa: F401
+from .settings import SettingsService, bootstrap_secrets
 from .settings import settings as global_settings
 from .version import __version__
 
@@ -52,15 +59,23 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
     models_refresh_task = None
     model_maps_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
+    invoice_watcher_task = None
 
     try:
         # Apply litellm-wide settings (drop_params, chat-completions URL,
         # 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()
 
@@ -70,17 +85,20 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
 
         # Initialize application settings (env -> computed -> DB precedence)
         async with create_session() as session:
+            # Move secrets into the encrypted/hashed store and decrypt the nsec
+            # into the in-memory settings BEFORE initializing settings: the
+            # initialize step strips secrets from the persisted blob, so legacy
+            # plaintext (env or old blob) must be migrated into the Secret store
+            # first or the only copy of a blob-only secret would be lost.
+            # Generates and logs an admin password on a fresh node; fails fast if
+            # a stored secret can't be decrypted.
+            await bootstrap_secrets(session)
             s = await SettingsService.initialize(session)
             if s.reset_reserved_balance_on_startup:
                 from .db import reset_all_reserved_balances
 
                 await reset_all_reserved_balances(session)
 
-        if not s.admin_password:
-            logger.warning(
-                f"Admin password is not set. Visit {s.http_url or 'http://localhost:8000'}/admin to set the password."
-            )
-
         # Apply app metadata from settings
         try:
             app.title = s.name
@@ -119,9 +137,14 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
         if global_settings.providers_refresh_interval_seconds > 0:
             providers_task = asyncio.create_task(providers_cache_refresher())
         key_reset_task = asyncio.create_task(periodic_key_reset())
+        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())
+        invoice_watcher_task = asyncio.create_task(periodic_invoice_watcher())
 
         yield
 
@@ -155,12 +178,18 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
             model_maps_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:
             refund_sweep_task.cancel()
         if routstr_fee_task is not None:
             routstr_fee_task.cancel()
+        if invoice_watcher_task is not None:
+            invoice_watcher_task.cancel()
 
         try:
             tasks_to_wait = []
@@ -182,12 +211,18 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
                 tasks_to_wait.append(model_maps_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:
                 tasks_to_wait.append(refund_sweep_task)
             if routstr_fee_task is not None:
                 tasks_to_wait.append(routstr_fee_task)
+            if invoice_watcher_task is not None:
+                tasks_to_wait.append(invoice_watcher_task)
 
             if tasks_to_wait:
                 await asyncio.gather(*tasks_to_wait, return_exceptions=True)
@@ -225,7 +260,20 @@ app.add_middleware(
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],
-    expose_headers=["x-routstr-request-id", "x-cashu"],
+    expose_headers=[
+        "x-routstr-request-id",
+        "x-cashu",
+        "x-routstr-cost-msats",
+        "x-routstr-cost-usd",
+        "x-routstr-input-cost-msats",
+        "x-routstr-output-cost-msats",
+        # EHBP (Tinfoil) protocol headers must be exposed so browser clients
+        # can detect and decrypt encrypted responses. Without these, the
+        # browser hides them via CORS and the SDK treats the response as a
+        # plaintext proxy error, returning raw ciphertext.
+        "Ehbp-Response-Nonce",
+        "Ehbp-Encapsulated-Key",
+    ],
 )
 
 # Add logging middleware
@@ -347,7 +395,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)
@@ -364,6 +415,7 @@ else:
 app.include_router(models_router)
 app.include_router(admin_router)
 app.include_router(balance_router)
+app.include_router(lightning_router)
 app.include_router(deprecated_wallet_router)
 app.include_router(providers_router)
 app.include_router(proxy_router)

routstr/core/not_found.py

@@ -0,0 +1,55 @@
+"""Shared 404 handler used by the proxy catch-all and tests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import Request
+from fastapi.responses import HTMLResponse, JSONResponse, Response
+
+_NOT_FOUND_HTML_FILE = Path(__file__).parent.parent.parent / "ui_out" / "404.html"
+
+
+def _read_not_found_html() -> str | None:
+    try:
+        return _NOT_FOUND_HTML_FILE.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+_NOT_FOUND_HTML: str | None = _read_not_found_html()
+
+
+def build_not_found_response(request: Request, path: str) -> Response:
+    """Return a 404 response.
+
+    HTML 404 page only for GET requests from browsers (Accept: text/html).
+    All POST requests and API clients receive a JSON 404.
+    """
+    accept = request.headers.get("accept", "").lower()
+    prefers_html = (
+        request.method == "GET"
+        and "text/html" in accept
+        and "application/json" not in accept
+    )
+    request_id = getattr(request.state, "request_id", "unknown")
+
+    if prefers_html and _NOT_FOUND_HTML is not None:
+        return HTMLResponse(content=_NOT_FOUND_HTML, status_code=404)
+
+    return JSONResponse(
+        status_code=404,
+        content={
+            "error": {
+                "message": f"Path '/{path}' not found",
+                "type": "not_found",
+                "code": 404,
+            },
+            "request_id": request_id,
+        },
+    )
+
+
+async def not_found_catch_all(request: Request, path: str) -> Response:
+    """ASGI handler form of :func:`build_not_found_response`."""
+    return build_not_found_response(request, path)

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

@@ -3,6 +3,8 @@ from __future__ import annotations
 import asyncio
 import json
 import os
+import secrets
+import time
 from datetime import datetime, timezone
 from typing import Any
 
@@ -26,7 +28,6 @@ class Settings(BaseSettings):
     # Core
     upstream_base_url: str = Field(default="", env="UPSTREAM_BASE_URL")
     upstream_api_key: str = Field(default="", env="UPSTREAM_API_KEY")
-    admin_password: str = Field(default="", env="ADMIN_PASSWORD")
 
     # Node info
     name: str = Field(default="ARoutstrNode", env="NAME")
@@ -40,6 +41,30 @@ class Settings(BaseSettings):
     receive_ln_address: str = Field(default="", env="RECEIVE_LN_ADDRESS")
     primary_mint: str = Field(default="", env="PRIMARY_MINT_URL")
     primary_mint_unit: str = Field(default="sat", env="PRIMARY_MINT_UNIT")
+    mint_operation_concurrency: int = Field(
+        default=4, ge=1, env="MINT_OPERATION_CONCURRENCY"
+    )
+
+    # Lightning payout configuration
+    # Minimum available balance (in satoshis) before profit is paid out over
+    # Lightning
+    min_payout_sat: int = Field(default=210, gt=0, env="MIN_PAYOUT_SAT")
+    # Interval (seconds) between periodic payout attempts. Must be positive.
+    payout_interval_seconds: int = Field(
+        default=900, gt=0, env="PAYOUT_INTERVAL_SECONDS"
+    )
+    # Timeout (seconds) for individual mint API operations (melt, mint, swap,
+    # checkstate). When a mint is slow or rate-limiting, operations are
+    # cancelled after this delay instead of hanging indefinitely.
+    mint_operation_timeout_seconds: int = Field(
+        default=30, gt=0, env="MINT_OPERATION_TIMEOUT_SECONDS"
+    )
+    # Maximum concurrent API operations per mint. Actual mint quotas vary by
+    # endpoint, so 429 responses drive adaptive cooldown instead of fixed RPM
+    # pacing. 0 = unlimited concurrency.
+    mint_max_concurrency: int = Field(default=4, ge=0, env="MINT_MAX_CONCURRENCY")
+    # Max retries when a mint returns 429 or times out (exponential backoff).
+    mint_retry_max_attempts: int = Field(default=3, ge=0, env="MINT_RETRY_MAX_ATTEMPTS")
 
     # Pricing
     # Default behavior: derive pricing from MODELS
@@ -58,6 +83,20 @@ class Settings(BaseSettings):
     reset_reserved_balance_on_startup: bool = Field(
         default=True, env="RESET_RESERVED_BALANCE_ON_STARTUP"
     )  # deactivate in horizontal scaling setups
+    # Reservations older than this are considered leaked (client disconnect,
+    # crash, abandoned stream) and released by the background sweeper and the
+    # refund endpoint.
+    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")
@@ -74,7 +113,27 @@ class Settings(BaseSettings):
     enable_pricing_refresh: bool = Field(default=True, env="ENABLE_PRICING_REFRESH")
     enable_models_refresh: bool = Field(default=True, env="ENABLE_MODELS_REFRESH")
     refund_cache_ttl_seconds: int = Field(default=3600, env="REFUND_CACHE_TTL_SECONDS")
-    refund_sweep_ttl_seconds: int = Field(default=604800, env="REFUND_SWEEP_TTL_SECONDS")
+    refund_sweep_ttl_seconds: int = Field(
+        default=604800, env="REFUND_SWEEP_TTL_SECONDS"
+    )
+    refund_sweep_claim_timeout_seconds: int = Field(
+        default=900, gt=0, env="REFUND_SWEEP_CLAIM_TIMEOUT_SECONDS"
+    )
+
+    # Database connection-pool controls (advanced). Capacity defaults match
+    # SQLAlchemy's established queue-pool behavior. Pre-ping is enabled by the
+    # engine factory for networked backends; SQLite can explicitly opt in.
+    # These fields are env-only below.
+    database_pool_size: int = Field(default=5, ge=1, env="DATABASE_POOL_SIZE")
+    database_max_overflow: int = Field(default=10, ge=0, env="DATABASE_MAX_OVERFLOW")
+    database_pool_timeout: float = Field(
+        default=30.0, gt=0, env="DATABASE_POOL_TIMEOUT"
+    )
+    database_pool_recycle: int = Field(default=1800, ge=0, env="DATABASE_POOL_RECYCLE")
+    database_pool_pre_ping: bool = Field(default=False, env="DATABASE_POOL_PRE_PING")
+    database_pool_hold_warn_seconds: float = Field(
+        default=10.0, gt=0, env="DATABASE_POOL_HOLD_WARN_SECONDS"
+    )
 
     # Logging
     log_level: str = Field(default="INFO", env="LOG_LEVEL")
@@ -93,9 +152,8 @@ class Settings(BaseSettings):
 
     # Discovery
     relays: list[str] = Field(default_factory=list, env="RELAYS")
-    enable_analytics_sharing: bool = Field(
-        default=True, env="ENABLE_ANALYTICS_SHARING"
-    )
+    enable_analytics_sharing: bool = Field(default=True, env="ENABLE_ANALYTICS_SHARING")
+
 
 def _normalize_settings_data(data: dict[str, Any]) -> dict[str, Any]:
     """Discard unknown keys from persisted settings."""
@@ -109,10 +167,92 @@ def _normalize_settings_data(data: dict[str, Any]) -> dict[str, Any]:
     return normalized
 
 
+# Secrets are credentials, not config: they live in the encrypted/hashed Secret
+# store (and decrypted in-memory for runtime use), never in the persisted
+# settings blob. ``admin_password`` is gone from the model entirely; ``nsec``
+# remains a live field but is stripped from every blob write so it is never
+# written back to plaintext. ``upstream_api_key`` is intentionally *not* here:
+# it has no encrypted home yet (it is node-scoped today but really belongs on a
+# provider), so stripping it would lose it on the next restart. It stays in the
+# blob as before; encrypting it is follow-up work. See ``bootstrap_secrets`` and
+# ``routstr.core.vault``.
+SECRET_FIELDS = frozenset({"admin_password", "nsec"})
+
+# Infrastructure the node needs *before* it can open a DB session — so it can
+# never be configured from the DB (chicken-and-egg) and stays env-only. Unlike
+# secrets (owned by bootstrap), these are excluded so the DB settings blob can
+# neither store nor shadow them; env is always authoritative.
+ENV_ONLY_FIELDS = frozenset(
+    {
+        "database_pool_size",
+        "database_max_overflow",
+        "database_pool_timeout",
+        "database_pool_recycle",
+        "database_pool_pre_ping",
+        "database_pool_hold_warn_seconds",
+    }
+)
+
+_NON_PERSISTED_FIELDS = SECRET_FIELDS | ENV_ONLY_FIELDS
+
+
+def _strip_secret_fields(data: dict[str, Any]) -> dict[str, Any]:
+    """Return a copy of ``data`` without secret or env-only fields.
+
+    Both are kept out of the persisted settings blob: secrets for confidentiality,
+    env-only fields (e.g. DB pool sizing) because they must never be sourced from
+    the database.
+    """
+    return {k: v for k, v in data.items() if k not in _NON_PERSISTED_FIELDS}
+
+
+def _apply_to_live_settings(data: dict[str, Any]) -> None:
+    """Apply ``data`` onto the live ``settings`` for all in-process importers.
+
+    Secrets are owned exclusively by ``bootstrap_secrets``, which runs first and
+    has already decrypted the authoritative nsec into memory (importing any
+    legacy plaintext on the way). Never re-apply secret fields from env/blob
+    here: a non-empty but stale ``NSEC`` env var would otherwise override an nsec
+    the vault has taken ownership of (e.g. after the operator rotates it in the
+    UI), and an empty one would wipe the live value. Skip them entirely.
+    """
+    for k, v in data.items():
+        if k in SECRET_FIELDS:
+            continue
+        setattr(settings, k, v)
+
+
 def _compute_primary_mint(cashu_mints: list[str]) -> str:
     return cashu_mints[0] if cashu_mints else "https://mint.minibits.cash/Bitcoin"
 
 
+def derive_npub_from_nsec(nsec: str) -> str | None:
+    """Derive the npub (bech32) from an nsec or 64-char hex private key, or None.
+
+    Parsing is delegated to :func:`routstr.nostr.listing.nsec_to_keypair`, the
+    single place that knows the nsec/hex formats (and already returns ``None`` on
+    any unusable input); this only bech32-encodes the resulting public key. The
+    contract stays "return None on unusable input", so a bad key never crashes
+    boot.
+    """
+    try:
+        from nostr.key import PublicKey  # type: ignore
+
+        from ..nostr.listing import nsec_to_keypair
+    except ImportError:
+        return None
+
+    keypair = nsec_to_keypair(nsec)
+    if keypair is None:
+        return None
+    _privkey_hex, pubkey_hex = keypair
+
+    try:
+        return PublicKey(bytes.fromhex(pubkey_hex)).bech32()
+    except (ValueError, AttributeError):
+        return None
+
+
 def resolve_bootstrap() -> Settings:
     base = Settings()  # Reads env with custom parse_env_var
     # Back-compat env mapping
@@ -167,23 +307,9 @@ def resolve_bootstrap() -> Settings:
             pass
     # Derive NPUB from NSEC if not provided
     if not base.npub and base.nsec:
-        try:
-            from nostr.key import PrivateKey  # type: ignore
-
-            if base.nsec.startswith("nsec"):
-                pk = PrivateKey.from_nsec(base.nsec)
-            elif len(base.nsec) == 64:
-                pk = PrivateKey(bytes.fromhex(base.nsec))
-            else:
-                pk = None
-            if pk is not None:
-                try:
-                    base.npub = pk.public_key.bech32()
-                except Exception:
-                    # Fallback to hex if bech32 not available
-                    base.npub = pk.public_key.hex()
-        except Exception:
-            pass
+        npub = derive_npub_from_nsec(base.nsec)
+        if npub:
+            base.npub = npub
     if not base.cors_origins:
         base.cors_origins = ["*"]
     if not base.primary_mint:
@@ -233,15 +359,14 @@ class SettingsService:
                     text(
                         "INSERT INTO settings (id, data, updated_at) VALUES (1, :data, :updated_at)"
                     ).bindparams(
-                        data=json.dumps(env_resolved.dict()),
+                        data=json.dumps(_strip_secret_fields(env_resolved.dict())),
                         updated_at=datetime.now(timezone.utc),
                     )
                 )
                 await db_session.commit()
                 cls._current = settings
                 # Update the existing instance in-place for all live importers
-                for k, v in env_resolved.dict().items():
-                    setattr(settings, k, v)
+                _apply_to_live_settings(env_resolved.dict())
                 return cls._current
 
             db_id, db_data, _updated_at = row
@@ -258,7 +383,13 @@ class SettingsService:
             valid_fields = set(env_resolved.dict().keys())
             merged_dict: dict[str, Any] = dict(env_resolved.dict())
             merged_dict.update(
-                {k: v for k, v in db_json.items() if v not in (None, "", [], {}) and k in valid_fields}
+                {
+                    k: v
+                    for k, v in db_json.items()
+                    if v not in (None, "", [], {})
+                    and k in valid_fields
+                    and k not in ENV_ONLY_FIELDS
+                }
             )
             merged_dict = Settings(**merged_dict).dict()
 
@@ -268,20 +399,37 @@ class SettingsService:
                     merged_dict.get("cashu_mints", [])
                 )
 
-            if db_json_raw != merged_dict:
+            # Keep npub consistent with the live nsec. bootstrap_secrets has
+            # already run and holds the single authoritative nsec (decrypted from
+            # the encrypted store, or freshly imported). merged_dict starts from
+            # the env/blob, which may carry a STALE nsec — and therefore a stale
+            # derived npub — after the vault took ownership. Derive from the live
+            # value and OVERRIDE, not just fill: otherwise the node keeps the
+            # vault's private key but announces the old env key's npub (npub is a
+            # pure derivation of nsec, never configured independently of it).
+            if settings.nsec:
+                derived_npub = derive_npub_from_nsec(settings.nsec)
+                if derived_npub:
+                    merged_dict["npub"] = derived_npub
+
+            # Persist without secrets; compare against the stripped target so a
+            # legacy blob that still carries plaintext secrets gets rewritten
+            # (and thereby sunset) even when its non-secret values are unchanged.
+            persisted = _strip_secret_fields(merged_dict)
+            if db_json_raw != persisted:
                 await db_session.exec(  # type: ignore
                     text(
                         "UPDATE settings SET data = :data, updated_at = :updated_at WHERE id = 1"
                     ).bindparams(
-                        data=json.dumps(merged_dict),
+                        data=json.dumps(persisted),
                         updated_at=datetime.now(timezone.utc),
                     )
                 )
                 await db_session.commit()
 
             # Update the existing instance in-place for all live importers
-            for k, v in merged_dict.items():
-                setattr(settings, k, v)
+            # (keeps the decrypted nsec live in memory).
+            _apply_to_live_settings(merged_dict)
             cls._current = settings
             return cls._current
 
@@ -303,13 +451,18 @@ class SettingsService:
                 text(
                     "UPDATE settings SET data = :data, updated_at = :updated_at WHERE id = 1"
                 ).bindparams(
-                    data=json.dumps(candidate.dict()),
+                    data=json.dumps(_strip_secret_fields(candidate.dict())),
                     updated_at=datetime.now(timezone.utc),
                 )
             )
             await db_session.commit()
-            # Update in-place
+            # Update in-place. Env-only fields (e.g. DB pool sizing) are never
+            # applied here: the engine pool is already built at boot from env,
+            # so letting an update mutate the live value would only make it
+            # diverge from the running pool.
             for k, v in candidate.dict().items():
+                if k in ENV_ONLY_FIELDS:
+                    continue
                 setattr(settings, k, v)
             cls._current = settings
             return settings
@@ -332,3 +485,152 @@ class SettingsService:
                     setattr(settings, k, v)
             cls._current = settings
             return settings
+
+
+async def _read_raw_settings_blob(db_session: AsyncSession) -> dict[str, Any]:
+    """Best-effort read of the raw persisted settings JSON (may not exist yet)."""
+    from sqlmodel import text
+
+    try:
+        result = await db_session.exec(  # type: ignore
+            text("SELECT data FROM settings WHERE id = 1")
+        )
+        row = result.first()
+    except Exception:
+        return {}
+    if row is None:
+        return {}
+    (data_str,) = row
+    try:
+        data = json.loads(data_str) if isinstance(data_str, str) else dict(data_str)
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _legacy_plaintext(
+    raw_blob: dict[str, Any], env_name: str, blob_key: str
+) -> str | None:
+    """Legacy plaintext for a secret: env first, then the old settings blob."""
+    env_value = os.environ.get(env_name)
+    if env_value:
+        return env_value
+    blob_value = raw_blob.get(blob_key)
+    if isinstance(blob_value, str) and blob_value:
+        return blob_value
+    return None
+
+
+async def bootstrap_secrets(db_session: AsyncSession) -> None:
+    """Move node secrets into the encrypted/hashed Secret store at startup.
+
+    Per secret:
+      * column already set -> use it (the nsec is decrypted into the in-memory
+        ``settings``; a wrong ROUTSTR_SECRET_KEY surfaces as a clear fail-fast).
+      * column empty but legacy plaintext exists (env, or the old settings
+        blob) -> transform it (hash the password / encrypt the nsec) into the
+        column.
+      * nothing (admin password only) -> generate a strong random password,
+        hash it, and log it once with the /admin URL.
+    """
+    from cryptography.fernet import InvalidToken
+    from sqlmodel import col, update
+
+    from . import vault
+    from .db import NsecState, Secret, get_secret
+
+    raw_blob = await _read_raw_settings_blob(db_session)
+    secret = await get_secret(db_session)
+    changed = False
+
+    # Admin password — one-way scrypt hash.
+    if secret.admin_password_hash is None:
+        legacy_password = _legacy_plaintext(
+            raw_blob, "ADMIN_PASSWORD", "admin_password"
+        )
+        if legacy_password:
+            secret.admin_password_hash = vault.hash_password(legacy_password)
+            changed = True
+        else:
+            generated = secrets.token_urlsafe(24)
+            # Claim the empty slot atomically: only the worker whose UPDATE flips
+            # NULL -> hash owns the generated password and announces it. On a
+            # shared DB a racing worker gets rowcount 0, so it neither clobbers
+            # the winner's hash (which the operator may already be using) nor
+            # prints a second password that would never work.
+            claim_stmt = (
+                update(Secret)
+                .where(col(Secret.id) == 1)
+                .where(col(Secret.admin_password_hash).is_(None))
+                .values(
+                    admin_password_hash=vault.hash_password(generated),
+                    updated_at=int(time.time()),
+                )
+            )
+            result = await db_session.exec(claim_stmt)  # type: ignore[call-overload]
+            await db_session.commit()
+            await db_session.refresh(secret)
+            if result.rowcount == 1:
+                admin_url = (settings.http_url or "http://localhost:8000").rstrip("/")
+                # Print to stdout rather than the logger: the operator must see
+                # this once (e.g. `docker compose logs`), but it must not be
+                # persisted into the on-disk log files the logger also writes to.
+                print(
+                    "No admin password set; generated a temporary one (shown "
+                    f"only now): {generated}\nLog in at {admin_url}/admin and "
+                    "change it from the dashboard settings.",
+                    flush=True,
+                )
+
+    # Nostr nsec — reversible Fernet encryption. ``nsec_state`` is the single
+    # source of truth for ownership, so "intentionally cleared" is never
+    # conflated with "never migrated" (the bug the old bool could not encode).
+    if secret.nsec_state == NsecState.encrypted:
+        # The vault owns the identity: decrypt the ciphertext, never re-read
+        # env/blob. A missing ciphertext here means the row is inconsistent (a
+        # failed write or manual edit); fail fast rather than silently dropping
+        # the identity and falling back to a stale legacy copy.
+        if secret.encrypted_nsec is None:
+            raise RuntimeError(
+                "nsec_state is 'encrypted' but no ciphertext is stored; the "
+                "secrets row is inconsistent. Refusing to boot rather than "
+                "silently resurrecting a stale legacy NSEC."
+            )
+        try:
+            settings.nsec = vault.decrypt(secret.encrypted_nsec)
+        except InvalidToken as exc:
+            raise RuntimeError(
+                "Stored nsec cannot be decrypted with the current "
+                "ROUTSTR_SECRET_KEY. The key changed, or this database came from "
+                "another node. Restore the original ROUTSTR_SECRET_KEY to recover."
+            ) from exc
+    elif secret.nsec_state == NsecState.cleared:
+        # The operator emptied the identity via the admin API. A fresh process
+        # has already reloaded a stale ``NSEC`` from env/blob into the live
+        # settings (and may have derived its npub); actively clear both so the
+        # cleared store wins rather than silently resurrecting the old identity.
+        settings.nsec = ""
+        settings.npub = ""
+    else:  # NsecState.legacy — the vault has not taken ownership yet.
+        # Import any legacy plaintext (env, or the old settings blob) exactly
+        # once. Encryption at rest is mandatory, but a missing key is
+        # provisioned, not fatal: vault.encrypt generates and persists a master
+        # key (with a loud one-time operator notice) when none was supplied, so
+        # an upgrading node keeps running. The nsec is never stored in plaintext.
+        legacy_nsec = _legacy_plaintext(raw_blob, "NSEC", "nsec")
+        if legacy_nsec:
+            secret.encrypted_nsec = vault.encrypt(legacy_nsec)
+            secret.nsec_state = NsecState.encrypted
+            settings.nsec = legacy_nsec
+            changed = True
+
+    # Derive npub from whatever nsec we now hold, if not already known.
+    if settings.nsec and not settings.npub:
+        npub = derive_npub_from_nsec(settings.nsec)
+        if npub:
+            settings.npub = npub
+
+    if changed:
+        secret.updated_at = int(time.time())
+        db_session.add(secret)
+        await db_session.commit()

routstr/core/vault.py

@@ -0,0 +1,320 @@
+"""Encrypt/hash/fingerprint helpers for secrets at rest (issue #553).
+
+Thin wrapper over ``cryptography`` so nothing else in the codebase touches
+Fernet/scrypt/HMAC directly:
+
+- :func:`encrypt`/:func:`decrypt` — Fernet symmetric encryption, keyed by the
+  mandatory master key. Ciphertext is self-describing (``fernet:v1:`` prefix) so
+  a value can be told apart from legacy plaintext and so reading it under the
+  wrong key surfaces as a hard error rather than silent corruption.
+- :func:`hash_password`/:func:`verify_password` — salted scrypt hashing. This is
+  *key-independent*: it never reads the master key, so password login and the
+  recovery script keep working even when the key is missing.
+
+Key custody is flexible but encryption is not optional. The key comes from the
+``ROUTSTR_SECRET_KEY`` env var, else a persisted key file
+(``ROUTSTR_SECRET_KEY_FILE``, defaulting beside the SQLite database so it persists
+on the same volume as the data); when neither is set, :func:`encrypt` generates
+one to the key file and prints a one-time notice, so an existing node upgrades
+without breaking instead of refusing to boot. Reading is strict — :func:`decrypt`
+never generates a key (a new key could not match existing ciphertext) and fails
+fast with the generation command when none is configured. A malformed
+``ROUTSTR_SECRET_KEY`` is an operator error and always fails fast.
+"""
+
+import base64
+import hashlib
+import hmac
+import os
+import secrets
+import tempfile
+from pathlib import Path
+
+from cryptography.fernet import Fernet
+from sqlalchemy.engine import make_url
+from sqlalchemy.exc import ArgumentError
+
+_PREFIX = "fernet:v1:"
+_GEN_COMMAND = (
+    'python -c "from cryptography.fernet import Fernet; '
+    'print(Fernet.generate_key().decode())"'
+)
+
+# Where an auto-generated master key is persisted when the operator supplies no
+# ``ROUTSTR_SECRET_KEY``. Defaults beside the SQLite database so it rides whatever
+# volume already persists the data (a container recreate would otherwise generate
+# a fresh key and be unable to decrypt existing secrets); falls back to the
+# working directory when the DB location is unknown. Override the exact path with
+# ``ROUTSTR_SECRET_KEY_FILE``.
+_KEY_FILE_ENV = "ROUTSTR_SECRET_KEY_FILE"
+_DEFAULT_KEY_FILE = "routstr_secret.key"
+
+# Minimum admin-password length, enforced wherever a password is set/changed
+# (admin endpoints + the recovery script) so the policy lives in one place.
+MIN_PASSWORD_LENGTH = 8
+
+# scrypt parameters; packed into each hash so verification is parameter-free.
+_SCRYPT_N = 2**14
+_SCRYPT_R = 8
+_SCRYPT_P = 1
+_SCRYPT_DKLEN = 32
+_SCRYPT_SALT_BYTES = 16
+
+
+def _database_dir() -> Path | None:
+    """Directory of the SQLite database file, or ``None`` when it has no on-disk
+    location (a non-SQLite URL or ``:memory:``).
+
+    Read from ``DATABASE_URL`` at call time and parsed here rather than importing
+    ``routstr.core.db`` — that module builds the engine at import, which the
+    crypto layer must not drag in. Mirrors db.py's ``DATABASE_URL`` default.
+    """
+    url_str = os.environ.get("DATABASE_URL", "sqlite+aiosqlite:///keys.db")
+    try:
+        url = make_url(url_str)
+    except ArgumentError:
+        return None
+    if url.get_backend_name() != "sqlite" or not url.database:
+        return None
+    if url.database == ":memory:":
+        return None
+    return Path(url.database).parent
+
+
+def _key_file_path() -> Path:
+    """Where the auto-generated master key is read from / written to.
+
+    ``ROUTSTR_SECRET_KEY_FILE`` wins; otherwise the key sits beside the SQLite
+    database so it persists on the same volume as the data, falling back to the
+    working directory when the DB location is unknown.
+    """
+    override = os.environ.get(_KEY_FILE_ENV)
+    if override:
+        return Path(override)
+    directory = _database_dir()
+    return (directory or Path()) / _DEFAULT_KEY_FILE
+
+
+def _read_key_file(path: Path) -> str | None:
+    try:
+        stored = path.read_text().strip()
+    except OSError:
+        return None
+    if not stored:
+        return None
+    _repair_key_file_perms(path)
+    return stored
+
+
+def _repair_key_file_perms(path: Path) -> None:
+    # A master key must never be group/other-readable. On POSIX, tighten loose
+    # permissions to owner-only (0600) rather than trust — or hard-fail on — a
+    # world-readable key; a friendlier repair keeps an upgrading node booting.
+    if os.name != "posix":
+        return
+    try:
+        mode = path.stat().st_mode
+    except OSError:
+        return
+    if mode & 0o077:
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass
+
+
+def _load_secret_key() -> str | None:
+    """The configured key without provisioning: env var, then the key file."""
+    return os.environ.get("ROUTSTR_SECRET_KEY") or _read_key_file(_key_file_path())
+
+
+def _warn_generated_key(path: Path) -> None:
+    # stdout, not the logger: the operator must see this once (e.g. in
+    # ``docker compose logs``), but it must never be persisted into the on-disk
+    # log files the logger also writes. Mirrors the generated-admin-password
+    # notice so an upgrade cannot silently create an unbacked key.
+    print(
+        "No ROUTSTR_SECRET_KEY was set; generated one to encrypt node secrets at "
+        f"rest and saved it to {path}.\n"
+        "!! BACK UP THIS FILE. If it is lost, the encrypted secrets cannot be "
+        "recovered and will have to be re-entered.\n"
+        "To manage the key yourself (e.g. from a secrets manager) set "
+        "ROUTSTR_SECRET_KEY in the environment instead; the value is in the file "
+        "above.",
+        flush=True,
+    )
+
+
+def _generate_and_persist_key(path: Path) -> str:
+    """Generate a Fernet key, persist it owner-only and atomically, warn once.
+
+    The key is written to a temp file in the same directory, flushed durably,
+    then ``os.link``-ed into place. ``os.link`` publishes the complete file in a
+    single atomic step — a crash mid-write leaves only the temp file (which is
+    removed), never a half-written or empty key at the final path that a later
+    boot would read as corrupt. It also refuses to overwrite an existing key, so
+    a racing worker that generated first keeps ownership (secrets may already be
+    encrypted under its key); the loser adopts that key instead of clobbering it.
+    """
+    key = Fernet.generate_key().decode()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        dir=path.parent, prefix=".routstr_secret.", suffix=".tmp"
+    )
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w") as handle:
+            handle.write(key)  # mkstemp already created it 0600
+            handle.flush()
+            os.fsync(handle.fileno())
+        try:
+            os.link(tmp, path)
+        except FileExistsError:
+            # A concurrent worker linked its key in first; adopt theirs rather
+            # than clobber a key that secrets may already be encrypted under.
+            existing = _read_key_file(path)
+            if existing:
+                return existing
+            raise
+        _fsync_dir(path.parent)
+    finally:
+        tmp.unlink(missing_ok=True)
+    _warn_generated_key(path)
+    return key
+
+
+def _fsync_dir(directory: Path) -> None:
+    # Persist the new directory entry so the linked key survives a crash right
+    # after publish. Best-effort: not every platform lets you fsync a directory.
+    try:
+        dir_fd = os.open(directory, os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(dir_fd)
+    except OSError:
+        pass
+    finally:
+        os.close(dir_fd)
+
+
+def ensure_secret_key() -> str:
+    """Return the master key, provisioning one if the operator supplied none.
+
+    Precedence: the ``ROUTSTR_SECRET_KEY`` env var, then the persisted key file,
+    otherwise a freshly generated key written to the key file (with a one-time
+    operator notice). This keeps encryption at rest mandatory while letting an
+    existing node upgrade without setting a key first. A malformed env key is
+    left to fail at :func:`get_fernet` — it is an operator error, not an unset
+    key, so it must not trigger silent self-provisioning.
+    """
+    env_key = os.environ.get("ROUTSTR_SECRET_KEY")
+    if env_key:
+        return env_key
+    path = _key_file_path()
+    return _read_key_file(path) or _generate_and_persist_key(path)
+
+
+def _fernet_from_key(key: str) -> Fernet:
+    try:
+        return Fernet(key.encode())
+    except (ValueError, TypeError) as exc:
+        raise RuntimeError(
+            "ROUTSTR_SECRET_KEY is malformed; it must be a url-safe base64 "
+            "32-byte Fernet key. Generate one with:\n    " + _GEN_COMMAND
+        ) from exc
+
+
+def get_fernet() -> Fernet:
+    """Build a :class:`Fernet` from the configured key (env var or key file).
+
+    Strict: this never generates a key, so already-encrypted ciphertext is never
+    shadowed by a fresh key. A read with no key configured fails fast with the
+    generation command.
+    """
+    key = _load_secret_key()
+    if not key:
+        raise RuntimeError(
+            "ROUTSTR_SECRET_KEY is not set. It is required to encrypt secrets at "
+            "rest. Generate one with:\n    " + _GEN_COMMAND
+        )
+    return _fernet_from_key(key)
+
+
+def encrypt(plaintext: str) -> str:
+    """Encrypt ``plaintext`` into a self-describing ``fernet:v1:`` token.
+
+    Provisions a master key (env var, key file, or a freshly generated one) so an
+    upgrading node never has to set one before its first secret is stored; the
+    value is always encrypted, never persisted in plaintext.
+    """
+    fernet = _fernet_from_key(ensure_secret_key())
+    return _PREFIX + fernet.encrypt(plaintext.encode()).decode()
+
+
+def is_encrypted(value: str) -> bool:
+    """True if ``value`` carries the ``fernet:v1:`` prefix this module emits."""
+    return value.startswith(_PREFIX)
+
+
+def decrypt(ciphertext: str) -> str:
+    """Decrypt a ``fernet:v1:`` token.
+
+    Raises ``ValueError`` for an unprefixed value (so legacy plaintext is never
+    mistaken for ciphertext) and ``InvalidToken`` when the value was written
+    under a different ``ROUTSTR_SECRET_KEY``.
+    """
+    if not is_encrypted(ciphertext):
+        raise ValueError("value is not fernet:v1: ciphertext")
+    token = ciphertext[len(_PREFIX) :]
+    return get_fernet().decrypt(token.encode()).decode()
+
+
+def hash_password(password: str) -> str:
+    """Salted scrypt hash, self-describing as ``scrypt:n:r:p:salt:hash``."""
+    salt = secrets.token_bytes(_SCRYPT_SALT_BYTES)
+    derived = hashlib.scrypt(
+        password.encode(),
+        salt=salt,
+        n=_SCRYPT_N,
+        r=_SCRYPT_R,
+        p=_SCRYPT_P,
+        dklen=_SCRYPT_DKLEN,
+    )
+    return ":".join(
+        [
+            "scrypt",
+            str(_SCRYPT_N),
+            str(_SCRYPT_R),
+            str(_SCRYPT_P),
+            base64.b64encode(salt).decode(),
+            base64.b64encode(derived).decode(),
+        ]
+    )
+
+
+def verify_password(password: str, stored: str) -> bool:
+    """Constant-time check of ``password`` against a :func:`hash_password` value."""
+    try:
+        scheme, n, r, p, salt_b64, hash_b64 = stored.split(":")
+        if scheme != "scrypt":
+            return False
+        n_int, r_int, p_int = int(n), int(r), int(p)
+        # Cap the work factor at the parameters this module emits. scrypt's
+        # memory cost grows with N*r, so an oversized N/r in a tampered or
+        # corrupt stored hash could turn a single login into an OOM/DoS.
+        if n_int > _SCRYPT_N or r_int > _SCRYPT_R or p_int > _SCRYPT_P:
+            return False
+        salt = base64.b64decode(salt_b64)
+        expected = base64.b64decode(hash_b64)
+        derived = hashlib.scrypt(
+            password.encode(),
+            salt=salt,
+            n=n_int,
+            r=r_int,
+            p=p_int,
+            dklen=len(expected),
+        )
+    except (ValueError, TypeError):
+        return False
+    return hmac.compare_digest(derived, expected)

routstr/core/version.py

@@ -20,7 +20,7 @@ import subprocess
 from functools import lru_cache
 from pathlib import Path
 
-BASE_VERSION = "0.4.3"
+BASE_VERSION = "0.4.4"
 
 _REPO_ROOT = Path(__file__).resolve().parents[2]
 _GIT_TIMEOUT_SECONDS = 2.0
@@ -55,9 +55,9 @@ def _on_tagged_release() -> bool:
     if tag:
         return tag.lstrip("v") == BASE_VERSION
     described = _run_git("describe", "--tags", "--exact-match", "HEAD")
-    if not described:
-        return False
-    return described.lstrip("v") == BASE_VERSION
+    if described and described.lstrip("v") == BASE_VERSION:
+        return True
+    return False
 
 
 @lru_cache(maxsize=1)

routstr/lightning.py

@@ -1,33 +1,99 @@
+import asyncio
 import hashlib
+import re
 import secrets
 import time
+from dataclasses import dataclass
+from typing import Any
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, Header, HTTPException
 from pydantic import BaseModel, Field
-from sqlmodel import select
+from sqlalchemy.orm.attributes import set_committed_value
+from sqlmodel import col, select, update
 from sqlmodel.ext.asyncio.session import AsyncSession
 
-from .core.db import ApiKey, LightningInvoice, get_session
+from .core.db import ApiKey, LightningInvoice, create_session, get_session
 from .core.logging import get_logger
 from .core.settings import settings
-from .wallet import get_wallet
+from .wallet import (
+    MintConnectionError,
+    _is_mint_rate_limited,
+    _mint_cooldown_remaining,
+    _mint_operation,
+    get_wallet,
+    is_mint_connection_error,
+    wallet_operation_guard,
+)
 
 logger = get_logger(__name__)
 
 lightning_router = APIRouter(prefix="/lightning")
 
+# Avoid duplicate work within one process. Cross-process credit fencing is done
+# by the conditional pending -> paid update in _finalize_invoice_settlement().
+_invoice_settlement_locks: dict[str, asyncio.Lock] = {}
+
+
+@dataclass(frozen=True)
+class _InvoiceSettlement:
+    id: str
+    payment_hash: str
+    amount_sats: int
+    purpose: str
+    api_key_hash: str | None
+    mint_url: str | None
+    balance_limit: int | None
+    balance_limit_reset: str | None
+    validity_date: int | None
+
+    @classmethod
+    def from_invoice(cls, invoice: LightningInvoice) -> "_InvoiceSettlement":
+        return cls(
+            id=invoice.id,
+            payment_hash=invoice.payment_hash,
+            amount_sats=invoice.amount_sats,
+            purpose=invoice.purpose,
+            api_key_hash=invoice.api_key_hash,
+            mint_url=invoice.mint_url,
+            balance_limit=invoice.balance_limit,
+            balance_limit_reset=invoice.balance_limit_reset,
+            validity_date=invoice.validity_date,
+        )
+
+
+def _publish_invoice_value(invoice: LightningInvoice, key: str, value: Any) -> None:
+    """Update a caller view without marking a mapped object dirty."""
+    try:
+        set_committed_value(invoice, key, value)
+    except AttributeError:
+        setattr(invoice, key, value)
+
 
 class InvoiceCreateRequest(BaseModel):
     amount_sats: int = Field(gt=0, le=1_000_000, description="Amount in satoshis")
-    purpose: str = Field(description="create or topup", pattern="^(create|topup)$")
+    purpose: str = Field(
+        default="create",
+        description="create or topup",
+        pattern="^(create|topup)$",
+    )
     api_key: str | None = Field(
-        default=None, description="Required for topup operations"
+        default=None,
+        description="Deprecated: legacy field for topup. Prefer Authorization header.",
     )
     balance_limit: int | None = Field(default=None)
     balance_limit_reset: str | None = Field(default=None)
     validity_date: int | None = Field(default=None)
 
 
+def _extract_bearer_api_key(authorization: str | None) -> str | None:
+    if not authorization:
+        return None
+    token = authorization.strip()
+    if token.lower().startswith("bearer "):
+        token = token[7:].strip()
+    return token or None
+
+
 class InvoiceCreateResponse(BaseModel):
     invoice_id: str
     bolt11: str
@@ -49,12 +115,80 @@ class InvoiceRecoverRequest(BaseModel):
     bolt11: str = Field(description="BOLT11 invoice string")
 
 
+def _trusted_mint_candidates() -> list[str]:
+    return [
+        mint
+        for mint in dict.fromkeys([settings.primary_mint, *settings.cashu_mints])
+        if mint
+    ]
+
+
+async def _request_mint_with_fallback(
+    amount_sats: int,
+    *,
+    allowed_mints: list[str] | None = None,
+) -> tuple[str, str, str]:
+    """Request a quote, falling back only among the allowed trusted mints.
+
+    Guards against amount_sats <= 0: the cashu library's PostMintQuoteRequest
+    enforces ``amount > 0`` (Pydantic Field(gt=0)), so passing 0 raises a
+    cryptic validation error deep in the stack.  Fail fast with context.
+    """
+    if amount_sats <= 0:
+        raise ValueError(
+            f"generate_lightning_invoice: amount_sats must be > 0, got {amount_sats}."
+        )
+    tried: list[str] = []
+    configured = allowed_mints or [settings.primary_mint, *settings.cashu_mints]
+    candidates = list(dict.fromkeys(configured))
+    for mint_url in candidates:
+        cooldown = _mint_cooldown_remaining(mint_url)
+        if cooldown > 0:
+            tried.append(f"{mint_url}: cooling down")
+            logger.info(
+                "Skipping rate-limited mint",
+                extra={
+                    "mint_url": mint_url,
+                    "cooldown_seconds": round(cooldown, 2),
+                    "op_name": "request_mint_invoice",
+                },
+            )
+            continue
+        try:
+            wallet = await get_wallet(mint_url, "sat", retry_on_rate_limit=False)
+            quote = await _mint_operation(
+                lambda: wallet.request_mint(amount_sats),
+                op_name="request_mint_invoice",
+                mint_url=mint_url,
+                retry_on_rate_limit=False,
+            )
+            return quote.request, quote.quote, mint_url
+        except Exception as e:
+            tried.append(f"{mint_url}: {type(e).__name__}")
+            if not is_mint_connection_error(e) and not _is_mint_rate_limited(e):
+                raise
+            logger.warning(
+                "request_mint failed, trying fallback mint",
+                extra={
+                    "failed_mint": mint_url,
+                    "error": str(e),
+                    "tried": tried,
+                },
+            )
+            continue
+    raise MintConnectionError(f"All mints failed for request_mint: {tried}")
+
+
 async def generate_lightning_invoice(
-    amount_sats: int, description: str
-) -> tuple[str, str]:
-    wallet = await get_wallet(settings.primary_mint, "sat")
-    quote = await wallet.request_mint(amount_sats)
-    return quote.request, quote.quote
+    amount_sats: int,
+    description: str,
+    *,
+    allowed_mints: list[str] | None = None,
+) -> tuple[str, str, str]:
+    bolt11, payment_hash, mint_url = await _request_mint_with_fallback(
+        amount_sats, allowed_mints=allowed_mints
+    )
+    return bolt11, payment_hash, mint_url
 
 
 def generate_invoice_id() -> str:
@@ -64,25 +198,38 @@ def generate_invoice_id() -> str:
 @lightning_router.post("/invoice", response_model=InvoiceCreateResponse)
 async def create_invoice(
     request: InvoiceCreateRequest,
+    authorization: str | None = Header(default=None),
     session: AsyncSession = Depends(get_session),
 ) -> InvoiceCreateResponse:
-    if request.purpose == "topup" and not request.api_key:
-        raise HTTPException(
-            status_code=400, detail="api_key is required for topup operations"
-        )
+    api_key_token = _extract_bearer_api_key(authorization) or request.api_key
+    topup_api_key: ApiKey | None = None
 
-    if request.purpose == "topup" and request.api_key:
-        if not request.api_key.startswith("sk-"):
+    if request.purpose == "topup":
+        if not api_key_token:
+            raise HTTPException(
+                status_code=401,
+                detail="Authorization bearer api key is required for topup",
+            )
+        if not api_key_token.startswith("sk-"):
             raise HTTPException(status_code=400, detail="Invalid API key format")
 
-        api_key = await session.get(ApiKey, request.api_key[3:])
-        if not api_key:
+        topup_api_key = await session.get(ApiKey, api_key_token[3:])
+        if not topup_api_key:
             raise HTTPException(status_code=404, detail="API key not found")
 
     try:
         description = f"Routstr {request.purpose} {request.amount_sats} sats"
-        bolt11, payment_hash = await generate_lightning_invoice(
-            request.amount_sats, description
+        allowed_mints = None
+        if request.purpose == "topup":
+            assert topup_api_key is not None
+            # A key's liabilities are attributed to a single refund mint. Keep
+            # top-up collateral on that same mint so balances and payouts cannot
+            # misclassify funds held by another mint as owner profit.
+            allowed_mints = [
+                topup_api_key.refund_mint_url or settings.primary_mint
+            ]
+        bolt11, payment_hash, mint_url = await generate_lightning_invoice(
+            request.amount_sats, description, allowed_mints=allowed_mints
         )
 
         invoice_id = generate_invoice_id()
@@ -95,8 +242,9 @@ async def create_invoice(
             description=description,
             payment_hash=payment_hash,
             status="pending",
-            api_key_hash=request.api_key[3:] if request.api_key else None,
+            api_key_hash=api_key_token[3:] if api_key_token else None,
             purpose=request.purpose,
+            mint_url=mint_url,
             balance_limit=request.balance_limit,
             balance_limit_reset=request.balance_limit_reset,
             validity_date=request.validity_date,
@@ -142,13 +290,13 @@ async def get_invoice_status(
     if not invoice:
         raise HTTPException(status_code=404, detail="Invoice not found")
 
+    if invoice.status == "pending":
+        await check_invoice_payment(invoice, session)
+
     if invoice.status == "pending" and int(time.time()) > invoice.expires_at:
         invoice.status = "expired"
         await session.commit()
 
-    if invoice.status == "pending":
-        await check_invoice_payment(invoice, session)
-
     api_key = None
     if invoice.status == "paid" and invoice.purpose == "create":
         if invoice.api_key_hash:
@@ -204,73 +352,292 @@ async def recover_invoice(
 async def check_invoice_payment(
     invoice: LightningInvoice, session: AsyncSession
 ) -> None:
-    try:
-        wallet = await get_wallet(settings.primary_mint, "sat")
-
-        mint_status = await wallet.get_mint_quote(invoice.payment_hash)
-
-        if mint_status.paid:
-            invoice.status = "paid"
-            invoice.paid_at = int(time.time())
-
-            if invoice.purpose == "create":
-                api_key = await create_api_key_from_invoice(invoice, session)
-                invoice.api_key_hash = api_key.hashed_key
-            elif invoice.purpose == "topup" and invoice.api_key_hash:
-                await topup_api_key_from_invoice(invoice, session)
-
+    lock = _invoice_settlement_locks.setdefault(invoice.id, asyncio.Lock())
+    async with lock, wallet_operation_guard():
+        minted = False
+        try:
+            # Snapshot the row and end the caller's read transaction before any
+            # potentially slow mint I/O. All final DB mutations use owned,
+            # short-lived sessions below.
+            await session.refresh(invoice)
+            if invoice.status != "pending":
+                await session.commit()
+                return
+            settlement = _InvoiceSettlement.from_invoice(invoice)
             await session.commit()
 
+            mint_url = settlement.mint_url or settings.primary_mint
+            wallet = await get_wallet(mint_url, "sat")
+            mint_status = await _mint_operation(
+                lambda: wallet.get_mint_quote(settlement.payment_hash),
+                op_name="get_mint_quote",
+                mint_url=mint_url,
+            )
+            if not mint_status.paid:
+                return
+
+            # Reject a paid top-up whose target was pruned before redeeming its
+            # single-use quote. The validation session is closed before mint I/O.
+            if settlement.purpose == "topup":
+                if not settlement.api_key_hash:
+                    raise ValueError("No API key associated with topup invoice")
+                async with create_session() as validation_session:
+                    target = await validation_session.get(
+                        ApiKey, settlement.api_key_hash
+                    )
+                    if target is None:
+                        terminal = await validation_session.exec(  # type: ignore[call-overload]
+                            update(LightningInvoice)
+                            .where(
+                                col(LightningInvoice.id) == settlement.id,
+                                col(LightningInvoice.status) == "pending",
+                            )
+                            .values(status="reconciliation_required")
+                        )
+                        await validation_session.commit()
+                        if terminal.rowcount == 1:
+                            _publish_invoice_value(
+                                invoice, "status", "reconciliation_required"
+                            )
+                        else:
+                            await _reload_invoice_view(invoice, session)
+                        logger.critical(
+                            "Paid topup invoice target API key was not found; reconciliation required",
+                            extra={"invoice_id": settlement.id},
+                        )
+                        return
+
+            # Quote-linked proof verification makes an ambiguous mint response
+            # retryable without crediting unrelated wallet balance growth.
+            await _mint_invoice_quote(wallet, settlement)
+            minted = True
+
+            paid_at = int(time.time())
+            async with create_session() as finalization_session:
+                settled, api_key_hash = await _finalize_invoice_settlement(
+                    settlement, finalization_session, paid_at
+                )
+            if not settled:
+                await _reload_invoice_view(invoice, session)
+                return
+
+            _publish_invoice_value(invoice, "status", "paid")
+            _publish_invoice_value(invoice, "paid_at", paid_at)
+            _publish_invoice_value(invoice, "api_key_hash", api_key_hash)
             logger.info(
                 "Lightning invoice paid",
                 extra={
-                    "invoice_id": invoice.id,
-                    "amount_sats": invoice.amount_sats,
-                    "purpose": invoice.purpose,
-                    "api_key_hash": invoice.api_key_hash[:8] + "..."
-                    if invoice.api_key_hash
+                    "invoice_id": settlement.id,
+                    "amount_sats": settlement.amount_sats,
+                    "purpose": settlement.purpose,
+                    "api_key_hash": api_key_hash[:8] + "..."
+                    if api_key_hash
                     else None,
                 },
             )
-
-    except Exception as e:
-        logger.error(f"Failed to check invoice payment: {e}")
+        except BaseException as error:
+            # Never roll back the caller-owned session: doing so expires invoice
+            # and sibling ORM objects. Owned sessions roll themselves back.
+            if minted:
+                logger.critical(
+                    "Invoice mint succeeded but DB finalization failed; reconciliation required",
+                    extra={"invoice_id": invoice.id, "purpose": invoice.purpose},
+                )
+            try:
+                await _reload_invoice_view(invoice, session)
+            except Exception:
+                pass
+            if not isinstance(error, Exception):
+                raise
+            logger.error(f"Failed to check invoice payment: {error}")
 
 
-async def create_api_key_from_invoice(
-    invoice: LightningInvoice, session: AsyncSession
-) -> ApiKey:
-    wallet = await get_wallet(settings.primary_mint, "sat")
-    await wallet.mint(invoice.amount_sats, quote_id=invoice.payment_hash)
-
-    dummy_token = f"invoice-{invoice.id}-{invoice.payment_hash}"
-    hashed_key = hashlib.sha256(dummy_token.encode()).hexdigest()
-
-    api_key = ApiKey(
-        hashed_key=hashed_key,
-        balance=invoice.amount_sats * 1000,  # Convert to msats
-        refund_currency="sat",
-        refund_mint_url=settings.primary_mint,
+def _is_outputs_already_signed(error: BaseException) -> bool:
+    message = str(error)
+    return bool(
+        re.search(
+            r"\boutputs?\s+(?:have\s+)?already\s+(?:been\s+)?signed(?:\s+before)?\b",
+            message,
+            re.IGNORECASE,
+        )
+        and re.search(r"\bcode\s*:\s*11003\b", message, re.IGNORECASE)
     )
 
+
+def _invoice_quote_proof_amount(wallet: Any, quote_id: str) -> int:
+    """Return spendable wallet value minted by one Lightning quote."""
+    return sum(
+        proof.amount
+        for proof in wallet.proofs
+        if proof.mint_id == quote_id and not proof.reserved
+    )
+
+
+async def _mint_invoice_quote(
+    wallet: Any, invoice: LightningInvoice | _InvoiceSettlement
+) -> None:
+    """Mint a paid quote, proving quote-linked outputs before DB credit."""
+    mint_url = invoice.mint_url or settings.primary_mint
+    await wallet.load_proofs(reload=True)
+    if _invoice_quote_proof_amount(wallet, invoice.payment_hash) >= invoice.amount_sats:
+        return
+
+    try:
+        await _mint_operation(
+            lambda: wallet.mint(invoice.amount_sats, quote_id=invoice.payment_hash),
+            op_name=f"invoice_mint_{invoice.purpose}",
+            mint_url=mint_url,
+            retry_timeouts=False,
+        )
+    except Exception as error:
+        if not _is_outputs_already_signed(error):
+            raise
+
+        for keyset_id in wallet.keysets:
+            await wallet.restore_tokens_for_keyset(keyset_id, to=1, batch=25)
+        await wallet.load_proofs(reload=True)
+        recovered = _invoice_quote_proof_amount(wallet, invoice.payment_hash)
+        if recovered < invoice.amount_sats:
+            raise RuntimeError(
+                "Invoice outputs were already signed but quote-linked recovery returned "
+                f"{recovered} sats; expected at least {invoice.amount_sats}"
+            ) from error
+    else:
+        await wallet.load_proofs(reload=True)
+        minted_amount = _invoice_quote_proof_amount(wallet, invoice.payment_hash)
+        if minted_amount < invoice.amount_sats:
+            raise RuntimeError(
+                "Invoice mint succeeded but quote-linked proofs total "
+                f"{minted_amount} sats; expected at least {invoice.amount_sats}"
+            )
+
+
+def _invoice_api_key_hash(invoice: LightningInvoice | _InvoiceSettlement) -> str:
+    dummy_token = f"invoice-{invoice.id}-{invoice.payment_hash}"
+    return hashlib.sha256(dummy_token.encode()).hexdigest()
+
+
+async def _create_api_key_record(
+    invoice: LightningInvoice | _InvoiceSettlement, session: AsyncSession
+) -> ApiKey:
+    mint_url = invoice.mint_url or settings.primary_mint
+    api_key = ApiKey(
+        hashed_key=_invoice_api_key_hash(invoice),
+        balance=invoice.amount_sats * 1000,
+        refund_currency="sat",
+        refund_mint_url=mint_url,
+        balance_limit=invoice.balance_limit,
+        balance_limit_reset=invoice.balance_limit_reset,
+        validity_date=invoice.validity_date,
+    )
     session.add(api_key)
     await session.flush()
-
     return api_key
 
 
-async def topup_api_key_from_invoice(
-    invoice: LightningInvoice, session: AsyncSession
+async def _topup_api_key_record(
+    invoice: LightningInvoice | _InvoiceSettlement, session: AsyncSession
 ) -> None:
-    wallet = await get_wallet(settings.primary_mint, "sat")
-    await wallet.mint(invoice.amount_sats, quote_id=invoice.payment_hash)
-
     if not invoice.api_key_hash:
         raise ValueError("No API key associated with topup invoice")
-
-    api_key = await session.get(ApiKey, invoice.api_key_hash)
-    if not api_key:
+    result = await session.exec(  # type: ignore[call-overload]
+        update(ApiKey)
+        .where(col(ApiKey.hashed_key) == invoice.api_key_hash)
+        .values(balance=col(ApiKey.balance) + invoice.amount_sats * 1000)
+        .execution_options(synchronize_session=False)
+    )
+    if result.rowcount != 1:
         raise ValueError("Associated API key not found")
 
-    api_key.balance += invoice.amount_sats * 1000  # Convert to msats
-    await session.flush()
+
+async def _finalize_invoice_settlement(
+    invoice: _InvoiceSettlement, session: AsyncSession, paid_at: int
+) -> tuple[bool, str | None]:
+    """Atomically fence and apply one invoice credit in the provided owned session."""
+    api_key_hash = (
+        _invoice_api_key_hash(invoice)
+        if invoice.purpose == "create"
+        else invoice.api_key_hash
+    )
+    claim = await session.exec(  # type: ignore[call-overload]
+        update(LightningInvoice)
+        .where(col(LightningInvoice.id) == invoice.id)
+        .where(col(LightningInvoice.status) == "pending")
+        .values(status="paid", paid_at=paid_at, api_key_hash=api_key_hash)
+        .execution_options(synchronize_session=False)
+    )
+    if claim.rowcount != 1:
+        await session.rollback()
+        return False, None
+
+    if invoice.purpose == "create":
+        await _create_api_key_record(invoice, session)
+    elif invoice.purpose == "topup":
+        await _topup_api_key_record(invoice, session)
+    else:
+        raise ValueError(f"Unsupported invoice purpose: {invoice.purpose}")
+    await session.commit()
+    return True, api_key_hash
+
+
+async def _reload_invoice_view(
+    invoice: LightningInvoice, _caller_session: AsyncSession
+) -> None:
+    """Publish committed invoice state without touching the caller transaction."""
+    async with create_session() as reload_session:
+        stored = await reload_session.get(LightningInvoice, invoice.id)
+        if stored is None:
+            return
+        status = stored.status
+        paid_at = stored.paid_at
+        api_key_hash = stored.api_key_hash
+        await reload_session.commit()
+    _publish_invoice_value(invoice, "status", status)
+    _publish_invoice_value(invoice, "paid_at", paid_at)
+    _publish_invoice_value(invoice, "api_key_hash", api_key_hash)
+
+
+async def _credit_topup_record(
+    invoice: LightningInvoice | _InvoiceSettlement, session: AsyncSession
+) -> None:
+    await _topup_api_key_record(invoice, session)
+
+
+# Nutshell mints throttle Lightning backend lookups to once per 10s per
+# quote, so polling faster just burns the global request budget for nothing.
+INVOICE_WATCH_INTERVAL_SECONDS = 10
+INVOICE_WATCH_BATCH_LIMIT = 100
+
+
+async def periodic_invoice_watcher() -> None:
+    """Background task: detect paid Lightning invoices and credit balances.
+
+    Removes the need for clients to poll the status endpoint after paying.
+    """
+    while True:
+        try:
+            async with create_session() as session:
+                now = int(time.time())
+                result = await session.exec(
+                    select(LightningInvoice)
+                    .where(
+                        LightningInvoice.status == "pending",
+                        col(LightningInvoice.expires_at) > now,
+                    )
+                    .limit(INVOICE_WATCH_BATCH_LIMIT)
+                )
+                pending = result.all()
+                for invoice in pending:
+                    try:
+                        await check_invoice_payment(invoice, session)
+                    except Exception as e:
+                        logger.error(
+                            "Invoice watcher failed for invoice",
+                            extra={"invoice_id": invoice.id, "error": str(e)},
+                        )
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.error(f"Invoice watcher loop error: {e}")
+
+        await asyncio.sleep(INVOICE_WATCH_INTERVAL_SECONDS)

routstr/payment/cost_calculation.py

@@ -1,11 +1,23 @@
 import math
+from typing import TYPE_CHECKING
 
 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
+
+if TYPE_CHECKING:
+    from .models import Model
+
+__all__ = [
+    "CostData",
+    "CostDataError",
+    "MaxCostData",
+    "calculate_cost",
+    "parse_token_count",
+]
 
 logger = get_logger(__name__)
 
@@ -18,6 +30,10 @@ class CostData(BaseModel):
     total_usd: float = 0.0
     input_tokens: int = 0
     output_tokens: int = 0
+    cache_read_input_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    cache_read_msats: int = 0
+    cache_creation_msats: int = 0
 
 
 class MaxCostData(CostData):
@@ -29,18 +45,54 @@ class CostDataError(BaseModel):
     code: str
 
 
-async def calculate_cost(  # todo: can be sync
-    response_data: dict, max_cost: int, session: AsyncSession
-) -> CostData | MaxCostData | CostDataError:
+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.
     """
-    Calculate the cost of an API request based on token usage.
+    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,
+    model_obj: "Model | None" = None,
+    provider_fee: float | None = None,
+) -> CostData | MaxCostData | CostDataError:
+    """Calculate the cost of an API request based on token usage.
 
     Args:
         response_data: Response data containing usage information
         max_cost: Maximum cost in millisats
+        model_obj: The model that actually served the request. When given,
+            its pricing is billed directly; without it, pricing is re-derived
+            from the response's model string via the alias map, which resolves
+            to the best-ranked candidate — not necessarily the serving one.
+        provider_fee: The serving provider's fee multiplier, applied on the
+            USD-cost path and the litellm pricing fallback (configured model
+            pricing already carries the fee baked in). Without it, the fee is
+            re-derived from the response's model string, which yields the
+            best-ranked provider's fee.
 
     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",
@@ -51,7 +103,9 @@ async def calculate_cost(  # todo: can be sync
         },
     )
 
-    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 "
@@ -66,86 +120,41 @@ async def calculate_cost(  # todo: can be sync
                 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,
-        )
+        return _empty_cost(MaxCostData)
 
-    usage_data = response_data["usage"]
+    usage_data = response_data.get("usage") or {}
+    if not isinstance(usage_data, dict):
+        usage_data = {}
 
-    def parse_token_count(value: object) -> int:
-        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
-
-    input_tokens = parse_token_count(usage_data.get("prompt_tokens", 0))
-    output_tokens = parse_token_count(usage_data.get("completion_tokens", 0))
-    input_tokens = (
-        input_tokens
-        if input_tokens != 0
-        else parse_token_count(usage_data.get("input_tokens", 0))
-    )
-    output_tokens = (
-        output_tokens
-        if output_tokens != 0
-        else parse_token_count(usage_data.get("output_tokens", 0))
-    )
-    input_tokens = (
-        input_tokens
-        if input_tokens != 0
-        else parse_token_count(response_data.get("usage", {}).get("input_tokens", 0))
-    )
-    output_tokens = (
-        output_tokens
-        if output_tokens != 0
-        else parse_token_count(response_data.get("usage", {}).get("output_tokens", 0))
-    )
-
-    usd_cost = 0.0
-    input_usd = 0.0
-    output_usd = 0.0
-
-    if "cost_details" in usage_data:
-        usd_cost = float(
-            usage_data["cost_details"].get("upstream_inference_cost", 0) or 0
-        )
-        input_usd = float(
-            usage_data["cost_details"].get("upstream_inference_prompt_cost", 0) or 0
-        )
-        output_usd = float(
-            usage_data["cost_details"].get("upstream_inference_completions_cost", 0)
-            or 0
-        )
-
-    # Fallback to cost field if upstream_inference_cost is 0
-    if usd_cost == 0 and "cost" in usage_data:
-        try:
-            usd_cost = float(usage_data.get("cost", 0) or 0)
-        except Exception:
-            pass
-
-    MSATS_PER_1K_INPUT_TOKENS: float = (
-        float(settings.fixed_per_1k_input_tokens) * 1000.0
-    )
-    MSATS_PER_1K_OUTPUT_TOKENS: float = (
-        float(settings.fixed_per_1k_output_tokens) * 1000.0
-    )
+    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 — "
@@ -163,43 +172,27 @@ async def calculate_cost(  # todo: can be sync
                 },
             )
         try:
-            sats_per_usd = 1.0 / sats_usd_price()
-            cost_in_sats = usd_cost * sats_per_usd
-            cost_in_msats = math.ceil(cost_in_sats * 1000)
-
-            input_msats = 0
-            output_msats = 0
-
-            if input_usd > 0 or output_usd > 0:
-                input_msats = int((input_usd * sats_per_usd) * 1000)
-                output_msats = int((output_usd * sats_per_usd) * 1000)
-            else:
-                total_tokens = input_tokens + output_tokens
-                if total_tokens > 0:
-                    input_ratio = input_tokens / total_tokens
-                    input_msats = int(cost_in_msats * input_ratio)
-                    output_msats = cost_in_msats - input_msats
-                else:
-                    output_msats = cost_in_msats
-
-            logger.info(
-                "Using cost from usage data/details",
-                extra={
-                    "usd_cost": usd_cost,
-                    "cost_in_sats": cost_in_sats,
-                    "cost_in_msats": cost_in_msats,
-                    "model": response_data.get("model", "unknown"),
-                },
+            cost_details = usage_data.get("cost_details", {})
+            if not isinstance(cost_details, dict):
+                cost_details = {}
+            input_usd = _coerce_usd(
+                cost_details.get("input_cost")
+                or cost_details.get("upstream_inference_prompt_cost")
             )
-
-            return CostData(
-                base_msats=0,
-                input_msats=input_msats,
-                output_msats=output_msats,
-                total_msats=cost_in_msats,
-                total_usd=usd_cost,
-                input_tokens=input_tokens,
-                output_tokens=output_tokens,
+            output_usd = _coerce_usd(
+                cost_details.get("output_cost")
+                or cost_details.get("upstream_inference_completions_cost")
+            )
+            return _calculate_from_usd_cost(
+                usd_cost,
+                input_usd,
+                output_usd,
+                input_tokens,
+                cache_read_tokens,
+                cache_creation_tokens,
+                output_tokens,
+                response_data,
+                provider_fee,
             )
         except Exception as e:
             logger.warning(
@@ -210,57 +203,22 @@ async def calculate_cost(  # todo: can be sync
                     "model": response_data.get("model", "unknown"),
                 },
             )
-            # Fall through to token-based calculation
 
-    if not settings.fixed_pricing:
-        response_model = response_data.get("model", "")
-        logger.debug(
-            "Using model-based pricing",
-            extra={"model": response_model},
-        )
+    # Fall back to token-based pricing
+    try:
+        pricing_rates = _get_pricing_rates(response_data, model_obj, provider_fee)
+    except ValueError as e:
+        return CostDataError(message=str(e), code="pricing_error")
 
-        from ..proxy import get_model_instance
+    if pricing_rates is None:
+        input_rate = float(settings.fixed_per_1k_input_tokens) * 1000.0
+        output_rate = float(settings.fixed_per_1k_output_tokens) * 1000.0
+        cache_read_rate = input_rate
+        cache_creation_rate = input_rate
+    else:
+        input_rate, output_rate, cache_read_rate, cache_creation_rate = pricing_rates
 
-        model_obj = get_model_instance(response_model)
-
-        if not model_obj:
-            logger.error(
-                "Invalid model in response",
-                extra={"response_model": response_model},
-            )
-            return CostDataError(
-                message=f"Invalid model in response: {response_model}",
-                code="model_not_found",
-            )
-
-        if not model_obj.sats_pricing:
-            logger.error(
-                "Model pricing not defined",
-                extra={"model": response_model, "model_id": response_model},
-            )
-            return CostDataError(
-                message="Model pricing not defined", code="pricing_not_found"
-            )
-
-        try:
-            mspp = float(model_obj.sats_pricing.prompt)
-            mspc = float(model_obj.sats_pricing.completion)
-        except Exception:
-            return CostDataError(message="Invalid pricing data", code="pricing_invalid")
-
-        MSATS_PER_1K_INPUT_TOKENS = mspp * 1_000_000.0
-        MSATS_PER_1K_OUTPUT_TOKENS = mspc * 1_000_000.0
-
-        logger.info(
-            "Applied model-specific pricing",
-            extra={
-                "model": response_model,
-                "input_price_msats_per_1k": MSATS_PER_1K_INPUT_TOKENS,
-                "output_price_msats_per_1k": MSATS_PER_1K_OUTPUT_TOKENS,
-            },
-        )
-
-    if not (MSATS_PER_1K_OUTPUT_TOKENS and MSATS_PER_1K_INPUT_TOKENS):
+    if not (input_rate and output_rate):
         logger.warning(
             "No token pricing configured — billing at flat MaxCostData. "
             "Token counts %s in the upstream response but cannot be "
@@ -283,12 +241,295 @@ async def calculate_cost(  # todo: can be sync
             total_msats=max_cost,
             input_tokens=input_tokens,
             output_tokens=output_tokens,
+            cache_read_input_tokens=cache_read_tokens,
+            cache_creation_input_tokens=cache_creation_tokens,
+            cache_read_msats=0,
+            cache_creation_msats=0,
         )
 
-    calc_input_msats = round(input_tokens / 1000 * MSATS_PER_1K_INPUT_TOKENS, 3)
+    return _calculate_from_tokens(
+        input_tokens,
+        output_tokens,
+        cache_read_tokens,
+        cache_creation_tokens,
+        input_rate,
+        output_rate,
+        cache_read_rate,
+        cache_creation_rate,
+        response_data,
+    )
 
-    calc_output_msats = round(output_tokens / 1000 * MSATS_PER_1K_OUTPUT_TOKENS, 3)
-    token_based_cost = math.ceil(calc_input_msats + calc_output_msats)
+
+# ============================================================================
+# Helper Functions (ordered by call sequence in calculate_cost)
+# ============================================================================
+
+
+def _coerce_usd(value: object) -> float:
+    """Coerce a value to USD float, handling various formats safely."""
+    if value is None or isinstance(value, bool):
+        return 0.0
+    if not isinstance(value, (int, float, str)):
+        return 0.0
+    try:
+        return max(0.0, float(value))
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _resolve_usd_cost(usage_data: dict, response_data: dict) -> float:
+    """Resolve USD cost with clear priority order.
+
+    Priority:
+
+    1. ``cost_details.total_cost``
+    2. ``cost_details.upstream_inference_cost`` (BYOK — see below)
+    3. ``total_cost`` → ``cost`` (in both usage and response)
+
+    **BYOK path (PPQ.AI):** when ``is_byok`` is true the ``usage.cost`` field
+    is only a small (~5 %) routing fee, not the inference cost.  The real cost
+    lives in ``cost_details.upstream_inference_cost`` and the provider's
+    balance is debited by ``upstream_inference_cost + byok_fee``.  Billing just
+    the fee under-charges by ~20×.
+    """
+    cost_details = usage_data.get("cost_details")
+    if isinstance(cost_details, dict):
+        cost = _coerce_usd(cost_details.get("total_cost"))
+        if cost > 0:
+            return cost
+
+        # PPQ.AI BYOK: upstream_inference_cost is the real inference cost;
+        # usage.cost is only a ~5 % BYOK routing fee.  Bill the sum — what PPQ
+        # actually deducts from the balance.  For non-BYOK providers (e.g.
+        # OpenRouter) usage.cost already equals upstream_inference_cost, so we
+        # fall through to the normal ``cost`` lookup below.
+        upstream_cost = _coerce_usd(
+            cost_details.get("upstream_inference_cost")
+        )
+        if upstream_cost > 0 and usage_data.get("is_byok"):
+            byok_fee = _coerce_usd(usage_data.get("cost"))
+            return upstream_cost + byok_fee
+
+    for source in [usage_data, response_data]:
+        if not isinstance(source, dict):
+            continue
+        for field in ("total_cost", "cost"):
+            cost = _coerce_usd(source.get(field))
+            if cost > 0:
+                return cost
+
+    return 0.0
+
+
+def _get_pricing_rates(
+    response_data: dict,
+    model_obj: "Model | None",
+    provider_fee: float | None,
+) -> tuple[float, float, float, float] | None:
+    """Get configured rates, falling back to LiteLLM's model cost map.
+
+    The served ``model_obj`` (when the caller has it) is billed directly;
+    otherwise the response's model string is resolved through the alias map,
+    which yields the best-ranked candidate rather than the serving one.
+
+    Returns: (input_rate, output_rate, cache_read_rate, cache_write_rate).
+    ``None`` means configured fixed pricing should be used by the caller.
+    """
+    if settings.fixed_pricing and (
+        settings.fixed_per_1k_input_tokens
+        or settings.fixed_per_1k_output_tokens
+    ):
+        return None
+
+    from ..proxy import get_model_instance
+    from .models import litellm_cost_entry
+
+    response_model = response_data.get("model", "")
+    if model_obj is None:
+        logger.warning(
+            "Settling without routed model identity — re-deriving pricing "
+            "from the response's model string via the alias map",
+            extra={"response_model": response_model},
+        )
+        model_obj = get_model_instance(response_model)
+
+    if model_obj and model_obj.sats_pricing:
+        try:
+            mspp = float(model_obj.sats_pricing.prompt)
+            mspc = float(model_obj.sats_pricing.completion)
+            mscr = float(model_obj.sats_pricing.input_cache_read or 0)
+            mscw = float(model_obj.sats_pricing.input_cache_write or 0)
+
+            mspp_1k = mspp * 1_000_000.0
+            mspc_1k = mspc * 1_000_000.0
+            mscr_1k = mscr * 1_000_000.0 if mscr > 0 else mspp_1k
+            mscw_1k = mscw * 1_000_000.0 if mscw > 0 else mspp_1k
+            source = "configured"
+        except Exception as e:
+            logger.error("Invalid pricing data", extra={"error": str(e)})
+            raise ValueError("Invalid pricing data") from e
+    else:
+        pricing_model = (
+            model_obj.forwarded_model_id if model_obj else None
+        ) or response_model
+        pricing = litellm_cost_entry(pricing_model)
+        if pricing is None:
+            logger.error(
+                "Model pricing not found in configured models or LiteLLM",
+                extra={
+                    "response_model": response_model,
+                    "pricing_model": pricing_model,
+                },
+            )
+            raise ValueError(f"Pricing not found for model: {response_model}")
+
+        input_usd = _coerce_usd(pricing.get("input_cost_per_token"))
+        output_usd = _coerce_usd(pricing.get("output_cost_per_token"))
+        if input_usd <= 0 or output_usd <= 0:
+            raise ValueError(f"Incomplete LiteLLM pricing for model: {pricing_model}")
+
+        if provider_fee is None:
+            provider_fee = _resolve_provider_fee(response_model)
+        usd_per_sat = sats_usd_price()
+        mspp_1k = input_usd * provider_fee * 1_000_000.0 / usd_per_sat
+        mspc_1k = output_usd * provider_fee * 1_000_000.0 / usd_per_sat
+        cache_read_usd = _coerce_usd(
+            pricing.get("cache_read_input_token_cost")
+        )
+        cache_write_usd = _coerce_usd(
+            pricing.get("cache_creation_input_token_cost")
+        )
+        mscr_1k = (
+            cache_read_usd * provider_fee * 1_000_000.0 / usd_per_sat
+            if cache_read_usd > 0
+            else mspp_1k
+        )
+        mscw_1k = (
+            cache_write_usd * provider_fee * 1_000_000.0 / usd_per_sat
+            if cache_write_usd > 0
+            else mspp_1k
+        )
+        source = "litellm"
+
+    logger.info(
+        "Applied model-specific pricing",
+        extra={
+            "model": response_model,
+            "pricing_source": source,
+            "input_price_msats_per_1k": mspp_1k,
+            "output_price_msats_per_1k": mspc_1k,
+            "cache_read_price_msats_per_1k": mscr_1k,
+            "cache_write_price_msats_per_1k": mscw_1k,
+        },
+    )
+    return mspp_1k, mspc_1k, mscr_1k, mscw_1k
+
+
+def _resolve_provider_fee(model_id: str) -> float:
+    """Resolve the provider fee multiplier for the given model id.
+
+    Falls back to 1.0 (no markup) when the provider cannot be resolved so
+    the USD cost path never silently double-applies or omits the fee.
+    """
+    from ..proxy import get_provider_for_model
+
+    if not model_id:
+        return 1.0
+    providers = get_provider_for_model(model_id)
+    if not providers:
+        return 1.0
+    return float(providers[0].provider_fee)
+
+
+def _calculate_from_usd_cost(
+    usd_cost: float,
+    input_usd: float,
+    output_usd: float,
+    input_tokens: int,
+    cache_read_tokens: int,
+    cache_creation_tokens: int,
+    output_tokens: int,
+    response_data: dict,
+    provider_fee: float | None,
+) -> CostData:
+    """Calculate cost from USD figures, deriving input/output split from tokens."""
+    if provider_fee is None:
+        provider_fee = _resolve_provider_fee(response_data.get("model", ""))
+    usd_cost = usd_cost * provider_fee
+    input_usd = input_usd * provider_fee
+    output_usd = output_usd * provider_fee
+    sats_per_usd = 1.0 / sats_usd_price()
+    cost_in_sats = usd_cost * sats_per_usd
+    cost_in_msats = math.ceil(cost_in_sats * 1000)
+
+    if input_usd > 0 or output_usd > 0:
+        # The total is the authoritative billed amount. Allocating that integer
+        # total proportionally avoids losing sub-millisatoshi remainders when
+        # input and output components are each truncated independently.
+        component_usd = input_usd + output_usd
+        input_msats = math.floor(cost_in_msats * input_usd / component_usd)
+        output_msats = cost_in_msats - input_msats
+    else:
+        effective_input_tokens = (
+            input_tokens + cache_read_tokens + cache_creation_tokens
+        )
+        total_tokens = effective_input_tokens + output_tokens
+        input_msats = (
+            int(cost_in_msats * effective_input_tokens / total_tokens)
+            if total_tokens > 0
+            else 0
+        )
+        output_msats = cost_in_msats - input_msats
+
+    logger.info(
+        "Using cost from usage data/details",
+        extra={
+            "usd_cost": usd_cost,
+            "cost_in_sats": cost_in_sats,
+            "cost_in_msats": cost_in_msats,
+            "model": response_data.get("model", "unknown"),
+        },
+    )
+
+    return CostData(
+        base_msats=0,
+        input_msats=input_msats,
+        output_msats=output_msats,
+        total_msats=cost_in_msats,
+        total_usd=usd_cost,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cache_read_input_tokens=cache_read_tokens,
+        cache_creation_input_tokens=cache_creation_tokens,
+        cache_read_msats=0,
+        cache_creation_msats=0,
+    )
+
+
+def _calculate_from_tokens(
+    input_tokens: int,
+    output_tokens: int,
+    cache_read_tokens: int,
+    cache_creation_tokens: int,
+    input_rate: float,
+    output_rate: float,
+    cache_read_rate: float,
+    cache_creation_rate: float,
+    response_data: dict,
+) -> CostData:
+    """Calculate cost from token counts using pricing rates."""
+    calc_input_msats = round(input_tokens / 1000 * input_rate, 3)
+    calc_output_msats = round(output_tokens / 1000 * output_rate, 3)
+    calc_cache_read_msats = round(cache_read_tokens / 1000 * cache_read_rate, 3)
+    calc_cache_write_msats = round(
+        cache_creation_tokens / 1000 * cache_creation_rate, 3
+    )
+    token_based_cost = math.ceil(
+        calc_input_msats
+        + calc_output_msats
+        + calc_cache_read_msats
+        + calc_cache_write_msats
+    )
     total_usd = (token_based_cost / 1000.0) * sats_usd_price()
 
     logger.info(
@@ -296,20 +537,39 @@ async def calculate_cost(  # todo: can be sync
         extra={
             "input_tokens": input_tokens,
             "output_tokens": output_tokens,
+            "cache_read_input_tokens": cache_read_tokens,
+            "cache_creation_input_tokens": cache_creation_tokens,
             "input_cost_msats": calc_input_msats,
             "output_cost_msats": calc_output_msats,
+            "cache_read_cost_msats": calc_cache_read_msats,
+            "cache_creation_cost_msats": calc_cache_write_msats,
             "total_cost_msats": token_based_cost,
             "total_usd": total_usd,
             "model": response_data.get("model", "unknown"),
         },
     )
 
+    # 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,
         output_tokens=output_tokens,
+        cache_read_input_tokens=cache_read_tokens,
+        cache_creation_input_tokens=cache_creation_tokens,
+        cache_read_msats=int(calc_cache_read_msats),
+        cache_creation_msats=int(calc_cache_write_msats),
     )

routstr/payment/helpers.py

@@ -11,11 +11,24 @@ 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
 
 logger = get_logger(__name__)
 
+# Interim policy: when Routstr must move value to another trusted mint, the
+# cross-mint Lightning round trip can consume fees that are not visible to the
+# client. Reserve 5% headroom until the fee-payer policy is made explicit.
+_MINT_FEE_ALLOWANCE = 0.05
+
+
+def apply_mint_fee_allowance(cost_msat: int) -> int:
+    """Reserve headroom for possible trusted-mint fallback fees."""
+    adjusted = math.ceil(cost_msat * (1 - _MINT_FEE_ALLOWANCE))
+    return max(settings.min_request_msat, adjusted)
+
 
 def check_token_balance(headers: dict, body: dict, max_cost_for_model: int) -> None:
     if x_cashu := headers.get("x-cashu", None):
@@ -418,16 +431,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 +459,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/lnurl.py

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

routstr/payment/models.py

@@ -3,7 +3,7 @@ import json
 import random
 
 import httpx
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel as V2BaseModel
 from pydantic.v1 import BaseModel
 from sqlmodel.ext.asyncio.session import AsyncSession
@@ -17,6 +17,24 @@ logger = get_logger(__name__)
 
 models_router = APIRouter()
 
+_MODEL_TEST_ENDPOINT_PATHS = {
+    "chat-completions": "chat/completions",
+    "completions": "completions",
+    "embeddings": "embeddings",
+    "responses": "responses",
+}
+
+# Cap the caller-supplied test payload to avoid forwarding oversized bodies
+# upstream on the operator's credentials.
+_MODEL_TEST_MAX_REQUEST_BYTES = 64 * 1024
+
+
+async def _require_admin_api(request: Request) -> None:
+    """Require admin auth without creating an import-time cycle with core.admin."""
+    from ..core.admin import require_admin_api
+
+    await require_admin_api(request)
+
 
 class Architecture(BaseModel):
     modality: str
@@ -67,6 +85,64 @@ class Model(BaseModel):
         return hash(self.id)
 
 
+def litellm_cost_entry(model_id: str) -> dict | None:
+    """Look up ``model_id`` in litellm's bundled cost map.
+
+    litellm ships per-model USD rates keyed by the exact OpenRouter id
+    (``deepseek/deepseek-chat``) or the bare model name (``gpt-4o``,
+    ``claude-sonnet-4-5``), so both spellings are tried. Keys are lowercase, so
+    a mixed-case upstream id (``deepseek-ai/DeepSeek-V4-Flash``) is retried via
+    a case-insensitive scan. Returns the matched cost dict, or ``None``.
+    """
+    import litellm
+
+    candidates = (model_id, model_id.split("/", 1)[-1])
+    for key in candidates:
+        info = litellm.model_cost.get(key)
+        if isinstance(info, dict):
+            return info
+
+    lowered = {c.lower() for c in candidates}
+    for key, info in litellm.model_cost.items():
+        if isinstance(key, str) and key.lower() in lowered and isinstance(info, dict):
+            return info
+    return None
+
+
+def backfill_cache_pricing(model_id: str, pricing: Pricing) -> Pricing:
+    """Fill missing cache rates from litellm's bundled cost map.
+
+    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). The lookup (see ``litellm_cost_entry``) tries both
+    id spellings and a case-insensitive fallback.
+
+    Rates already present (e.g. provided by OpenRouter) are authoritative and
+    never overwritten. Unknown models are returned unchanged.
+    """
+    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
+
+    info = litellm_cost_entry(model_id)
+    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", {})
@@ -155,13 +231,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,
@@ -363,7 +455,7 @@ async def _update_sats_pricing_once() -> None:
             for m in upstream.get_cached_models()
         ]
         upstream._models_cache = updated_models
-        upstream._models_by_id = {m.id: m for m in updated_models}
+        upstream._models_by_id = {m.forwarded_model_id or m.id: m for m in updated_models}
         updated_count += len(updated_models)
 
     if updated_count > 0:
@@ -418,7 +510,9 @@ class ModelTestRequest(V2BaseModel):
     request_data: dict
 
 
-@models_router.post("/api/models/test")
+@models_router.post(
+    "/api/models/test", dependencies=[Depends(_require_admin_api)]
+)
 async def test_model(
     payload: ModelTestRequest,
     session: AsyncSession = Depends(get_session),
@@ -446,16 +540,35 @@ async def test_model(
             "status_code": 404,
         }
 
-    base_url = provider.base_url.rstrip("/")
-    if payload.endpoint_type == "chat-completions":
-        url = f"{base_url}/chat/completions"
-    else:
-        url = f"{base_url}/{payload.endpoint_type}"
+    endpoint_path = _MODEL_TEST_ENDPOINT_PATHS.get(payload.endpoint_type)
+    if endpoint_path is None:
+        raise HTTPException(status_code=400, detail="Unsupported endpoint_type")
 
     actual_model_id = model_row.forwarded_model_id or model_row.id
     request_data = dict(payload.request_data)
     request_data["model"] = actual_model_id
 
+    try:
+        request_size = len(json.dumps(request_data).encode("utf-8"))
+    except (TypeError, ValueError):
+        raise HTTPException(status_code=400, detail="Invalid request_data")
+    if request_size > _MODEL_TEST_MAX_REQUEST_BYTES:
+        raise HTTPException(status_code=413, detail="request_data too large")
+
+    base_url = provider.base_url.rstrip("/")
+    url = f"{base_url}/{endpoint_path}"
+
+    logger.info(
+        "admin model test",
+        extra={
+            "model_id": payload.model_id,
+            "forwarded_model_id": actual_model_id,
+            "endpoint_type": payload.endpoint_type,
+            "upstream_provider_id": model_row.upstream_provider_id,
+            "request_bytes": request_size,
+        },
+    )
+
     headers = {
         "Content-Type": "application/json",
         "Authorization": f"Bearer {provider.api_key}",

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

@@ -1,3 +1,5 @@
+import asyncio
+import inspect
 import json
 from typing import Any
 
@@ -6,7 +8,13 @@ from fastapi.responses import Response, StreamingResponse
 from sqlmodel import select
 
 from .algorithm import create_model_mappings
-from .auth import pay_for_request, revert_pay_for_request, validate_bearer_key
+from .auth import (
+    ReservationSnapshot,
+    get_reservation_snapshot,
+    pay_for_request,
+    revert_pay_for_request,
+    validate_bearer_key,
+)
 from .core import get_logger
 from .core.db import (
     ApiKey,
@@ -17,28 +25,38 @@ from .core.db import (
     get_session,
 )
 from .core.exceptions import UpstreamError
-from .core.settings import settings
+from .core.not_found import build_not_found_response
 from .payment.helpers import (
+    apply_mint_fee_allowance,
     calculate_discounted_max_cost,
     check_token_balance,
     create_error_response,
+    create_upstream_error_response,
     get_max_cost_for_model,
 )
 from .payment.models import Model
 from .upstream import BaseUpstreamProvider
+from .upstream.ehbp import forward_ehbp_request, forward_ehbp_x_cashu_request
 from .upstream.helpers import init_upstreams
+from .upstream.request_correction import correct_request, extract_error_message
 
 logger = get_logger(__name__)
 proxy_router = APIRouter()
 
 _upstreams: list[BaseUpstreamProvider] = []
-_model_instances: dict[str, Model] = {}  # All aliases -> Model
 _provider_map: dict[
-    str, list[BaseUpstreamProvider]
-] = {}  # All aliases -> List[Provider]
+    str, list[tuple[Model, BaseUpstreamProvider]]
+] = {}  # All aliases -> sorted [(candidate Model, its Provider)]
 _unique_models: dict[str, Model] = {}  # Unique model.id -> Model (no duplicates)
 
 
+async def _finish_read_transaction(session: AsyncSession) -> None:
+    """Release a read transaction without assuming a particular session mock."""
+    commit_result = session.commit()
+    if inspect.isawaitable(commit_result):
+        await commit_result
+
+
 async def initialize_upstreams() -> None:
     """Initialize upstream providers from database during application startup."""
     global _upstreams
@@ -67,32 +85,44 @@ def get_upstreams() -> list[BaseUpstreamProvider]:
     return _upstreams
 
 
-def get_model_instance(model_id: str) -> Model | None:
-    """Get Model instance by ID from global cache."""
+def get_candidates(
+    model_id: str,
+) -> list[tuple[Model, BaseUpstreamProvider]] | None:
+    """Get the sorted (model, provider) candidate list for a model ID.
+
+    Each provider is paired with its own model for the alias, so routing can
+    forward and bill the candidate that actually serves. Version suffixes
+    (e.g. ``-20251222``) are stripped as a retry when the exact ID is
+    unknown, since upstreams may return a specific version of a base model
+    we track.
+    """
     if not model_id:
         return None
 
     model_id_lower = model_id.lower()
-    # Try exact match first
-    if model := _model_instances.get(model_id_lower):
-        return model
+    if candidates := _provider_map.get(model_id_lower):
+        return candidates
 
-    # Try stripping common version suffixes (e.g., -20251222)
-    # This handles cases where upstream returns a specific version
-    # but we only track the base model name.
     import re
 
     base_model_id = re.sub(r"-\d{8}$", "", model_id_lower)
     if base_model_id != model_id_lower:
-        if model := _model_instances.get(base_model_id):
-            return model
+        if candidates := _provider_map.get(base_model_id):
+            return candidates
 
     return None
 
 
+def get_model_instance(model_id: str) -> Model | None:
+    """Get the best-ranked Model instance for a model ID."""
+    candidates = get_candidates(model_id)
+    return candidates[0][0] if candidates else None
+
+
 def get_provider_for_model(model_id: str) -> list[BaseUpstreamProvider] | None:
-    """Get UpstreamProvider list for model ID from global cache."""
-    return _provider_map.get(model_id.lower())
+    """Get the sorted UpstreamProvider list for a model ID."""
+    candidates = get_candidates(model_id)
+    return [provider for _, provider in candidates] if candidates else None
 
 
 def get_unique_models() -> list[Model]:
@@ -100,11 +130,39 @@ def get_unique_models() -> list[Model]:
     return list(_unique_models.values())
 
 
+def _is_tinfoil_attestation_path(path: str) -> bool:
+    """Return True for exact Tinfoil attestation routes, with optional slash."""
+    return path in {
+        "attestation",
+        "attestation/",
+        "tee/attestation",
+        "tee/attestation/",
+    }
+
+
+def _select_unauthenticated_get_upstreams(
+    path: str, upstreams: list[BaseUpstreamProvider]
+) -> list[BaseUpstreamProvider]:
+    """Select upstream candidates for unauthenticated GET bypass paths.
+
+    Tinfoil attestation endpoints are provider-specific. Trying every enabled
+    upstream can return an unrelated provider's 404 before Tinfoil is reached,
+    so route those paths only to Tinfoil providers.
+    """
+    if _is_tinfoil_attestation_path(path):
+        return [
+            upstream
+            for upstream in upstreams
+            if getattr(upstream, "provider_type", None) == "tinfoil"
+        ]
+    return upstreams
+
+
 async def refresh_model_maps() -> None:
     """Refresh global model and provider maps using the cost-based algorithm."""
     from sqlalchemy.orm import selectinload
 
-    global _model_instances, _provider_map, _unique_models
+    global _provider_map, _unique_models
 
     async with create_session() as session:
         # Fetch all providers with their models in a single logical operation
@@ -114,22 +172,23 @@ async def refresh_model_maps() -> None:
         result = await session.exec(query)
         provider_rows = result.all()
 
-    overrides_by_id: dict[str, tuple[ModelRow, float]] = {}
-    disabled_model_ids: set[str] = set()
+    overrides_by_key: dict[tuple[str, int], tuple[ModelRow, float]] = {}
+    disabled_model_keys: set[tuple[str, int]] = set()
 
     for provider in provider_rows:
         if not provider.enabled:
             continue
         for model in provider.models:
+            model_key = (model.id.lower(), model.upstream_provider_id)
             if model.enabled:
-                overrides_by_id[model.id] = (model, provider.provider_fee)
+                overrides_by_key[model_key] = (model, provider.provider_fee)
             else:
-                disabled_model_ids.add(model.id)
+                disabled_model_keys.add(model_key)
 
-    _model_instances, _provider_map, _unique_models = create_model_mappings(
+    _, _provider_map, _unique_models = create_model_mappings(
         upstreams=_upstreams,
-        overrides_by_id=overrides_by_id,
-        disabled_model_ids=disabled_model_ids,
+        overrides_by_key=overrides_by_key,
+        disabled_model_keys=disabled_model_keys,
     )
 
 
@@ -150,40 +209,144 @@ async def refresh_model_maps_periodically() -> None:
             )
 
 
+_API_PATH_PREFIXES = (
+    "v1/",
+    "responses",
+    "chat/",
+    "completions",
+    "models",
+    "embeddings",
+    "audio/",
+    "images/",
+    "moderations",
+    "providers",
+    "tee/",
+    "attestation",
+)
+
+
 @proxy_router.api_route("/{path:path}", methods=["GET", "POST"], response_model=None)
 async def proxy(
     request: Request, path: str, session: AsyncSession = Depends(get_session)
 ) -> Response | StreamingResponse:
+    """Run proxy setup in a short request session, never across response streaming."""
+    try:
+        return await _proxy(request, path, session)
+    finally:
+        # FastAPI yield dependencies normally close after the response body is
+        # sent. Close explicitly so a long stream cannot retain DB resources.
+        close_result = session.close()
+        if inspect.isawaitable(close_result):
+            await close_result
+
+
+async def _proxy(
+    request: Request, path: str, session: AsyncSession
+) -> Response | StreamingResponse:
+    # GET requests must hit a known API prefix; otherwise return a 404 (HTML
+    # for browsers, JSON for API clients). POST requests are always forwarded
+    # so that OpenAI-style endpoints work with or without the `v1/` prefix
+    # (e.g. `/chat/completions` as well as `/v1/chat/completions`).
+    if request.method == "GET" and not path.startswith(_API_PATH_PREFIXES):
+        return build_not_found_response(request, path)
+
     headers = dict(request.headers)
 
     is_responses_api = path.startswith("v1/responses") or path.startswith("responses")
     request_body = await request.body()
-    request_body_dict = parse_request_body_json(request_body, path)
 
-    if is_responses_api:
-        model_id = extract_model_from_responses_request(request_body_dict)
+    # EHBP (Encrypted HTTP Body Protocol) requests carry an Ehbp-Encapsulated-Key
+    # header and a binary HPKE-sealed body. The proxy cannot parse the body to
+    # extract the model id, so the SDK sends it in X-Routstr-Model. Forward the
+    # raw encrypted body to the upstream's /private/ endpoint and stream the
+    # encrypted response back untouched — the SDK's SecureClient decrypts it.
+    is_ehbp = "ehbp-encapsulated-key" in headers
+    if is_ehbp:
+        request_body_dict = {}
+        model_id = headers.get("x-routstr-model", "")
+        if not model_id:
+            return create_error_response(
+                "invalid_request",
+                "EHBP request missing X-Routstr-Model header",
+                400,
+                request=request,
+            )
     else:
-        model_id = request_body_dict.get("model", "unknown")
+        request_body_dict = parse_request_body_json(request_body, path)
+        if is_responses_api:
+            model_id = extract_model_from_responses_request(request_body_dict)
+        else:
+            model_id = request_body_dict.get("model", "unknown")
 
-    model_obj = get_model_instance(model_id)
+    # Exact Tinfoil attestation GET routes don't map to models — forward
+    # without model/cost/auth lookups. Do not prefix-match here: paths such as
+    # /attestationjunk must continue through normal authentication.
+    if request.method == "GET" and _is_tinfoil_attestation_path(path):
+        selected_upstreams = _select_unauthenticated_get_upstreams(path, _upstreams)
+        if not selected_upstreams:
+            return create_error_response(
+                "upstream_error",
+                "No upstream available for unauthenticated GET path",
+                502,
+                request=request,
+            )
 
-    if not model_obj:
+        last_error_response = None
+        for i, upstream in enumerate(selected_upstreams):
+            try:
+                headers = upstream.prepare_headers(dict(request.headers))
+                response = await upstream.forward_get_request(request, path, headers)
+                if (
+                    response.status_code in [502, 429]
+                    and i < len(selected_upstreams) - 1
+                ):
+                    logger.warning(
+                        "Upstream %s returned %s for unauthenticated GET %s, trying next",
+                        upstream.provider_type,
+                        response.status_code,
+                        path,
+                    )
+                    continue
+                return response
+            except UpstreamError as e:
+                logger.warning(
+                    "Upstream %s failed for unauthenticated GET %s: %s",
+                    upstream.provider_type,
+                    path,
+                    e,
+                )
+                if i == len(selected_upstreams) - 1:
+                    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
+        )
+
+    candidates = get_candidates(model_id)
+
+    if not candidates:
         return create_error_response(
             "invalid_model", f"Model '{model_id}' not found", 400, request=request
         )
 
-    upstreams = get_provider_for_model(model_id)
-    if not upstreams:
-        return create_error_response(
-            "invalid_model",
-            f"No provider found for model '{model_id}'",
-            400,
-            request=request,
-        )
+    if is_ehbp:
+        candidates = [
+            (model, upstream)
+            for model, upstream in candidates
+            if upstream.supports_ehbp
+        ]
+        if not candidates:
+            return create_error_response(
+                "unsupported_request",
+                f"No EHBP-capable provider found for model '{model_id}'",
+                400,
+                request=request,
+            )
 
-    # todo figure out cost calculation since fallback provider is usually not the same price
-    # Use first provider for initial checks/cost calculation
-    # primary_upstream = upstreams[0]
+    # Reserve/max-cost checks use the best-ranked candidate; the failover loop
+    # below rebinds (model_obj, upstream) per candidate so forwarding and
+    # settlement always use the model of the provider actually being tried.
+    model_obj = candidates[0][0]
 
     _max_cost_for_model = await get_max_cost_for_model(
         model=model_id, session=session, model_obj=model_obj
@@ -191,16 +354,31 @@ async def proxy(
     max_cost_for_model = await calculate_discounted_max_cost(
         _max_cost_for_model, request_body_dict, model_obj=model_obj
     )
-    # Ensure max_cost_for_model is at least the minimum allowed request cost
-    max_cost_for_model = max(max_cost_for_model, settings.min_request_msat)
+    max_cost_for_model = apply_mint_fee_allowance(max_cost_for_model)
 
     check_token_balance(headers, request_body_dict, max_cost_for_model)
 
     if x_cashu := headers.get("x-cashu", None):
         last_error = None
-        for i, upstream in enumerate(upstreams):
+        for i, (model_obj, upstream) in enumerate(candidates):
             try:
-                if is_responses_api:
+                if is_ehbp:
+                    if not upstream.supports_ehbp:
+                        logger.warning(
+                            "Upstream %s does not support EHBP for model=%s",
+                            upstream.provider_type,
+                            model_id,
+                        )
+                        continue
+                    return await forward_ehbp_x_cashu_request(
+                        request=request,
+                        x_cashu_token=x_cashu,
+                        path=path,
+                        max_cost_for_model=max_cost_for_model,
+                        model_obj=model_obj,
+                        upstream=upstream,
+                    )
+                elif is_responses_api:
                     return await upstream.handle_x_cashu_responses(
                         request, x_cashu, path, max_cost_for_model, model_obj
                     )
@@ -210,17 +388,24 @@ async def proxy(
                     )
             except UpstreamError as e:
                 logger.warning(
-                    f"Upstream {upstream.provider_type} failed (x-cashu): {e}"
+                    "Upstream %s failed (x-cashu) for model=%s: %s",
+                    upstream.provider_type,
+                    model_id,
+                    e,
+                    extra={
+                        "provider": upstream.provider_type,
+                        "model": model_id,
+                        "status_code": e.status_code,
+                    },
                 )
-                if i == len(upstreams) - 1:
+                if i == len(candidates) - 1:
                     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):
@@ -240,12 +425,12 @@ async def proxy(
         logger.debug("Processing unauthenticated GET request", extra={"path": path})
 
         last_error_response = None
-        for i, upstream in enumerate(upstreams):
+        for i, (_, upstream) in enumerate(candidates):
             try:
                 headers = upstream.prepare_headers(dict(request.headers))
                 response = await upstream.forward_get_request(request, path, headers)
 
-                if response.status_code in [502, 429] and i < len(upstreams) - 1:
+                if response.status_code in [502, 429] and i < len(candidates) - 1:
                     error_message = ""
                     try:
                         if hasattr(response, "body"):
@@ -275,67 +460,165 @@ async def proxy(
                 return response
             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
-                    )
+                if i == len(candidates) - 1:
+                    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
         )
 
-    if request_body_dict:
+    reservation_snapshot: ReservationSnapshot | None = None
+    if is_ehbp or request_body_dict:
         await pay_for_request(key, max_cost_for_model, session)
+        reservation_snapshot = await get_reservation_snapshot(key, session)
+        # Snapshot validation performs SELECTs after pay_for_request commits.
+        # End that read transaction before waiting on upstream response headers.
+        await _finish_read_transaction(session)
+
+    # Tracks request params already removed in response to upstream rejections,
+    # shared across providers so a stripped param stays stripped on failover and
+    # the reactive retry can never loop unboundedly.
+    already_stripped: set[str] = set()
+
+    for i, (model_obj, upstream) in enumerate(candidates):
+        if i > 0 and request_body_dict:
+            # The reservation was sized to the previous candidate's envelope;
+            # settlement bills the serving candidate, so a pricier fallback
+            # must be re-reserved at its own max cost before it is tried. A
+            # candidate whose envelope the key cannot cover is rejected, just
+            # as it would be had it been ranked first.
+            candidate_max = await get_max_cost_for_model(
+                model=model_id, session=session, model_obj=model_obj
+            )
+            candidate_max = await calculate_discounted_max_cost(
+                candidate_max, request_body_dict, model_obj=model_obj
+            )
+            # Apply the same interim 5% trusted-mint fee headroom used for the
+            # first candidate; failover must not silently change admission.
+            candidate_max = apply_mint_fee_allowance(candidate_max)
+            if candidate_max > max_cost_for_model:
+                await revert_pay_for_request(
+                    key, session, max_cost_for_model, reservation_snapshot
+                )
+                try:
+                    await pay_for_request(key, candidate_max, session)
+                except HTTPException:
+                    if i == len(candidates) - 1:
+                        raise
+                    await pay_for_request(key, max_cost_for_model, session)
+                    reservation_snapshot = await get_reservation_snapshot(key, session)
+                    await _finish_read_transaction(session)
+                    continue
+                reservation_snapshot = await get_reservation_snapshot(key, session)
+                await _finish_read_transaction(session)
+                max_cost_for_model = candidate_max
 
-    for i, upstream in enumerate(upstreams):
         headers = upstream.prepare_headers(dict(request.headers))
 
         try:
-            try:
-                if is_responses_api:
-                    response = await upstream.forward_responses_request(
-                        request,
-                        path,
-                        headers,
-                        request_body,
-                        key,
-                        max_cost_for_model,
-                        session,
-                        model_obj,
+            while True:
+                try:
+                    if is_ehbp:
+                        if not upstream.supports_ehbp:
+                            logger.warning(
+                                "Upstream %s does not support EHBP for model=%s",
+                                upstream.provider_type,
+                                model_id,
+                            )
+                            raise UpstreamError(
+                                f"Provider {upstream.provider_type} does not support EHBP",
+                                status_code=400,
+                            )
+                        response = await forward_ehbp_request(
+                            request=request,
+                            path=path,
+                            headers=headers,
+                            request_body=request_body,
+                            upstream=upstream,
+                            key=key,
+                            max_cost_for_model=max_cost_for_model,
+                            session=session,
+                            model_obj=model_obj,
+                            reservation_snapshot=reservation_snapshot,
+                        )
+                    elif is_responses_api:
+                        response = await upstream.forward_responses_request(
+                            request,
+                            path,
+                            headers,
+                            request_body,
+                            key,
+                            max_cost_for_model,
+                            session,
+                            model_obj,
+                            reservation_snapshot,
+                        )
+                    else:
+                        response = await upstream.forward_request(
+                            request,
+                            path,
+                            headers,
+                            request_body,
+                            key,
+                            max_cost_for_model,
+                            session,
+                            model_obj,
+                            reservation_snapshot,
+                        )
+                except UpstreamError:
+                    # Let the outer UpstreamError handler manage retry/revert
+                    raise
+                except Exception as e:
+                    # Unexpected error (not an upstream failure) — revert and propagate
+                    logger.error(
+                        "Unexpected error in upstream request, reverting payment",
+                        extra={
+                            "error": str(e),
+                            "error_type": type(e).__name__,
+                            "path": path,
+                            "key_hash": key.hashed_key[:8] + "...",
+                            "max_cost_for_model": max_cost_for_model,
+                        },
                     )
-                else:
-                    response = await upstream.forward_request(
-                        request,
-                        path,
-                        headers,
-                        request_body,
-                        key,
-                        max_cost_for_model,
-                        session,
-                        model_obj,
+                    await revert_pay_for_request(
+                        key, session, max_cost_for_model, reservation_snapshot
                     )
-            except UpstreamError:
-                # Let the outer UpstreamError handler manage retry/revert
-                raise
-            except Exception as e:
-                # Unexpected error (not an upstream failure) — revert and propagate
-                logger.error(
-                    "Unexpected error in upstream request, reverting payment",
-                    extra={
-                        "error": str(e),
-                        "error_type": type(e).__name__,
-                        "path": path,
-                        "key_hash": key.hashed_key[:8] + "...",
-                        "max_cost_for_model": max_cost_for_model,
-                    },
-                )
-                await revert_pay_for_request(key, session, max_cost_for_model)
-                raise
+                    raise
+
+                # Reactive recovery: some models reject one specific request
+                # param (e.g. newer Anthropic models deprecating `temperature`).
+                # When the upstream 400s naming such a param, strip it from the
+                # body and retry the SAME upstream. ``already_stripped`` bounds
+                # this to one retry per distinct param so it always terminates.
+                if response.status_code == 400 and not is_ehbp:
+                    correction = correct_request(
+                        request_body,
+                        extract_error_message(response),
+                        already_stripped,
+                    )
+                    if correction is not None:
+                        request_body, bad_param = correction.body, correction.label
+                        already_stripped.add(bad_param)
+                        logger.warning(
+                            "Upstream %s rejected param '%s' for model=%s; "
+                            "stripping and retrying same upstream",
+                            upstream.provider_type,
+                            bad_param,
+                            model_id,
+                            extra={
+                                "provider": upstream.provider_type,
+                                "model": model_id,
+                                "stripped_param": bad_param,
+                                "path": path,
+                            },
+                        )
+                        continue
+                break
 
             if response.status_code != 200:
                 # Check if we should retry (502 Upstream Error or 429 Rate Limit)
                 should_retry = response.status_code in [502, 429, 400, 401, 403, 404]
-                if should_retry and i < len(upstreams) - 1:
+                if should_retry and i < len(candidates) - 1:
                     error_message = ""
                     try:
                         if hasattr(response, "body"):
@@ -355,45 +638,80 @@ async def proxy(
                     )
 
                     logger.warning(
-                        f"Upstream {upstream.provider_type} returned {response.status_code}, trying next provider",
+                        "Upstream %s returned %s for model=%s, trying next provider",
+                        upstream.provider_type,
+                        response.status_code,
+                        model_id,
                         extra={
                             "status_code": response.status_code,
-                            "upstream": upstream.provider_type,
+                            "provider": upstream.provider_type,
+                            "model": model_id,
                         },
                     )
                     continue
 
                 # 4xx error (user error), or other non-retryable error, or last provider failed
-                await revert_pay_for_request(key, session, max_cost_for_model)
+                await revert_pay_for_request(
+                    key, session, max_cost_for_model, reservation_snapshot
+                )
                 logger.warning(
-                    "Upstream request failed, revert payment",
+                    "Upstream request failed, revert payment "
+                    "(provider=%s model=%s status=%s path=%s)",
+                    upstream.provider_type,
+                    model_id,
+                    response.status_code,
+                    path,
                     extra={
                         "status_code": response.status_code,
                         "path": path,
+                        "provider": upstream.provider_type,
+                        "model": model_id,
                         "key_hash": key.hashed_key[:8] + "...",
                         "key_balance": key.balance,
                         "max_cost_for_model": max_cost_for_model,
-                        "upstream_headers": response.headers
-                        if hasattr(response, "headers")
-                        else None,
                     },
                 )
                 return response
 
             return response
 
+        except asyncio.CancelledError:
+            logger.warning(
+                "Client disconnected mid-request, reverting reservation",
+                extra={
+                    "path": path,
+                    "model": model_id,
+                    "key_hash": key.hashed_key[:8] + "...",
+                    "max_cost_for_model": max_cost_for_model,
+                },
+            )
+            # The cancellation has been caught, so complete exact cleanup in
+            # this task before the request-scoped session can be torn down.
+            await revert_pay_for_request(
+                key, session, max_cost_for_model, reservation_snapshot
+            )
+            raise
+
         except UpstreamError as e:
             logger.warning(
-                f"Upstream {upstream.provider_type} failed: {e}",
-                extra={"retry": i < len(upstreams) - 1},
+                "Upstream %s failed for model=%s: %s",
+                upstream.provider_type,
+                model_id,
+                e,
+                extra={
+                    "provider": upstream.provider_type,
+                    "model": model_id,
+                    "status_code": e.status_code,
+                    "retry": i < len(candidates) - 1,
+                },
             )
 
             # 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
+            if i == len(candidates) - 1:
+                await revert_pay_for_request(
+                    key, session, max_cost_for_model, reservation_snapshot
                 )
+                return create_upstream_error_response(e, request)
 
             # Otherwise loop continues to next provider
             continue
@@ -477,17 +795,29 @@ async def get_bearer_token_key(
             },
         )
         return key
-    except Exception as e:
-        key_preview = bearer_key[:20] + "..." if len(bearer_key) > 20 else bearer_key
-        logger.error(
-            f"Bearer token validation failed: {type(e).__name__}: {e} path={path} model={model_id!r} min_cost={min_cost} key={key_preview!r}",
+    except HTTPException as error:
+        detail: dict[str, Any] = error.detail if isinstance(error.detail, dict) else {}
+        raw_error = detail.get("error")
+        error_info = raw_error if isinstance(raw_error, dict) else {}
+        logger.warning(
+            "Bearer token rejected",
             extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
+                "status_code": error.status_code,
+                "error_code": error_info.get("code"),
                 "path": path,
                 "model_id": model_id,
-                "min_cost_msat": min_cost,
-                "bearer_key_preview": key_preview,
+                "required_msat": min_cost,
+            },
+        )
+        raise
+    except Exception as error:
+        logger.exception(
+            "Bearer token validation failed",
+            extra={
+                "error_type": type(error).__name__,
+                "path": path,
+                "model_id": model_id,
+                "required_msat": min_cost,
             },
         )
         raise

routstr/upstream/__init__.py

@@ -11,6 +11,7 @@ from .openrouter import OpenRouterUpstreamProvider
 from .perplexity import PerplexityUpstreamProvider
 from .ppqai import PPQAIUpstreamProvider
 from .routstr import RoutstrUpstreamProvider
+from .tinfoil import TinfoilUpstreamProvider
 from .xai import XAIUpstreamProvider
 
 upstream_provider_classes: list[type[BaseUpstreamProvider]] = [
@@ -26,6 +27,7 @@ upstream_provider_classes: list[type[BaseUpstreamProvider]] = [
     PerplexityUpstreamProvider,
     PPQAIUpstreamProvider,
     RoutstrUpstreamProvider,
+    TinfoilUpstreamProvider,
     XAIUpstreamProvider,
 ]
 """List of all upstream classes"""

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

@@ -4,8 +4,15 @@ import json
 from sqlmodel import select
 
 from ..core import get_logger
-from ..core.db import UpstreamProviderRow, create_session
-from ..wallet import send_token
+from ..core.db import (
+    CashuTransaction,
+    UpstreamProviderRow,
+    create_session,
+)
+from ..core.db import (
+    store_cashu_transaction_with_retry as store_cashu_transaction,
+)
+from ..wallet import release_token_reservation, send_token, token_mint_url
 from .routstr import RoutstrUpstreamProvider
 
 logger = get_logger(__name__)
@@ -97,6 +104,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:
@@ -121,7 +130,6 @@ async def _check_and_topup(row: UpstreamProviderRow) -> None:
         },
     )
 
-    print(amount, mint_url)
     try:
         token = await send_token(amount, "sat", mint_url)
     except Exception as e:
@@ -136,6 +144,40 @@ async def _check_and_topup(row: UpstreamProviderRow) -> None:
         )
         return
 
+    actual_mint_url = token_mint_url(token, mint_url)
+    try:
+        await store_cashu_transaction(
+            token=token,
+            amount=amount,
+            unit="sat",
+            mint_url=actual_mint_url,
+            typ="out",
+            collected=False,
+            source="auto_topup",
+        )
+    except Exception:
+        logger.critical(
+            "Aborting auto top-up because its cashu token could not be persisted",
+            extra={"provider_id": row.id, "mint_url": actual_mint_url},
+        )
+        try:
+            await release_token_reservation(token)
+        except Exception as error:
+            logger.critical(
+                "Failed to release untracked auto-topup token",
+                extra={
+                    "provider_id": row.id,
+                    "mint_url": actual_mint_url,
+                    "error": str(error),
+                },
+            )
+        else:
+            logger.warning(
+                "Auto-topup token was released after persistence failed",
+                extra={"provider_id": row.id, "mint_url": actual_mint_url},
+            )
+        return
+
     result = await provider.topup(token)
 
     if "error" in result:
@@ -147,6 +189,26 @@ async def _check_and_topup(row: UpstreamProviderRow) -> None:
             },
         )
     else:
+        async with create_session() as session:
+            transaction = (
+                await session.exec(
+                    select(CashuTransaction).where(
+                        CashuTransaction.token == token,
+                        CashuTransaction.type == "out",
+                        CashuTransaction.source == "auto_topup",
+                    )
+                )
+            ).first()
+            if transaction is None:
+                logger.critical(
+                    "Completed auto top-up transaction is missing from the database",
+                    extra={"provider_id": row.id, "mint_url": mint_url},
+                )
+            else:
+                transaction.collected = True
+                session.add(transaction)
+                await session.commit()
+
         logger.info(
             "Auto top-up completed successfully",
             extra={

routstr/upstream/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/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/count_tokens.py

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

routstr/upstream/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

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

routstr/upstream/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
 
@@ -93,12 +94,10 @@ async def get_all_models_with_overrides(
         provider_result = await session.exec(select(UpstreamProviderRow))
         providers_by_id = {p.id: p for p in provider_result.all()}
 
-        overrides_by_id: dict[str, tuple[ModelRow, float]] = {
-            row.id: (
+        overrides_by_key: dict[tuple[str, int], tuple[ModelRow, float]] = {
+            (row.id.lower(), row.upstream_provider_id): (
                 row,
-                providers_by_id[row.upstream_provider_id].provider_fee
-                if row.upstream_provider_id in providers_by_id
-                else 1.01,
+                providers_by_id[row.upstream_provider_id].provider_fee,
             )
             for row in override_rows
             if row.upstream_provider_id is not None
@@ -106,17 +105,28 @@ async def get_all_models_with_overrides(
             and providers_by_id[row.upstream_provider_id].enabled
         }
 
-    all_models: dict[str, Model] = {}
+    all_models: dict[tuple[str, str], Model] = {}
 
     for upstream in upstreams:
+        upstream_db_id = getattr(upstream, "db_id", None)
+        provider_key = (
+            f"db:{upstream_db_id}"
+            if isinstance(upstream_db_id, int)
+            else f"{getattr(upstream, 'provider_type', '')}|{getattr(upstream, 'base_url', '')}"
+        )
         for model in upstream.get_cached_models():
-            if model.id in overrides_by_id:
-                override_row, provider_fee = overrides_by_id[model.id]
-                all_models[model.id] = _row_to_model(
+            model_key = (
+                (model.id.lower(), upstream_db_id)
+                if isinstance(upstream_db_id, int)
+                else None
+            )
+            if model_key is not None and model_key in overrides_by_key:
+                override_row, provider_fee = overrides_by_key[model_key]
+                all_models[(model.id.lower(), provider_key)] = _row_to_model(
                     override_row, apply_provider_fee=True, provider_fee=provider_fee
                 )
             elif model.enabled:
-                all_models[model.id] = model
+                all_models[(model.id.lower(), provider_key)] = model
 
     return list(all_models.values())
 
@@ -215,9 +225,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 +257,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
@@ -264,6 +272,7 @@ async def _seed_providers_from_settings(
         ("PERPLEXITY_API_KEY", "perplexity", None, None),
         ("FIREWORKS_API_KEY", "fireworks", None, None),
         ("XAI_API_KEY", "xai", None, None),
+        ("TINFOIL_API_KEY", "tinfoil", None, None),
     ]
 
     for env_key, provider_type, _, _ in env_mappings:
@@ -279,8 +288,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 +313,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 +339,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 +366,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 +385,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 +420,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__)
 
@@ -248,12 +250,28 @@ class AnnotatedEvent(NamedTuple):
     streaming paths in ``BaseUpstreamProvider`` consume ``sse_bytes`` plus
     the tallies and only differ in whether they stream live or buffer
     first.
+
+    ``cache_read_input_tokens`` and ``cache_creation_input_tokens`` are
+    surfaced separately so the cost path can price them against the cache
+    rate rather than fold them silently into the regular input bucket.
+
+    ``total_cost`` / ``input_cost`` / ``output_cost`` carry any
+    USD cost figures the upstream attached to this event (from
+    ``usage.cost``, ``usage.total_cost``, or ``usage.cost_details``) so the
+    streaming paths can re-embed them in the rebuilt ``usage`` dict and let
+    ``calculate_cost`` convert directly USD→sats instead of falling back to
+    token-based math.
     """
 
     event: dict
     sse_bytes: bytes
     input_tokens: int
     output_tokens: int
+    cache_read_input_tokens: int
+    cache_creation_input_tokens: int
+    total_cost: float
+    input_cost: float
+    output_cost: float
     model: str | None
 
 
@@ -272,21 +290,65 @@ def annotate_event(event: dict, requested_model: str | None) -> AnnotatedEvent:
 
     in_tokens = 0
     out_tokens = 0
+    cache_read_tokens = 0
+    cache_create_tokens = 0
+    total_cost = 0.0
+    input_cost = 0.0
+    output_cost = 0.0
     model: str | None = None
 
+    def _coerce_float(value: object) -> float:
+        if value is None or isinstance(value, bool):
+            return 0.0
+        if not isinstance(value, (int, float, str)):
+            return 0.0
+        try:
+            return max(0.0, float(value))
+        except (TypeError, ValueError):
+            return 0.0
+
+    def _accumulate(usage: dict) -> None:
+        nonlocal in_tokens, out_tokens, cache_read_tokens, cache_create_tokens
+        nonlocal total_cost, input_cost, output_cost
+        in_tokens += int(usage.get("input_tokens") or 0)
+        out_tokens += int(usage.get("output_tokens") or 0)
+        cache_read_tokens += int(usage.get("cache_read_input_tokens") or 0)
+        cache_create_tokens += int(usage.get("cache_creation_input_tokens") or 0)
+        total_cost += _coerce_float(usage.get("total_cost"))
+        input_cost += _coerce_float(usage.get("input_cost"))
+        output_cost += _coerce_float(usage.get("output_cost"))
+
     msg_for_meta = event.get("message")
     if isinstance(msg_for_meta, dict):
         if msg_for_meta.get("model"):
             model = str(msg_for_meta["model"])
         usage = msg_for_meta.get("usage")
         if isinstance(usage, dict):
-            in_tokens += int(usage.get("input_tokens") or 0)
-            out_tokens += int(usage.get("output_tokens") or 0)
+            _accumulate(usage)
 
     if isinstance(event.get("usage"), dict):
-        usage = event["usage"]
-        in_tokens += int(usage.get("input_tokens") or 0)
-        out_tokens += int(usage.get("output_tokens") or 0)
+        _accumulate(event["usage"])
+
+    # Some upstreams (notably OpenRouter-style proxies) attach cost fields
+    # directly at the event root rather than inside ``usage``.
+    for field in ("total_cost", "cost"):
+        total_cost = max(total_cost, _coerce_float(event.get(field)))
+    input_cost = max(input_cost, _coerce_float(event.get("input_cost")))
+    output_cost = max(output_cost, _coerce_float(event.get("output_cost")))
+    root_cost_details = event.get("cost_details")
+    if isinstance(root_cost_details, dict):
+        total_cost = max(
+            total_cost,
+            _coerce_float(root_cost_details.get("total_cost")),
+        )
+        input_cost = max(
+            input_cost,
+            _coerce_float(root_cost_details.get("input_cost")),
+        )
+        output_cost = max(
+            output_cost,
+            _coerce_float(root_cost_details.get("output_cost")),
+        )
 
     event_type = str(event.get("type") or "")
     payload = json.dumps(event)
@@ -295,7 +357,18 @@ def annotate_event(event: dict, requested_model: str | None) -> AnnotatedEvent:
     else:
         sse_bytes = f"data: {payload}\n\n".encode()
 
-    return AnnotatedEvent(event, sse_bytes, in_tokens, out_tokens, model)
+    return AnnotatedEvent(
+        event,
+        sse_bytes,
+        in_tokens,
+        out_tokens,
+        cache_read_tokens,
+        cache_create_tokens,
+        total_cost,
+        input_cost,
+        output_cost,
+        model,
+    )
 
 
 async def stream_annotated_events(
@@ -315,6 +388,38 @@ async def stream_annotated_events(
             yield annotate_event(event, requested_model)
 
 
+def embed_usd_costs(
+    usage: dict,
+    total_cost: float,
+    input_cost: float,
+    output_cost: float,
+) -> None:
+    """Mutate ``usage`` so ``calculate_cost`` will pick up the USD totals.
+
+    Mirrors the upstream shape: when any USD figure is present, attach
+    ``cost`` (used by the simple-fallback branch in ``calculate_cost``) and
+    a ``cost_details`` block (used by the preferred branch — also gives the
+    input/output USD split when we have one).
+    """
+    if total_cost <= 0 and input_cost <= 0 and output_cost <= 0:
+        return
+
+    cost_details: dict[str, float] = {}
+    effective_total = total_cost
+    if effective_total <= 0 and (input_cost > 0 or output_cost > 0):
+        effective_total = input_cost + output_cost
+
+    if effective_total > 0:
+        cost_details["total_cost"] = effective_total
+        usage["cost"] = effective_total
+    if input_cost > 0:
+        cost_details["input_cost"] = input_cost
+    if output_cost > 0:
+        cost_details["output_cost"] = output_cost
+    if cost_details:
+        usage["cost_details"] = cost_details
+
+
 def compute_refund(amount: int, unit: str, cost_msats: int) -> int:
     if unit == "msat":
         return amount - cost_msats
@@ -402,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,
@@ -426,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/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(
@@ -185,7 +185,7 @@ class OllamaUpstreamProvider(BaseUpstreamProvider):
             except Exception:
                 self._models_cache = models_with_fees
 
-            self._models_by_id = {m.id: m for m in self._models_cache}
+            self._models_by_id = {m.forwarded_model_id or m.id: m for m in self._models_cache}
             logger.info(
                 f"Refreshed models cache for {self.base_url}",
                 extra={"model_count": len(models)},

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

@@ -18,6 +18,33 @@ class OpenRouterUpstreamProvider(BaseUpstreamProvider):
     supports_anthropic_messages = True
     litellm_provider_prefix = "openrouter/"
 
+    def _apply_provider_field(self, response_json: object) -> None:
+        """Stamp the ``provider`` field for OpenRouter responses.
+
+        OpenRouter is a router, not the real serving provider, so a bare
+        ``"openrouter"`` value carries no useful information. Rules:
+
+        - Real upstream sub-provider (e.g. ``"GMICloud"``) -> ``"openrouter:GMICloud"``.
+        - Missing sub-provider, or one that merely echoes ``"openrouter"`` ->
+          ``"unknown"``.
+        - Idempotent: re-stamping never produces ``"openrouter:openrouter:..."``;
+          the ``openrouter:`` prefix appears at most once.
+        """
+        if not isinstance(response_json, dict):
+            return
+        provider_type = (self.provider_type or "").strip()
+        existing = response_json.get("provider")
+        sub = existing.strip() if isinstance(existing, str) else ""
+        # Strip any already-applied "openrouter:" prefixes (idempotency).
+        prefix = f"{provider_type}:"
+        while sub.lower().startswith(prefix.lower()):
+            sub = sub[len(prefix) :].strip()
+        # No real sub-provider, or it just echoes our own router name.
+        if not sub or sub.lower() == provider_type.lower():
+            response_json["provider"] = "unknown"
+            return
+        response_json["provider"] = f"{provider_type}:{sub}"
+
     def __init__(self, api_key: str, provider_fee: float = 1.06):
         """Initialize OpenRouter provider with API key.
 
@@ -30,7 +57,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

@@ -8,6 +8,7 @@ from pydantic.v1 import BaseModel, Field
 from ..core.logging import get_logger
 from ..payment.models import Architecture, Model, Pricing, async_fetch_openrouter_models
 from .base import BaseUpstreamProvider, TopupData
+from .ehbp import EHBPForwardingTarget
 
 if TYPE_CHECKING:
     from ..core.db import UpstreamProviderRow
@@ -39,6 +40,10 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
     default_base_url = "https://api.ppq.ai"
     platform_url = "https://ppq.ai/api-docs"
     IGNORED_MODEL_IDS: list[str] = ["auto"]
+    # PPQ.AI has a private encrypted endpoint, but this proxy currently has no
+    # provider-attested usage extractor/model binding for it. Keep EHBP disabled
+    # until a ConfidentialInferenceProfile can bill it without max-cost fallback.
+    supports_ehbp = False
 
     def __init__(self, api_key: str, provider_fee: float = 1.0):
         super().__init__(
@@ -46,7 +51,7 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "PPQAIUpstreamProvider":
         return cls(
@@ -70,6 +75,20 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
     def transform_model_name(self, model_id: str) -> str:
         return model_id
 
+    def get_ehbp_forwarding_target(
+        self, path: str, model_obj: Model
+    ) -> EHBPForwardingTarget:
+        """Return the PPQ.AI private enclave target for EHBP requests.
+
+        PPQ.AI exposes EHBP-aware inference under /private/v1/... separate
+        from the public /v1/... endpoint. The encrypted body remains opaque to
+        Routstr, so PPQ.AI also needs X-Private-Model for routing/billing.
+        """
+        return EHBPForwardingTarget(
+            url=f"{self.base_url.rstrip('/')}/private/{path.lstrip('/')}",
+            headers={"X-Private-Model": model_obj.forwarded_model_id or model_obj.id},
+        )
+
     @classmethod
     async def create_account_static(cls) -> dict[str, object]:
         """Create a new PPQ.AI account without requiring an instance.
@@ -229,17 +248,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/pricing_resolver.py

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

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/request_correction.py

@@ -0,0 +1,142 @@
+"""Reactive request-correction layer.
+
+When an upstream rejects a request with a recoverable 4xx error, this layer
+tries to *fix* the request body and let the caller retry the same upstream
+instead of failing outright. It is provider-agnostic: correctors key off the
+upstream's own error wording, so the same recovery works across every provider.
+
+The layer is a small pipeline of :data:`Corrector` callables. Each corrector
+inspects the parsed request body and the upstream error message and either
+returns a corrected body (plus a short label identifying the fix) or declines
+by returning ``None``. Adding a new reactive fix means writing one corrector
+and adding it to :data:`DEFAULT_CORRECTORS` — no changes to the proxy loop.
+
+All corrections are immutable: a corrector never mutates the body it is given,
+it returns a new ``dict``. The proxy threads an ``applied`` set of fix labels
+through retries so each distinct fix is applied at most once, guaranteeing the
+retry loop always terminates.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from fastapi.responses import Response
+
+from ..core import get_logger
+
+logger = get_logger(__name__)
+
+
+# Matches upstream error text that names a single rejected request parameter,
+# e.g. "`temperature` is deprecated for this model." or
+# "parameter 'top_p' is not supported". Keys off the upstream's own wording so
+# a 400 about an unsupported sampling/option field can be recovered by stripping
+# that field and retrying the same upstream.
+_UNSUPPORTED_PARAM_RE = re.compile(
+    r"[`'\"]?(?P<param>[a-zA-Z_][a-zA-Z0-9_]*)[`'\"]?\s+is\s+"
+    r"(?:deprecated|not\s+supported|unsupported|no\s+longer\s+supported)",
+    re.IGNORECASE,
+)
+
+
+# A corrector inspects the parsed request body and the upstream error message
+# and returns ``(new_body_dict, label)`` for a fix it can apply, or ``None`` to
+# decline. ``label`` identifies the fix so it is applied at most once per request.
+Corrector = Callable[[dict, str], "tuple[dict, str] | None"]
+
+
+@dataclass(frozen=True)
+class Correction:
+    """A successful request correction ready to retry.
+
+    ``body`` is the corrected JSON body (encoded), ``label`` identifies the fix
+    that was applied (e.g. the stripped param name) so the caller can guard
+    against applying the same fix twice.
+    """
+
+    body: bytes
+    label: str
+
+
+def extract_error_message(response: Response) -> str:
+    """Best-effort extraction of an error message string from a proxy Response."""
+    body_bytes = getattr(response, "body", None)
+    if not body_bytes:
+        return ""
+    try:
+        data = json.loads(body_bytes)
+    except Exception:
+        return body_bytes.decode("utf-8", errors="ignore")[:500]
+    if isinstance(data, dict):
+        err = data.get("error")
+        if isinstance(err, dict):
+            msg = err.get("message") or err.get("detail")
+            if isinstance(msg, str):
+                return msg
+        elif isinstance(err, str):
+            return err
+        if isinstance(data.get("message"), str):
+            return data["message"]
+    return ""
+
+
+def strip_unsupported_param(
+    body: dict, error_message: str
+) -> tuple[dict, str] | None:
+    """Drop a top-level param the upstream named as unsupported/deprecated.
+
+    Returns ``(new_body, param)`` (a new dict, original untouched) when the
+    error names a top-level param present in the body, otherwise ``None``.
+    """
+    match = _UNSUPPORTED_PARAM_RE.search(error_message)
+    if not match:
+        return None
+    param = match.group("param")
+    if param not in body:
+        return None
+    new_body = {k: v for k, v in body.items() if k != param}
+    return new_body, param
+
+
+# Ordered pipeline of correctors tried on each recoverable rejection.
+DEFAULT_CORRECTORS: tuple[Corrector, ...] = (strip_unsupported_param,)
+
+
+def correct_request(
+    request_body: bytes,
+    error_message: str,
+    applied: set[str],
+    correctors: Sequence[Corrector] = DEFAULT_CORRECTORS,
+) -> Correction | None:
+    """Try to correct a rejected request body so it can be retried.
+
+    Runs each corrector in order against the parsed body and ``error_message``.
+    The first corrector that proposes a fix whose ``label`` is not already in
+    ``applied`` wins; its result is returned as a :class:`Correction`. Returns
+    ``None`` when nothing parses, nothing matches, or every proposed fix was
+    already applied — the caller then treats the response as a normal failure.
+
+    ``applied`` is read-only here; the caller records the returned ``label`` to
+    bound retries and guarantee forward progress.
+    """
+    if not request_body or not error_message:
+        return None
+    try:
+        data = json.loads(request_body)
+    except Exception:
+        return None
+    if not isinstance(data, dict):
+        return None
+    for corrector in correctors:
+        result = corrector(data, error_message)
+        if result is None:
+            continue
+        new_body, label = result
+        if label in applied:
+            continue
+        return Correction(body=json.dumps(new_body).encode(), label=label)
+    return None

routstr/upstream/routstr.py

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

routstr/upstream/tinfoil.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+from fastapi import Request
+from fastapi.responses import Response, StreamingResponse
+from pydantic.v1 import BaseModel
+
+from ..core.exceptions import UpstreamError
+from ..core.logging import get_logger
+from ..payment.models import Architecture, Model, Pricing
+from .base import BaseUpstreamProvider
+from .ehbp import (
+    _ENCLAVE_URL_HEADER,
+    _PROXY_ONLY_HEADERS,
+    _RESPONSE_USAGE_HEADER,
+    ConfidentialInferenceProfile,
+    EHBPForwardingTarget,
+)
+
+if TYPE_CHECKING:
+    from ..core.db import UpstreamProviderRow
+
+logger = get_logger(__name__)
+
+
+class TinfoilModelPricing(BaseModel):
+    inputTokenPricePer1M: float = 0.0
+    outputTokenPricePer1M: float = 0.0
+    requestPrice: float = 0.0
+
+
+class TinfoilModel(BaseModel):
+    id: str
+    context_window: int = 0
+    created: int = 0
+    multimodal: bool = False
+    reasoning: bool = False
+    tool_calling: bool = False
+    type: str = "chat"
+    pricing: TinfoilModelPricing = TinfoilModelPricing()
+    endpoints: list[str] = []
+
+
+class TinfoilUpstreamProvider(BaseUpstreamProvider):
+    """Direct upstream provider for the Tinfoil inference API.
+
+    Tinfoil hosts open-source models inside attested secure enclaves and exposes
+    an OpenAI-compatible API at ``https://inference.tinfoil.sh``. Request and
+    response bodies are encrypted end-to-end with EHBP (HPKE), so Routstr acts
+    as a blind relay: it forwards the opaque encrypted body, never sees
+    plaintext, and bills from the ``X-Tinfoil-Usage-Metrics`` header that
+    Tinfoil returns outside the encrypted body when
+    ``X-Tinfoil-Request-Usage-Metrics: true`` is set.
+    """
+
+    provider_type = "tinfoil"
+    default_base_url = "https://inference.tinfoil.sh"
+    platform_url = "https://docs.tinfoil.sh"
+    supports_ehbp = True
+    confidential_inference_profile = ConfidentialInferenceProfile(
+        usage_response_header=_RESPONSE_USAGE_HEADER,
+        client_target_url_header=_ENCLAVE_URL_HEADER,
+        allow_client_target_override=True,
+        proxy_only_headers=_PROXY_ONLY_HEADERS,
+    )
+
+    def __init__(self, api_key: str, provider_fee: float = 1.0):
+        super().__init__(
+            base_url=self.default_base_url,
+            api_key=api_key,
+            provider_fee=provider_fee,
+        )
+
+    @classmethod
+    def _build_from_row(
+        cls, provider_row: "UpstreamProviderRow"
+    ) -> "TinfoilUpstreamProvider":
+        return cls(
+            api_key=provider_row.api_key,
+            provider_fee=provider_row.provider_fee,
+        )
+
+    @classmethod
+    def get_provider_metadata(cls) -> dict[str, object]:
+        return {
+            "id": cls.provider_type,
+            "name": "Tinfoil",
+            "default_base_url": cls.default_base_url,
+            "fixed_base_url": True,
+            "platform_url": cls.platform_url,
+            "can_create_account": False,
+            "can_topup": False,
+            "can_show_balance": False,
+        }
+
+    def transform_model_name(self, model_id: str) -> str:
+        return model_id.removeprefix("tinfoil/")
+
+    def get_confidential_inference_profile(self) -> ConfidentialInferenceProfile:
+        return self.confidential_inference_profile
+
+    async def forward_get_request(
+        self,
+        request: Request,
+        path: str,
+        headers: dict,
+    ) -> Response | StreamingResponse:
+        """Handle Tinfoil-specific GET endpoints.
+
+        * ``/attestation`` (or ``/tee/attestation``): proxy to the Tinfoil ATC
+          (attestation bundle proxy) at ``https://atc.tinfoil.sh/attestation``.
+        * Other GETs: forward to the provider base URL
+          (``https://inference.tinfoil.sh``). ``X-Tinfoil-Enclave-Url`` is an
+          EHBP-only header used for encrypted POST requests and is not honored
+          for unencrypted GET requests.
+        """
+        clean_path = path.removeprefix("tee/").rstrip("/")
+        if clean_path == "attestation":
+            return await self._proxy_attestation(headers)
+        return await super().forward_get_request(request, path, headers)
+
+    async def _proxy_attestation(self, headers: dict) -> Response:
+        url = "https://atc.tinfoil.sh/attestation"
+        async with httpx.AsyncClient(
+            transport=httpx.AsyncHTTPTransport(retries=1),
+            timeout=30.0,
+        ) as client:
+            try:
+                resp = await client.get(
+                    url,
+                    headers={
+                        "Accept": headers.get("accept", "application/json"),
+                    },
+                )
+                response_headers = dict(resp.headers)
+                response_headers.pop("content-encoding", None)
+                response_headers.pop("content-length", None)
+                return Response(
+                    content=resp.content,
+                    status_code=resp.status_code,
+                    headers=response_headers,
+                )
+            except Exception as exc:
+                raise UpstreamError(
+                    f"Error fetching Tinfoil attestation: {type(exc).__name__}",
+                    status_code=502,
+                ) from exc
+
+    def get_ehbp_forwarding_target(
+        self, path: str, model_obj: Model
+    ) -> EHBPForwardingTarget:
+        """Return the Tinfoil enclave target for EHBP requests.
+
+        Requests usage metrics from the enclave so Routstr can bill exactly
+        without decrypting the response body. The actual forwarding URL is
+        overridden at dispatch time by ``X-Tinfoil-Enclave-Url`` when the SDK
+        sends it (see ``routstr/upstream/ehbp.py``).
+        """
+        return EHBPForwardingTarget(
+            url=f"{self.base_url.rstrip('/')}/{path.lstrip('/')}",
+            headers={"X-Tinfoil-Request-Usage-Metrics": "true"},
+            profile=self.confidential_inference_profile,
+        )
+
+    async def fetch_models(self) -> list[Model]:
+        """Fetch models from the public Tinfoil models endpoint.
+
+        ``GET /v1/models`` is unauthenticated and returns all available models
+        with their pricing in USD per 1M tokens.
+        """
+        url = f"{self.base_url}/v1/models"
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.get(url)
+                response.raise_for_status()
+                data = response.json()
+                models_data = data.get("data", [])
+
+                models: list[Model] = []
+                for model_data in models_data:
+                    try:
+                        tf = TinfoilModel.parse_obj(model_data)
+                        input_price = tf.pricing.inputTokenPricePer1M
+                        output_price = tf.pricing.outputTokenPricePer1M
+                        request_price = tf.pricing.requestPrice
+
+                        modality = "text->text"
+                        input_modalities = ["text"]
+                        output_modalities = ["text"]
+                        if tf.multimodal:
+                            modality = "text->text+image"
+                            input_modalities = ["text", "image"]
+
+                        models.append(
+                            Model(
+                                id=tf.id,
+                                name=tf.id,
+                                created=tf.created,
+                                description=f"Tinfoil {tf.type} model",
+                                context_length=tf.context_window,
+                                architecture=Architecture(
+                                    modality=modality,
+                                    input_modalities=input_modalities,
+                                    output_modalities=output_modalities,
+                                    tokenizer="Unknown",
+                                    instruct_type=None,
+                                ),
+                                pricing=Pricing(
+                                    prompt=input_price / 1_000_000,
+                                    completion=output_price / 1_000_000,
+                                    request=request_price,
+                                    image=0.0,
+                                    web_search=0.0,
+                                    internal_reasoning=0.0,
+                                ),
+                            )
+                        )
+                    except Exception as e:
+                        logger.warning(
+                            "Failed to parse Tinfoil model",
+                            extra={
+                                "model_id": model_data.get("id", "unknown"),
+                                "error": str(e),
+                                "error_type": type(e).__name__,
+                            },
+                        )
+
+                return models
+        except Exception as e:
+            logger.error(
+                "Error fetching models from Tinfoil",
+                extra={"error": str(e), "error_type": type(e).__name__},
+            )
+            return []

routstr/upstream/tinfoil_trailer.py

@@ -0,0 +1,189 @@
+"""h11-based HTTP client for EHBP requests that captures HTTP trailers.
+
+httpx/httpcore silently discard HTTP trailers during chunked transfer
+decoding. Tinfoil returns ``X-Tinfoil-Usage-Metrics`` as a trailer on
+streaming responses, so we need a lower-level HTTP client that preserves
+trailers from the h11 ``EndOfMessage`` event.
+
+Because EHBP response bodies are opaque encrypted blobs, buffering the full
+response is acceptable — the client decrypts the complete body regardless of
+whether it arrived streamed or buffered.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ssl
+from dataclasses import dataclass, field
+from urllib.parse import urlsplit
+
+import h11
+
+from ..core import get_logger
+
+logger = get_logger(__name__)
+
+_READ_BUFSIZE = 65536
+_DEFAULT_TIMEOUT_SECONDS = 30.0
+_DEFAULT_CLOSE_TIMEOUT_SECONDS = 1.0
+_DEFAULT_MAX_RESPONSE_BYTES = 25 * 1024 * 1024
+_HOP_BY_HOP_HEADERS = {
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+}
+
+
+@dataclass
+class TrailerResponse:
+    """Buffered HTTP response with optional trailer headers."""
+
+    status_code: int
+    headers: list[tuple[str, str]]
+    body: bytes
+    trailers: list[tuple[str, str]] = field(default_factory=list)
+
+
+def _get_header(headers: list[tuple[str, str]], name: str) -> str | None:
+    name_lower = name.lower()
+    for k, v in headers:
+        if k.lower() == name_lower:
+            return v
+    return None
+
+
+def _strip_hop_by_hop_headers(headers: dict[str, str]) -> dict[str, str]:
+    """Remove connection-specific headers before serializing a new request."""
+    connection_tokens: set[str] = set()
+    for key, value in headers.items():
+        if key.lower() == "connection":
+            connection_tokens.update(
+                token.strip().lower() for token in value.split(",") if token.strip()
+            )
+
+    excluded = _HOP_BY_HOP_HEADERS | connection_tokens
+    return {key: value for key, value in headers.items() if key.lower() not in excluded}
+
+
+async def forward_with_trailer(
+    *,
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    body: bytes,
+    timeout_seconds: float = _DEFAULT_TIMEOUT_SECONDS,
+    max_response_bytes: int = _DEFAULT_MAX_RESPONSE_BYTES,
+    close_timeout_seconds: float = _DEFAULT_CLOSE_TIMEOUT_SECONDS,
+) -> TrailerResponse:
+    """Send an HTTP/1.1 request via h11 and capture HTTP trailers.
+
+    Returns a :class:`TrailerResponse` with the full buffered body and any
+    trailer headers from the ``EndOfMessage`` event.
+    """
+    parsed = urlsplit(url)
+    host = parsed.hostname
+    if not host:
+        raise ValueError(f"Invalid URL (no hostname): {url}")
+    port = parsed.port or 443
+    path = parsed.path or "/"
+    if parsed.query:
+        path = f"{path}?{parsed.query}"
+
+    # FastAPI has already decoded the incoming request body. Do not carry the
+    # original connection's framing or other hop-by-hop metadata into the new
+    # upstream connection.
+    headers = _strip_hop_by_hop_headers(headers)
+
+    ssl_ctx = ssl.create_default_context()
+    reader, writer = await asyncio.wait_for(
+        asyncio.open_connection(host, port, ssl=ssl_ctx),
+        timeout=timeout_seconds,
+    )
+
+    try:
+        # Build HTTP/1.1 request
+        header_lines = [f"{method} {path} HTTP/1.1"]
+        has_host = any(k.lower() == "host" for k in headers)
+        if not has_host:
+            header_lines.append(f"Host: {host}")
+        header_lines.append("Connection: close")
+
+        for key, value in headers.items():
+            if key.lower() == "host":
+                continue
+            header_lines.append(f"{key}: {value}")
+
+        if body and not any(k.lower() == "content-length" for k in headers):
+            header_lines.append(f"Content-Length: {len(body)}")
+
+        request_data = "\r\n".join(header_lines).encode() + b"\r\n\r\n"
+        if body:
+            request_data += body
+
+        writer.write(request_data)
+        await asyncio.wait_for(writer.drain(), timeout=timeout_seconds)
+
+        # Parse response with h11
+        conn = h11.Connection(h11.CLIENT)
+        status_code = 0
+        resp_headers: list[tuple[str, str]] = []
+        body_chunks: list[bytes] = []
+        body_size = 0
+        trailers: list[tuple[str, str]] = []
+
+        while True:
+            event = conn.next_event()
+
+            if event is h11.NEED_DATA:
+                data = await asyncio.wait_for(
+                    reader.read(_READ_BUFSIZE),
+                    timeout=timeout_seconds,
+                )
+                conn.receive_data(data if data else b"")
+                continue
+
+            if isinstance(event, h11.Response):
+                status_code = event.status_code
+                resp_headers = [(k.decode(), v.decode()) for k, v in event.headers]
+
+            elif isinstance(event, h11.Data):
+                body_size += len(event.data)
+                if body_size > max_response_bytes:
+                    raise ValueError(
+                        f"EHBP response exceeded {max_response_bytes} bytes"
+                    )
+                body_chunks.append(event.data)
+
+            elif isinstance(event, h11.EndOfMessage):
+                for k, v in event.headers:
+                    trailers.append((k.decode(), v.decode()))
+                break
+
+            elif isinstance(event, h11.PAUSED):
+                # Shouldn't happen for simple request/response, but break safely
+                logger.warning("h11 PAUSED event during EHBP response parsing")
+                break
+
+            elif isinstance(event, h11.ConnectionClosed):
+                break
+
+        return TrailerResponse(
+            status_code=status_code,
+            headers=resp_headers,
+            body=b"".join(body_chunks),
+            trailers=trailers,
+        )
+    finally:
+        writer.close()
+        if close_timeout_seconds > 0:
+            try:
+                await asyncio.wait_for(
+                    writer.wait_closed(), timeout=close_timeout_seconds
+                )
+            except Exception:
+                pass

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,

scripts/__init__.py

@@ -0,0 +1 @@
+"""Operational and recovery scripts for routstr-core (not a shipped package)."""

scripts/reset_admin_password.py

@@ -0,0 +1,104 @@
+"""Recover admin access by resetting the stored admin password (issue #553).
+
+The lockout escape hatch for an operator who has lost the admin password. It
+talks to the ``secrets`` table directly and deliberately does *not* require
+``ROUTSTR_SECRET_KEY``: the admin password is scrypt-hashed (key-independent),
+so recovery works even when the encryption key is missing or has changed.
+
+Two explicit, mutually exclusive actions — running with no arguments only prints
+help, so the password can't be reset by accident:
+
+    python scripts/reset_admin_password.py --password <new-password>
+        Hash and store <new-password> now.
+
+    python scripts/reset_admin_password.py --regenerate
+        Clear the stored hash; the next node startup generates a fresh random
+        password and logs it once (with the /admin URL).
+"""
+
+import argparse
+import asyncio
+import sys
+import time
+
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.db import create_session, get_secret, set_admin_password
+from routstr.core.vault import MIN_PASSWORD_LENGTH
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="reset_admin_password",
+        description="Reset the node's admin password (recovery from lockout).",
+    )
+    action = parser.add_mutually_exclusive_group()
+    action.add_argument(
+        "--password",
+        metavar="NEW_PASSWORD",
+        help=f"set this as the new admin password (min {MIN_PASSWORD_LENGTH} chars)",
+    )
+    action.add_argument(
+        "--regenerate",
+        action="store_true",
+        help="clear the password so the next startup generates and logs a new one",
+    )
+    return parser
+
+
+async def apply_reset(
+    session: AsyncSession,
+    *,
+    password: str | None = None,
+    regenerate: bool = False,
+) -> str:
+    """Perform the requested reset against ``session``; return a status message."""
+    if password is not None:
+        if len(password) < MIN_PASSWORD_LENGTH:
+            raise ValueError(
+                f"New password must be at least {MIN_PASSWORD_LENGTH} characters"
+            )
+        await set_admin_password(session, password)
+        return "Admin password updated."
+
+    if regenerate:
+        secret = await get_secret(session)
+        secret.admin_password_hash = None
+        secret.updated_at = int(time.time())
+        session.add(secret)
+        await session.commit()
+        return (
+            "Admin password cleared. The next node startup will generate a new "
+            "one and log it once with the /admin URL."
+        )
+
+    return ""
+
+
+async def _run(password: str | None, regenerate: bool) -> str:
+    async with create_session() as session:
+        return await apply_reset(
+            session, password=password, regenerate=regenerate
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.password is None and not args.regenerate:
+        parser.print_help()
+        return 0
+
+    try:
+        message = asyncio.run(_run(args.password, args.regenerate))
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    print(message)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/conftest.py

@@ -0,0 +1,15 @@
+"""Shared pytest configuration for the whole suite.
+
+A fixed, valid ``ROUTSTR_SECRET_KEY`` is set before any app import so that
+secret encryption is deterministic across the suite and the mandatory-key
+fail-fast does not break app-boot tests. Tests that need a different key (or an
+absent one) override this per-test via ``monkeypatch``.
+"""
+
+import os
+
+# Valid Fernet keys; KEY_A is the suite default, KEY_B is for wrong-key tests.
+TEST_SECRET_KEY = "l_Tkp-7xmjcQ-IFhr6qhILrU8HPRbEmYMrfSbo_5srU="
+TEST_SECRET_KEY_ALT = "_Teyrky_iToeDK51Tj1FsI9MJ340_cqKGmeher-a7MQ="
+
+os.environ.setdefault("ROUTSTR_SECRET_KEY", TEST_SECRET_KEY)

tests/integration/conftest.py

@@ -174,17 +174,20 @@ class TestmintWallet:
         """Fallback method to create a basic test token"""
         import base64
         import json
-        import random
-        import time
+        import secrets
 
-        unique_id = int(time.time() * 1000000) + random.randint(1000, 9999)
+        # Use a cryptographically random id/secret so every minted token is
+        # guaranteed unique. Time/PRNG-based ids can collide on hosts with
+        # coarse clock resolution, producing byte-identical tokens that hash to
+        # the same api_key and silently dedupe (flaky concurrency tests).
+        unique_id = secrets.token_hex(16)
         token_data = {
             "token": [
                 {
                     "mint": self.mint_url,
                     "proofs": [
                         {
-                            "id": f"009a1f293253e41e{unique_id % 100000000:08d}",
+                            "id": f"009a1f293253e41e{unique_id[:8]}",
                             "amount": amount,
                             "secret": f"test-secret-{amount}-{unique_id}",
                             "C": "02194603ffa36356f4a56b7df9371fc3192472351453ec7398b8da8117e7c3e104",

tests/integration/test_admin_auth.py

@@ -0,0 +1,121 @@
+"""Tests for admin password auth backed by the hashed Secret store (issue #553).
+
+Login and password change verify against the one-way ``Secret.admin_password_hash``
+(scrypt) instead of a plaintext settings field, which also closes the old ``!=``
+timing-attack comparison. The first hash is written by ``bootstrap_secrets`` at
+startup (generated, or migrated from a legacy password); here it is seeded
+directly into the store, then login checks against it and a password change
+re-hashes so the old password stops working and the new one starts.
+"""
+
+from __future__ import annotations
+
+import pytest
+from httpx import AsyncClient, Response
+
+from routstr.core.db import create_session, set_admin_password
+
+
+async def _seed_password(password: str) -> None:
+    # bootstrap_secrets owns first-password creation at startup; tests seed the
+    # hash straight into the store the same way, then exercise login/change.
+    async with create_session() as session:
+        await set_admin_password(session, password)
+
+
+async def _login(client: AsyncClient, password: str) -> Response:
+    return await client.post("/admin/api/login", json={"password": password})
+
+
+# --- login -----------------------------------------------------------------
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_login_500_when_no_password_configured(
+    integration_client: AsyncClient,
+) -> None:
+    resp = await _login(integration_client, "anything")
+    assert resp.status_code == 500
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_login_succeeds_with_correct_password(
+    integration_client: AsyncClient,
+) -> None:
+    await _seed_password("correct horse")
+    resp = await _login(integration_client, "correct horse")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["ok"] is True
+    assert isinstance(body["token"], str) and body["token"]
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_login_rejects_wrong_password(
+    integration_client: AsyncClient,
+) -> None:
+    await _seed_password("correct horse")
+    resp = await _login(integration_client, "wrong horse")
+    assert resp.status_code == 401
+
+
+# --- password change -------------------------------------------------------
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_update_password_rehashes_so_only_new_works(
+    integration_client: AsyncClient,
+) -> None:
+    await _seed_password("old password")
+    login = await _login(integration_client, "old password")
+    token = login.json()["token"]
+    integration_client.headers["Authorization"] = f"Bearer {token}"
+
+    resp = await integration_client.patch(
+        "/admin/api/password",
+        json={"current_password": "old password", "new_password": "new password"},
+    )
+    assert resp.status_code == 200, resp.text
+
+    # Drop admin auth so the login calls aren't treated as authenticated noise.
+    integration_client.headers.pop("Authorization", None)
+    assert (await _login(integration_client, "old password")).status_code == 401
+    assert (await _login(integration_client, "new password")).status_code == 200
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_update_password_rejects_wrong_current(
+    integration_client: AsyncClient,
+) -> None:
+    await _seed_password("old password")
+    login = await _login(integration_client, "old password")
+    token = login.json()["token"]
+    integration_client.headers["Authorization"] = f"Bearer {token}"
+
+    resp = await integration_client.patch(
+        "/admin/api/password",
+        json={"current_password": "not the password", "new_password": "new password"},
+    )
+    assert resp.status_code == 401
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_update_password_rejects_short_new(
+    integration_client: AsyncClient,
+) -> None:
+    await _seed_password("old password")
+    login = await _login(integration_client, "old password")
+    token = login.json()["token"]
+    integration_client.headers["Authorization"] = f"Bearer {token}"
+
+    resp = await integration_client.patch(
+        "/admin/api/password",
+        json={"current_password": "old password", "new_password": "x"},
+    )
+    assert resp.status_code == 400

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_admin_nsec_endpoint.py

@@ -0,0 +1,113 @@
+"""Tests for the admin nsec rotation endpoint (issue #553).
+
+The Nostr identity is a secret: it lives encrypted in the Secret store, never in
+the settings blob, so it cannot be set through the general settings PATCH. This
+dedicated endpoint is the supported way to set/rotate/clear it — it encrypts the
+key at rest, updates the live runtime identity (so signing picks it up without a
+restart), and derives the npub. Invalid keys are rejected.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from collections.abc import AsyncGenerator
+
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+
+from routstr.core import vault
+from routstr.core.admin import admin_sessions
+from routstr.core.db import AsyncSession, get_secret
+from routstr.core.settings import derive_npub_from_nsec, settings
+
+# A valid 64-char hex private key (accepted by nsec_to_keypair, as in bootstrap).
+NSEC_HEX = "1" * 64
+
+
+@pytest_asyncio.fixture
+async def admin_client(
+    integration_client: AsyncClient,
+) -> AsyncGenerator[AsyncClient, None]:
+    """An integration_client pre-authenticated with an admin session token."""
+    token = secrets.token_urlsafe(24)
+    admin_sessions[token] = int(time.time()) + 3600
+    integration_client.headers["Authorization"] = f"Bearer {token}"
+    yield integration_client
+    admin_sessions.pop(token, None)
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_update_nsec_stores_encrypted_and_derives_npub(
+    admin_client: AsyncClient,
+    integration_session: AsyncSession,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(settings, "nsec", "")
+    monkeypatch.setattr(settings, "npub", "")
+
+    resp = await admin_client.patch("/admin/api/nsec", json={"nsec": NSEC_HEX})
+    assert resp.status_code == 200
+
+    expected_npub = derive_npub_from_nsec(NSEC_HEX)
+    assert resp.json() == {"ok": True, "npub": expected_npub}
+
+    # Stored encrypted at rest, decryptable back to the original key.
+    integration_session.expunge_all()
+    secret = await get_secret(integration_session)
+    assert secret.encrypted_nsec is not None
+    assert vault.is_encrypted(secret.encrypted_nsec)
+    assert vault.decrypt(secret.encrypted_nsec) == NSEC_HEX
+
+    # Live runtime identity updated so Nostr signing reflects it without restart.
+    assert settings.nsec == NSEC_HEX
+    assert settings.npub == expected_npub
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_update_nsec_rejects_invalid_key(
+    admin_client: AsyncClient,
+    integration_session: AsyncSession,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(settings, "nsec", "")
+    monkeypatch.setattr(settings, "npub", "")
+
+    resp = await admin_client.patch(
+        "/admin/api/nsec", json={"nsec": "not-a-real-nsec"}
+    )
+    assert resp.status_code == 400
+
+    # Nothing stored, live identity untouched.
+    integration_session.expunge_all()
+    secret = await get_secret(integration_session)
+    assert secret.encrypted_nsec is None
+    assert settings.nsec == ""
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_update_nsec_clears_identity_with_empty_value(
+    admin_client: AsyncClient,
+    integration_session: AsyncSession,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Start from a node that has an identity...
+    monkeypatch.setattr(settings, "nsec", "")
+    monkeypatch.setattr(settings, "npub", "")
+    set_resp = await admin_client.patch("/admin/api/nsec", json={"nsec": NSEC_HEX})
+    assert set_resp.status_code == 200
+
+    # ...then clear it.
+    clear_resp = await admin_client.patch("/admin/api/nsec", json={"nsec": ""})
+    assert clear_resp.status_code == 200
+    assert clear_resp.json() == {"ok": True, "npub": ""}
+
+    integration_session.expunge_all()
+    secret = await get_secret(integration_session)
+    assert secret.encrypted_nsec is None
+    assert settings.nsec == ""
+    assert settings.npub == ""

tests/integration/test_admin_settings_endpoint.py

@@ -0,0 +1,82 @@
+"""Tests for the admin settings endpoint's handling of secrets (issue #553).
+
+``admin_password`` is no longer a settings field (it lives only as a one-way
+hash in the Secret store), so it must never appear in the GET/PATCH payloads.
+``nsec`` (in-memory at runtime) and ``upstream_api_key`` (still in the settings
+blob) are both redacted on read and ignored on write — they cannot be set
+through the general settings endpoint, only through their dedicated paths.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from collections.abc import AsyncGenerator
+
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+
+from routstr.core.admin import admin_sessions
+from routstr.core.db import AsyncSession
+from routstr.core.settings import SettingsService, settings
+
+
+@pytest_asyncio.fixture
+async def admin_client(
+    integration_client: AsyncClient,
+) -> AsyncGenerator[AsyncClient, None]:
+    """An integration_client pre-authenticated with an admin session token."""
+    token = secrets.token_urlsafe(24)
+    admin_sessions[token] = int(time.time()) + 3600
+    integration_client.headers["Authorization"] = f"Bearer {token}"
+    yield integration_client
+    admin_sessions.pop(token, None)
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_get_settings_omits_admin_password_and_redacts_secrets(
+    admin_client: AsyncClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(settings, "nsec", "nsec-secret")
+    monkeypatch.setattr(settings, "upstream_api_key", "sk-secret")
+
+    resp = await admin_client.get("/admin/api/settings")
+    assert resp.status_code == 200
+
+    data = resp.json()
+    assert "admin_password" not in data
+    assert data["nsec"] == "[REDACTED]"
+    assert data["upstream_api_key"] == "[REDACTED]"
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_patch_settings_ignores_secret_fields(
+    admin_client: AsyncClient,
+    integration_session: AsyncSession,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # The PATCH path persists through SettingsService, which needs an
+    # initialized current snapshot and a settings row in the shared test DB.
+    await SettingsService.initialize(integration_session)
+    monkeypatch.setattr(settings, "nsec", "original-nsec")
+
+    resp = await admin_client.patch(
+        "/admin/api/settings",
+        json={
+            "name": "Renamed",
+            "nsec": "attacker-nsec",
+            "upstream_api_key": "attacker-key",
+            "admin_password": "attacker-pw",
+        },
+    )
+    assert resp.status_code == 200
+
+    data = resp.json()
+    assert data["name"] == "Renamed"
+    assert "admin_password" not in data
+    assert data["nsec"] == "[REDACTED]"
+    # The live secret was not overwritten through the general settings endpoint.
+    assert settings.nsec == "original-nsec"

tests/integration/test_balance_negative_on_cost_overrun.py

@@ -15,6 +15,7 @@ from unittest.mock import patch
 import pytest
 from sqlmodel.ext.asyncio.session import AsyncSession
 
+from routstr.auth import ReservationSnapshot
 from routstr.core.db import ApiKey
 from routstr.payment.cost_calculation import CostData
 
@@ -23,7 +24,7 @@ def _make_key(balance: int, reserved: int) -> ApiKey:
     return ApiKey(
         hashed_key=f"test_{uuid.uuid4().hex}",
         balance=balance,
-        reserved_balance=reserved,
+        reserved_balance=0,
         total_spent=0,
         total_requests=1,
     )
@@ -75,6 +76,8 @@ async def test_balance_never_negative_when_cost_exceeds_reservation(
     key = _make_key(balance=deducted_max_cost, reserved=deducted_max_cost)
     integration_session.add(key)
     await integration_session.commit()
+    from routstr.auth import pay_for_request
+    await pay_for_request(key, deducted_max_cost, integration_session)
 
     response_data = {"model": "test-model", "usage": {"prompt_tokens": 100, "completion_tokens": 100}}
 
@@ -82,7 +85,9 @@ async def test_balance_never_negative_when_cost_exceeds_reservation(
         "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 adjust_payment_for_tokens(
+            key, response_data, integration_session, deducted_max_cost, None, None
+        )
 
     await _refresh(integration_session, key)
 
@@ -109,6 +114,8 @@ async def test_balance_floor_at_zero_on_overrun(
     key = _make_key(balance=500, reserved=500)
     integration_session.add(key)
     await integration_session.commit()
+    from routstr.auth import pay_for_request
+    await pay_for_request(key, deducted_max_cost, integration_session)
 
     response_data = {"model": "test-model", "usage": {"prompt_tokens": 50, "completion_tokens": 50}}
 
@@ -116,7 +123,9 @@ async def test_balance_floor_at_zero_on_overrun(
         "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 adjust_payment_for_tokens(
+            key, response_data, integration_session, deducted_max_cost, None, None
+        )
 
     await _refresh(integration_session, key)
 
@@ -148,6 +157,8 @@ async def test_full_cost_charged_when_balance_sufficient_for_overrun(
     key = _make_key(balance=2000, reserved=990)
     integration_session.add(key)
     await integration_session.commit()
+    from routstr.auth import pay_for_request
+    await pay_for_request(key, deducted_max_cost, integration_session)
 
     response_data = {"model": "test-model", "usage": {"prompt_tokens": 100, "completion_tokens": 100}}
 
@@ -155,7 +166,9 @@ async def test_full_cost_charged_when_balance_sufficient_for_overrun(
         "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 adjust_payment_for_tokens(
+            key, response_data, integration_session, deducted_max_cost, None, None
+        )
 
     await _refresh(integration_session, key)
 
@@ -184,7 +197,11 @@ async def test_concurrent_cost_overruns_never_negative(
     """Concurrent finalization with cost overruns must never produce negative balance."""
     import asyncio
 
-    from routstr.auth import adjust_payment_for_tokens, pay_for_request
+    from routstr.auth import (
+        adjust_payment_for_tokens,
+        get_reservation_snapshot,
+        pay_for_request,
+    )
     from routstr.core.db import create_session
 
     deducted_max_cost = 990
@@ -210,12 +227,14 @@ async def test_concurrent_cost_overruns_never_negative(
     async with create_session() as session:
         key_to_reserve = await session.get(ApiKey, key_hash)
         assert key_to_reserve is not None
+        reservations = []
         for _ in range(n_requests):
             await pay_for_request(key_to_reserve, deducted_max_cost, session)
+            reservations.append(await get_reservation_snapshot(key_to_reserve, session))
             await session.refresh(key_to_reserve)
 
     # Now finalize all concurrently with cost overrun
-    async def finalize() -> None:
+    async def finalize(reservation: ReservationSnapshot) -> None:
         response_data = {
             "model": "test-model",
             "usage": {"prompt_tokens": 100, "completion_tokens": 100},
@@ -223,15 +242,22 @@ async def test_concurrent_cost_overruns_never_negative(
         async with create_session() as session:
             fresh_key = await session.get(ApiKey, key_hash)
             assert fresh_key is not None
-            with patch(
-                "routstr.auth.calculate_cost",
-                return_value=_cost_data(actual_token_cost),
-            ):
-                await adjust_payment_for_tokens(
-                    fresh_key, response_data, session, deducted_max_cost
-                )
+            await adjust_payment_for_tokens(
+                fresh_key,
+                response_data,
+                session,
+                deducted_max_cost,
+                reservation_snapshot=reservation,
+            )
 
-    await asyncio.gather(*[finalize() for _ in range(n_requests)])
+    # Patch once around the gather: entering the same patch target from
+    # concurrent tasks un-patches in the wrong order and leaks the mock into
+    # every later test in the session.
+    with patch(
+        "routstr.auth.calculate_cost",
+        return_value=_cost_data(actual_token_cost),
+    ):
+        await asyncio.gather(*(finalize(r) for r in reservations))
 
     async with create_session() as session:
         final_key = await session.get(ApiKey, key_hash)
@@ -272,6 +298,8 @@ async def test_zero_free_balance_overrun_is_safe(
     key = _make_key(balance=1000, reserved=1000)
     integration_session.add(key)
     await integration_session.commit()
+    from routstr.auth import pay_for_request
+    await pay_for_request(key, deducted_max_cost, integration_session)
 
     response_data = {"model": "test-model", "usage": {"prompt_tokens": 50, "completion_tokens": 100}}
 
@@ -279,7 +307,9 @@ async def test_zero_free_balance_overrun_is_safe(
         "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 adjust_payment_for_tokens(
+            key, response_data, integration_session, deducted_max_cost, None, None
+        )
 
     await _refresh(integration_session, key)
 
@@ -308,7 +338,11 @@ async def test_parallel_requests_no_free_inference(
     """Second parallel finalization must be charged even when first depleted free balance."""
     import asyncio
 
-    from routstr.auth import adjust_payment_for_tokens
+    from routstr.auth import (
+        adjust_payment_for_tokens,
+        get_reservation_snapshot,
+        pay_for_request,
+    )
     from routstr.core.db import create_session
 
     deducted_max_cost = 100
@@ -329,14 +363,18 @@ async def test_parallel_requests_no_free_inference(
         key = ApiKey(
             hashed_key=key_hash,
             balance=starting_balance,
-            reserved_balance=deducted_max_cost * 2,  # both slots pre-reserved
+            reserved_balance=0,
             total_spent=0,
             total_requests=2,
         )
         session.add(key)
         await session.commit()
+        reservations = []
+        for _ in range(2):
+            await pay_for_request(key, deducted_max_cost, session)
+            reservations.append(await get_reservation_snapshot(key, session))
 
-    async def finalize() -> None:
+    async def finalize(reservation: ReservationSnapshot) -> None:
         response_data = {
             "model": "test-model",
             "usage": {"prompt_tokens": 50, "completion_tokens": 100},
@@ -344,15 +382,22 @@ async def test_parallel_requests_no_free_inference(
         async with create_session() as session:
             fresh_key = await session.get(ApiKey, key_hash)
             assert fresh_key is not None
-            with patch(
-                "routstr.auth.calculate_cost",
-                return_value=_cost_data(actual_token_cost),
-            ):
-                await adjust_payment_for_tokens(
-                    fresh_key, response_data, session, deducted_max_cost
-                )
+            await adjust_payment_for_tokens(
+                fresh_key,
+                response_data,
+                session,
+                deducted_max_cost,
+                reservation_snapshot=reservation,
+            )
 
-    await asyncio.gather(finalize(), finalize())
+    # Patch once around the gather: entering the same patch target from two
+    # concurrent tasks un-patches in the wrong order and leaks the mock into
+    # every later test in the session.
+    with patch(
+        "routstr.auth.calculate_cost",
+        return_value=_cost_data(actual_token_cost),
+    ):
+        await asyncio.gather(*(finalize(r) for r in reservations))
 
     async with create_session() as session:
         final_key = await session.get(ApiKey, key_hash)

tests/integration/test_child_keys.py

@@ -1,3 +1,4 @@
+import asyncio
 import secrets
 from typing import Any
 
@@ -7,7 +8,7 @@ from sqlmodel.ext.asyncio.session import AsyncSession
 
 from routstr.auth import adjust_payment_for_tokens, pay_for_request
 from routstr.balance import ChildKeyRequest, create_child_key
-from routstr.core.db import ApiKey
+from routstr.core.db import ApiKey, create_session
 from routstr.core.settings import settings
 
 
@@ -76,7 +77,7 @@ async def test_child_key_flow(integration_session: AsyncSession) -> None:
 
     try:
         adjustment = await adjust_payment_for_tokens(
-            child_key_db, response_data, integration_session, 500
+            child_key_db, response_data, integration_session, 500, None, None
         )
         assert adjustment["total_msats"] == 400
 
@@ -119,6 +120,54 @@ async def test_child_key_insufficient_balance(
     assert exc.value.status_code == 402
 
 
+@pytest.mark.asyncio
+async def test_concurrent_child_key_creation_is_atomic(
+    patched_db_engine: None,
+) -> None:
+    """Two concurrent create_child_key() calls with balance for exactly one must
+    result in exactly one success and one 402, with the parent balance deducted
+    only once."""
+    child_key_cost = 1000
+    settings.child_key_cost = child_key_cost
+
+    parent_hash = f"parent_concurrent_{secrets.token_hex(8)}"
+    async with create_session() as session:
+        parent = ApiKey(hashed_key=parent_hash, balance=child_key_cost)
+        session.add(parent)
+        await session.commit()
+
+    results: list[str] = []
+
+    async def attempt() -> None:
+        async with create_session() as session:
+            fresh_parent = await session.get(ApiKey, parent_hash)
+            assert fresh_parent is not None
+            try:
+                await create_child_key(ChildKeyRequest(count=1), fresh_parent, session)
+                results.append("success")
+            except HTTPException as exc:
+                assert exc.status_code == 402
+                results.append("blocked")
+
+    await asyncio.gather(attempt(), attempt())
+
+    assert sorted(results) == ["blocked", "success"], (
+        f"Expected exactly one success and one 402, got: {results}"
+    )
+
+    async with create_session() as session:
+        final = await session.get(ApiKey, parent_hash)
+        assert final is not None
+
+    assert final.balance == 0, (
+        f"Balance should be fully deducted once: expected 0, got {final.balance}"
+    )
+    assert final.total_spent == child_key_cost, (
+        f"total_spent should equal one deduction: expected {child_key_cost}, "
+        f"got {final.total_spent}"
+    )
+
+
 @pytest.mark.asyncio
 async def test_child_key_cannot_create_child(integration_session: AsyncSession) -> None:
     parent_key = ApiKey(

tests/integration/test_child_keys_api.py

@@ -69,9 +69,14 @@ async def test_wallet_info_child_key_no_child_keys(
     info_response = await integration_client.get("/v1/wallet/info")
     assert info_response.status_code == 200
     info_data = info_response.json()
+    parent_key = authenticated_client._test_api_key  # type: ignore[attr-defined]
+    parent_key_hash = parent_key.removeprefix("sk-")
 
     assert info_data["is_child"] is True
     assert "child_keys" not in info_data
+    assert "parent_key" not in info_data
+    assert info_data["parent_key_preview"] == parent_key_hash[:8] + "..."
+    assert info_data["parent_key_preview"] not in {parent_key, parent_key_hash}
 
 
 @pytest.mark.integration

tests/integration/test_failover_billing.py

@@ -0,0 +1,666 @@
+"""Failover requests are billed and forwarded as the provider that served them.
+
+Covers the whole-system settlement path when two enabled providers expose the
+same model under different spellings and prices: the routing winner fails with
+a 502, the fallback provider serves, and the response must be billed at the
+fallback's configured rate, carry the fallback's model id in the forwarded
+request body, and echo the fallback's model id to the client.
+"""
+
+import json
+from typing import Any, AsyncGenerator
+from unittest.mock import patch
+
+import httpx
+import pytest
+from httpx import AsyncClient
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.db import ApiKey, ReservationRelease
+from routstr.payment.models import Architecture, Model, Pricing
+from routstr.proxy import refresh_model_maps
+from routstr.upstream.base import BaseUpstreamProvider
+
+CHEAP_BASE_URL = "https://cheap.example.com/v1"
+EXPENSIVE_BASE_URL = "https://expensive.example.com/v1"
+THIRD_BASE_URL = "https://third.example.com/v1"
+
+
+def _make_model(
+    model_id: str,
+    prompt_sats: float,
+    completion_sats: float,
+    max_cost: float = 50.0,
+) -> Model:
+    """Build a model whose USD and sats pricing rank consistently."""
+    return Model(
+        id=model_id,
+        name=model_id,
+        created=1,
+        description="test model",
+        context_length=8192,
+        architecture=Architecture(
+            modality="text",
+            input_modalities=["text"],
+            output_modalities=["text"],
+            tokenizer="gpt",
+            instruct_type=None,
+        ),
+        pricing=Pricing(
+            prompt=prompt_sats, completion=completion_sats, max_cost=max_cost
+        ),
+        sats_pricing=Pricing(
+            prompt=prompt_sats, completion=completion_sats, max_cost=max_cost
+        ),
+    )
+
+
+class _StaticProvider(BaseUpstreamProvider):
+    """Upstream provider with a fixed model catalog and no remote refresh."""
+
+    def __init__(self, base_url: str, api_key: str, fee: float, model: Model) -> None:
+        super().__init__(base_url, api_key, fee)
+        self.provider_type = "custom"
+        self._static_model = model
+
+    def get_cached_models(self) -> list[Model]:
+        return [self._static_model]
+
+    async def refresh_models_cache(self) -> None:
+        pass
+
+
+async def _install_providers(
+    providers: list[_StaticProvider],
+) -> AsyncGenerator[None, None]:
+    """Install providers into the routing maps, restoring the originals after."""
+    from routstr import proxy
+
+    original_upstreams = proxy.get_upstreams()
+    with patch("routstr.proxy._upstreams", providers):
+        await refresh_model_maps()
+        yield
+    with patch("routstr.proxy._upstreams", original_upstreams):
+        await refresh_model_maps()
+
+
+@pytest.fixture
+async def dual_provider_maps(
+    patched_db_engine: None,
+) -> AsyncGenerator[tuple[_StaticProvider, _StaticProvider], None]:
+    """Two same-tail providers under different spellings and prices."""
+    cheap = _StaticProvider(
+        CHEAP_BASE_URL,
+        "key-cheap",
+        1.0,
+        _make_model("prova/dual-model", 0.001, 0.002),
+    )
+    expensive = _StaticProvider(
+        EXPENSIVE_BASE_URL,
+        "key-expensive",
+        1.0,
+        _make_model("provb/dual-model", 0.005, 0.010, max_cost=100.0),
+    )
+    async for _ in _install_providers([cheap, expensive]):
+        yield cheap, expensive
+
+
+def _upstream_response(request: httpx.Request) -> httpx.Response:
+    """502 from the cheap (winning) provider; a served completion elsewhere."""
+    if request.url.host == "cheap.example.com":
+        return httpx.Response(
+            502,
+            content=json.dumps({"error": {"message": "bad gateway"}}).encode(),
+            headers={"content-type": "application/json"},
+        )
+    body = {
+        "id": "chatcmpl-served",
+        "object": "chat.completion",
+        "created": 1,
+        "model": "dual-model",
+        "choices": [
+            {
+                "index": 0,
+                "message": {"role": "assistant", "content": "hi"},
+                "finish_reason": "stop",
+            }
+        ],
+        "usage": {
+            "prompt_tokens": 1000,
+            "completion_tokens": 500,
+            "total_tokens": 1500,
+        },
+    }
+    return httpx.Response(
+        200,
+        content=json.dumps(body).encode(),
+        headers={"content-type": "application/json"},
+    )
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_failover_serve_billed_at_serving_providers_rate(
+    authenticated_client: AsyncClient,
+    dual_provider_maps: tuple[_StaticProvider, _StaticProvider],
+    integration_session: AsyncSession,
+) -> None:
+    """A fallback serve is billed at the fallback's price, not the winner's.
+
+    The cheap provider ranks first for the shared tail; it 502s and the
+    expensive provider serves 1000 input + 500 output tokens. At the serving
+    provider's sats pricing (0.005/0.010 sats per token) that is 10_000 msats;
+    at the winner's (0.001/0.002) it would be 2_000 msats.
+    """
+    sent_requests: list[httpx.Request] = []
+
+    # Patch the network transport (not AsyncClient.send) so the in-process
+    # ASGI test client is untouched and only the proxy's upstream hop is mocked.
+    async def fake_transport(
+        request: httpx.Request, *args: Any, **kwargs: Any
+    ) -> httpx.Response:
+        sent_requests.append(request)
+        return _upstream_response(request)
+
+    with (
+        patch(
+            "httpx.AsyncHTTPTransport.handle_async_request",
+            side_effect=fake_transport,
+        ),
+        # cost_calculation binds sats_usd_price at import time, so the price
+        # patch in the app fixture does not reach it; patch its own binding.
+        patch(
+            "routstr.payment.cost_calculation.sats_usd_price",
+            return_value=0.0005,
+        ),
+    ):
+        response = await authenticated_client.post(
+            "/v1/chat/completions",
+            json={
+                "model": "dual-model",
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+
+    assert response.status_code == 200
+    payload = response.json()
+
+    # Both providers were attempted, cheapest first.
+    assert [r.url.host for r in sent_requests] == [
+        "cheap.example.com",
+        "expensive.example.com",
+    ]
+
+    # The fallback must be asked for ITS OWN model spelling, not the winner's.
+    forwarded_body = json.loads(sent_requests[1].content)
+    assert forwarded_body["model"] == "provb/dual-model"
+
+    # The response echo names the model that actually served.
+    assert payload["model"] == "provb/dual-model"
+
+    # Billed at the serving provider's rate: 1000/1000*5000 + 500/1000*10000.
+    assert payload["cost"]["total_msats"] == 10_000
+
+    # The fallback's larger max-cost envelope requires a replacement
+    # reservation. The failed candidate is released, the serving candidate is
+    # charged, and no request-owned reservation remains active.
+    key_hash = authenticated_client._test_api_key.removeprefix("sk-")  # type: ignore[attr-defined]
+    records = (
+        await integration_session.exec(
+            select(ReservationRelease).where(ReservationRelease.key_hash == key_hash)
+        )
+    ).all()
+    assert sorted(record.status for record in records) == ["charged", "released"]
+
+
+@pytest.fixture
+async def same_id_provider_maps(
+    patched_db_engine: None,
+) -> AsyncGenerator[None, None]:
+    """Two providers exposing the IDENTICAL model id at different prices."""
+    cheap = _StaticProvider(
+        CHEAP_BASE_URL,
+        "key-cheap",
+        1.0,
+        _make_model("dual-model", 0.001, 0.002),
+    )
+    expensive = _StaticProvider(
+        EXPENSIVE_BASE_URL,
+        "key-expensive",
+        1.0,
+        _make_model("dual-model", 0.005, 0.010),
+    )
+    async for _ in _install_providers([cheap, expensive]):
+        yield
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_same_id_failover_settles_at_serving_price(
+    authenticated_client: AsyncClient,
+    same_id_provider_maps: None,
+) -> None:
+    """Settlement must not re-derive pricing from the response's model string.
+
+    Both providers expose the exact same model id, so the forwarded body is
+    identical either way — the only observable difference is the settled
+    amount. The response's model string resolves to the alias winner (cheap),
+    but the expensive provider served, so the bill must be 10_000 msats, not
+    the winner's 2_000.
+    """
+    sent_requests: list[httpx.Request] = []
+
+    async def fake_transport(
+        request: httpx.Request, *args: Any, **kwargs: Any
+    ) -> httpx.Response:
+        sent_requests.append(request)
+        return _upstream_response(request)
+
+    with (
+        patch(
+            "httpx.AsyncHTTPTransport.handle_async_request",
+            side_effect=fake_transport,
+        ),
+        patch(
+            "routstr.payment.cost_calculation.sats_usd_price",
+            return_value=0.0005,
+        ),
+    ):
+        response = await authenticated_client.post(
+            "/v1/chat/completions",
+            json={
+                "model": "dual-model",
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+
+    assert response.status_code == 200
+    assert [r.url.host for r in sent_requests] == [
+        "cheap.example.com",
+        "expensive.example.com",
+    ]
+    assert response.json()["cost"]["total_msats"] == 10_000
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_version_suffixed_model_id_routes(
+    authenticated_client: AsyncClient,
+    same_id_provider_maps: None,
+) -> None:
+    """A version-suffixed request (``…-YYYYMMDD``) routes to the base model.
+
+    Model resolution stripped the suffix but the provider lookup did not, so
+    such requests resolved a model yet found no provider and 400'd. With the
+    unified candidate lookup the strip applies to both.
+    """
+
+    async def fake_transport(
+        request: httpx.Request, *args: Any, **kwargs: Any
+    ) -> httpx.Response:
+        return _upstream_response(request)
+
+    with (
+        patch(
+            "httpx.AsyncHTTPTransport.handle_async_request",
+            side_effect=fake_transport,
+        ),
+        patch(
+            "routstr.payment.cost_calculation.sats_usd_price",
+            return_value=0.0005,
+        ),
+    ):
+        response = await authenticated_client.post(
+            "/v1/chat/completions",
+            json={
+                "model": "dual-model-20260101",
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+
+    assert response.status_code == 200
+
+
+@pytest.fixture
+async def fee_split_provider_maps(
+    patched_db_engine: None,
+) -> AsyncGenerator[None, None]:
+    """Same-tail providers whose fees differ; the serving one charges 1.5x."""
+    cheap = _StaticProvider(
+        CHEAP_BASE_URL,
+        "key-cheap",
+        1.0,
+        _make_model("dual-model", 0.001, 0.002),
+    )
+    expensive = _StaticProvider(
+        EXPENSIVE_BASE_URL,
+        "key-expensive",
+        1.5,
+        _make_model("dual-model", 0.005, 0.010),
+    )
+    async for _ in _install_providers([cheap, expensive]):
+        yield
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_usd_cost_serve_carries_serving_providers_fee(
+    authenticated_client: AsyncClient,
+    fee_split_provider_maps: None,
+) -> None:
+    """The USD-cost billing path applies the SERVING provider's fee.
+
+    The upstream that serves reports ``usage.cost`` in USD, so billing goes
+    through the USD-cost path where the provider fee is applied explicitly.
+    The serving provider's fee is 1.5; the alias winner's is 1.0. At 0.001 USD
+    reported cost and 0.0005 USD/sat: 0.001 * 1.5 / 0.0005 = 3 sats = 3000
+    msats (fee 1.0 would give 2000).
+    """
+    sent_requests: list[httpx.Request] = []
+
+    def usd_cost_response(request: httpx.Request) -> httpx.Response:
+        if request.url.host == "cheap.example.com":
+            return httpx.Response(
+                502,
+                content=json.dumps({"error": {"message": "bad gateway"}}).encode(),
+                headers={"content-type": "application/json"},
+            )
+        body = {
+            "id": "chatcmpl-usd",
+            "object": "chat.completion",
+            "created": 1,
+            "model": "dual-model",
+            "choices": [
+                {
+                    "index": 0,
+                    "message": {"role": "assistant", "content": "hi"},
+                    "finish_reason": "stop",
+                }
+            ],
+            "usage": {
+                "prompt_tokens": 100,
+                "completion_tokens": 50,
+                "total_tokens": 150,
+                "cost": 0.001,
+            },
+        }
+        return httpx.Response(
+            200,
+            content=json.dumps(body).encode(),
+            headers={"content-type": "application/json"},
+        )
+
+    async def fake_transport(
+        request: httpx.Request, *args: Any, **kwargs: Any
+    ) -> httpx.Response:
+        sent_requests.append(request)
+        return usd_cost_response(request)
+
+    with (
+        patch(
+            "httpx.AsyncHTTPTransport.handle_async_request",
+            side_effect=fake_transport,
+        ),
+        patch(
+            "routstr.payment.cost_calculation.sats_usd_price",
+            return_value=0.0005,
+        ),
+    ):
+        response = await authenticated_client.post(
+            "/v1/chat/completions",
+            json={
+                "model": "dual-model",
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+
+    assert response.status_code == 200
+    assert [r.url.host for r in sent_requests] == [
+        "cheap.example.com",
+        "expensive.example.com",
+    ]
+    assert response.json()["cost"]["total_msats"] == 3_000
+
+
+@pytest.fixture
+async def envelope_split_provider_maps(
+    patched_db_engine: None,
+) -> AsyncGenerator[None, None]:
+    """Same-id providers where the fallback's max cost dwarfs the key balance."""
+    cheap = _StaticProvider(
+        CHEAP_BASE_URL,
+        "key-cheap",
+        1.0,
+        _make_model("dual-model", 0.001, 0.002, max_cost=50.0),
+    )
+    expensive = _StaticProvider(
+        EXPENSIVE_BASE_URL,
+        "key-expensive",
+        1.0,
+        _make_model("dual-model", 0.005, 0.010, max_cost=20_000.0),
+    )
+    async for _ in _install_providers([cheap, expensive]):
+        yield
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_failover_beyond_balance_envelope_is_rejected(
+    authenticated_client: AsyncClient,
+    envelope_split_provider_maps: None,
+) -> None:
+    """A fallback whose max-cost envelope exceeds the balance is not served.
+
+    Admission and reservation are sized to the best-ranked candidate's max
+    cost. When that candidate fails and the next one's envelope exceeds the
+    key's balance, serving it could settle far beyond what admission allowed,
+    so the request must be rejected (as it would be if the pricier candidate
+    were ranked first) instead of forwarded.
+    """
+    sent_requests: list[httpx.Request] = []
+
+    async def fake_transport(
+        request: httpx.Request, *args: Any, **kwargs: Any
+    ) -> httpx.Response:
+        sent_requests.append(request)
+        return _upstream_response(request)
+
+    with (
+        patch(
+            "httpx.AsyncHTTPTransport.handle_async_request",
+            side_effect=fake_transport,
+        ),
+        patch(
+            "routstr.payment.cost_calculation.sats_usd_price",
+            return_value=0.0005,
+        ),
+    ):
+        response = await authenticated_client.post(
+            "/v1/chat/completions",
+            json={
+                "model": "dual-model",
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+
+    # The 20_000-sat envelope exceeds the key's 10_000-sat balance: the
+    # fallback must be rejected before its upstream is ever contacted.
+    assert response.status_code == 402
+    assert [r.url.host for r in sent_requests] == ["cheap.example.com"]
+
+
+@pytest.fixture
+async def three_candidate_child_maps(
+    patched_db_engine: None,
+) -> AsyncGenerator[None, None]:
+    """Second candidate cannot fit the child limit; third restores and serves."""
+    first = _StaticProvider(
+        CHEAP_BASE_URL,
+        "key-first",
+        1.0,
+        _make_model("dual-model", 0.001, 0.002, max_cost=50.0),
+    )
+    too_large = _StaticProvider(
+        EXPENSIVE_BASE_URL,
+        "key-too-large",
+        1.0,
+        _make_model("dual-model", 0.002, 0.003, max_cost=100.0),
+    )
+    third = _StaticProvider(
+        THIRD_BASE_URL,
+        "key-third",
+        1.0,
+        _make_model("dual-model", 0.003, 0.004, max_cost=50.0),
+    )
+    async for _ in _install_providers([first, too_large, third]):
+        yield
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_child_failover_rolls_back_failed_larger_reserve_before_restoring(
+    authenticated_client: AsyncClient,
+    three_candidate_child_maps: None,
+    integration_session: AsyncSession,
+) -> None:
+    """A failed child guard cannot leak its parent update into restoration."""
+    key_hash = authenticated_client._test_api_key.removeprefix("sk-")  # type: ignore[attr-defined]
+    child = await integration_session.get(ApiKey, key_hash)
+    assert child is not None
+    parent = ApiKey(hashed_key="failover-parent", balance=10_000_000)
+    child.parent_key_hash = parent.hashed_key
+    child.balance_limit = 75_000
+    integration_session.add(parent)
+    integration_session.add(child)
+    await integration_session.commit()
+
+    sent_requests: list[httpx.Request] = []
+
+    async def fake_transport(
+        request: httpx.Request, *args: Any, **kwargs: Any
+    ) -> httpx.Response:
+        sent_requests.append(request)
+        return _upstream_response(request)
+
+    with (
+        patch(
+            "httpx.AsyncHTTPTransport.handle_async_request",
+            side_effect=fake_transport,
+        ),
+        patch(
+            "routstr.payment.cost_calculation.sats_usd_price",
+            return_value=0.0005,
+        ),
+    ):
+        response = await authenticated_client.post(
+            "/v1/chat/completions",
+            json={
+                "model": "dual-model",
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+
+    assert response.status_code == 200
+    # The 100-sat candidate is rejected before forwarding; the third serves.
+    assert [request.url.host for request in sent_requests] == [
+        "cheap.example.com",
+        "third.example.com",
+    ]
+
+    await integration_session.refresh(parent)
+    await integration_session.refresh(child)
+    assert parent.reserved_balance == 0
+    assert child.reserved_balance == 0
+    assert parent.total_spent == response.json()["cost"]["total_msats"]
+
+    records = (
+        await integration_session.exec(
+            select(ReservationRelease).where(ReservationRelease.key_hash == key_hash)
+        )
+    ).all()
+    assert len(records) == 2
+    assert sorted(record.status for record in records) == ["charged", "released"]
+    assert len({record.reserved_msats for record in records}) == 1
+    assert all(record.status != "active" for record in records)
+
+
+@pytest.fixture
+async def raised_envelope_provider_maps(
+    patched_db_engine: None,
+) -> AsyncGenerator[None, None]:
+    """Same-id providers where the fallback needs a larger, affordable reserve."""
+    cheap = _StaticProvider(
+        CHEAP_BASE_URL,
+        "key-cheap",
+        1.0,
+        _make_model("dual-model", 0.001, 0.002, max_cost=50.0),
+    )
+    expensive = _StaticProvider(
+        EXPENSIVE_BASE_URL,
+        "key-expensive",
+        1.0,
+        _make_model("dual-model", 0.005, 0.010, max_cost=100.0),
+    )
+    async for _ in _install_providers([cheap, expensive]):
+        yield
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_failover_reserves_serving_candidates_envelope(
+    authenticated_client: AsyncClient,
+    raised_envelope_provider_maps: None,
+    integration_session: AsyncSession,
+) -> None:
+    """An affordable pricier fallback is re-reserved, served, and billed.
+
+    The fallback's max cost (100 sats) exceeds the winner's (50 sats) but fits
+    the key's balance, so the reservation is raised to the serving candidate's
+    envelope and the request completes, billed at the serving rate with the
+    unused reserve refunded.
+    """
+    sent_requests: list[httpx.Request] = []
+
+    async def fake_transport(
+        request: httpx.Request, *args: Any, **kwargs: Any
+    ) -> httpx.Response:
+        sent_requests.append(request)
+        return _upstream_response(request)
+
+    with (
+        patch(
+            "httpx.AsyncHTTPTransport.handle_async_request",
+            side_effect=fake_transport,
+        ),
+        patch(
+            "routstr.payment.cost_calculation.sats_usd_price",
+            return_value=0.0005,
+        ),
+    ):
+        response = await authenticated_client.post(
+            "/v1/chat/completions",
+            json={
+                "model": "dual-model",
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+
+    assert response.status_code == 200
+    assert [r.url.host for r in sent_requests] == [
+        "cheap.example.com",
+        "expensive.example.com",
+    ]
+    assert response.json()["cost"]["total_msats"] == 10_000
+
+    key_hash = authenticated_client._test_api_key.removeprefix("sk-")  # type: ignore[attr-defined]
+    records = (
+        await integration_session.exec(
+            select(ReservationRelease).where(ReservationRelease.key_hash == key_hash)
+        )
+    ).all()
+    assert len(records) == 2
+    released = next(record for record in records if record.status == "released")
+    charged = next(record for record in records if record.status == "charged")
+    assert charged.reserved_msats > released.reserved_msats
+    assert all(record.status != "active" for record in records)

tests/integration/test_free_response_stale_reservation.py

@@ -0,0 +1,165 @@
+"""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, pay_for_request
+
+    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()
+    await pay_for_request(key, deducted_max_cost, integration_session)
+    key.reserved_balance = 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, None, None
+        )
+
+    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,
+        get_reservation_snapshot,
+        pay_for_request,
+    )
+    from routstr.core.db import (
+        ReservationRelease,
+        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)
+        snapshot = await get_reservation_snapshot(key, session)
+        await session.refresh(key)
+        assert key.reserved_balance == deducted_max_cost
+        key.reserved_at = int(time.time()) - 10_000
+        record = await session.get(ReservationRelease, snapshot.release_id)
+        assert record is not None
+        record.created_at = int(time.time()) - 10_000
+        session.add(key)
+        session.add(record)
+        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,
+                reservation_snapshot=snapshot,
+            )
+
+    async with create_session() as session:
+        final = await session.get(ApiKey, key_hash)
+        assert final is not None
+
+    # Stale release is terminal for this reservation. A late finalizer must not
+    # charge aggregate balance that may now belong to a newer request.
+    assert final.total_spent == 0
+    assert final.balance == 1000
+    assert final.balance >= 0
+    assert final.reserved_balance == 0

tests/integration/test_insufficient_balance.py

@@ -124,6 +124,40 @@ async def test_pay_for_request_raises_402_when_all_balance_reserved(
     assert key.reserved_balance == 50_000
 
 
+@pytest.mark.asyncio
+async def test_balance_info_matches_chat_available_balance(
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """
+    Regression for /v1/balance/info showing gross funds while chat admission
+    rejects with a negative available balance.
+    """
+    from routstr.auth import pay_for_request
+
+    key = _key(balance=4_404_339, reserved=4_410_636)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    response = await integration_client.get(
+        "/v1/balance/info",
+        headers={"Authorization": f"Bearer sk-{key.hashed_key}"},
+    )
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["balance"] == -6_297
+    assert body["reserved"] == 4_410_636
+
+    with pytest.raises(HTTPException) as exc_info:
+        await pay_for_request(key, 1, integration_session)
+
+    assert exc_info.value.status_code == 402
+    detail = exc_info.value.detail
+    assert isinstance(detail, dict)
+    assert "-6297 available" in detail["error"]["message"]
+
+
 # ---------------------------------------------------------------------------
 # Test 4 — balance just one msat below model cost
 # ---------------------------------------------------------------------------
@@ -173,8 +207,30 @@ async def test_pay_for_request_succeeds_when_balance_equals_cost(
     assert key.balance == model_cost   # balance unchanged, only reserved goes up
 
 
+@pytest.mark.asyncio
+async def test_five_percent_mint_fallback_headroom_is_admitted_and_reserved(
+    integration_session: AsyncSession,
+) -> None:
+    from routstr.auth import pay_for_request, validate_bearer_key
+    from routstr.payment.helpers import apply_mint_fee_allowance
+
+    key = _key(balance=95_000)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    admission_cost = apply_mint_fee_allowance(100_000)
+    validated = await validate_bearer_key(
+        f"sk-{key.hashed_key}", integration_session, min_cost=admission_cost
+    )
+    await pay_for_request(validated, admission_cost, integration_session)
+
+    await integration_session.refresh(key)
+    assert admission_cost == 95_000
+    assert key.reserved_balance == 95_000
+
+
 # ---------------------------------------------------------------------------
-# Test 6 — HTTP layer returns 402 JSON with the right shape
+# HTTP layer returns 402 JSON with the right shape
 # ---------------------------------------------------------------------------
 
 @pytest.mark.asyncio
@@ -207,8 +263,10 @@ async def test_http_402_response_shape_on_insufficient_balance(
     mock_upstream.prepare_headers = MagicMock(return_value={})
 
     with (
-        patch("routstr.proxy.get_model_instance", return_value=mock_model),
-        patch("routstr.proxy.get_provider_for_model", return_value=[mock_upstream]),
+        patch(
+            "routstr.proxy.get_candidates",
+            return_value=[(mock_model, mock_upstream)],
+        ),
         # Patch where it is used (proxy imports it at module level)
         patch(
             "routstr.proxy.get_max_cost_for_model",
@@ -230,8 +288,8 @@ async def test_http_402_response_shape_on_insufficient_balance(
     error = body["detail"]["error"]
     assert error["code"] == "insufficient_balance"
     assert error["type"] == "insufficient_quota"
-    assert str(model_cost) in error["message"]
-    assert str(user_balance) in error["message"]
+    assert "591.744 sats (591744 msats) required" in error["message"]
+    assert "20.32 sats (20320 msats) available" in error["message"]
 
     # Balance must be completely untouched
     await integration_session.refresh(key)

tests/integration/test_key_logic.py

@@ -1,12 +1,14 @@
+import asyncio
 import time
 from datetime import datetime, timedelta
 
 import pytest
+from fastapi import HTTPException
 from sqlmodel import select
 from sqlmodel.ext.asyncio.session import AsyncSession
 
 from routstr.auth import pay_for_request
-from routstr.core.db import ApiKey
+from routstr.core.db import ApiKey, create_session
 
 
 @pytest.mark.asyncio
@@ -120,6 +122,270 @@ async def test_periodic_key_reset_job(integration_session: AsyncSession) -> None
     assert key2.total_spent == 0
 
 
+@pytest.mark.asyncio
+async def test_balance_limit_enforced_atomically_under_concurrency(
+    patched_db_engine: None,
+) -> None:
+    parent_hash = "parent_limit_atomic"
+    child_hash = "child_limit_atomic"
+    cost = 300
+
+    async with create_session() as session:
+        parent = ApiKey(hashed_key=parent_hash, balance=10000)
+        child = ApiKey(
+            hashed_key=child_hash,
+            balance=0,
+            parent_key_hash=parent_hash,
+            balance_limit=cost,
+            total_spent=0,
+        )
+        session.add(parent)
+        session.add(child)
+        await session.commit()
+
+    results: list[str] = []
+
+    async def attempt() -> None:
+        async with create_session() as session:
+            fresh_child = await session.get(ApiKey, child_hash)
+            assert fresh_child is not None
+            try:
+                await pay_for_request(fresh_child, cost, session)
+                results.append("success")
+            except HTTPException as exc:
+                assert exc.status_code == 402
+                results.append("blocked")
+
+    await asyncio.gather(attempt(), attempt())
+
+    assert sorted(results) == ["blocked", "success"], (
+        f"Expected exactly one success and one 402, got: {results}"
+    )
+
+    async with create_session() as session:
+        final_child = await session.get(ApiKey, child_hash)
+        assert final_child is not None
+
+    assert final_child.reserved_balance == cost, (
+        f"Child reserved_balance should equal one reservation, "
+        f"got {final_child.reserved_balance}"
+    )
+
+
+@pytest.mark.asyncio
+async def test_parallel_payments_with_parent_and_child_key(
+    patched_db_engine: None,
+) -> None:
+    parent_hash = "parent_parallel_mixed"
+    child_hash = "child_parallel_mixed"
+    cost = 300
+
+    async with create_session() as session:
+        parent = ApiKey(hashed_key=parent_hash, balance=10000)
+        child = ApiKey(
+            hashed_key=child_hash,
+            balance=0,
+            parent_key_hash=parent_hash,
+            balance_limit=2 * cost,
+        )
+        session.add(parent)
+        session.add(child)
+        await session.commit()
+
+    async def attempt(key_hash: str) -> str:
+        async with create_session() as session:
+            fresh_key = await session.get(ApiKey, key_hash)
+            assert fresh_key is not None
+            try:
+                await pay_for_request(fresh_key, cost, session)
+                return "success"
+            except HTTPException as exc:
+                assert exc.status_code == 402
+                return "blocked"
+
+    results = await asyncio.gather(attempt(parent_hash), attempt(child_hash))
+
+    assert results == ["success", "success"], (
+        f"Both parent and child payments should succeed, got: {results}"
+    )
+
+    async with create_session() as session:
+        final_parent = await session.get(ApiKey, parent_hash)
+        final_child = await session.get(ApiKey, child_hash)
+        assert final_parent is not None
+        assert final_child is not None
+
+    # Both requests bill the parent; only the child request reserves on the child.
+    assert final_parent.reserved_balance == 2 * cost
+    assert final_parent.total_requests == 2
+    assert final_child.reserved_balance == cost
+    assert final_child.total_requests == 1
+
+
+@pytest.mark.asyncio
+async def test_balance_limit_with_existing_total_spent_under_concurrency(
+    patched_db_engine: None,
+) -> None:
+    parent_hash = "parent_total_spent"
+    child_hash = "child_total_spent"
+    cost = 300
+
+    async with create_session() as session:
+        parent = ApiKey(hashed_key=parent_hash, balance=10000)
+        # 700 already spent against a 1000 limit: only one more 300 request fits.
+        child = ApiKey(
+            hashed_key=child_hash,
+            balance=0,
+            parent_key_hash=parent_hash,
+            balance_limit=1000,
+            total_spent=700,
+        )
+        session.add(parent)
+        session.add(child)
+        await session.commit()
+
+    results: list[str] = []
+
+    async def attempt() -> None:
+        async with create_session() as session:
+            fresh_child = await session.get(ApiKey, child_hash)
+            assert fresh_child is not None
+            try:
+                await pay_for_request(fresh_child, cost, session)
+                results.append("success")
+            except HTTPException as exc:
+                assert exc.status_code == 402
+                results.append("blocked")
+
+    await asyncio.gather(attempt(), attempt())
+
+    assert sorted(results) == ["blocked", "success"], (
+        f"Expected exactly one success and one 402, got: {results}"
+    )
+
+    async with create_session() as session:
+        final_child = await session.get(ApiKey, child_hash)
+        assert final_child is not None
+
+    assert final_child.reserved_balance == cost
+    assert final_child.total_spent == 700
+
+
+@pytest.mark.asyncio
+async def test_balance_limit_with_existing_reserved_balance(
+    patched_db_engine: None,
+) -> None:
+    parent_hash = "parent_reserved_set"
+    blocked_hash = "child_reserved_blocked"
+    allowed_hash = "child_reserved_allowed"
+    cost = 300
+
+    async with create_session() as session:
+        parent = ApiKey(hashed_key=parent_hash, balance=10000)
+        # 800 already reserved against a 1000 limit: another 300 must be rejected.
+        blocked_child = ApiKey(
+            hashed_key=blocked_hash,
+            balance=0,
+            parent_key_hash=parent_hash,
+            balance_limit=1000,
+            reserved_balance=800,
+        )
+        # 500 reserved against a 1000 limit: another 300 still fits.
+        allowed_child = ApiKey(
+            hashed_key=allowed_hash,
+            balance=0,
+            parent_key_hash=parent_hash,
+            balance_limit=1000,
+            reserved_balance=500,
+        )
+        session.add(parent)
+        session.add(blocked_child)
+        session.add(allowed_child)
+        await session.commit()
+
+    async with create_session() as session:
+        fresh_blocked = await session.get(ApiKey, blocked_hash)
+        assert fresh_blocked is not None
+        with pytest.raises(HTTPException) as exc_info:
+            await pay_for_request(fresh_blocked, cost, session)
+        assert exc_info.value.status_code == 402
+
+    async with create_session() as session:
+        fresh_allowed = await session.get(ApiKey, allowed_hash)
+        assert fresh_allowed is not None
+        await pay_for_request(fresh_allowed, cost, session)
+
+    async with create_session() as session:
+        final_blocked = await session.get(ApiKey, blocked_hash)
+        final_allowed = await session.get(ApiKey, allowed_hash)
+        final_parent = await session.get(ApiKey, parent_hash)
+        assert final_blocked is not None
+        assert final_allowed is not None
+        assert final_parent is not None
+
+    assert final_blocked.reserved_balance == 800, "Rejected request must not reserve"
+    assert final_blocked.total_requests == 0
+    assert final_allowed.reserved_balance == 500 + cost
+    assert final_allowed.total_requests == 1
+    # Only the allowed request should have billed the parent.
+    assert final_parent.reserved_balance == cost
+    assert final_parent.total_requests == 1
+
+
+@pytest.mark.asyncio
+async def test_child_reservation_discarded_when_parent_balance_depleted(
+    patched_db_engine: None,
+) -> None:
+    parent_hash = "parent_depleted"
+    child_hash = "child_depleted"
+    cost = 300
+
+    async with create_session() as session:
+        # Parent can only afford one request; child has no balance_limit.
+        parent = ApiKey(hashed_key=parent_hash, balance=cost)
+        child = ApiKey(
+            hashed_key=child_hash,
+            balance=0,
+            parent_key_hash=parent_hash,
+        )
+        session.add(parent)
+        session.add(child)
+        await session.commit()
+
+    results: list[str] = []
+
+    async def attempt() -> None:
+        async with create_session() as session:
+            fresh_child = await session.get(ApiKey, child_hash)
+            assert fresh_child is not None
+            try:
+                await pay_for_request(fresh_child, cost, session)
+                results.append("success")
+            except HTTPException as exc:
+                assert exc.status_code == 402
+                results.append("blocked")
+
+    await asyncio.gather(attempt(), attempt())
+
+    assert sorted(results) == ["blocked", "success"], (
+        f"Expected exactly one success and one 402, got: {results}"
+    )
+
+    async with create_session() as session:
+        final_parent = await session.get(ApiKey, parent_hash)
+        final_child = await session.get(ApiKey, child_hash)
+        assert final_parent is not None
+        assert final_child is not None
+
+    assert final_parent.reserved_balance == cost
+    # The failed request must not leave a committed reservation on the child.
+    assert final_child.reserved_balance == cost, (
+        f"Child reserved_balance should reflect only the successful request, "
+        f"got {final_child.reserved_balance}"
+    )
+    assert final_child.total_requests == 1
+
+
 @pytest.mark.asyncio
 async def test_refund_does_not_delete_key(integration_session: AsyncSession) -> None:
     # This requires mocking the router call or testing the logic in balance.py

tests/integration/test_lightning_invoice_constraints.py

@@ -0,0 +1,511 @@
+"""Integration tests for Lightning invoice key constraint fields.
+
+Covers two things:
+- The three constraint fields (balance_limit, balance_limit_reset, validity_date)
+  are persisted on LightningInvoice and survive a DB round-trip.
+- The production-path API-key record helper propagates those fields to the
+  created ApiKey, so the constraints are actually enforced when the key is used.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from cashu.core.base import Proof
+from sqlalchemy import inspect
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.db import ApiKey, LightningInvoice
+from routstr.lightning import _create_api_key_record
+
+
+def _configure_quote_proof_wallet(wallet: MagicMock) -> None:
+    wallet.proofs = []
+    wallet.keysets = {}
+    wallet.load_proofs = AsyncMock()
+
+
+def _make_invoice(**kwargs: object) -> LightningInvoice:
+    base = dict(
+        id="inv_test_001",
+        bolt11="lnbc1000n1test",
+        amount_sats=1000,
+        description="test invoice",
+        payment_hash="deadbeef" * 8,
+        status="paid",
+        purpose="create",
+        expires_at=int(time.time()) + 3600,
+        paid_at=int(time.time()),
+    )
+    base.update(kwargs)
+    return LightningInvoice(**base)  # type: ignore[arg-type]
+
+
+@pytest.fixture(autouse=True)
+def mock_wallet_mint() -> object:
+    with patch("routstr.lightning.get_wallet") as mock_get_wallet:
+        wallet = AsyncMock()
+        wallet.proofs = []
+        wallet.load_proofs = AsyncMock()
+
+        async def mint(amount: int, quote_id: str) -> list[Proof]:
+            proofs = [Proof(amount=amount, mint_id=quote_id)]
+            wallet.proofs.extend(proofs)
+            return proofs
+
+        wallet.mint = AsyncMock(side_effect=mint)
+        mock_get_wallet.return_value = wallet
+        yield mock_get_wallet
+
+
+# ---------------------------------------------------------------------------
+# Persistence
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_invoice_persists_balance_limit(
+    integration_session: AsyncSession,
+) -> None:
+    invoice = _make_invoice(balance_limit=5000)
+    integration_session.add(invoice)
+    await integration_session.commit()
+
+    stored = await integration_session.get(LightningInvoice, invoice.id)
+    assert stored is not None
+    assert stored.balance_limit == 5000
+
+
+@pytest.mark.asyncio
+async def test_invoice_persists_balance_limit_reset(
+    integration_session: AsyncSession,
+) -> None:
+    invoice = _make_invoice(balance_limit=5000, balance_limit_reset="daily")
+    integration_session.add(invoice)
+    await integration_session.commit()
+
+    stored = await integration_session.get(LightningInvoice, invoice.id)
+    assert stored is not None
+    assert stored.balance_limit_reset == "daily"
+
+
+@pytest.mark.asyncio
+async def test_invoice_persists_validity_date(
+    integration_session: AsyncSession,
+) -> None:
+    expiry = int(time.time()) + 86400
+    invoice = _make_invoice(validity_date=expiry)
+    integration_session.add(invoice)
+    await integration_session.commit()
+
+    stored = await integration_session.get(LightningInvoice, invoice.id)
+    assert stored is not None
+    assert stored.validity_date == expiry
+
+
+# ---------------------------------------------------------------------------
+# Propagation to ApiKey
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_created_key_receives_balance_limit(
+    integration_session: AsyncSession,
+) -> None:
+    invoice = _make_invoice(balance_limit=8000)
+    integration_session.add(invoice)
+    await integration_session.flush()
+
+    api_key = await _create_api_key_record(invoice, integration_session)
+    await integration_session.commit()
+
+    stored_key = await integration_session.get(ApiKey, api_key.hashed_key)
+    assert stored_key is not None
+    assert stored_key.balance_limit == 8000
+
+
+@pytest.mark.asyncio
+async def test_created_key_receives_balance_limit_reset(
+    integration_session: AsyncSession,
+) -> None:
+    invoice = _make_invoice(balance_limit=8000, balance_limit_reset="monthly")
+    integration_session.add(invoice)
+    await integration_session.flush()
+
+    api_key = await _create_api_key_record(invoice, integration_session)
+    await integration_session.commit()
+
+    stored_key = await integration_session.get(ApiKey, api_key.hashed_key)
+    assert stored_key is not None
+    assert stored_key.balance_limit_reset == "monthly"
+
+
+@pytest.mark.asyncio
+async def test_created_key_receives_validity_date(
+    integration_session: AsyncSession,
+) -> None:
+    expiry = int(time.time()) + 86400
+    invoice = _make_invoice(validity_date=expiry)
+    integration_session.add(invoice)
+    await integration_session.flush()
+
+    api_key = await _create_api_key_record(invoice, integration_session)
+    await integration_session.commit()
+
+    stored_key = await integration_session.get(ApiKey, api_key.hashed_key)
+    assert stored_key is not None
+    assert stored_key.validity_date == expiry
+
+
+@pytest.mark.asyncio
+async def test_payment_check_releases_connection_during_mint_quote(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    invoice = _make_invoice(id="inv_slow_quote", status="pending", paid_at=None)
+    async with AsyncSession(integration_engine, expire_on_commit=False) as setup:
+        setup.add(invoice)
+        await setup.commit()
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as session:
+        stored = await session.get(LightningInvoice, invoice.id)
+        assert stored is not None
+
+        async def quote_status(*args: object, **kwargs: object) -> MagicMock:
+            assert integration_engine.pool.checkedout() == 0  # type: ignore[attr-defined]
+            return MagicMock(paid=False)
+
+        wallet = MagicMock()
+        wallet.get_mint_quote = AsyncMock(side_effect=quote_status)
+        with patch("routstr.lightning.get_wallet", AsyncMock(return_value=wallet)):
+            from routstr.lightning import check_invoice_payment
+
+            await check_invoice_payment(stored, session)
+
+
+@pytest.mark.asyncio
+async def test_concurrent_payment_checks_mint_and_credit_invoice_once(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    invoice = _make_invoice(id="inv_concurrent", status="pending", paid_at=None)
+    async with AsyncSession(integration_engine, expire_on_commit=False) as setup:
+        setup.add(invoice)
+        await setup.commit()
+
+    wallet = MagicMock()
+    _configure_quote_proof_wallet(wallet)
+    wallet.get_mint_quote = AsyncMock(return_value=MagicMock(paid=True))
+
+    mint_calls = 0
+
+    async def single_use_mint(*args: object, **kwargs: object) -> list[object]:
+        # Real mints enforce single-use quotes: the second concurrent minter
+        # gets rejected at the mint, mirroring cashu quote semantics.
+        nonlocal mint_calls
+        mint_calls += 1
+        call_number = mint_calls
+        await asyncio.sleep(0.05)
+        if call_number > 1:
+            raise Exception("quote already issued")
+        proof = Proof(amount=invoice.amount_sats, mint_id=invoice.payment_hash)
+        wallet.proofs.append(proof)
+        return [proof]
+
+    wallet.mint = AsyncMock(side_effect=single_use_mint)
+
+    async with (
+        AsyncSession(integration_engine, expire_on_commit=False) as first,
+        AsyncSession(integration_engine, expire_on_commit=False) as second,
+    ):
+        first_invoice = await first.get(LightningInvoice, invoice.id)
+        second_invoice = await second.get(LightningInvoice, invoice.id)
+        assert first_invoice is not None
+        assert second_invoice is not None
+
+        with patch("routstr.lightning.get_wallet", AsyncMock(return_value=wallet)):
+            from routstr.lightning import check_invoice_payment
+
+            await asyncio.gather(
+                check_invoice_payment(first_invoice, first),
+                check_invoice_payment(second_invoice, second),
+            )
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        stored_invoice = await verify.get(LightningInvoice, invoice.id)
+        assert stored_invoice is not None
+        assert stored_invoice.status == "paid"
+        assert stored_invoice.api_key_hash is not None
+        stored_key = await verify.get(ApiKey, stored_invoice.api_key_hash)
+        assert stored_key is not None
+        assert stored_key.balance == invoice.amount_sats * 1000
+
+
+@pytest.mark.asyncio
+async def test_failed_mint_keeps_invoice_pending_for_retry(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    invoice = _make_invoice(id="inv_mint_failure", status="pending", paid_at=None)
+    async with AsyncSession(integration_engine, expire_on_commit=False) as setup:
+        setup.add(invoice)
+        await setup.commit()
+
+    wallet = MagicMock()
+    _configure_quote_proof_wallet(wallet)
+    wallet.get_mint_quote = AsyncMock(return_value=MagicMock(paid=True))
+    wallet.mint = AsyncMock(side_effect=TimeoutError("mint unavailable"))
+    async with AsyncSession(integration_engine, expire_on_commit=False) as session:
+        stored = await session.get(LightningInvoice, invoice.id)
+        assert stored is not None
+        with patch("routstr.lightning.get_wallet", AsyncMock(return_value=wallet)):
+            from routstr.lightning import check_invoice_payment
+
+            await check_invoice_payment(stored, session)
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        stored = await verify.get(LightningInvoice, invoice.id)
+        assert stored is not None
+        assert stored.status == "pending"
+
+
+@pytest.mark.asyncio
+async def test_unpaid_topup_does_not_query_target_key(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    invoice = _make_invoice(
+        id="inv_unpaid_topup",
+        status="pending",
+        paid_at=None,
+        purpose="topup",
+        api_key_hash="target-key",
+    )
+    async with AsyncSession(integration_engine, expire_on_commit=False) as setup:
+        setup.add(invoice)
+        await setup.commit()
+
+    wallet = MagicMock()
+    wallet.get_mint_quote = AsyncMock(return_value=MagicMock(paid=False))
+    create_session = MagicMock(side_effect=RuntimeError("target lookup should not run"))
+    async with AsyncSession(integration_engine, expire_on_commit=False) as session:
+        stored = await session.get(LightningInvoice, invoice.id)
+        assert stored is not None
+        with (
+            patch("routstr.lightning.get_wallet", AsyncMock(return_value=wallet)),
+            patch("routstr.lightning.create_session", create_session),
+        ):
+            from routstr.lightning import check_invoice_payment
+
+            await check_invoice_payment(stored, session)
+
+    wallet.get_mint_quote.assert_awaited_once_with(invoice.payment_hash)
+    create_session.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_missing_topup_target_is_rejected_before_mint(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    invoice = _make_invoice(
+        id="inv_missing_topup_target",
+        status="pending",
+        paid_at=None,
+        purpose="topup",
+        api_key_hash="pruned-key",
+        expires_at=int(time.time()) - 1,
+    )
+    async with AsyncSession(integration_engine, expire_on_commit=False) as setup:
+        setup.add(invoice)
+        await setup.commit()
+
+    wallet = MagicMock()
+    wallet.get_mint_quote = AsyncMock(return_value=MagicMock(paid=True))
+    wallet.mint = AsyncMock()
+    async with AsyncSession(integration_engine, expire_on_commit=False) as session:
+        stored = await session.get(LightningInvoice, invoice.id)
+        assert stored is not None
+        with (
+            patch("routstr.lightning.get_wallet", AsyncMock(return_value=wallet)),
+            patch("routstr.lightning.logger.critical") as critical,
+        ):
+            from routstr.lightning import get_invoice_status
+
+            response = await get_invoice_status(invoice.id, session)
+
+        assert response.status == "reconciliation_required"
+        assert stored.status == "reconciliation_required"
+        assert stored not in session.dirty
+        critical.assert_called_once()
+
+    wallet.mint.assert_not_awaited()
+    async with AsyncSession(integration_engine) as verify:
+        stored = await verify.get(LightningInvoice, invoice.id)
+        assert stored is not None
+        assert stored.status == "reconciliation_required"
+
+
+@pytest.mark.asyncio
+async def test_post_mint_db_failure_keeps_invoice_pending_for_reconciliation(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    invoice = _make_invoice(id="inv_finalize_failure", status="pending", paid_at=None)
+    sibling = _make_invoice(
+        id="inv_finalize_failure_sibling",
+        bolt11="lnbc1000n1sibling",
+        payment_hash="cafebabe" * 8,
+        status="pending",
+        paid_at=None,
+    )
+    async with AsyncSession(integration_engine, expire_on_commit=False) as setup:
+        setup.add_all([invoice, sibling])
+        await setup.commit()
+
+    wallet = MagicMock()
+    _configure_quote_proof_wallet(wallet)
+    wallet.get_mint_quote = AsyncMock(return_value=MagicMock(paid=True))
+
+    async def successful_mint(*args: object, **kwargs: object) -> list[Proof]:
+        proof = Proof(amount=invoice.amount_sats, mint_id=invoice.payment_hash)
+        wallet.proofs.append(proof)
+        return [proof]
+
+    wallet.mint = AsyncMock(side_effect=successful_mint)
+    async with AsyncSession(integration_engine, expire_on_commit=False) as session:
+        stored = await session.get(LightningInvoice, invoice.id)
+        stored_sibling = await session.get(LightningInvoice, sibling.id)
+        assert stored is not None
+        assert stored_sibling is not None
+        with (
+            patch("routstr.lightning.get_wallet", AsyncMock(return_value=wallet)),
+            patch(
+                "routstr.lightning._create_api_key_record",
+                AsyncMock(side_effect=RuntimeError("database unavailable")),
+            ),
+        ):
+            from routstr.lightning import check_invoice_payment
+
+            await check_invoice_payment(stored, session)
+
+        stored_state = inspect(stored)
+        sibling_state = inspect(stored_sibling)
+        assert stored_state is not None
+        assert sibling_state is not None
+        assert stored_state.expired is False
+        assert sibling_state.expired is False
+        assert stored.status == "pending"
+        assert stored_sibling.id == sibling.id
+
+    assert wallet.mint.await_count == 1
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        stored = await verify.get(LightningInvoice, invoice.id)
+        assert stored is not None
+        assert stored.status == "pending"
+
+
+@pytest.mark.asyncio
+async def test_created_key_without_constraints_has_none_fields(
+    integration_session: AsyncSession,
+) -> None:
+    invoice = _make_invoice()
+    integration_session.add(invoice)
+    await integration_session.flush()
+
+    api_key = await _create_api_key_record(invoice, integration_session)
+    await integration_session.commit()
+
+    stored_key = await integration_session.get(ApiKey, api_key.hashed_key)
+    assert stored_key is not None
+    assert stored_key.balance_limit is None
+    assert stored_key.balance_limit_reset is None
+    assert stored_key.validity_date is None
+
+
+@pytest.mark.asyncio
+async def test_db_guard_credits_once_when_both_mints_succeed(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    """Even if the mint fails to enforce single-use quotes and both racers
+    mint successfully, the conditional status update must credit exactly once."""
+    key = ApiKey(hashed_key="race-key", balance=1_000)
+    invoice = _make_invoice(
+        id="inv_db_guard",
+        status="pending",
+        paid_at=None,
+        purpose="topup",
+        api_key_hash="race-key",
+    )
+    sibling = _make_invoice(
+        id="inv_db_guard_sibling",
+        bolt11="lnbc1000n1race-sibling",
+        payment_hash="01234567" * 8,
+        status="pending",
+        paid_at=None,
+    )
+    async with AsyncSession(integration_engine, expire_on_commit=False) as setup:
+        setup.add_all([key, invoice, sibling])
+        await setup.commit()
+
+    wallet = MagicMock()
+    _configure_quote_proof_wallet(wallet)
+    wallet.get_mint_quote = AsyncMock(return_value=MagicMock(paid=True))
+
+    async def always_succeeding_mint(*args: object, **kwargs: object) -> list[Proof]:
+        await asyncio.sleep(0.05)
+        proof = Proof(amount=invoice.amount_sats, mint_id=invoice.payment_hash)
+        wallet.proofs.append(proof)
+        return [proof]
+
+    wallet.mint = AsyncMock(side_effect=always_succeeding_mint)
+
+    async with (
+        AsyncSession(integration_engine, expire_on_commit=False) as first,
+        AsyncSession(integration_engine, expire_on_commit=False) as second,
+    ):
+        first_invoice = await first.get(LightningInvoice, invoice.id)
+        first_sibling = await first.get(LightningInvoice, sibling.id)
+        second_invoice = await second.get(LightningInvoice, invoice.id)
+        assert first_invoice is not None
+        assert first_sibling is not None
+        assert second_invoice is not None
+
+        with patch("routstr.lightning.get_wallet", AsyncMock(return_value=wallet)):
+            from routstr.lightning import check_invoice_payment
+
+            await asyncio.gather(
+                check_invoice_payment(first_invoice, first),
+                check_invoice_payment(second_invoice, second),
+            )
+
+        first_state = inspect(first_invoice)
+        sibling_state = inspect(first_sibling)
+        second_state = inspect(second_invoice)
+        assert first_state is not None
+        assert sibling_state is not None
+        assert second_state is not None
+        assert first_state.expired is False
+        assert sibling_state.expired is False
+        assert second_state.expired is False
+        assert first_invoice.id == invoice.id
+        assert first_sibling.id == sibling.id
+        assert second_invoice.id == invoice.id
+        assert first_invoice.status == "paid"
+        assert second_invoice.status == "paid"
+        assert first_invoice not in first.dirty
+        assert second_invoice not in second.dirty
+
+    assert wallet.mint.await_count == 1
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        stored_invoice = await verify.get(LightningInvoice, invoice.id)
+        assert stored_invoice is not None
+        assert stored_invoice.status == "paid"
+        stored_key = await verify.get(ApiKey, "race-key")
+        assert stored_key is not None
+        assert stored_key.balance == 1_000 + invoice.amount_sats * 1000

tests/integration/test_lightning_invoice_rip08.py

@@ -0,0 +1,206 @@
+"""RIP-08 lightning invoice endpoint tests.
+
+Verifies both the spec-compliant path (`POST /lightning/invoice` with
+`Authorization: Bearer sk-...`) and the legacy path
+(`POST /v1/balance/lightning/invoice` with `api_key` in body).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.db import ApiKey
+
+RIP08_PATH = "/lightning/invoice"
+LEGACY_PATH = "/v1/balance/lightning/invoice"
+
+
+@pytest_asyncio.fixture
+async def patch_invoice_generation() -> Any:
+    """Stub out `generate_lightning_invoice` so no mint round-trip is needed."""
+    counter = {"n": 0}
+
+    async def fake_generate(
+        amount_sats: int,
+        description: str,
+        *,
+        allowed_mints: list[str] | None = None,
+    ) -> tuple[str, str, str]:
+        counter["n"] += 1
+        return (
+            f"lnbc{amount_sats}n1pfakeinvoice{counter['n']}",
+            f"payment_hash_{counter['n']}",
+            "http://localhost:3338",
+        )
+
+    with patch(
+        "routstr.lightning.generate_lightning_invoice",
+        side_effect=fake_generate,
+    ) as m:
+        yield m
+
+
+@pytest_asyncio.fixture
+async def seeded_topup_key(integration_session: AsyncSession) -> str:
+    """Insert an ApiKey row and return the public `sk-...` form."""
+    hashed = "0" * 64
+    key = ApiKey(
+        hashed_key=hashed,
+        balance=0,
+        refund_currency="sat",
+        refund_mint_url="http://localhost:3338",
+    )
+    integration_session.add(key)
+    await integration_session.commit()
+    return f"sk-{hashed}"
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+@pytest.mark.parametrize("path", [RIP08_PATH, LEGACY_PATH])
+async def test_create_invoice_purpose_create(
+    integration_client: AsyncClient,
+    patch_invoice_generation: Any,
+    path: str,
+) -> None:
+    """`purpose=create` works on both paths and requires no auth."""
+    resp = await integration_client.post(
+        path,
+        json={"amount_sats": 1000, "purpose": "create"},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["amount_sats"] == 1000
+    assert body["bolt11"].startswith("lnbc")
+    assert body["invoice_id"]
+    assert body["payment_hash"]
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+@pytest.mark.parametrize("path", [RIP08_PATH, LEGACY_PATH])
+async def test_topup_with_authorization_header(
+    integration_client: AsyncClient,
+    patch_invoice_generation: Any,
+    seeded_topup_key: str,
+    path: str,
+) -> None:
+    """RIP-08: topup using `Authorization: Bearer sk-...` header (no api_key in body)."""
+    resp = await integration_client.post(
+        path,
+        json={"amount_sats": 500, "purpose": "topup"},
+        headers={"Authorization": f"Bearer {seeded_topup_key}"},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["amount_sats"] == 500
+    assert body["bolt11"].startswith("lnbc")
+    allowed_mints = patch_invoice_generation.call_args.kwargs["allowed_mints"]
+    assert allowed_mints == ["http://localhost:3338"]
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+@pytest.mark.parametrize("path", [RIP08_PATH, LEGACY_PATH])
+async def test_topup_with_legacy_api_key_in_body(
+    integration_client: AsyncClient,
+    patch_invoice_generation: Any,
+    seeded_topup_key: str,
+    path: str,
+) -> None:
+    """Legacy: topup with `api_key` in body still accepted on both paths."""
+    resp = await integration_client.post(
+        path,
+        json={
+            "amount_sats": 250,
+            "purpose": "topup",
+            "api_key": seeded_topup_key,
+        },
+    )
+    assert resp.status_code == 200, resp.text
+    assert resp.json()["amount_sats"] == 250
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+@pytest.mark.parametrize("path", [RIP08_PATH, LEGACY_PATH])
+async def test_topup_missing_auth_returns_401(
+    integration_client: AsyncClient,
+    patch_invoice_generation: Any,
+    path: str,
+) -> None:
+    """Topup without any credential is rejected on both paths."""
+    resp = await integration_client.post(
+        path,
+        json={"amount_sats": 100, "purpose": "topup"},
+    )
+    assert resp.status_code == 401
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+@pytest.mark.parametrize("path", [RIP08_PATH, LEGACY_PATH])
+async def test_topup_unknown_api_key_returns_404(
+    integration_client: AsyncClient,
+    patch_invoice_generation: Any,
+    path: str,
+) -> None:
+    resp = await integration_client.post(
+        path,
+        json={"amount_sats": 100, "purpose": "topup"},
+        headers={"Authorization": "Bearer sk-deadbeef"},
+    )
+    assert resp.status_code == 404
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+@pytest.mark.parametrize("path", [RIP08_PATH, LEGACY_PATH])
+async def test_invoice_status_404_for_unknown_id(
+    integration_client: AsyncClient,
+    path: str,
+) -> None:
+    base = path.rsplit("/invoice", 1)[0] + "/invoice"
+    resp = await integration_client.get(f"{base}/does-not-exist/status")
+    assert resp.status_code == 404
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_purpose_defaults_to_create(
+    integration_client: AsyncClient,
+    patch_invoice_generation: Any,
+) -> None:
+    """Per RIP-08, `purpose` may be omitted and defaults to `create`."""
+    resp = await integration_client.post(
+        RIP08_PATH,
+        json={"amount_sats": 100},
+    )
+    assert resp.status_code == 200, resp.text
+    assert resp.json()["amount_sats"] == 100
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_authorization_header_overrides_body_api_key(
+    integration_client: AsyncClient,
+    patch_invoice_generation: Any,
+    seeded_topup_key: str,
+) -> None:
+    """Header api_key wins over body api_key: bogus body must not cause 404."""
+    resp = await integration_client.post(
+        RIP08_PATH,
+        json={
+            "amount_sats": 100,
+            "purpose": "topup",
+            "api_key": "sk-" + "f" * 64,  # bogus body key
+        },
+        headers={"Authorization": f"Bearer {seeded_topup_key}"},
+    )
+    assert resp.status_code == 200, resp.text

tests/integration/test_lightning_settlement.py

@@ -0,0 +1,273 @@
+import asyncio
+import time
+import uuid
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+from cashu.core.base import Proof
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel import col, update
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.db import ApiKey, LightningInvoice
+from routstr.lightning import (
+    _finalize_invoice_settlement,
+    _InvoiceSettlement,
+    check_invoice_payment,
+)
+
+
+def _lightning_invoice(**overrides: object) -> LightningInvoice:
+    suffix = uuid.uuid4().hex
+    values = {
+        "id": f"invoice-{suffix}",
+        "bolt11": f"lnbc-{suffix}",
+        "amount_sats": 100,
+        "description": "settlement test",
+        "payment_hash": f"quote-{suffix}",
+        "status": "pending",
+        "purpose": "create",
+        "mint_url": "http://mint:3338",
+        "expires_at": int(time.time()) + 3600,
+    }
+    values.update(overrides)
+    return LightningInvoice(**values)  # type: ignore[arg-type]
+
+
+@pytest.mark.asyncio
+async def test_invoice_read_transaction_closes_before_external_mint_io(
+    integration_session: AsyncSession,
+) -> None:
+    invoice = _lightning_invoice()
+    integration_session.add(invoice)
+    await integration_session.commit()
+    stored = await integration_session.get(LightningInvoice, invoice.id)
+    assert stored is not None
+
+    wallet = Mock(get_mint_quote=AsyncMock(return_value=Mock(paid=False)))
+
+    async def get_wallet_without_open_db_transaction(
+        *args: object, **kwargs: object
+    ) -> Mock:
+        assert not integration_session.in_transaction()
+        return wallet
+
+    with patch(
+        "routstr.lightning.get_wallet", side_effect=get_wallet_without_open_db_transaction
+    ):
+        await check_invoice_payment(stored, integration_session)
+
+    assert not integration_session.in_transaction()
+
+
+@pytest.mark.asyncio
+async def test_separate_sessions_cas_topup_credit_exactly_once(
+    integration_engine: AsyncEngine,
+) -> None:
+    key_hash = uuid.uuid4().hex
+    invoice = _lightning_invoice(
+        purpose="topup",
+        api_key_hash=key_hash,
+        amount_sats=100,
+    )
+    key = ApiKey(
+        hashed_key=key_hash,
+        balance=100_000,
+        refund_currency="sat",
+        refund_mint_url="http://mint:3338",
+    )
+    async with AsyncSession(integration_engine, expire_on_commit=False) as seed:
+        seed.add(key)
+        seed.add(invoice)
+        await seed.commit()
+
+    snapshot_a = _InvoiceSettlement.from_invoice(invoice)
+    snapshot_b = _InvoiceSettlement.from_invoice(invoice)
+    async with (
+        AsyncSession(integration_engine, expire_on_commit=False) as session_a,
+        AsyncSession(integration_engine, expire_on_commit=False) as session_b,
+    ):
+        results = await asyncio.gather(
+            _finalize_invoice_settlement(snapshot_a, session_a, 1_700_000_000),
+            _finalize_invoice_settlement(snapshot_b, session_b, 1_700_000_001),
+        )
+
+    assert sorted(settled for settled, _ in results) == [False, True]
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        stored_invoice = await verify.get(LightningInvoice, invoice.id)
+        stored_key = await verify.get(ApiKey, key_hash)
+        assert stored_invoice is not None
+        assert stored_invoice.status == "paid"
+        assert stored_key is not None
+        assert stored_key.balance == 200_000
+
+
+@pytest.mark.asyncio
+async def test_topup_atomic_increment_preserves_concurrent_balance_mutation(
+    integration_engine: AsyncEngine,
+) -> None:
+    key_hash = uuid.uuid4().hex
+    invoice = _lightning_invoice(
+        purpose="topup", api_key_hash=key_hash, amount_sats=100
+    )
+    key = ApiKey(
+        hashed_key=key_hash,
+        balance=100_000,
+        refund_currency="sat",
+        refund_mint_url="http://mint:3338",
+    )
+    async with AsyncSession(integration_engine, expire_on_commit=False) as seed:
+        seed.add(key)
+        seed.add(invoice)
+        await seed.commit()
+
+    async def debit_balance(session: AsyncSession) -> None:
+        result = await session.exec(  # type: ignore[call-overload]
+            update(ApiKey)
+            .where(col(ApiKey.hashed_key) == key_hash)
+            .values(balance=col(ApiKey.balance) - 10_000)
+            .execution_options(synchronize_session=False)
+        )
+        assert result.rowcount == 1
+        await session.commit()
+
+    snapshot = _InvoiceSettlement.from_invoice(invoice)
+    async with (
+        AsyncSession(integration_engine, expire_on_commit=False) as settlement,
+        AsyncSession(integration_engine, expire_on_commit=False) as debit,
+    ):
+        settlement_result, _ = await asyncio.gather(
+            _finalize_invoice_settlement(snapshot, settlement, 1_700_000_000),
+            debit_balance(debit),
+        )
+
+    assert settlement_result[0]
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        stored_key = await verify.get(ApiKey, key_hash)
+        assert stored_key is not None
+        assert stored_key.balance == 190_000
+
+
+@pytest.mark.asyncio
+async def test_failed_final_commit_rolls_back_claim_and_credit_for_retry(
+    integration_engine: AsyncEngine,
+) -> None:
+    key_hash = uuid.uuid4().hex
+    invoice = _lightning_invoice(
+        purpose="topup",
+        api_key_hash=key_hash,
+        amount_sats=100,
+    )
+    key = ApiKey(
+        hashed_key=key_hash,
+        balance=100_000,
+        refund_currency="sat",
+        refund_mint_url="http://mint:3338",
+    )
+    async with AsyncSession(integration_engine, expire_on_commit=False) as seed:
+        seed.add(key)
+        seed.add(invoice)
+        await seed.commit()
+
+    snapshot = _InvoiceSettlement.from_invoice(invoice)
+    async with AsyncSession(integration_engine, expire_on_commit=False) as failed:
+        with patch.object(
+            failed, "commit", AsyncMock(side_effect=Exception("db unavailable"))
+        ):
+            with pytest.raises(Exception, match="db unavailable"):
+                await _finalize_invoice_settlement(snapshot, failed, 1_700_000_000)
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        pending = await verify.get(LightningInvoice, invoice.id)
+        unchanged = await verify.get(ApiKey, key_hash)
+        assert pending is not None
+        assert pending.status == "pending"
+        assert unchanged is not None
+        assert unchanged.balance == 100_000
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as retry:
+        settled, _ = await _finalize_invoice_settlement(
+            snapshot, retry, 1_700_000_001
+        )
+        assert settled
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        paid = await verify.get(LightningInvoice, invoice.id)
+        credited = await verify.get(ApiKey, key_hash)
+        assert paid is not None
+        assert paid.status == "paid"
+        assert credited is not None
+        assert credited.balance == 200_000
+
+
+@pytest.mark.asyncio
+async def test_check_invoice_payment_retries_after_mint_success_and_db_failure(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    key_hash = uuid.uuid4().hex
+    invoice = _lightning_invoice(
+        purpose="topup", api_key_hash=key_hash, amount_sats=100
+    )
+    key = ApiKey(
+        hashed_key=key_hash,
+        balance=100_000,
+        refund_currency="sat",
+        refund_mint_url="http://mint:3338",
+    )
+    async with AsyncSession(integration_engine, expire_on_commit=False) as seed:
+        seed.add(key)
+        seed.add(invoice)
+        await seed.commit()
+
+    wallet = Mock(
+        proofs=[],
+        keysets={"keyset-1": Mock()},
+        load_proofs=AsyncMock(),
+        get_mint_quote=AsyncMock(return_value=Mock(paid=True)),
+        restore_tokens_for_keyset=AsyncMock(),
+    )
+
+    async def mint(amount: int, quote_id: str) -> list[Proof]:
+        proofs = [Proof(amount=amount, mint_id=quote_id)]
+        wallet.proofs.extend(proofs)
+        return proofs
+
+    wallet.mint = AsyncMock(side_effect=mint)
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as failed:
+        stored = await failed.get(LightningInvoice, invoice.id)
+        assert stored is not None
+        with (
+            patch("routstr.lightning.get_wallet", AsyncMock(return_value=wallet)),
+            patch(
+                "routstr.lightning._finalize_invoice_settlement",
+                AsyncMock(side_effect=Exception("db unavailable")),
+            ),
+        ):
+            await check_invoice_payment(stored, failed)
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        pending = await verify.get(LightningInvoice, invoice.id)
+        unchanged = await verify.get(ApiKey, key_hash)
+        assert pending is not None
+        assert pending.status == "pending"
+        assert unchanged is not None
+        assert unchanged.balance == 100_000
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as retry:
+        stored = await retry.get(LightningInvoice, invoice.id)
+        assert stored is not None
+        with patch("routstr.lightning.get_wallet", AsyncMock(return_value=wallet)):
+            await check_invoice_payment(stored, retry)
+
+    async with AsyncSession(integration_engine, expire_on_commit=False) as verify:
+        paid = await verify.get(LightningInvoice, invoice.id)
+        credited = await verify.get(ApiKey, key_hash)
+        assert paid is not None
+        assert paid.status == "paid"
+        assert credited is not None
+        assert credited.balance == 200_000
+
+    wallet.mint.assert_awaited_once_with(100, quote_id=invoice.payment_hash)
+    wallet.restore_tokens_for_keyset.assert_not_awaited()

tests/integration/test_model_test_endpoint_security.py

@@ -0,0 +1,224 @@
+import time
+from types import TracebackType
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+from httpx import AsyncClient
+
+from routstr.core.admin import admin_sessions
+from routstr.core.db import ModelRow, UpstreamProviderRow
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_model_test_endpoint_requires_admin_auth(
+    integration_client: AsyncClient,
+) -> None:
+    with patch("httpx.AsyncClient") as mock_async_client:
+        response = await integration_client.post(
+            "/api/models/test",
+            json={
+                "model_id": "model-a",
+                "endpoint_type": "chat-completions",
+                "request_data": {"messages": []},
+            },
+        )
+
+    assert response.status_code == 403
+    mock_async_client.assert_not_called()
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_model_test_endpoint_rejects_unsupported_endpoint_type(
+    integration_client: AsyncClient,
+    integration_session: Any,
+) -> None:
+    admin_token = "test-admin-token-model-test"
+    admin_sessions[admin_token] = int(time.time()) + 3600
+    integration_client.headers["Authorization"] = f"Bearer {admin_token}"
+
+    provider = UpstreamProviderRow(
+        provider_type="custom",
+        base_url="https://api.example.com/v1",
+        api_key="sk-upstream-test",
+        enabled=True,
+        provider_fee=1.01,
+    )
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+    assert provider.id is not None
+
+    model = ModelRow(
+        id="model-a",
+        name="Model A",
+        created=1,
+        description="desc",
+        context_length=100,
+        architecture='{"modality": "text", "input_modalities": ["text"], "output_modalities": ["text"], "tokenizer": "tiktoken", "instruct_type": "chat"}',
+        pricing='{"prompt": 1.0, "completion": 1.0}',
+        upstream_provider_id=provider.id,
+        enabled=True,
+    )
+    integration_session.add(model)
+    await integration_session.commit()
+
+    try:
+        with patch("httpx.AsyncClient") as mock_async_client:
+            response = await integration_client.post(
+                "/api/models/test",
+                json={
+                    "model_id": "model-a",
+                    "endpoint_type": "../../abuse",
+                    "request_data": {"messages": []},
+                },
+            )
+
+        assert response.status_code == 400
+        assert response.json()["detail"] == "Unsupported endpoint_type"
+        mock_async_client.assert_not_called()
+    finally:
+        admin_sessions.pop(admin_token, None)
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_model_test_endpoint_rejects_oversized_request_data(
+    integration_client: AsyncClient,
+    integration_session: Any,
+) -> None:
+    admin_token = "test-admin-token-model-test-oversized"
+    admin_sessions[admin_token] = int(time.time()) + 3600
+    integration_client.headers["Authorization"] = f"Bearer {admin_token}"
+
+    provider = UpstreamProviderRow(
+        provider_type="custom",
+        base_url="https://api.example.com/v1",
+        api_key="sk-upstream-test",
+        enabled=True,
+        provider_fee=1.01,
+    )
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+    assert provider.id is not None
+
+    model = ModelRow(
+        id="model-a",
+        name="Model A",
+        created=1,
+        description="desc",
+        context_length=100,
+        architecture='{"modality": "text", "input_modalities": ["text"], "output_modalities": ["text"], "tokenizer": "tiktoken", "instruct_type": "chat"}',
+        pricing='{"prompt": 1.0, "completion": 1.0}',
+        upstream_provider_id=provider.id,
+        enabled=True,
+    )
+    integration_session.add(model)
+    await integration_session.commit()
+
+    oversized = "x" * (64 * 1024 + 1)
+
+    try:
+        with patch("httpx.AsyncClient") as mock_async_client:
+            response = await integration_client.post(
+                "/api/models/test",
+                json={
+                    "model_id": "model-a",
+                    "endpoint_type": "chat-completions",
+                    "request_data": {"blob": oversized},
+                },
+            )
+
+        assert response.status_code == 413
+        assert response.json()["detail"] == "request_data too large"
+        mock_async_client.assert_not_called()
+    finally:
+        admin_sessions.pop(admin_token, None)
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_model_test_endpoint_admin_uses_allowed_upstream_path(
+    integration_client: AsyncClient,
+    integration_session: Any,
+) -> None:
+    admin_token = "test-admin-token-model-test-success"
+    admin_sessions[admin_token] = int(time.time()) + 3600
+    integration_client.headers["Authorization"] = f"Bearer {admin_token}"
+
+    provider = UpstreamProviderRow(
+        provider_type="custom",
+        base_url="https://api.example.com/v1",
+        api_key="sk-upstream-test",
+        enabled=True,
+        provider_fee=1.01,
+    )
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+    assert provider.id is not None
+
+    model = ModelRow(
+        id="model-a",
+        name="Model A",
+        created=1,
+        description="desc",
+        context_length=100,
+        architecture='{"modality": "text", "input_modalities": ["text"], "output_modalities": ["text"], "tokenizer": "tiktoken", "instruct_type": "chat"}',
+        pricing='{"prompt": 1.0, "completion": 1.0}',
+        upstream_provider_id=provider.id,
+        enabled=True,
+        forwarded_model_id="upstream-model-a",
+    )
+    integration_session.add(model)
+    await integration_session.commit()
+
+    class MockResponse:
+        status_code = 200
+        text = '{"ok": true}'
+
+        def json(self) -> dict[str, bool]:
+            return {"ok": True}
+
+    class MockAsyncClient:
+        async def __aenter__(self) -> "MockAsyncClient":
+            return self
+
+        async def __aexit__(
+            self,
+            exc_type: type[BaseException] | None,
+            exc: BaseException | None,
+            tb: TracebackType | None,
+        ) -> None:
+            return None
+
+        async def post(
+            self, url: str, json: dict[str, Any], headers: dict[str, str]
+        ) -> MockResponse:
+            assert url == "https://api.example.com/v1/chat/completions"
+            assert json["model"] == "upstream-model-a"
+            assert headers["Authorization"] == "Bearer sk-upstream-test"
+            return MockResponse()
+
+    try:
+        with patch("httpx.AsyncClient", return_value=MockAsyncClient()):
+            response = await integration_client.post(
+                "/api/models/test",
+                json={
+                    "model_id": "model-a",
+                    "endpoint_type": "chat-completions",
+                    "request_data": {"messages": []},
+                },
+            )
+
+        assert response.status_code == 200
+        assert response.json() == {
+            "success": True,
+            "data": {"ok": True},
+            "status_code": 200,
+        }
+    finally:
+        admin_sessions.pop(admin_token, None)

tests/integration/test_periodic_payout_safety.py

@@ -0,0 +1,174 @@
+"""Money-safety regression coverage for automatic wallet payouts."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core import db
+from routstr.core.db import ApiKey
+from routstr.core.settings import settings
+from routstr.wallet import credit_balance, periodic_payout
+
+PRIMARY_MINT = "http://primary:3338"
+REFUND_MINT = "http://refund:3338"
+PAYOUT_INTERVAL = 987
+
+
+class _LoopBreak(Exception):
+    """Stop the otherwise-infinite payout loop after one cycle."""
+
+
+def _one_payout_cycle() -> Callable[[float], Coroutine[Any, Any, None]]:
+    intervals_seen = 0
+
+    async def sleep(seconds: float) -> None:
+        nonlocal intervals_seen
+        if seconds == PAYOUT_INTERVAL:
+            intervals_seen += 1
+            if intervals_seen == 2:
+                raise _LoopBreak()
+
+    return sleep
+
+
+@pytest.mark.asyncio
+async def test_cross_mint_liability_is_not_paid_as_owner_profit(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    """Refund preferences must not make primary-mint customer funds payable."""
+    async with AsyncSession(integration_engine, expire_on_commit=False) as setup:
+        setup.add(
+            ApiKey(
+                hashed_key="cross-mint-key",
+                balance=50_000,
+                refund_mint_url=REFUND_MINT,
+                refund_currency="sat",
+            )
+        )
+        await setup.commit()
+
+    primary_proof = MagicMock(amount=50)
+    raw_send = AsyncMock(return_value=50)
+
+    def proofs_for_mint(
+        _wallet: object, mint_url: str, unit: str, **_kwargs: object
+    ) -> list[MagicMock]:
+        if mint_url == PRIMARY_MINT and unit == "sat":
+            return [primary_proof]
+        return []
+
+    with (
+        patch.object(settings, "cashu_mints", [REFUND_MINT]),
+        patch.object(settings, "primary_mint", PRIMARY_MINT),
+        patch.object(settings, "receive_ln_address", "owner@ln.test"),
+        patch.object(settings, "payout_interval_seconds", PAYOUT_INTERVAL),
+        patch.object(settings, "min_payout_sat", 10),
+        patch("routstr.wallet.asyncio.sleep", _one_payout_cycle()),
+        patch("routstr.wallet.get_wallet", AsyncMock(return_value=MagicMock())),
+        patch(
+            "routstr.wallet.get_proofs_per_mint_and_unit",
+            MagicMock(side_effect=proofs_for_mint),
+        ),
+        patch(
+            "routstr.wallet.slow_filter_spend_proofs",
+            AsyncMock(side_effect=lambda proofs, _wallet: proofs),
+        ),
+        patch("routstr.wallet.raw_send_to_lnurl", raw_send),
+    ):
+        with pytest.raises(_LoopBreak):
+            await periodic_payout()
+
+    raw_send.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_payout_does_not_send_proofs_whose_liability_commit_is_in_flight(
+    integration_engine: AsyncEngine,
+    patched_db_engine: None,
+) -> None:
+    """Proof visibility before liability commit must not expose customer funds."""
+    key = ApiKey(
+        hashed_key="in-flight-topup-key",
+        balance=0,
+        refund_mint_url=PRIMARY_MINT,
+        refund_currency="sat",
+    )
+    async with AsyncSession(integration_engine, expire_on_commit=False) as setup:
+        setup.add(key)
+        await setup.commit()
+
+    proofs: list[MagicMock] = []
+    proof_visible = asyncio.Event()
+    finish_redemption = asyncio.Event()
+    liability_read = asyncio.Event()
+
+    async def redeem_token(token: str) -> tuple[int, str, str]:
+        proofs.append(MagicMock(amount=200))
+        proof_visible.set()
+        await finish_redemption.wait()
+        return 200, "sat", PRIMARY_MINT
+
+    real_total_liability = db.total_user_liability
+
+    async def read_liability(_session: AsyncSession) -> int:
+        async with db.create_session() as snapshot_session:
+            value = await real_total_liability(snapshot_session)
+        liability_read.set()
+        return value
+
+    raw_send = AsyncMock(return_value=200)
+
+    with (
+        patch.object(settings, "cashu_mints", []),
+        patch.object(settings, "primary_mint", PRIMARY_MINT),
+        patch.object(settings, "receive_ln_address", "owner@ln.test"),
+        patch.object(settings, "payout_interval_seconds", PAYOUT_INTERVAL),
+        patch.object(settings, "min_payout_sat", 10),
+        patch("routstr.wallet.asyncio.sleep", _one_payout_cycle()),
+        patch("routstr.wallet.recieve_token", AsyncMock(side_effect=redeem_token)),
+        patch("routstr.wallet.get_wallet", AsyncMock(return_value=MagicMock())),
+        patch(
+            "routstr.wallet.get_proofs_per_mint_and_unit",
+            MagicMock(side_effect=lambda *_args, **_kwargs: list(proofs)),
+        ),
+        patch(
+            "routstr.wallet.slow_filter_spend_proofs",
+            AsyncMock(side_effect=lambda visible, _wallet: visible),
+        ),
+        patch(
+            "routstr.wallet.db.total_user_liability",
+            AsyncMock(side_effect=read_liability),
+        ),
+        patch("routstr.wallet.raw_send_to_lnurl", raw_send),
+    ):
+        async with AsyncSession(integration_engine, expire_on_commit=False) as credit_session:
+            stored_key = await credit_session.get(ApiKey, key.hashed_key)
+            assert stored_key is not None
+            credit_task = asyncio.create_task(
+                credit_balance("cashu-token", stored_key, credit_session)
+            )
+            await asyncio.wait_for(proof_visible.wait(), timeout=2)
+
+            payout_task = asyncio.create_task(periodic_payout())
+            try:
+                await asyncio.wait_for(liability_read.wait(), timeout=0.1)
+                liability_was_read_while_crediting = True
+            except TimeoutError:
+                liability_was_read_while_crediting = False
+
+            finish_redemption.set()
+            await asyncio.wait_for(credit_task, timeout=2)
+
+            with pytest.raises(_LoopBreak):
+                await asyncio.wait_for(payout_task, timeout=2)
+
+    assert liability_was_read_while_crediting is False
+    raw_send.assert_not_awaited()

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_proxy_session_lifecycle.py

@@ -0,0 +1,65 @@
+"""Integration coverage for proxy database-session lifetime."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from fastapi import Response
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr import proxy as proxy_module
+from routstr.core.db import ApiKey
+
+
+@pytest.mark.asyncio
+async def test_authenticated_proxy_releases_db_connection_before_upstream_headers(
+    integration_engine: AsyncEngine,
+    integration_session: AsyncSession,
+    patched_db_engine: None,
+) -> None:
+    """Slow upstream header waits must not retain a checked-out DB connection."""
+    key = ApiKey(
+        hashed_key="proxy-pool-key",
+        balance=1_000_000,
+        refund_mint_url="http://primary:3338",
+        refund_currency="sat",
+    )
+    integration_session.add(key)
+    await integration_session.commit()
+
+    request = MagicMock()
+    request.method = "POST"
+    request.headers = {"authorization": "Bearer test-key"}
+    request.body = AsyncMock(return_value=json.dumps({"model": "test-model"}).encode())
+    request.url.path = "/v1/chat/completions"
+    request.state.request_id = "pool-hold-regression"
+
+    model = MagicMock()
+    upstream = MagicMock()
+    upstream.provider_type = "test"
+    upstream.prepare_headers.return_value = {}
+
+    async def wait_for_headers(*args: object, **kwargs: object) -> Response:
+        assert integration_engine.pool.checkedout() == 0  # type: ignore[attr-defined]
+        return Response(status_code=200)
+
+    upstream.forward_request = AsyncMock(side_effect=wait_for_headers)
+
+    with (
+        patch("routstr.proxy.get_candidates", return_value=[(model, upstream)]),
+        patch("routstr.proxy.get_max_cost_for_model", AsyncMock(return_value=100)),
+        patch(
+            "routstr.proxy.calculate_discounted_max_cost",
+            AsyncMock(return_value=100),
+        ),
+        patch("routstr.proxy.check_token_balance"),
+        patch("routstr.proxy.get_bearer_token_key", AsyncMock(return_value=key)),
+    ):
+        response = await proxy_module._proxy(
+            request, "v1/chat/completions", integration_session
+        )
+
+    assert response.status_code == 200

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_reservation_lifecycle.py

@@ -120,7 +120,9 @@ async def test_finalise_releases_reservation_and_charges_balance(
     response_data = {"model": "test-model", "usage": {"prompt_tokens": 50, "completion_tokens": 50}}
 
     with patch("routstr.auth.calculate_cost", return_value=cost_data):
-        await adjust_payment_for_tokens(key, response_data, integration_session, cost)
+        await adjust_payment_for_tokens(
+            key, response_data, integration_session, cost, None, None
+        )
 
     await integration_session.refresh(key)