update migration

make sure to always emit sats cost

.env.example

@@ -14,6 +14,7 @@ UPSTREAM_API_KEY=your-upstream-api-key
 # 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"
 # RECEIVE_LN_ADDRESS=
 

.github/workflows/test.yml

@@ -67,7 +67,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "18"
+          node-version: "20"
           cache: "pnpm"
           cache-dependency-path: ui/pnpm-lock.yaml
 

Dockerfile.full

@@ -0,0 +1,50 @@
+# Multi-stage Dockerfile for Routstr (includes UI build)
+# Stage 1: Build the UI
+FROM node:23-alpine AS ui-builder
+WORKDIR /app/ui
+
+# Install pnpm
+RUN corepack enable pnpm && corepack prepare pnpm@latest --activate
+
+# Copy UI source
+COPY ui/package.json ui/pnpm-lock.yaml* ./
+RUN pnpm install --frozen-lockfile
+
+COPY ui/ ./
+ENV NEXT_TELEMETRY_DISABLED=1
+# Next.js build produces a static export in 'out' directory
+RUN pnpm run build
+
+# Stage 2: Build the Routstr Node
+FROM ghcr.io/astral-sh/uv:python3.11-alpine AS runner
+
+# Install system dependencies
+RUN apk add --no-cache \
+    pkgconf \
+    build-base \
+    automake \
+    autoconf \
+    libtool \
+    m4 \
+    perl \
+    git
+
+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
+
+ENV PORT=8000
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 8000
+
+# Run the application
+CMD ["/app/.venv/bin/fastapi", "run", "routstr", "--host", "0.0.0.0"]

README.md

@@ -51,14 +51,26 @@ curl https://api.routstr.com/v1/chat/completions \
 
 ## Quick Start (Docker)
 
-If you are a node runner, start a Routstr Core instance and configure upstream access in the dashboard.
+If you are a node runner, start a Routstr Core instance using Docker Compose:
 
-```bash
-docker run -d \
-  --name routstr-proxy \
-  -p 8000:8000 \
-  ghcr.io/routstr/proxy:latest
-```
+1. **Prepare your `.env`**:
+   ```bash
+   ADMIN_PASSWORD=mysecretpassword
+   NAME="My AI Node"
+   DESCRIPTION="Fast access to models"
+   NSEC=yournsec
+   RECEIVE_LN_ADDRESS=yourname@wallet.com
+   ```
+
+2. **Start the services**:
+   ```bash
+   docker compose up -d
+   ```
+
+3. **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/)**.
 
 ## Development
 

compose.yml

@@ -6,7 +6,7 @@ services:
       context: ./ui
       dockerfile: Dockerfile.build
       args:
-        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://127.0.0.1:8000}
+        # NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://127.0.0.1:8000}
         NEXT_PUBLIC_ADMIN_API_KEY: ${NEXT_PUBLIC_ADMIN_API_KEY:-}
     volumes:
       - ./ui_out:/output

docs/api/endpoints.md

@@ -360,6 +360,42 @@ POST /v1/wallet/create
 }
 ```
 
+### Get Key Information
+
+Get current balance, consumption data, and child keys for an API key.
+
+```http
+GET /v1/balance/info
+Authorization: Bearer sk-...
+```
+
+**Response:**
+
+```json
+{
+  "api_key": "sk-abc...",
+  "balance": 8500000,
+  "reserved": 0,
+  "is_child": false,
+  "parent_key": null,
+  "total_requests": 42,
+  "total_spent": 1500000,
+  "balance_limit": null,
+  "balance_limit_reset": null,
+  "validity_date": null,
+  "child_keys": [
+    {
+      "api_key": "sk-child1...",
+      "total_requests": 10,
+      "total_spent": 500000,
+      "balance_limit": 1000000,
+      "balance_limit_reset": "daily",
+      "validity_date": 1738000000
+    }
+  ]
+}
+```
+
 ### Check Balance
 
 Get current wallet balance.
@@ -434,6 +470,42 @@ Authorization: Bearer sk-...
 }
 ```
 
+### Create Child Key
+
+Creates one or more child API keys that share the parent's balance. Each child key creation costs a fixed amount (configurable).
+
+```http
+POST /v1/balance/child-key
+Authorization: Bearer sk-...
+```
+
+**Request Body:**
+
+```json
+{
+  "count": 1
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `count` | integer | Yes | - | Number of child keys to create (1-50) |
+
+**Response:**
+
+```json
+{
+  "api_keys": ["sk-abc...", "sk-def..."],
+  "count": 2,
+  "cost_msats": 2000,
+  "cost_sats": 2,
+  "parent_balance": 98000,
+  "parent_balance_sats": 98
+}
+```
+
 ## Provider Discovery
 
 ## Admin Settings

docs/provider/configuration.md

@@ -6,6 +6,32 @@ For automated deployments, you can optionally pre-configure settings via environ
 
 ---
 
+## Initial Setup (.env file)
+
+Before running your node, you should create a `.env` file in the project root. This file is used to bootstrap the initial configuration and store sensitive secrets.
+
+### Example .env
+
+```bash
+ADMIN_PASSWORD=your-secure-password
+
+# Node Identity
+NAME="My AI Node"
+DESCRIPTION="Fast access to models"
+
+# Lightning Payouts
+RECEIVE_LN_ADDRESS=yourname@wallet.com
+```
+
+### Setting the UI Password
+
+There are two ways to set or change your Admin Dashboard password:
+
+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.
+
+---
+
 ## Admin Dashboard (Primary)
 
 Access the dashboard at `/admin/` on your node.
@@ -14,29 +40,29 @@ Access the dashboard at `/admin/` on your node.
 
 Connect to your AI provider(s):
 
-| Setting | Description |
-|---------|-------------|
+| Setting          | Description                                      |
+| ---------------- | ------------------------------------------------ |
 | **Upstream URL** | API endpoint (e.g., `https://api.openai.com/v1`) |
-| **API Key** | Your provider's API key |
+| **API Key**      | Your provider's API key                          |
 
 ### Node Identity
 
 How your node appears to clients:
 
-| Setting | Description |
-|---------|-------------|
-| **Name** | Display name (e.g., "Fast GPT-4 Node") |
-| **Description** | Brief description of your service |
+| Setting         | Description                            |
+| --------------- | -------------------------------------- |
+| **Name**        | Display name (e.g., "Fast GPT-4 Node") |
+| **Description** | Brief description of your service      |
 
 ### Pricing
 
 Control your profit margins:
 
-| Setting | Description | Default |
-|---------|-------------|---------|
-| **Fixed Pricing** | Charge flat rate per request vs. per-token | Off |
-| **Exchange Fee** | Buffer for BTC volatility | 1.005 (0.5%) |
-| **Upstream Fee** | Your profit markup | 1.10 (10%) |
+| Setting           | Description                                | Default      |
+| ----------------- | ------------------------------------------ | ------------ |
+| **Fixed Pricing** | Charge flat rate per request vs. per-token | Off          |
+| **Exchange Fee**  | Buffer for BTC volatility                  | 1.005 (0.5%) |
+| **Upstream Fee**  | Your profit markup                         | 1.10 (10%)   |
 
 See [Pricing](pricing.md) for detailed strategies.
 
@@ -44,33 +70,34 @@ See [Pricing](pricing.md) for detailed strategies.
 
 Which mints to accept payments from:
 
-| Setting | Description |
-|---------|-------------|
+| Setting   | Description                     |
+| --------- | ------------------------------- |
 | **Mints** | List of trusted Cashu mint URLs |
 
 ### Lightning Withdrawals
 
 Automatic profit withdrawal:
 
-| Setting | Description |
-|---------|-------------|
+| Setting               | Description                     |
+| --------------------- | ------------------------------- |
 | **Lightning Address** | Your LN address for withdrawals |
 
 ### Security
 
-| Setting | Description |
-|---------|-------------|
+| Setting            | Description                   |
+| ------------------ | ----------------------------- |
 | **Admin Password** | Password for dashboard access |
 
 ### Nostr Discovery
 
 Announce your node on the network:
 
-| Setting | Description |
-|---------|-------------|
-| **Npub** | Your Nostr public key |
-| **Nsec** | Your Nostr private key (for signing) |
-| **Relays** | Relays to publish announcements |
+| Setting    | Description                          |
+| ---------- | ------------------------------------ |
+| **Npub**   | Your Nostr public key                |
+| **Nsec**   | Your Nostr private key (for signing) |
+| **Relays** | Relays to publish announcements      |
+| **Share Analytics** | Publish aggregate usage stats to Nostr |
 
 See [Discovery](discovery.md) for details.
 
@@ -86,21 +113,22 @@ Use environment variables for:
 
 ### All Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `UPSTREAM_BASE_URL` | Upstream API endpoint | — |
-| `UPSTREAM_API_KEY` | Upstream API key | — |
-| `ADMIN_PASSWORD` | Dashboard password | (none) |
-| `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 | — |
-| `CASHU_MINTS` | Comma-separated mint URLs | `https://mint.minibits.cash/Bitcoin` |
-| `RECEIVE_LN_ADDRESS` | Lightning address for withdrawals | — |
-| `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) |
+| Variable             | Description                       | Default                              |
+| -------------------- | --------------------------------- | ------------------------------------ |
+| `UPSTREAM_BASE_URL`  | Upstream API endpoint             | —                                    |
+| `UPSTREAM_API_KEY`   | Upstream API key                  | —                                    |
+| `ADMIN_PASSWORD`     | Dashboard password                | (none)                               |
+| `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                 | —                                    |
+| `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 | —                                    |
+| `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)                        |
 
 ### Priority
 

docs/provider/dashboard.md

@@ -152,6 +152,7 @@ Manage which mints you accept payments from:
 |-------|-------------|
 | **Nsec** | Private key for signing announcements |
 | **Relays** | Where to publish your node advertisement |
+| **Share Analytics** | Toggle publishing aggregate usage stats to Nostr |
 
 ### Security
 

docs/provider/deployment.md

@@ -6,30 +6,16 @@ Production deployment guide for Routstr Provider nodes.
 
 For production, use Docker Compose with persistent storage and optional Tor support.
 
-### Basic Setup
-
-Create a `compose.yml`:
-
-```yaml
-services:
-  routstr:
-    image: ghcr.io/routstr/proxy:latest
-    container_name: routstr
-    restart: unless-stopped
-    ports:
-      - "8000:8000"
-    volumes:
-      - ./data:/app/data
-      - ./logs:/app/logs
-```
-
-Start the node:
+Use the included `compose.yml` for a flexible setup that handles both the UI and the node execution. This is useful for development or when you want to manage Tor as a separate service.
 
 ```bash
 docker compose up -d
 ```
 
-Then configure everything via the [Admin Dashboard](http://localhost:8000/admin/).
+This will:
+1.  **Build the UI**: Compiles the frontend and copies it to a shared volume.
+2.  **Start Routstr**: Runs the Python node, mounting the built UI.
+3.  **Start Tor**: Provides anonymous access via a `.onion` address.
 
 ---
 
@@ -189,8 +175,16 @@ docker compose up -d
 
 ## Building from Source
 
+### Using Docker Compose
+The easiest way to build everything from source:
+
 ```bash
-git clone https://github.com/routstr/routstr-core.git
-cd routstr-core
-docker build -t routstr-local .
+docker compose build
+```
+
+### Individual Components
+If you prefer building the node only (requires manual UI build first):
+
+```bash
+docker build -t routstr-node .
 ```

docs/provider/quickstart.md

@@ -13,7 +13,7 @@ A **Routstr Provider Node** acts as a gateway that:
 You bring the API keys, Routstr handles the billing, payments, and client management.
 
 !!! tip "Future: Node-to-Node Routing"
-    In future versions, you'll be able to run a node that connects to other Routstr nodes—eliminating the need to configure upstream providers yourself. For now, you'll need your own API credentials.
+In future versions, you'll be able to run a node that connects to other Routstr nodes—eliminating the need to configure upstream providers yourself. For now, you'll need your own API credentials.
 
 ---
 
@@ -24,14 +24,30 @@ You bring the API keys, Routstr handles the billing, payments, and client manage
 
 ---
 
-## 1. Start the Node
+## 1. Prepare Configuration
+
+Create a `.env` file in the root of the project to store your secrets:
 
 ```bash
-docker run -d \
-  --name routstr \
-  -p 8000:8000 \
-  -v routstr-data:/app/data \
-  ghcr.io/routstr/proxy:latest
+# Initial Admin Password
+ADMIN_PASSWORD=mysecretpassword
+
+# Node Identity
+NAME="My AI Node"
+DESCRIPTION="Fast access to models"
+NSEC=yournsec
+
+# Lightning Payouts
+RECEIVE_LN_ADDRESS=yourname@wallet.com
+
+```
+
+## 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.
+
+```bash
+docker compose up -d
 ```
 
 Verify it's running:
@@ -40,14 +56,23 @@ Verify it's running:
 curl http://localhost:8000/v1/info
 ```
 
+### Build from Source (Optional)
+
+If you've cloned the repository and want to build the images yourself:
+
+```bash
+docker compose build
+docker compose up -d
+```
+
 ---
 
-## 2. Configure via Dashboard
+## 3. Configure via Dashboard
 
 Open the **Admin Dashboard** at [http://localhost:8000/admin/](http://localhost:8000/admin/).
 
-!!! note "Default Access"
-    The dashboard has no password by default. Set one immediately in Settings for production use.
+!!! 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.
 
 ### Connect Your AI Providers
 

examples/create_child_keys.py

@@ -0,0 +1,45 @@
+import json
+import sys
+
+import httpx
+
+
+def create_child_keys(base_url: str, api_key: str, count: int = 3) -> list[str]:
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    print(f"Requesting {count} child keys from {base_url}...")
+
+    child_keys = []
+
+    for i in range(count):
+        try:
+            response = httpx.post(f"{base_url}/v1/balance/child-key", headers=headers)
+            if response.status_code == 200:
+                data = response.json()
+                child_keys.append(data["api_key"])
+                print(
+                    f"  [{i + 1}] Created: {data['api_key']} (Cost: {data['cost_msats']} msats)"
+                )
+            else:
+                print(f"  [{i + 1}] Failed: {response.status_code} - {response.text}")
+        except Exception as e:
+            print(f"  [{i + 1}] Error: {str(e)}")
+
+    return child_keys
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python create_child_keys.py <api_key_or_cashu_token> [base_url]")
+        sys.exit(1)
+
+    auth_key = sys.argv[1]
+    base_url = sys.argv[2] if len(sys.argv) > 2 else "http://localhost:8000"
+
+    keys = create_child_keys(base_url, auth_key)
+
+    if keys:
+        print("\nSuccessfully created child keys:")
+        print(json.dumps(keys, indent=2))
+    else:
+        print("\nNo child keys were created.")

logs/.gitkeep

@@ -0,0 +1 @@
+

migrations/versions/02650cd6f028_add_routstr_fees_table.py

@@ -0,0 +1,32 @@
+"""add routstr_fees table
+
+Revision ID: 02650cd6f028
+Revises: c3d4e5f6a7b8
+Create Date: 2026-04-24 00:00:00.000000
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "02650cd6f028"
+down_revision = "c3d4e5f6a7b8"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "routstr_fees",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("accumulated_msats", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("total_paid_msats", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("last_paid_at", sa.Integer(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    # Seed with a single row
+    op.execute("INSERT INTO routstr_fees (id, accumulated_msats, total_paid_msats) VALUES (1, 0, 0)")
+
+
+def downgrade() -> None:
+    op.drop_table("routstr_fees")

migrations/versions/06f81c0fc88d_add_key_management_and_reset_fields_to_.py

@@ -0,0 +1,37 @@
+"""add key management and reset fields to api_keys
+
+Revision ID: 06f81c0fc88d
+Revises: c2d3e4f5a6b7
+Create Date: 2026-02-04 22:44:03.311983
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "06f81c0fc88d"
+down_revision = "c2d3e4f5a6b7"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("api_keys", sa.Column("balance_limit", sa.Integer(), nullable=True))
+    op.add_column(
+        "api_keys",
+        sa.Column(
+            "balance_limit_reset", sqlmodel.sql.sqltypes.AutoString(), nullable=True
+        ),
+    )
+    op.add_column(
+        "api_keys", sa.Column("balance_limit_reset_date", sa.Integer(), nullable=True)
+    )
+    op.add_column("api_keys", sa.Column("validity_date", sa.Integer(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("api_keys", "validity_date")
+    op.drop_column("api_keys", "balance_limit_reset_date")
+    op.drop_column("api_keys", "balance_limit_reset")
+    op.drop_column("api_keys", "balance_limit")

migrations/versions/614c0a740e68_add_provider_settings_to_upstream_.py

@@ -0,0 +1,32 @@
+"""add provider_settings to upstream_providers
+
+Revision ID: 614c0a740e68
+Revises: 06f81c0fc88d
+Create Date: 2026-02-13 22:36:53.608737
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "614c0a740e68"
+down_revision = "06f81c0fc88d"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Check if column exists before adding it
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    columns = [c["name"] for c in inspector.get_columns("upstream_providers")]
+
+    if "provider_settings" not in columns:
+        op.add_column(
+            "upstream_providers",
+            sa.Column("provider_settings", sa.Text(), nullable=True),
+        )
+
+
+def downgrade() -> None:
+    op.drop_column("upstream_providers", "provider_settings")

migrations/versions/6d2fa295fa43_add_provider_fee_schedules.py

@@ -0,0 +1,57 @@
+"""add provider_fee_schedules and provider_fee_default to upstream_providers
+
+Revision ID: 6d2fa295fa43
+Revises: cli_tokens_001
+Create Date: 2026-04-28 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "6d2fa295fa43"
+down_revision = "cli_tokens_001"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    columns = {c["name"] for c in inspector.get_columns("upstream_providers")}
+
+    if "provider_fee_default" not in columns:
+        op.add_column(
+            "upstream_providers",
+            sa.Column(
+                "provider_fee_default",
+                sa.Float(),
+                nullable=False,
+                server_default="1.01",
+            ),
+        )
+        # Preserve any custom per-provider fees by copying from provider_fee.
+        op.execute(
+            "UPDATE upstream_providers "
+            "SET provider_fee_default = provider_fee "
+            "WHERE provider_fee IS NOT NULL"
+        )
+
+    if "provider_fee_schedules" not in columns:
+        op.add_column(
+            "upstream_providers",
+            sa.Column("provider_fee_schedules", sa.Text(), nullable=True),
+        )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    columns = {c["name"] for c in inspector.get_columns("upstream_providers")}
+
+    if "provider_fee_schedules" in columns:
+        op.drop_column("upstream_providers", "provider_fee_schedules")
+    if "provider_fee_default" in columns:
+        op.drop_column("upstream_providers", "provider_fee_default")

migrations/versions/a776ca70e5fe_add_cashu_refunds_table.py

@@ -0,0 +1,42 @@
+"""add cashu_transactions table
+
+Revision ID: a776ca70e5fe
+Revises: 614c0a740e68
+Create Date: 2026-03-11 22:00:01.554762
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "a776ca70e5fe"
+down_revision = "614c0a740e68"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "cashu_transactions",
+        sa.Column("id", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("token", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("amount", sa.Integer(), nullable=False),
+        sa.Column("unit", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("mint_url", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+        sa.Column(
+            "type",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=False,
+            server_default="out",
+        ),
+        sa.Column("request_id", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+        sa.Column("created_at", sa.Integer(), nullable=False),
+        sa.Column("collected", sa.Boolean(), nullable=False),
+        sa.Column("swept", sa.Boolean(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("cashu_transactions")

migrations/versions/a86e5348850b_.py

@@ -0,0 +1,42 @@
+"""
+
+Revision ID: a86e5348850b
+Revises: b9667ffc5701
+Create Date: 2026-01-10 18:57:48.475781
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "a86e5348850b"
+down_revision = "b9667ffc5701"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Use batch_alter_table for SQLite compatibility
+    with op.batch_alter_table("api_keys", schema=None) as batch_op:
+        batch_op.add_column(
+            sa.Column(
+                "parent_key_hash", sqlmodel.sql.sqltypes.AutoString(), nullable=True
+            )
+        )
+        batch_op.create_index(
+            batch_op.f("ix_api_keys_parent_key_hash"), ["parent_key_hash"], unique=False
+        )
+        batch_op.create_foreign_key(
+            "fk_api_keys_parent_key_hash",
+            "api_keys",
+            ["parent_key_hash"],
+            ["hashed_key"],
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("api_keys", schema=None) as batch_op:
+        batch_op.drop_constraint("fk_api_keys_parent_key_hash", type_="foreignkey")
+        batch_op.drop_index(batch_op.f("ix_api_keys_parent_key_hash"))
+        batch_op.drop_column("parent_key_hash")

migrations/versions/b1c2d3e4f5a6_add_upstream_model_id_to_models.py

@@ -0,0 +1,33 @@
+"""add forwarded_model_id to models
+
+Revision ID: b1c2d3e4f5a6
+Revises: a776ca70e5fe
+Create Date: 2026-04-05 00:00:00.000000
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "b1c2d3e4f5a6"
+down_revision = "a776ca70e5fe"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "models",
+        sa.Column(
+            "forwarded_model_id",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=True,
+        ),
+    )
+    # Backfill: set forwarded_model_id = id for all existing rows
+    op.execute("UPDATE models SET forwarded_model_id = id WHERE forwarded_model_id IS NULL")
+
+
+def downgrade() -> None:
+    op.drop_column("models", "forwarded_model_id")

migrations/versions/c2d3e4f5a6b7_upstream_provider_base_url_api_key_unique.py

@@ -0,0 +1,118 @@
+"""make upstream provider base_url + api_key unique
+
+Revision ID: c2d3e4f5a6b7
+Revises: a86e5348850b
+Create Date: 2026-01-25 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "c2d3e4f5a6b7"
+down_revision = "a86e5348850b"
+branch_labels = None
+depends_on = None
+
+
+def _recreate_table_sqlite(add_base_url_unique: bool) -> None:
+    conn = op.get_bind()
+    existing_tables = {
+        row[0]
+        for row in conn.exec_driver_sql(
+            "SELECT name FROM sqlite_master WHERE type='table'"
+        ).fetchall()
+    }
+    if "upstream_providers_old" in existing_tables:
+        if "upstream_providers" in existing_tables:
+            op.drop_table("upstream_providers_old")
+        else:
+            op.execute(
+                "ALTER TABLE upstream_providers_old RENAME TO upstream_providers"
+            )
+            existing_tables.add("upstream_providers")
+    if "upstream_providers" not in existing_tables:
+        return
+
+    constraints = [
+        sa.UniqueConstraint(
+            "base_url",
+            "api_key",
+            name="uq_upstream_providers_base_url_api_key",
+        )
+    ]
+    if add_base_url_unique:
+        constraints.append(
+            sa.UniqueConstraint("base_url", name="uq_upstream_providers_base_url")
+        )
+
+    op.execute("ALTER TABLE upstream_providers RENAME TO upstream_providers_old")
+    op.create_table(
+        "upstream_providers",
+        sa.Column(
+            "id", sa.Integer(), primary_key=True, nullable=False, autoincrement=True
+        ),
+        sa.Column("provider_type", sa.String(), nullable=False),
+        sa.Column("base_url", sa.String(), nullable=False),
+        sa.Column("api_key", sa.String(), nullable=False),
+        sa.Column("api_version", sa.String(), nullable=True),
+        sa.Column("enabled", sa.Boolean(), nullable=False),
+        sa.Column("provider_fee", sa.Float(), nullable=False, server_default="1.01"),
+        *constraints,
+    )
+    op.execute(
+        "INSERT INTO upstream_providers (id, provider_type, base_url, api_key, api_version, enabled, provider_fee) "
+        "SELECT id, provider_type, base_url, api_key, api_version, enabled, provider_fee "
+        "FROM upstream_providers_old"
+    )
+    op.drop_table("upstream_providers_old")
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    if conn.dialect.name == "sqlite":
+        _recreate_table_sqlite(add_base_url_unique=False)
+        return
+
+    inspector = sa.inspect(conn)
+    for constraint in inspector.get_unique_constraints("upstream_providers"):
+        name = constraint.get("name")
+        if constraint.get("column_names") == ["base_url"] and name:
+            op.drop_constraint(
+                name,
+                "upstream_providers",
+                type_="unique",
+            )
+    index_names = {idx["name"] for idx in inspector.get_indexes("upstream_providers")}
+    if "ix_upstream_providers_base_url" in index_names:
+        op.drop_index("ix_upstream_providers_base_url", table_name="upstream_providers")
+    op.create_unique_constraint(
+        "uq_upstream_providers_base_url_api_key",
+        "upstream_providers",
+        ["base_url", "api_key"],
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    if conn.dialect.name == "sqlite":
+        _recreate_table_sqlite(add_base_url_unique=True)
+        return
+
+    op.drop_constraint(
+        "uq_upstream_providers_base_url_api_key",
+        "upstream_providers",
+        type_="unique",
+    )
+    op.create_unique_constraint(
+        "uq_upstream_providers_base_url",
+        "upstream_providers",
+        ["base_url"],
+    )
+    op.create_index(
+        "ix_upstream_providers_base_url",
+        "upstream_providers",
+        ["base_url"],
+        unique=True,
+    )

migrations/versions/c3d4e5f6a7b8_add_source_to_cashu_transactions.py

@@ -0,0 +1,36 @@
+"""add source to cashu_transactions
+
+Revision ID: c3d4e5f6a7b8
+Revises: b1c2d3e4f5a6
+Create Date: 2026-04-10 00:00:00.000000
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "c3d4e5f6a7b8"
+down_revision = "b1c2d3e4f5a6"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    columns = [col["name"] for col in inspector.get_columns("cashu_transactions")]
+    if "source" not in columns:
+        op.add_column(
+            "cashu_transactions",
+            sa.Column(
+                "source",
+                sqlmodel.sql.sqltypes.AutoString(),
+                nullable=False,
+                server_default="x-cashu",
+            ),
+        )
+
+
+def downgrade() -> None:
+    op.drop_column("cashu_transactions", "source")

migrations/versions/cli_tokens_table.py

@@ -0,0 +1,34 @@
+"""add cli_tokens table
+
+Revision ID: cli_tokens_001
+Revises: e8f9a0b1c2d3
+Create Date: 2026-04-25 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "cli_tokens_001"
+down_revision = "e8f9a0b1c2d3"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "cli_tokens",
+        sa.Column("id", sa.String(), primary_key=True, nullable=False),
+        sa.Column("token", sa.String(), nullable=False, unique=True),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("created_at", sa.Integer(), nullable=False),
+        sa.Column("last_used_at", sa.Integer(), nullable=True),
+        sa.Column("expires_at", sa.Integer(), nullable=True),
+    )
+    op.create_index("ix_cli_tokens_token", "cli_tokens", ["token"], unique=True)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_cli_tokens_token", table_name="cli_tokens")
+    op.drop_table("cli_tokens")

migrations/versions/d4e5f6a7b8c9_add_api_key_to_cashu_transactions.py

@@ -0,0 +1,46 @@
+"""add api key link to cashu_transactions
+
+Revision ID: d4e5f6a7b8c9
+Revises: c3d4e5f6a7b8
+Create Date: 2026-04-20 00:00:00.000000
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "d4e5f6a7b8c9"
+down_revision = "c3d4e5f6a7b8"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    columns = [col["name"] for col in inspector.get_columns("cashu_transactions")]
+    indexes = {index["name"] for index in inspector.get_indexes("cashu_transactions")}
+
+    if "api_key_hashed_key" not in columns:
+        op.add_column(
+            "cashu_transactions",
+            sa.Column(
+                "api_key_hashed_key",
+                sqlmodel.sql.sqltypes.AutoString(),
+                nullable=True,
+            ),
+        )
+
+    if "ix_cashu_transactions_api_key_hashed_key" not in indexes:
+        op.create_index(
+            "ix_cashu_transactions_api_key_hashed_key",
+            "cashu_transactions",
+            ["api_key_hashed_key"],
+            unique=False,
+        )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_cashu_transactions_api_key_hashed_key", table_name="cashu_transactions")
+    op.drop_column("cashu_transactions", "api_key_hashed_key")

migrations/versions/e8f9a0b1c2d3_merge_heads.py

@@ -0,0 +1,20 @@
+"""merge heads: routstr_fees + api_key_to_cashu_transactions
+
+Revision ID: e8f9a0b1c2d3
+Revises: 02650cd6f028, d4e5f6a7b8c9
+Create Date: 2026-04-24 00:00:00.000000
+"""
+
+# revision identifiers, used by Alembic.
+revision = "e8f9a0b1c2d3"
+down_revision = ("02650cd6f028", "d4e5f6a7b8c9")
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

plans/other-mints-balance-tracking-plan.md

@@ -0,0 +1,355 @@
+# Plan: Track unsupported incoming mints in `other_mints` and include them in balances
+
+## Goal
+
+When a Cashu token arrives from a mint that is **not** in `settings.cashu_mints`, we currently create/use a wallet for that mint and swap value into the primary mint. Any change/surplus left behind after `melt()` remains in the foreign `token_wallet`, but that balance is not surfaced by `fetch_all_balances()` because it only iterates over configured mints.
+
+This plan adds persistent tracking for those foreign mints in a new database table called `other_mints`, and updates balance reporting to include them.
+
+---
+
+## Current behavior
+
+### Incoming unsupported mint flow
+
+In `routstr/wallet.py`:
+
+- `recieve_token()` deserializes the token
+- if `token_obj.mint not in settings.cashu_mints`, it calls `swap_to_primary_mint(token_obj, wallet)`
+- `swap_to_primary_mint()` calls `token_wallet.melt(...)` to pay the primary mint invoice
+
+### Important detail: change is retained, not discarded
+
+The underlying Cashu wallet library keeps any melt change:
+
+- `Wallet.melt()` constructs blank outputs for change
+- when the melt succeeds, returned change is reconstructed into proofs
+- those proofs are appended to `self.proofs` and stored in the wallet DB
+
+So surplus from unsupported mints is **not discarded**, but it may become invisible operationally.
+
+### Visibility problem
+
+`fetch_all_balances()` currently only loops over:
+
+- `settings.cashu_mints`
+- units `sat` and `msat`
+
+This means balances left on unsupported mints are not shown in admin balance reporting.
+
+---
+
+## Proposed design
+
+## 1. Add a new DB table: `other_mints`
+
+Add a small table in `routstr/core/db.py` to persist unsupported mints we have seen in incoming tokens.
+
+Suggested schema:
+
+- `mint_url: str` primary key
+- `created_at: int`
+- `last_seen_at: int`
+
+Minimal model:
+
+```python
+class OtherMint(SQLModel, table=True):
+    __tablename__ = "other_mints"
+
+    mint_url: str = Field(primary_key=True)
+    created_at: int = Field(default_factory=lambda: int(time.time()))
+    last_seen_at: int = Field(default_factory=lambda: int(time.time()))
+```
+
+Why minimal:
+
+- the only required function is mint discovery/tracking
+- unit handling can remain dynamic via existing balance queries over `sat` and `msat`
+
+---
+
+## 2. Add DB helpers for `other_mints`
+
+In `routstr/core/db.py`, add helper functions:
+
+### `register_other_mint(mint_url: str) -> None`
+
+Behavior:
+
+- if the mint is not present, insert it
+- if it already exists, update `last_seen_at`
+
+### `list_other_mints(session) -> list[str]`
+
+Behavior:
+
+- return all tracked unsupported mint URLs
+
+Optional later:
+
+- `delete_other_mint(...)`
+- admin cleanup helpers
+
+---
+
+## 3. Register unsupported mints during token receipt
+
+Update `recieve_token()` in `routstr/wallet.py`.
+
+Current logic:
+
+```python
+if token_obj.mint not in settings.cashu_mints:
+    return await swap_to_primary_mint(token_obj, wallet)
+```
+
+Planned logic:
+
+```python
+if token_obj.mint not in settings.cashu_mints:
+    await db.register_other_mint(token_obj.mint)
+    return await swap_to_primary_mint(token_obj, wallet)
+```
+
+Why here:
+
+- this is the earliest reliable point where we know the mint came in via an actual token
+- this is exactly the path that can leave foreign-mint change behind
+- it avoids needing to infer unsupported mints later from wallet internals
+
+---
+
+## 4. Update `fetch_all_balances()` to include `other_mints`
+
+Current behavior only includes configured mints.
+
+Planned behavior:
+
+- load tracked unsupported mints from DB
+- combine them with `settings.cashu_mints`
+- dedupe while preserving order
+- fetch balances for all tracked mints across requested units
+
+Conceptual flow:
+
+```python
+tracked_mints = dedupe(settings.cashu_mints + other_mints_from_db)
+```
+
+Then existing per-mint/per-unit balance logic can remain mostly unchanged.
+
+This ensures that retained change on unsupported mints becomes visible in admin balance reporting.
+
+---
+
+## 5. Add a balance source marker
+
+Extend `BalanceDetail` in `routstr/wallet.py` to identify whether a balance row comes from a configured mint or an `other_mints` entry.
+
+Suggested field:
+
+- `source: str` with values:
+  - `"configured"`
+  - `"other"`
+
+Updated shape:
+
+```python
+class BalanceDetail(TypedDict, total=False):
+    mint_url: str
+    unit: str
+    source: str
+    wallet_balance: int
+    user_balance: int
+    owner_balance: int
+    error: str
+```
+
+Why this helps:
+
+- admin can distinguish normal configured wallet balances from foreign/unsupported balances
+- avoids confusion if unexpected mint URLs show up in the balances API/UI
+
+---
+
+## 6. Admin/API impact
+
+Backend impact is minimal because `/admin/api/balances` already returns `fetch_all_balances()` output.
+
+Effects:
+
+- supported mints continue to show as before
+- tracked unsupported mints will also appear
+- UI can optionally display the new `source` field
+
+No API contract break is expected if the frontend ignores unknown fields.
+
+---
+
+## 7. Payout behavior: do not change in phase 1
+
+`periodic_payout()` currently only iterates over `settings.cashu_mints`.
+
+Recommendation for this change:
+
+- **do not** expand `periodic_payout()` to include `other_mints` yet
+- only improve visibility through balance reporting
+
+Reason:
+
+- automatic payout from unsupported/foreign mints may be operationally undesirable
+- visibility should come first, automation second
+
+Possible future phase:
+
+- add optional sweeping/payout support for `other_mints`
+- or provide an admin-triggered withdrawal/sweep flow
+
+---
+
+## 8. Logging improvements (optional)
+
+Optional follow-up improvement in `swap_to_primary_mint()`:
+
+- capture the return value from `token_wallet.melt(...)`
+- if feasible, log any reported change amount
+- otherwise, rely on wallet balance reporting to surface residual amounts
+
+This is useful but not required for the first implementation.
+
+---
+
+## Files to change
+
+### `routstr/core/db.py`
+
+Add:
+
+- `OtherMint` SQLModel
+- `register_other_mint()`
+- `list_other_mints()`
+
+### `migrations/versions/<new_revision>_add_other_mints_table.py`
+
+Create migration to add the `other_mints` table.
+
+### `routstr/wallet.py`
+
+Update:
+
+- `recieve_token()` to register unsupported mints
+- `BalanceDetail` to include `source`
+- `fetch_all_balances()` to include both configured and tracked unsupported mints
+
+### `routstr/core/admin.py`
+
+Likely no backend changes required unless a dedicated `other_mints` API is desired.
+
+---
+
+## Behavior rules
+
+### Register a mint when
+
+- an incoming token is processed
+- the token mint is not in `settings.cashu_mints`
+
+### Do not remove automatically when
+
+- balance reaches zero
+
+Reason:
+
+- historical visibility is useful
+- avoids flapping entries in the admin balance list
+- mint may receive additional unsupported tokens later
+
+Potential future enhancement:
+
+- admin endpoint to prune zero-balance `other_mints`
+
+---
+
+## Edge cases
+
+### A mint later becomes configured
+
+If a mint in `other_mints` is later added to `settings.cashu_mints`:
+
+- deduplication prevents duplicate balance rows
+- `source` should resolve to `configured`
+
+### Unsupported mint with zero balance
+
+A tracked unsupported mint may show zero balances.
+
+Initial recommendation:
+
+- allow it to appear
+- consider later filtering zero-balance `other` rows if the UI becomes noisy
+
+### Units
+
+Balance fetching can continue to query both `sat` and `msat` for each tracked mint.
+
+If a mint has no proofs in one unit, current error/zero handling can continue to apply.
+
+---
+
+## Test plan
+
+### DB tests
+
+- registering a new unsupported mint inserts a row
+- registering the same mint again updates `last_seen_at` without duplication
+- listing other mints returns expected mint URLs
+
+### Wallet tests
+
+#### `recieve_token()`
+
+- when mint is unsupported, `db.register_other_mint()` is called before swap
+- when mint is configured, `db.register_other_mint()` is not called
+
+#### `fetch_all_balances()`
+
+- includes configured mints
+- includes `other_mints` from DB
+- dedupes if a mint exists in both configured and other lists
+- sets `source` correctly
+
+### Regression tests
+
+- existing trusted mint balance reporting remains unchanged
+- `/admin/api/balances` continues to work
+
+---
+
+## Recommended implementation order
+
+1. Add `OtherMint` model to `routstr/core/db.py`
+2. Add Alembic migration for `other_mints`
+3. Add `register_other_mint()` and `list_other_mints()` helpers
+4. Update `recieve_token()` to register unsupported mints
+5. Update `fetch_all_balances()` to union configured + tracked other mints
+6. Add `source` to `BalanceDetail`
+7. Add/adjust tests
+
+---
+
+## Summary
+
+This change solves an operational visibility problem:
+
+- unsupported incoming mints can leave retained change in foreign wallets
+- those funds are currently preserved but not surfaced in balance reporting
+- introducing `other_mints` makes those mints discoverable and auditable
+- expanding `fetch_all_balances()` ensures their balances are visible in admin tooling
+
+Recommended scope for the first pass:
+
+- track unsupported mints in DB
+- include them in balance reporting
+- mark them as `source="other"`
+- do not yet change payout/sweeping behavior

pyproject.toml

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

routstr/algorithm.py

@@ -84,93 +84,26 @@ def get_provider_penalty(provider: "BaseUpstreamProvider") -> float:
     return penalty
 
 
-def should_prefer_model(
-    candidate_model: "Model",
-    candidate_provider: "BaseUpstreamProvider",
-    current_model: "Model",
-    current_provider: "BaseUpstreamProvider",
-    alias: str,
-) -> bool:
-    """Determine if candidate model should replace current model for an alias.
-
-    This is the core decision function for model prioritization. It considers:
-    1. Alias matching quality (exact match vs. canonical slug match)
-    2. Model cost (lower is better)
-    3. Provider penalties (e.g., slight preference against OpenRouter)
-
-    Args:
-        candidate_model: The new model being considered
-        candidate_provider: Provider offering the candidate model
-        current_model: The currently selected model for this alias
-        current_provider: Provider offering the current model
-        alias: The model alias being mapped
-
-    Returns:
-        True if candidate should replace current, False otherwise
-    """
-
-    def get_base_model_id(model_id: str) -> str:
-        """Get base model ID by removing provider prefix."""
-        return model_id.split("/", 1)[1] if "/" in model_id else model_id
-
-    def alias_priority(model: "Model") -> int:
-        """Rank how strong the mapping of alias->model is.
-
-        Highest priority when alias exactly equals the model ID without provider prefix.
-        Next when alias equals canonical slug without prefix. Otherwise lowest.
-        """
-        model_base = get_base_model_id(model.id)
-        if model_base == alias:
-            return 3
-        if model.canonical_slug:
-            canonical_base = get_base_model_id(model.canonical_slug)
-            if canonical_base == alias:
-                return 2
-        return 1
-
-    candidate_alias_priority = alias_priority(candidate_model)
-    current_alias_priority = alias_priority(current_model)
-
-    # If candidate has better alias match, prefer it regardless of cost
-    if candidate_alias_priority > current_alias_priority:
-        return True
-
-    # If current has better alias match, keep it regardless of cost
-    if current_alias_priority > candidate_alias_priority:
-        return False
-
-    # Same alias priority - compare costs
-    candidate_cost = calculate_model_cost_score(candidate_model)
-    current_cost = calculate_model_cost_score(current_model)
-
-    # Apply provider penalties
-    candidate_adjusted = candidate_cost * get_provider_penalty(candidate_provider)
-    current_adjusted = current_cost * get_provider_penalty(current_provider)
-
-    # Prefer lower adjusted cost
-    should_replace = candidate_adjusted < current_adjusted
-
-    return should_replace
-
-
 def create_model_mappings(
     upstreams: list["BaseUpstreamProvider"],
     overrides_by_id: dict[str, tuple],
     disabled_model_ids: set[str],
-) -> tuple[dict[str, "Model"], dict[str, "BaseUpstreamProvider"], dict[str, "Model"]]:
+) -> tuple[
+    dict[str, "Model"], dict[str, list["BaseUpstreamProvider"]], dict[str, "Model"]
+]:
     """Create optimal model mappings based on cost and provider preferences.
 
     This is the main entry point for the algorithm. It processes all upstream providers
     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 -> UpstreamProvider (which provider to use for each alias)
+    2. provider_map: alias -> List[UpstreamProvider] (sorted list of providers for each alias)
     3. unique_models: base_id -> Model (unique models without provider prefixes)
 
     The algorithm:
     - Processes non-OpenRouter providers first (they're typically cheaper)
     - Then processes OpenRouter models (they can still win if cheaper)
-    - For each model alias, uses should_prefer_model() to select the best provider
+    - For each model alias, collects all candidates and sorts them by priority and cost.
 
     Args:
         upstreams: List of all upstream provider instances
@@ -183,15 +116,34 @@ def create_model_mappings(
     from .payment.models import _row_to_model
     from .upstream.helpers import resolve_model_alias
 
-    model_instances: dict[str, "Model"] = {}
-    provider_map: dict[str, "BaseUpstreamProvider"] = {}
+    candidates: dict[str, list[tuple["Model", "BaseUpstreamProvider"]]] = {}
     unique_models: dict[str, "Model"] = {}
+    seen_model_provider: set[tuple[str, str]] = set()
+
+    providers_by_db_id: dict[int, "BaseUpstreamProvider"] = {}
+    for upstream in upstreams:
+        db_id = getattr(upstream, "db_id", None)
+        if isinstance(db_id, int):
+            providers_by_db_id[db_id] = upstream
+
+    # Group upstreams by URL and keep only the one with the lowest fee for each URL
+    upstreams_by_url: dict[str, list["BaseUpstreamProvider"]] = {}
+    for upstream in upstreams:
+        url = getattr(upstream, "base_url", "")
+        if url not in upstreams_by_url:
+            upstreams_by_url[url] = []
+        upstreams_by_url[url].append(upstream)
+
+    filtered_upstreams: list["BaseUpstreamProvider"] = []
+    for providers in upstreams_by_url.values():
+        best_provider = min(providers, key=lambda p: p.provider_fee)
+        filtered_upstreams.append(best_provider)
 
     # Separate OpenRouter from other providers
     openrouter: "BaseUpstreamProvider" | None = None
     other_upstreams: list["BaseUpstreamProvider"] = []
 
-    for upstream in upstreams:
+    for upstream in filtered_upstreams:
         base_url = getattr(upstream, "base_url", "")
         if base_url == "https://openrouter.ai/api/v1":
             openrouter = upstream
@@ -202,30 +154,31 @@ def create_model_mappings(
         """Get base model ID by removing provider prefix."""
         return model_id.split("/", 1)[1] if "/" in model_id else model_id
 
-    def _maybe_set_alias(
+    def get_provider_identity(upstream: "BaseUpstreamProvider") -> str:
+        """Get a stable provider identity used for deduplication."""
+        db_id = getattr(upstream, "db_id", None)
+        if isinstance(db_id, int):
+            return f"db:{db_id}"
+
+        provider_type = str(getattr(upstream, "provider_type", "") or "").lower()
+        base_url = str(getattr(upstream, "base_url", "") or "").lower()
+        return f"{provider_type}|{base_url}"
+
+    def _add_candidate(
         alias: str, model: "Model", provider: "BaseUpstreamProvider"
     ) -> None:
-        """Set alias to model/provider if not set or if new model is preferred."""
+        """Add candidate model/provider for an alias."""
         alias_lower = alias.lower()
-        existing_model = model_instances.get(alias_lower)
-        if not existing_model:
-            # No existing mapping, set it
-            model_instances[alias_lower] = model
-            provider_map[alias_lower] = provider
-        else:
-            # Check if candidate should replace existing
-            existing_provider = provider_map[alias_lower]
-            if should_prefer_model(
-                model, provider, existing_model, existing_provider, alias
-            ):
-                model_instances[alias_lower] = model
-                provider_map[alias_lower] = provider
+        if alias_lower not in candidates:
+            candidates[alias_lower] = []
+        candidates[alias_lower].append((model, provider))
 
     def process_provider_models(
         upstream: "BaseUpstreamProvider", is_openrouter: bool = False
     ) -> None:
         """Process all models from a given provider."""
         upstream_prefix = getattr(upstream, "upstream_name", None)
+        provider_key = get_provider_identity(upstream)
 
         for model in upstream.get_cached_models():
             if not model.enabled or model.id in disabled_model_ids:
@@ -264,23 +217,145 @@ def create_model_mappings(
                 if prefixed_id not in aliases:
                     aliases.append(prefixed_id)
 
+            # Register forwarded_model_id as a routable alias
+            if model_to_use.forwarded_model_id and model_to_use.forwarded_model_id not in aliases:
+                aliases.append(model_to_use.forwarded_model_id)
+
             # Try to set each alias
             for alias in aliases:
-                _maybe_set_alias(alias, model_to_use, upstream)
+                _add_candidate(alias, model_to_use, upstream)
+            seen_model_provider.add((model_to_use.id.lower(), provider_key))
 
-    # Process non-OpenRouter providers first (they're typically cheaper)
+    # Process non-OpenRouter providers first
     for upstream in other_upstreams:
         process_provider_models(upstream, is_openrouter=False)
 
-    # Process OpenRouter last - models only win if they're cheaper or better matched
+    # Process OpenRouter last
     if openrouter:
         process_provider_models(openrouter, is_openrouter=True)
 
-    # Log provider distribution
+    # 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:
+            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:
+            continue
+
+        provider_key = get_provider_identity(upstream_for_override)
+        dedupe_key = (model_id.lower(), provider_key)
+        if dedupe_key in seen_model_provider:
+            continue
+
+        try:
+            model_to_use = _row_to_model(
+                override_row, apply_provider_fee=True, provider_fee=provider_fee
+            )
+        except Exception as exc:
+            logger.warning(
+                "Skipping invalid model override while building model mappings",
+                extra={
+                    "model_id": model_id,
+                    "upstream_provider_id": upstream_provider_id,
+                    "error": str(exc),
+                    "error_type": type(exc).__name__,
+                },
+            )
+            continue
+        if not model_to_use.enabled:
+            continue
+
+        base_id = get_base_model_id(model_to_use.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:
+            unique_model = model_to_use.copy(
+                update={
+                    "id": base_id,
+                    "upstream_provider_id": upstream_for_override.provider_type,
+                }
+            )
+            unique_models[base_id] = unique_model
+
+        try:
+            aliases = resolve_model_alias(
+                model_to_use.id,
+                model_to_use.canonical_slug,
+                alias_ids=model_to_use.alias_ids,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Skipping model aliases for invalid override model",
+                extra={
+                    "model_id": model_id,
+                    "upstream_provider_id": upstream_provider_id,
+                    "error": str(exc),
+                    "error_type": type(exc).__name__,
+                },
+            )
+            continue
+
+        upstream_prefix = getattr(upstream_for_override, "upstream_name", None)
+        if upstream_prefix and "/" not in model_to_use.id:
+            prefixed_id = f"{upstream_prefix}/{model_to_use.id}"
+            if prefixed_id not in aliases:
+                aliases.append(prefixed_id)
+
+        # Register forwarded_model_id as a routable alias
+        if model_to_use.forwarded_model_id and model_to_use.forwarded_model_id not in aliases:
+            aliases.append(model_to_use.forwarded_model_id)
+
+        for alias in aliases:
+            _add_candidate(alias, model_to_use, upstream_for_override)
+        seen_model_provider.add(dedupe_key)
+
+    # Sort candidates and build final maps
+    model_instances: dict[str, "Model"] = {}
+    provider_map: dict[str, list["BaseUpstreamProvider"]] = {}
+
+    def alias_priority(model: "Model", alias: str) -> int:
+        """Rank how strong the mapping of alias->model is."""
+        model_base = get_base_model_id(model.id)
+        if model_base == alias:
+            return 3
+        if model.canonical_slug:
+            canonical_base = get_base_model_id(model.canonical_slug)
+            if canonical_base == alias:
+                return 2
+        return 1
+
+    for alias, items in candidates.items():
+        # Sort key: (priority DESC, cost ASC)
+        # Using negative cost for DESC sort overall to keep high priority first
+        def sort_key(item: tuple["Model", "BaseUpstreamProvider"]) -> tuple[int, float]:
+            model, provider = item
+            priority = alias_priority(model, alias)
+            cost = calculate_model_cost_score(model)
+            penalty = get_provider_penalty(provider)
+            adjusted_cost = cost * penalty
+            return (priority, -adjusted_cost)
+
+        items.sort(key=sort_key, reverse=True)
+
+        best_model, best_provider = items[0]
+        model_instances[alias] = best_model
+        provider_map[alias] = [p for _, p in items]
+
+    # Log provider distribution (using top provider for stats)
     provider_counts: dict[str, int] = {}
-    for provider in provider_map.values():
-        provider_name = getattr(provider, "upstream_name", "unknown")
-        provider_counts[provider_name] = provider_counts.get(provider_name, 0) + 1
+    for providers in provider_map.values():
+        if providers:
+            provider = providers[0]
+            provider_name = getattr(provider, "upstream_name", "unknown")
+            provider_counts[provider_name] = provider_counts.get(provider_name, 0) + 1
 
     logger.debug(
         f"Updated model mappings with ({len(unique_models)} unique models and {len(model_instances)} aliases)",

routstr/balance.py

@@ -1,13 +1,22 @@
 import asyncio
 import hashlib
+import time
 from time import monotonic
 from typing import Annotated, NoReturn
 
 from fastapi import APIRouter, Depends, Header, HTTPException
+from fastapi.responses import JSONResponse
 from pydantic import BaseModel
+from sqlmodel import col, select, update
 
-from .auth import validate_bearer_key
-from .core.db import ApiKey, AsyncSession, get_session
+from .auth import get_billing_key, validate_bearer_key
+from .core.db import (
+    ApiKey,
+    AsyncSession,
+    CashuTransaction,
+    get_session,
+    store_cashu_transaction,
+)
 from .core.logging import get_logger
 from .core.settings import settings
 from .lightning import lightning_router
@@ -32,14 +41,49 @@ async def get_key_from_header(
     )
 
 
+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,
+        "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,
+        "balance_limit_reset": key.balance_limit_reset,
+        "validity_date": key.validity_date,
+    }
+
+    if not key.parent_key_hash:
+        # 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)
+        child_keys = results.all()
+        if child_keys:
+            info["child_keys"] = [
+                {
+                    "api_key": "sk-" + ck.hashed_key,
+                    "total_requests": ck.total_requests,
+                    "total_spent": ck.total_spent,
+                    "balance_limit": ck.balance_limit,
+                    "balance_limit_reset": ck.balance_limit_reset,
+                    "validity_date": ck.validity_date,
+                }
+                for ck in child_keys
+            ]
+
+    return info
+
+
 # TODO: remove this endpoint when frontend is updated
 @router.get("/", include_in_schema=False)
-async def account_info(key: ApiKey = Depends(get_key_from_header)) -> dict:
-    return {
-        "api_key": "sk-" + key.hashed_key,
-        "balance": key.balance,
-        "reserved": key.reserved_balance,
-    }
+async def account_info(
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    return await get_balance_info(key, session)
 
 
 # TODO: Implement POST /v1/wallet/create endpoint
@@ -56,9 +100,24 @@ async def account_info(key: ApiKey = Depends(get_key_from_header)) -> dict:
 
 @router.get("/create")
 async def create_balance(
-    initial_balance_token: str, session: AsyncSession = Depends(get_session)
+    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:
     key = await validate_bearer_key(initial_balance_token, session)
+
+    if balance_limit is not None or balance_limit_reset or validity_date:
+        key.balance_limit = balance_limit
+        key.balance_limit_reset = balance_limit_reset
+        key.validity_date = validity_date
+        if balance_limit_reset:
+            key.balance_limit_reset_date = int(time.time())
+        session.add(key)
+        await session.commit()
+        await session.refresh(key)
+
     return {
         "api_key": "sk-" + key.hashed_key,
         "balance": key.balance,
@@ -66,12 +125,11 @@ async def create_balance(
 
 
 @router.get("/info")
-async def wallet_info(key: ApiKey = Depends(get_key_from_header)) -> dict:
-    return {
-        "api_key": "sk-" + key.hashed_key,
-        "balance": key.balance,
-        "reserved": key.reserved_balance,
-    }
+async def wallet_info(
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    return await get_balance_info(key, session)
 
 
 class TopupRequest(BaseModel):
@@ -85,6 +143,8 @@ async def topup_wallet_endpoint(
     key: ApiKey = Depends(get_key_from_header),
     session: AsyncSession = Depends(get_session),
 ) -> dict[str, int]:
+    billing_key = await get_billing_key(key, session)
+
     if topup_request is not None:
         cashu_token = topup_request.cashu_token
     if cashu_token is None:
@@ -94,16 +154,30 @@ async def topup_wallet_endpoint(
     if len(cashu_token) < 10 or "cashu" not in cashu_token:
         raise HTTPException(status_code=400, detail="Invalid token format")
     try:
-        amount_msats = await credit_balance(cashu_token, key, session)
+        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="Failed to redeem token")
-    except Exception:
+            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__},
+        )
         raise HTTPException(status_code=500, detail="Internal server error")
     return {"msats": amount_msats}
 
@@ -137,24 +211,95 @@ async def _refund_cache_set(authorization: str, value: dict[str, str]) -> None:
         _refund_cache[key] = (expiry, value)
 
 
-@router.post("/refund")
+async def _restore_balance(
+    session: AsyncSession, hashed_key: str, balance: int, reserved_balance: int
+) -> None:
+    """Restore balance after a failed refund mint attempt."""
+    restore_stmt = (
+        update(ApiKey)
+        .where(col(ApiKey.hashed_key) == hashed_key)
+        .values(
+            balance=col(ApiKey.balance) + balance,
+            reserved_balance=col(ApiKey.reserved_balance) + reserved_balance,
+        )
+    )
+    await session.exec(restore_stmt)  # type: ignore[call-overload]
+    await session.commit()
+    logger.info(
+        "refund_wallet_endpoint: balance restored after mint failure",
+        extra={"hashed_key": hashed_key, "restored_balance": balance},
+    )
+
+
+@router.post("/refund", response_model=None)
 async def refund_wallet_endpoint(
-    authorization: Annotated[str, Header(...)],
+    authorization: Annotated[str | None, Header()] = None,
+    x_cashu: Annotated[str | None, Header()] = None,
     session: AsyncSession = Depends(get_session),
-) -> dict[str, str]:
-    if not authorization.startswith("Bearer "):
+) -> JSONResponse | dict[str, str]:
+    if x_cashu:
+        # Find the "in" transaction by the original payment token
+        in_tx_result = await session.exec(
+            select(CashuTransaction).where(
+                CashuTransaction.token == x_cashu,
+                CashuTransaction.type == "in",
+            )
+        )
+        in_tx = in_tx_result.first()
+        if in_tx is None:
+            raise HTTPException(status_code=404, detail="Refund not found")
+
+        # Use the request_id to find the associated "out" (refund) transaction
+        if in_tx.request_id is None:
+            raise HTTPException(status_code=404, detail="Refund not found")
+
+        out_tx_result = await session.exec(
+            select(CashuTransaction).where(
+                CashuTransaction.request_id == in_tx.request_id,
+                CashuTransaction.type == "out",
+            )
+        )
+        out_tx = out_tx_result.first()
+        if out_tx is None:
+            raise HTTPException(status_code=404, detail="Refund not found")
+        if out_tx.swept:
+            raise HTTPException(status_code=410, detail="Refund has been swept")
+
+        out_tx.collected = True
+        session.add(out_tx)
+        await session.commit()
+        body: dict[str, str] = {"token": out_tx.token}
+        if out_tx.unit == "sat":
+            body["sats"] = str(out_tx.amount)
+        else:
+            body["msats"] = str(out_tx.amount)
+        return JSONResponse(content=body, headers={"X-Cashu": out_tx.token})
+
+    if authorization is None or not authorization.startswith("Bearer "):
         raise HTTPException(
             status_code=401,
             detail="Invalid authorization. Use 'Bearer <cashu-token>' or 'Bearer <api-key>'",
         )
 
     bearer_value: str = authorization[7:]
-
-    if cached := await _refund_cache_get(bearer_value):
-        return cached
-
     key: ApiKey = await validate_bearer_key(bearer_value, session)
 
+    if key.total_balance <= 0:
+        if cached := await _refund_cache_get(bearer_value):
+            return cached
+
+    if key.parent_key_hash:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot refund child key. Please refund the parent key instead.",
+        )
+
+    if key.reserved_balance > 0:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot refund key. There are ongoing requests for this api key.",
+        )
+
     remaining_balance_msats: int = key.total_balance
 
     if key.refund_currency == "sat":
@@ -167,7 +312,31 @@ async def refund_wallet_endpoint(
     elif remaining_balance <= 0:
         raise HTTPException(status_code=400, detail="No balance to refund")
 
-    # Perform refund operation first, before modifying balance
+    # Capture values before debit — the session may refresh key after commit
+    pre_debit_balance = key.balance
+    pre_debit_reserved = key.reserved_balance
+
+    # --- DEBIT FIRST: atomically zero the balance before minting tokens ---
+    # This prevents the race where a concurrent topup/spend happens between
+    # reading the balance and minting the refund token (double-spend).
+    debit_stmt = (
+        update(ApiKey)
+        .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)
+    )
+    debit_result = await session.exec(debit_stmt)  # type: ignore[call-overload]
+    await session.commit()
+
+    if debit_result.rowcount == 0:
+        # Balance changed between read and debit — another request is active
+        raise HTTPException(
+            status_code=409,
+            detail="Balance changed concurrently. Please retry the refund.",
+        )
+
+    # --- MINT: balance is locked at zero, safe to create the refund token ---
     try:
         if key.refund_address:
             from .core.settings import settings as global_settings
@@ -191,11 +360,24 @@ async def refund_wallet_endpoint(
         else:
             result["msats"] = str(remaining_balance_msats)
 
+        if "token" in result:
+            logger.info(
+                "refund_wallet_endpoint: cashu token issued",
+                extra={
+                    "path": "/v1/wallet/refund",
+                    "token": result["token"],
+                    "amount": remaining_balance,
+                    "currency": key.refund_currency or "sat",
+                },
+            )
+
     except HTTPException:
-        # Re-raise HTTP exceptions (like 400 for balance too small)
+        # Minting failed — restore the debited balance
+        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved)
         raise
     except Exception as e:
-        # If refund fails, don't modify the database
+        # Minting failed — restore the debited balance
+        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved)
         error_msg = str(e)
         if (
             "mint" in error_msg.lower()
@@ -209,12 +391,67 @@ async def refund_wallet_endpoint(
 
     await _refund_cache_set(bearer_value, result)
 
-    await session.delete(key)
-    await session.commit()
+    if "token" in result:
+        try:
+            await store_cashu_transaction(
+                token=result["token"],
+                amount=remaining_balance,
+                unit=key.refund_currency or "sat",
+                mint_url=key.refund_mint_url,
+                typ="out",
+                collected=False,
+                source="apikey",
+                api_key_hashed_key=key.hashed_key,
+            )
+        except Exception:
+            pass  # store_cashu_transaction already logs
+
+    logger.info(
+        "refund_wallet_endpoint: refund successful",
+        extra={
+            "refunded_msats": remaining_balance_msats,
+            "previous_reserved_balance": key.reserved_balance,
+        },
+    )
 
     return result
 
 
+@router.get("/history")
+async def wallet_history(
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict[str, list[dict[str, str | int | bool | None]]]:
+    if key.parent_key_hash:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot view child key history. Please use the parent key instead.",
+        )
+
+    result = await session.exec(
+        select(CashuTransaction)
+        .where(CashuTransaction.api_key_hashed_key == key.hashed_key)
+        .order_by(col(CashuTransaction.created_at).desc())
+    )
+    transactions = result.all()
+    return {
+        "transactions": [
+            {
+                "id": tx.id,
+                "type": tx.type,
+                "source": tx.source,
+                "amount": tx.amount,
+                "unit": tx.unit,
+                "mint_url": tx.mint_url,
+                "created_at": tx.created_at,
+                "collected": tx.collected,
+                "swept": tx.swept,
+            }
+            for tx in transactions
+        ]
+    }
+
+
 @router.post("/donate")
 async def donate(token: str, ref: str | None = None) -> str:
     try:
@@ -228,6 +465,138 @@ async def donate(token: str, ref: str | None = None) -> str:
         return "Invalid token."
 
 
+class ChildKeyRequest(BaseModel):
+    count: int
+    balance_limit: int | None = None
+    balance_limit_reset: str | None = None
+    validity_date: int | None = None
+
+
+@router.post("/child-key")
+async def create_child_key(
+    payload: ChildKeyRequest,
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    """Creates one or more child API keys that use the parent's balance."""
+    # Log incoming request for debugging
+    logger.debug(f"Child key creation request: count={payload.count}")
+
+    count = payload.count
+    if count < 1 or count > 50:
+        raise HTTPException(status_code=400, detail="Count must be between 1 and 50.")
+
+    # Check if this is already a child key
+    if key.parent_key_hash:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot create a child key for another child key.",
+        )
+
+    cost_per_key = settings.child_key_cost
+    total_cost = cost_per_key * count
+
+    if key.total_balance < total_cost:
+        raise HTTPException(
+            status_code=402,
+            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)
+
+    # Generate new keys
+    import secrets
+
+    new_keys = []
+    for _ in range(count):
+        new_key_raw = secrets.token_hex(32)
+        new_key_hash = new_key_raw  # We use the raw key as the hash for sk- keys
+
+        child_key = ApiKey(
+            hashed_key=new_key_hash,
+            balance=0,
+            parent_key_hash=key.hashed_key,
+            balance_limit=payload.balance_limit,
+            balance_limit_reset=payload.balance_limit_reset,
+            balance_limit_reset_date=int(time.time())
+            if payload.balance_limit_reset
+            else None,
+            validity_date=payload.validity_date,
+        )
+        session.add(child_key)
+        new_keys.append("sk-" + new_key_hash)
+
+    await session.commit()
+
+    response_data = {
+        "api_keys": new_keys,
+        "count": count,
+        "cost_msats": total_cost,
+        "cost_sats": total_cost // 1000,
+        "parent_balance": key.balance,
+        "parent_balance_sats": key.balance // 1000,
+    }
+    logger.debug(f"Child key creation response: {response_data}")
+    return response_data
+
+
+class ChildKeyResetRequest(BaseModel):
+    child_key: str
+
+
+@router.post("/child-key/reset")
+async def reset_child_key_spent(
+    payload: ChildKeyResetRequest,
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    """Resets the total_spent of a child key. Must be called by the parent."""
+    child_key_raw = payload.child_key
+    if child_key_raw.startswith("sk-"):
+        child_key_raw = child_key_raw[3:]
+
+    child_key = await session.get(ApiKey, child_key_raw)
+    if not child_key:
+        raise HTTPException(status_code=404, detail="Child key not found.")
+
+    if child_key.parent_key_hash != key.hashed_key:
+        raise HTTPException(
+            status_code=403, detail="Unauthorized. You are not the parent of this key."
+        )
+
+    child_key.total_spent = 0
+    if child_key.balance_limit_reset:
+        child_key.balance_limit_reset_date = int(time.time())
+    session.add(child_key)
+    await session.commit()
+
+    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"],

routstr/core/db.py

@@ -1,12 +1,18 @@
 import os
+import pathlib
+import sqlite3
 import time
+import uuid
 from contextlib import asynccontextmanager
 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.ext.asyncio.engine import create_async_engine
-from sqlmodel import Field, Relationship, SQLModel, func, select, update
+from sqlmodel import Field, Relationship, SQLModel, col, func, select, update
 from sqlmodel.ext.asyncio.session import AsyncSession
 
 from .logging import get_logger
@@ -47,6 +53,25 @@ class ApiKey(SQLModel, table=True):  # type: ignore
         default=None,
         description="Currency of the cashu-token",
     )
+    parent_key_hash: str | None = Field(
+        default=None, foreign_key="api_keys.hashed_key", index=True
+    )
+    balance_limit: int | None = Field(
+        default=None,
+        description="Max spendable balance in msats for this key (mostly for child keys)",
+    )
+    balance_limit_reset: str | None = Field(
+        default=None,
+        description="Reset policy for balance limit (manual, daily, monthly, etc.)",
+    )
+    balance_limit_reset_date: int | None = Field(
+        default=None,
+        description="Unix timestamp of the last time the balance limit was reset",
+    )
+    validity_date: int | None = Field(
+        default=None,
+        description="Unix timestamp after which the key is no longer valid",
+    )
 
     @property
     def total_balance(self) -> int:
@@ -81,6 +106,10 @@ class ModelRow(SQLModel, table=True):  # type: ignore
         default=None, description="JSON array of model alias IDs"
     )
     enabled: bool = Field(default=True, description="Whether this model is enabled")
+    forwarded_model_id: str | None = Field(
+        default=None,
+        description="Model ID to use when forwarding requests to upstream provider. Defaults to id if not set.",
+    )
     upstream_provider: "UpstreamProviderRow" = Relationship(back_populates="models")
 
 
@@ -106,20 +135,101 @@ class LightningInvoice(SQLModel, table=True):  # type: ignore
     paid_at: int | None = Field(default=None, description="Unix timestamp when paid")
 
 
+class CashuTransaction(SQLModel, table=True):  # type: ignore
+    __tablename__ = "cashu_transactions"
+
+    id: str = Field(
+        primary_key=True,
+        default_factory=lambda: uuid.uuid4().hex,
+        description="Unique transaction identifier",
+    )
+    token: str = Field(description="Serialized Cashu token")
+    amount: int = Field(description="Amount in the token's unit")
+    unit: str = Field(description="Token unit (sat or msat)")
+    mint_url: str | None = Field(default=None, description="Mint URL for the token")
+    type: str = Field(default="out", description="Transaction type: in or out")
+    request_id: str | None = Field(default=None, description="Associated request ID")
+    created_at: int = Field(
+        default_factory=lambda: int(time.time()),
+        description="Unix timestamp",
+    )
+    collected: bool = Field(default=False)
+    swept: bool = Field(default=False)
+    source: str = Field(
+        default="x-cashu",
+        description="Payment source: x-cashu or apikey",
+    )
+    api_key_hashed_key: str | None = Field(
+        default=None,
+        foreign_key="api_keys.hashed_key",
+        index=True,
+        description="Associated API key hash for wallet history",
+    )
+
+
+async def store_cashu_transaction(
+    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,
+) -> None:
+    try:
+        async with create_session() as session:
+            tx = CashuTransaction(
+                token=token,
+                amount=amount,
+                unit=unit,
+                mint_url=mint_url,
+                type=typ,
+                request_id=request_id,
+                collected=collected,
+                created_at=created_at or int(time.time()),
+                source=source,
+                api_key_hashed_key=api_key_hashed_key,
+            )
+            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},
+        )
+
+
 class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
     __tablename__ = "upstream_providers"
+    __table_args__ = (
+        UniqueConstraint(
+            "base_url", "api_key", name="uq_upstream_providers_base_url_api_key"
+        ),
+    )
     id: int | None = Field(default=None, primary_key=True)
     provider_type: str = Field(
         description="Provider type: custom, openai, anthropic, azure, openrouter, etc."
     )
-    base_url: str = Field(unique=True, description="Base URL of the upstream API")
+    base_url: str = Field(description="Base URL of the upstream API")
     api_key: str = Field(description="API key for the upstream provider")
     api_version: str | None = Field(
         default=None, description="API version for Azure OpenAI"
     )
     enabled: bool = Field(default=True, description="Whether this provider is enabled")
     provider_fee: float = Field(
-        default=1.01, description="Provider fee multiplier (default 1%)"
+        default=1.01, description="Active fee multiplier (can be set by schedule)"
+    )
+    provider_fee_default: float = Field(
+        default=1.01, description="Default fee multiplier (outside schedules)"
+    )
+    provider_settings: str | None = Field(
+        default=None, description="JSON string for provider-specific settings"
+    )
+    provider_fee_schedules: str | None = Field(
+        default=None, description="JSON array of fee time ranges (HH:MM UTC)"
     )
     models: list["ModelRow"] = Relationship(
         back_populates="upstream_provider",
@@ -127,6 +237,66 @@ class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
     )
 
 
+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)
+
+
+class CliToken(SQLModel, table=True):  # type: ignore
+    """Long-lived authorization token for CLI/agent use against admin endpoints."""
+
+    __tablename__ = "cli_tokens"
+    id: str = Field(
+        primary_key=True, default_factory=lambda: uuid.uuid4().hex
+    )
+    token: str = Field(unique=True, index=True, description="Bearer token value")
+    name: str = Field(description="Human-readable label for this token")
+    created_at: int = Field(default_factory=lambda: int(time.time()))
+    last_used_at: int | None = Field(default=None)
+    expires_at: int | None = Field(
+        default=None, description="Optional expiry unix timestamp; null = never expires"
+    )
+
+
+async def accumulate_routstr_fee(session: AsyncSession, amount_msats: int) -> None:
+    stmt = (
+        update(RoutstrFee)
+        .where(col(RoutstrFee.id) == 1)
+        .values(accumulated_msats=RoutstrFee.accumulated_msats + amount_msats)
+    )
+    result = await session.exec(stmt)  # type: ignore[call-overload]
+    if result.rowcount == 0:
+        session.add(RoutstrFee(id=1, accumulated_msats=amount_msats))
+    await session.commit()
+
+
+async def get_routstr_fee(session: AsyncSession) -> RoutstrFee:
+    fee = await session.get(RoutstrFee, 1)
+    if fee is None:
+        fee = RoutstrFee(id=1, accumulated_msats=0, total_paid_msats=0)
+        session.add(fee)
+        await session.commit()
+        await session.refresh(fee)
+    return fee
+
+
+async def reset_routstr_fee(session: AsyncSession, paid_msats: int) -> None:
+    stmt = (
+        update(RoutstrFee)
+        .where(col(RoutstrFee.id) == 1)
+        .values(
+            accumulated_msats=RoutstrFee.accumulated_msats - paid_msats,
+            total_paid_msats=RoutstrFee.total_paid_msats + paid_msats,
+            last_paid_at=int(time.time()),
+        )
+    )
+    await session.exec(stmt)  # type: ignore[call-overload]
+    await session.commit()
+
+
 async def balances_for_mint_and_unit(
     db_session: AsyncSession, mint_url: str, unit: str
 ) -> int:
@@ -156,11 +326,64 @@ async def create_session() -> AsyncGenerator[AsyncSession, None]:
         yield session
 
 
+def fix_cashu_migrations() -> None:
+    """
+    Fixes Cashu wallet migrations that are not idempotent.
+    This specifically addresses the 'duplicate column name: public_keys' error
+    in the keysets table of Cashu's internal SQLite databases.
+    """
+    project_root = pathlib.Path(__file__).resolve().parents[2]
+    wallet_dir = project_root / ".wallet"
+
+    if not wallet_dir.exists() or not wallet_dir.is_dir():
+        return
+
+    logger.info("Checking Cashu wallet databases for migration idempotency")
+
+    for db_file in wallet_dir.glob("*.sqlite3"):
+        try:
+            conn = sqlite3.connect(db_file)
+            cursor = conn.cursor()
+
+            # Check if keysets table exists
+            cursor.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='keysets'"
+            )
+            if not cursor.fetchone():
+                conn.close()
+                continue
+
+            # Check if public_keys column exists
+            cursor.execute("PRAGMA table_info(keysets)")
+            columns = [info[1] for info in cursor.fetchall()]
+
+            if "public_keys" not in columns:
+                logger.info(f"Adding missing public_keys column to {db_file.name}")
+                cursor.execute("ALTER TABLE keysets ADD COLUMN public_keys TEXT")
+                conn.commit()
+
+            conn.close()
+        except Exception as e:
+            logger.warning(f"Could not check/fix Cashu database {db_file}: {e}")
+
+
+def _clear_alembic_version() -> None:
+    """Clear the alembic_version table so stamp/upgrade can proceed."""
+    sync_url = DATABASE_URL.replace("+aiosqlite", "")
+    from sqlalchemy import create_engine, text
+
+    eng = create_engine(sync_url)
+    with eng.begin() as conn:
+        conn.execute(text("DELETE FROM alembic_version"))
+    eng.dispose()
+
+
 def run_migrations() -> None:
     """Run Alembic migrations programmatically."""
-    import pathlib
-
     try:
+        # Run Cashu migration fix first
+        fix_cashu_migrations()
+
         # Get the path to the alembic.ini file
         project_root = pathlib.Path(__file__).resolve().parents[2]
         alembic_ini_path = project_root / "alembic.ini"
@@ -176,8 +399,30 @@ def run_migrations() -> None:
         # Set the database URL in the config
         alembic_cfg.set_main_option("sqlalchemy.url", DATABASE_URL)
 
-        # Run migrations to the latest revision
-        command.upgrade(alembic_cfg, "head")
+        try:
+            command.upgrade(alembic_cfg, "head")
+        except CommandError as e:
+            if "Can't locate revision" in str(e):
+                logger.warning(
+                    "Database stamped with unknown revision (likely from another branch). "
+                    "Re-stamping to current head.",
+                    extra={"error": str(e)},
+                )
+                _clear_alembic_version()
+                command.stamp(alembic_cfg, "head")
+            else:
+                raise
+        except OperationalError as e:
+            if "duplicate column name" in str(e).lower():
+                logger.warning(
+                    "Migration hit a column that already exists (likely added via "
+                    "create_all on another branch). Stamping to current head.",
+                    extra={"error": str(e)},
+                )
+                _clear_alembic_version()
+                command.stamp(alembic_cfg, "head")
+            else:
+                raise
 
         logger.info("Database migrations completed successfully")
 

routstr/core/exceptions.py

@@ -6,6 +6,15 @@ from .logging import get_logger
 logger = get_logger(__name__)
 
 
+class UpstreamError(Exception):
+    """Exception raised when an upstream provider fails."""
+
+    def __init__(self, message: str, status_code: int = 502):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
 async def http_exception_handler(request: Request, exc: Exception) -> JSONResponse:
     """Handle HTTP exceptions and include request ID in response."""
     request_id = getattr(request.state, "request_id", "unknown")

routstr/core/logging.py

@@ -3,36 +3,38 @@ Logging configuration for Routstr.
 
 CRITICAL LOG MESSAGES FOR USAGE STATISTICS:
 ===========================================
-The following log messages are parsed by the usage tracking system (routstr/core/admin.py).
+The following log messages are parsed by the usage tracking system
+(routstr/core/usage_analytics_store.py and routstr/core/log_manager.py).
 DO NOT modify or remove these messages without updating the usage tracking logic:
 
 1. "Received proxy request" (INFO) - routstr/proxy.py
    - Used to count total incoming requests
    - Includes model information in context
 
-    2. "Payment adjustment completed for streaming" (INFO) - routstr/upstream/base.py
-       "Payment adjustment completed for non-streaming" (INFO) - routstr/upstream/base.py
+2. "Calculated token-based cost" (INFO) - routstr/auth.py
    - Used to track successful completions and revenue
-   - The 'cost_data.total_msats' field is extracted for revenue calculation
-   - Must include 'cost_data' in extra dict
+   - The 'token_cost', 'model', 'input_tokens', and 'output_tokens' fields are extracted for dashboard metrics
 
-3. "Payment processed successfully" (INFO) - routstr/auth.py
+3. "Max cost payment finalized" (INFO) - routstr/auth.py
+   - Used as the successful completion fallback when token usage is unavailable
+   - The 'charged_amount', 'model', 'input_tokens', and 'output_tokens' fields are extracted for dashboard metrics
+
+4. "Payment processed successfully" (INFO) - routstr/auth.py
    - Used to count successful payment processing events
    - Tracks payment-related metrics
 
-4. "Upstream request failed, revert payment" (WARNING) - routstr/proxy.py
+5. "Upstream request failed, revert payment" (WARNING) - routstr/proxy.py
    - Used to track failed requests and refunds
    - The 'max_cost_for_model' field is extracted for refund calculation
    - Must include 'max_cost_for_model' in extra dict
 
-5. Any ERROR level logs with "upstream" in the message
+6. Any ERROR level logs with "upstream" in the message
    - Used to count upstream provider errors
    - Helps identify service reliability issues
 
 If you need to modify these messages, ensure you also update the parsing logic in:
-- routstr/core/admin.py:_aggregate_metrics_by_time()
-- routstr/core/admin.py:_get_summary_stats()
-- routstr/core/admin.py:get_revenue_by_model()
+- routstr/core/usage_analytics_store.py
+- routstr/core/log_manager.py
 """
 
 import logging.config

routstr/core/main.py

@@ -10,16 +10,19 @@ from fastapi.responses import FileResponse, RedirectResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.exceptions import HTTPException
 
+from ..auth import periodic_key_reset
 from ..balance import balance_router, deprecated_wallet_router
-from ..discovery import providers_cache_refresher, providers_router
-from ..nip91 import announce_provider
-from ..payment.models import (
-    models_router,
-    update_sats_pricing,
+from ..nostr import (
+    announce_provider,
+    providers_cache_refresher,
+    publish_usage_analytics,
 )
+from ..nostr.discovery import providers_router
+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 ..wallet import periodic_payout
+from ..upstream.auto_topup import periodic_auto_topup
+from ..wallet import periodic_payout, periodic_refund_sweep, periodic_routstr_fee_payout
 from .admin import admin_router
 from .db import create_session, init_db, run_migrations
 from .exceptions import general_exception_handler, http_exception_handler
@@ -33,9 +36,9 @@ setup_logging()
 logger = get_logger(__name__)
 
 if os.getenv("VERSION_SUFFIX") is not None:
-    __version__ = f"0.2.2-{os.getenv('VERSION_SUFFIX')}"
+    __version__ = f"0.4.3-{os.getenv('VERSION_SUFFIX')}"
 else:
-    __version__ = "0.2.2"
+    __version__ = "0.4.3"
 
 
 @asynccontextmanager
@@ -46,9 +49,14 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
     pricing_task = None
     payout_task = None
     nip91_task = None
+    analytics_task = None
     providers_task = None
     models_refresh_task = None
     model_maps_refresh_task = None
+    key_reset_task = None
+    auto_topup_task = None
+    refund_sweep_task = None
+    routstr_fee_task = None
 
     try:
         # Run database migrations on startup
@@ -95,15 +103,23 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
         btc_price_task = asyncio.create_task(update_prices_periodically())
         pricing_task = asyncio.create_task(update_sats_pricing())
         if global_settings.models_refresh_interval_seconds > 0:
+            # Pass the accessor (not its current value) so the loop sees providers
+            # added/changed via reinitialize_upstreams() instead of staying pinned
+            # to the startup snapshot.
             models_refresh_task = asyncio.create_task(
-                refresh_upstreams_models_periodically(get_upstreams())
+                refresh_upstreams_models_periodically(get_upstreams)
             )
         model_maps_refresh_task = asyncio.create_task(refresh_model_maps_periodically())
         payout_task = asyncio.create_task(periodic_payout())
         if global_settings.nsec:
             nip91_task = asyncio.create_task(announce_provider())
+        analytics_task = asyncio.create_task(publish_usage_analytics())
         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())
+        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())
 
         yield
 
@@ -127,12 +143,22 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
             payout_task.cancel()
         if nip91_task is not None:
             nip91_task.cancel()
+        if analytics_task is not None:
+            analytics_task.cancel()
         if providers_task is not None:
             providers_task.cancel()
         if models_refresh_task is not None:
             models_refresh_task.cancel()
         if model_maps_refresh_task is not None:
             model_maps_refresh_task.cancel()
+        if key_reset_task is not None:
+            key_reset_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()
 
         try:
             tasks_to_wait = []
@@ -144,12 +170,22 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
                 tasks_to_wait.append(payout_task)
             if nip91_task is not None:
                 tasks_to_wait.append(nip91_task)
+            if analytics_task is not None:
+                tasks_to_wait.append(analytics_task)
             if providers_task is not None:
                 tasks_to_wait.append(providers_task)
             if models_refresh_task is not None:
                 tasks_to_wait.append(models_refresh_task)
             if model_maps_refresh_task is not None:
                 tasks_to_wait.append(model_maps_refresh_task)
+            if key_reset_task is not None:
+                tasks_to_wait.append(key_reset_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 tasks_to_wait:
                 await asyncio.gather(*tasks_to_wait, return_exceptions=True)
@@ -170,7 +206,7 @@ app.add_middleware(
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],
-    expose_headers=["x-routstr-request-id"],
+    expose_headers=["x-routstr-request-id", "x-cashu"],
 )
 
 # Add logging middleware
@@ -191,6 +227,7 @@ async def info() -> dict:
         "mints": global_settings.cashu_mints,
         "http_url": global_settings.http_url,
         "onion_url": global_settings.onion_url,
+        "child_key_cost_msats": global_settings.child_key_cost,
     }
 
 

routstr/core/middleware.py

@@ -38,11 +38,6 @@ class LoggingMiddleware(BaseHTTPMiddleware):
             except Exception:
                 pass
 
-        # Extract request info
-        client_host = None
-        if request.client:
-            client_host = request.client.host
-
         # Log incoming request
         logger.info(
             "Incoming request",
@@ -51,7 +46,6 @@ class LoggingMiddleware(BaseHTTPMiddleware):
                 "method": request.method,
                 "path": request.url.path,
                 "query_params": dict(request.query_params),
-                "client_host": client_host,
                 "headers": {
                     k: v
                     for k, v in request.headers.items()
@@ -100,7 +94,6 @@ class LoggingMiddleware(BaseHTTPMiddleware):
                     "path": request.url.path,
                     "status_code": response.status_code,
                     "duration_ms": round(duration * 1000, 2),
-                    "client_host": client_host,
                 },
             )
             if hasattr(response, "headers"):
@@ -120,7 +113,6 @@ class LoggingMiddleware(BaseHTTPMiddleware):
                     "method": request.method,
                     "path": request.url.path,
                     "duration_ms": round(duration * 1000, 2),
-                    "client_host": client_host,
                     "error": str(e),
                     "error_type": type(e).__name__,
                 },

routstr/core/settings.py

@@ -52,6 +52,7 @@ class Settings(BaseSettings):
     exchange_fee: float = Field(default=1.005, env="EXCHANGE_FEE")
     upstream_provider_fee: float = Field(default=1.05, env="UPSTREAM_PROVIDER_FEE")
     tolerance_percentage: float = Field(default=1.0, env="TOLERANCE_PERCENTAGE")
+    child_key_cost: int = Field(default=0, env="CHILD_KEY_COST")
     # Minimum per-request charge in millisatoshis when model pricing is free/zero
     min_request_msat: int = Field(default=1, env="MIN_REQUEST_MSAT")
     reset_reserved_balance_on_startup: bool = Field(
@@ -73,6 +74,7 @@ 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")
 
     # Logging
     log_level: str = Field(default="INFO", env="LOG_LEVEL")
@@ -91,6 +93,20 @@ class Settings(BaseSettings):
 
     # Discovery
     relays: list[str] = Field(default_factory=list, env="RELAYS")
+    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."""
+    normalized: dict[str, Any] = {}
+    known_fields = Settings.__fields__
+
+    for key, value in data.items():
+        if key in known_fields:
+            normalized[key] = value
+
+    return normalized
 
 
 def _compute_primary_mint(cashu_mints: list[str]) -> str:
@@ -142,7 +158,7 @@ def resolve_bootstrap() -> Settings:
         pass
     if not base.onion_url:
         try:
-            from ..nip91 import discover_onion_url_from_tor  # type: ignore
+            from ..nostr.listing import discover_onion_url_from_tor  # type: ignore
 
             discovered = discover_onion_url_from_tor()
             if discovered:
@@ -230,16 +246,21 @@ class SettingsService:
 
             db_id, db_data, _updated_at = row
             try:
-                db_json = (
+                db_json_raw = (
                     json.loads(db_data) if isinstance(db_data, str) else dict(db_data)
                 )
+                if not isinstance(db_json_raw, dict):
+                    db_json_raw = {}
             except Exception:
-                db_json = {}
+                db_json_raw = {}
+            db_json = _normalize_settings_data(db_json_raw)
 
+            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, "", [], {})}
+                {k: v for k, v in db_json.items() if v not in (None, "", [], {}) and k in valid_fields}
             )
+            merged_dict = Settings(**merged_dict).dict()
 
             # Ensure primary_mint is consistent with cashu_mints if not explicitly set
             if not merged_dict.get("primary_mint"):
@@ -247,7 +268,7 @@ class SettingsService:
                     merged_dict.get("cashu_mints", [])
                 )
 
-            if any(k not in db_json for k in merged_dict.keys()):
+            if db_json_raw != merged_dict:
                 await db_session.exec(  # type: ignore
                     text(
                         "UPDATE settings SET data = :data, updated_at = :updated_at WHERE id = 1"
@@ -270,7 +291,7 @@ class SettingsService:
     ) -> Settings:
         async with cls._lock:
             current = cls.get()
-            candidate_dict = {**current.dict(), **partial}
+            candidate_dict = {**current.dict(), **_normalize_settings_data(partial)}
             candidate = Settings(**candidate_dict)
             from sqlmodel import text
 
@@ -304,8 +325,10 @@ class SettingsService:
                 raise RuntimeError("Settings row missing")
             (data_str,) = row
             data = json.loads(data_str) if isinstance(data_str, str) else dict(data_str)
+            valid_fields = set(settings.dict().keys())
             # Update in-place
             for k, v in data.items():
-                setattr(settings, k, v)
+                if k in valid_fields:
+                    setattr(settings, k, v)
             cls._current = settings
             return settings

routstr/lightning.py

@@ -23,6 +23,9 @@ class InvoiceCreateRequest(BaseModel):
     api_key: str | None = Field(
         default=None, description="Required for topup operations"
     )
+    balance_limit: int | None = Field(default=None)
+    balance_limit_reset: str | None = Field(default=None)
+    validity_date: int | None = Field(default=None)
 
 
 class InvoiceCreateResponse(BaseModel):
@@ -94,6 +97,9 @@ async def create_invoice(
             status="pending",
             api_key_hash=request.api_key[3:] if request.api_key else None,
             purpose=request.purpose,
+            balance_limit=request.balance_limit,
+            balance_limit_reset=request.balance_limit_reset,
+            validity_date=request.validity_date,
             expires_at=expires_at,
         )
 

routstr/nostr/__init__.py

@@ -0,0 +1,5 @@
+from .analytics import publish_usage_analytics
+from .discovery import providers_cache_refresher
+from .listing import announce_provider
+
+__all__ = ["providers_cache_refresher", "announce_provider", "publish_usage_analytics"]

routstr/nostr/analytics.py

@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+"""
+Nostr usage analytics publisher.
+Publishes a single replaceable analytics snapshot for each provider.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import time
+from typing import Any
+
+from nostr.event import Event
+from nostr.key import PrivateKey
+
+from ..core import get_logger
+from ..core.log_manager import log_manager
+from ..core.settings import settings
+from .listing import nsec_to_keypair, publish_to_relay
+
+logger = get_logger(__name__)
+
+ANALYTICS_KIND = 38422
+ANALYTICS_SCHEMA = "routstr.analytics.snapshot.v1"
+DEFAULT_RELAYS = [
+    "wss://relay.nostr.band",
+    "wss://relay.damus.io",
+    "wss://relay.routstr.com",
+    "wss://nos.lol",
+]
+PUBLISH_INTERVAL_SECONDS = 15 * 60
+DISABLED_POLL_SECONDS = 60
+DASHBOARD_WINDOW_HOURS = 24
+DASHBOARD_INTERVAL_MINUTES = 60
+MODEL_LIMIT = 20
+WINDOW_DEFINITIONS: tuple[tuple[str, int, int], ...] = (
+    ("24h", 24, 60),
+    ("7d", 7 * 24, 6 * 60),
+    ("30d", 30 * 24, 24 * 60),
+    ("3m", 90 * 24, 24 * 60),
+    ("1y", 365 * 24, 7 * 24 * 60),
+)
+
+
+def _event_to_dict(ev: Event) -> dict[str, Any]:
+    return {
+        "id": ev.id,
+        "pubkey": ev.public_key,
+        "created_at": ev.created_at,
+        "kind": int(ev.kind) if not isinstance(ev.kind, int) else ev.kind,
+        "tags": ev.tags,
+        "content": ev.content,
+        "sig": ev.signature,
+    }
+
+
+def _resolve_provider_id(public_key_hex: str) -> str:
+    explicit_provider_id = (settings.provider_id or "").strip()
+    if explicit_provider_id:
+        return explicit_provider_id
+    return public_key_hex[:12]
+
+
+def _resolve_endpoint_urls() -> list[str]:
+    urls: list[str] = []
+    http_url = (settings.http_url or "").strip()
+    onion_url = (settings.onion_url or "").strip()
+
+    if http_url and http_url != "http://localhost:8000":
+        urls.append(http_url)
+
+    if onion_url:
+        if onion_url.endswith(".onion") and not (
+            onion_url.startswith("http://") or onion_url.startswith("https://")
+        ):
+            onion_url = f"http://{onion_url}"
+        urls.append(onion_url)
+
+    return urls
+
+
+def _resolve_relays() -> list[str]:
+    configured = [url.strip() for url in settings.relays if url.strip()]
+    return configured if configured else list(DEFAULT_RELAYS)
+
+
+def _to_int(value: Any) -> int:
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    if isinstance(value, str):
+        try:
+            return int(float(value))
+        except ValueError:
+            return 0
+    return 0
+
+
+def _to_float(value: Any) -> float:
+    if isinstance(value, bool):
+        return float(int(value))
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            return 0.0
+    return 0.0
+
+
+def _aggregate_top_model_usage(
+    model_usage_mix: dict[str, Any],
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    top_models_raw = model_usage_mix.get("top_models", [])
+    mix_metrics_raw = model_usage_mix.get("metrics", [])
+
+    top_models = [model for model in top_models_raw if isinstance(model, str)]
+    metrics = [row for row in mix_metrics_raw if isinstance(row, dict)]
+
+    model_totals: dict[str, dict[str, float | int]] = {
+        model: {
+            "successful_requests": 0,
+            "revenue_msats": 0.0,
+            "total_tokens": 0,
+        }
+        for model in top_models
+    }
+    others = {
+        "successful_requests": 0,
+        "revenue_msats": 0.0,
+        "total_tokens": 0,
+    }
+
+    for metric in metrics:
+        model_counts = metric.get("model_counts", {})
+        model_revenue = metric.get("model_revenue_msats", {})
+        model_tokens = metric.get("model_tokens", {})
+
+        if isinstance(model_counts, dict):
+            for model, count in model_counts.items():
+                if model in model_totals:
+                    model_totals[model]["successful_requests"] += _to_int(count)
+
+        if isinstance(model_revenue, dict):
+            for model, amount in model_revenue.items():
+                if model in model_totals:
+                    model_totals[model]["revenue_msats"] += _to_float(amount)
+
+        if isinstance(model_tokens, dict):
+            for model, token_count in model_tokens.items():
+                if model in model_totals:
+                    model_totals[model]["total_tokens"] += _to_int(token_count)
+
+        others["successful_requests"] += _to_int(metric.get("others", 0))
+        others["revenue_msats"] += _to_float(metric.get("others_revenue_msats", 0.0))
+        others["total_tokens"] += _to_int(metric.get("others_tokens", 0))
+
+    model_rows = [
+        {
+            "model": model,
+            "successful_requests": int(values["successful_requests"]),
+            "revenue_msats": float(values["revenue_msats"]),
+            "total_tokens": int(values["total_tokens"]),
+        }
+        for model, values in model_totals.items()
+    ]
+    model_rows.sort(
+        key=lambda row: _to_int(row.get("successful_requests", 0)),
+        reverse=True,
+    )
+
+    return model_rows, others
+
+
+def _build_summary_payload(summary: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "total_requests": _to_int(summary.get("total_requests", 0)),
+        "successful_chat_completions": _to_int(
+            summary.get("successful_chat_completions", 0)
+        ),
+        "failed_requests": _to_int(summary.get("failed_requests", 0)),
+        "success_rate": _to_float(summary.get("success_rate", 0.0)),
+        "unique_models_count": _to_int(summary.get("unique_models_count", 0)),
+        "input_tokens": _to_int(summary.get("input_tokens", 0)),
+        "output_tokens": _to_int(summary.get("output_tokens", 0)),
+        "total_tokens": _to_int(summary.get("total_tokens", 0)),
+        "revenue_msats": _to_float(summary.get("revenue_msats", 0.0)),
+        "refunds_msats": _to_float(summary.get("refunds_msats", 0.0)),
+        "net_revenue_msats": _to_float(summary.get("net_revenue_msats", 0.0)),
+        "revenue_sats": _to_float(summary.get("revenue_sats", 0.0)),
+        "refunds_sats": _to_float(summary.get("refunds_sats", 0.0)),
+        "net_revenue_sats": _to_float(summary.get("net_revenue_sats", 0.0)),
+    }
+
+
+def _build_window_payload(
+    *,
+    hours: int,
+    interval_minutes: int,
+    model_limit: int,
+) -> dict[str, Any]:
+    dashboard = log_manager.get_usage_dashboard(
+        interval=interval_minutes,
+        hours=hours,
+        error_limit=1,
+        model_limit=model_limit,
+    )
+
+    summary = dashboard.get("summary", {})
+    model_usage_mix = dashboard.get("model_usage_mix", {})
+
+    summary_payload = _build_summary_payload(summary if isinstance(summary, dict) else {})
+    usage_mix_payload = model_usage_mix if isinstance(model_usage_mix, dict) else {}
+    top_model_usage, others_usage = _aggregate_top_model_usage(usage_mix_payload)
+
+    return {
+        "window_hours": hours,
+        "interval_minutes": interval_minutes,
+        "summary": summary_payload,
+        "model_usage_mix": usage_mix_payload,
+        "top_model_usage": top_model_usage,
+        "others_usage": others_usage,
+    }
+
+
+def build_stats_snapshot_payload(
+    provider_id: str,
+    *,
+    public_key_hex: str,
+    generated_at: int,
+    window_hours: int = DASHBOARD_WINDOW_HOURS,
+    interval_minutes: int = DASHBOARD_INTERVAL_MINUTES,
+    model_limit: int = MODEL_LIMIT,
+) -> dict[str, Any]:
+    _ = (window_hours, interval_minutes)
+    windows: dict[str, dict[str, Any]] = {}
+    for key, hours, window_interval_minutes in WINDOW_DEFINITIONS:
+        windows[key] = _build_window_payload(
+            hours=hours,
+            interval_minutes=window_interval_minutes,
+            model_limit=model_limit,
+        )
+
+    primary_window = windows.get("24h", {})
+    summary_payload = (
+        primary_window.get("summary", {})
+        if isinstance(primary_window.get("summary", {}), dict)
+        else {}
+    )
+    usage_mix_payload = (
+        primary_window.get("model_usage_mix", {})
+        if isinstance(primary_window.get("model_usage_mix", {}), dict)
+        else {}
+    )
+    top_model_usage = (
+        primary_window.get("top_model_usage", [])
+        if isinstance(primary_window.get("top_model_usage", []), list)
+        else []
+    )
+    others_usage = (
+        primary_window.get("others_usage", {})
+        if isinstance(primary_window.get("others_usage", {}), dict)
+        else {}
+    )
+
+    return {
+        "schema": ANALYTICS_SCHEMA,
+        "generated_at": generated_at,
+        "provider_id": provider_id,
+        "pubkey": public_key_hex,
+        "npub": settings.npub or "",
+        "endpoint_urls": _resolve_endpoint_urls(),
+        "window_hours": DASHBOARD_WINDOW_HOURS,
+        "interval_minutes": DASHBOARD_INTERVAL_MINUTES,
+        "summary": summary_payload,
+        "model_usage_mix": usage_mix_payload,
+        "top_model_usage": top_model_usage,
+        "others_usage": others_usage,
+        "windows": windows,
+    }
+
+
+def create_stats_snapshot_event(
+    private_key_hex: str,
+    provider_id: str,
+    payload_json: str,
+    *,
+    d_tag: str,
+) -> dict[str, Any]:
+    private_key = PrivateKey(bytes.fromhex(private_key_hex))
+    tags = [
+        ["d", d_tag],
+        ["provider", provider_id],
+        ["schema", ANALYTICS_SCHEMA],
+    ]
+
+    event = Event(
+        public_key=private_key.public_key.hex(),
+        content=payload_json,
+        kind=ANALYTICS_KIND,
+        tags=tags,
+    )
+    private_key.sign_event(event)
+    return _event_to_dict(event)
+
+
+def _fingerprint_payload(payload: dict[str, Any]) -> str:
+    normalized = dict(payload)
+    # Ignore generated timestamp for semantic dedupe.
+    normalized.pop("generated_at", None)
+    payload_json = json.dumps(normalized, separators=(",", ":"), sort_keys=True)
+    return hashlib.sha256(payload_json.encode("utf-8")).hexdigest()
+
+
+async def publish_usage_analytics() -> None:
+    last_payload_hash: str | None = None
+
+    parsed_nsec: str | None = None
+    private_key_hex: str | None = None
+    public_key_hex: str | None = None
+    provider_id: str | None = None
+    warned_missing_nsec = False
+
+    logger.info("Usage analytics sharing task started")
+
+    while True:
+        try:
+            if not settings.enable_analytics_sharing:
+                await asyncio.sleep(DISABLED_POLL_SECONDS)
+                continue
+
+            nsec = (settings.nsec or "").strip()
+            if not nsec:
+                if not warned_missing_nsec:
+                    logger.info("NSEC is not configured; skipping analytics sharing to Nostr")
+                    warned_missing_nsec = True
+                await asyncio.sleep(DISABLED_POLL_SECONDS)
+                continue
+
+            warned_missing_nsec = False
+            if nsec != parsed_nsec or private_key_hex is None or public_key_hex is None:
+                keypair = nsec_to_keypair(nsec)
+                if not keypair:
+                    logger.error("Invalid NSEC; analytics sharing is paused")
+                    await asyncio.sleep(DISABLED_POLL_SECONDS)
+                    continue
+                private_key_hex, public_key_hex = keypair
+                parsed_nsec = nsec
+                provider_id = _resolve_provider_id(public_key_hex)
+                last_payload_hash = None
+
+            if private_key_hex is None or public_key_hex is None:
+                await asyncio.sleep(DISABLED_POLL_SECONDS)
+                continue
+
+            relay_urls = _resolve_relays()
+            if not relay_urls:
+                logger.warning("No Nostr relays configured; analytics sharing skipped")
+                await asyncio.sleep(DISABLED_POLL_SECONDS)
+                continue
+
+            resolved_provider_id = provider_id or _resolve_provider_id(public_key_hex)
+            now_ts = int(time.time())
+            payload = build_stats_snapshot_payload(
+                resolved_provider_id,
+                public_key_hex=public_key_hex,
+                generated_at=now_ts,
+            )
+
+            payload_hash = _fingerprint_payload(payload)
+            if last_payload_hash == payload_hash:
+                await asyncio.sleep(PUBLISH_INTERVAL_SECONDS)
+                continue
+
+            payload_json = json.dumps(payload, separators=(",", ":"), sort_keys=True)
+            d_tag = f"{resolved_provider_id}:stats"
+            event = create_stats_snapshot_event(
+                private_key_hex,
+                resolved_provider_id,
+                payload_json,
+                d_tag=d_tag,
+            )
+
+            success_count = 0
+            for relay_url in relay_urls:
+                if await publish_to_relay(relay_url, event):
+                    success_count += 1
+
+            if success_count > 0:
+                last_payload_hash = payload_hash
+
+            logger.info(
+                "Published analytics snapshot (success=%s/%s provider=%s)",
+                success_count,
+                len(relay_urls),
+                resolved_provider_id,
+                extra={
+                    "relay_success_count": success_count,
+                    "relay_total": len(relay_urls),
+                    "provider_id": resolved_provider_id,
+                },
+            )
+            await asyncio.sleep(PUBLISH_INTERVAL_SECONDS)
+
+        except asyncio.CancelledError:
+            logger.info("Usage analytics sharing task cancelled")
+            break
+        except Exception as e:
+            logger.error(
+                "Usage analytics sharing error",
+                extra={"error": str(e), "error_type": type(e).__name__},
+            )
+            await asyncio.sleep(DISABLED_POLL_SECONDS)

routstr/nostr/discovery.py

@@ -8,8 +8,8 @@ import httpx
 import websockets
 from fastapi import APIRouter, HTTPException
 
-from .core.logging import get_logger
-from .core.settings import settings
+from ..core.logging import get_logger
+from ..core.settings import settings
 
 logger = get_logger(__name__)
 
@@ -72,8 +72,6 @@ async def query_nostr_relay_for_providers(
                     elif data[0] == "NOTICE":
                         try:
                             msg = str(data[1])
-                            if len(msg) > 200:
-                                msg = msg[:200] + "..."
                             logger.debug(f"Relay notice: {msg}")
                         except Exception:
                             logger.debug("Relay notice received")

routstr/nostr/listing.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-NIP-91: Routstr Provider Discoverability Implementation
+Listing: Routstr Provider Discoverability Implementation
 Automatically announces this Routstr proxy instance to Nostr relays.
 """
 
@@ -18,15 +18,15 @@ from nostr.key import PrivateKey
 from nostr.message_type import ClientMessageType
 from nostr.relay_manager import RelayManager
 
-from .core import get_logger
-from .core.settings import settings
+from ..core import get_logger
+from ..core.settings import settings
 
 logger = get_logger(__name__)
 
 
 def get_app_version() -> str | None:
     try:
-        from .core.main import __version__ as imported_version
+        from ..core.main import __version__ as imported_version
 
         return imported_version
     except Exception:
@@ -71,7 +71,7 @@ def nsec_to_keypair(nsec: str) -> tuple[str, str] | None:
         return None
 
 
-def create_nip91_event(
+def create_listing_event(
     private_key_hex: str,
     provider_id: str,
     endpoint_urls: list[str],
@@ -80,7 +80,7 @@ def create_nip91_event(
     metadata: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """
-    Create a NIP-91 compliant provider announcement event (kind:38421).
+    Create a listing provider announcement event (kind:38421).
 
     Args:
         private_key_hex: 32-byte hex private key for signing
@@ -164,14 +164,14 @@ def events_semantically_equal(a: dict[str, Any], b: dict[str, Any]) -> bool:
     return True
 
 
-async def query_nip91_events(
+async def query_listing_events(
     relay_url: str,
     pubkey: str,
     provider_id: str | None = None,
     timeout: int = 30,
 ) -> tuple[list[dict[str, Any]], bool]:
     """
-    Query a Nostr relay for NIP-91 provider announcements (kind:38421) via nostr library.
+    Query a Nostr relay for listing provider announcements (kind:38421) via nostr library.
 
     Returns a tuple of (events, ok) where ok indicates whether the relay interaction
     succeeded without transport-level errors.
@@ -188,7 +188,7 @@ async def query_nip91_events(
 
             flt = Filter(kinds=[38421], authors=[pubkey], limit=10)
             filters = Filters([flt])
-            sub_id = f"nip91_{int(time.time())}"
+            sub_id = f"routstr_listing_{int(time.time())}"
             rm.add_subscription(sub_id, filters)
             req: list[Any] = [ClientMessageType.REQUEST, sub_id]
             req.extend(filters.to_json_array())
@@ -294,7 +294,7 @@ async def _determine_provider_id(public_key_hex: str, relay_urls: list[str]) ->
 
     async def query_single_relay(relay_url: str) -> list[dict[str, Any]]:
         try:
-            events, _ok = await query_nip91_events(relay_url, public_key_hex, None)
+            events, _ok = await query_listing_events(relay_url, public_key_hex, None)
             return events
         except Exception:
             return []
@@ -330,7 +330,7 @@ async def publish_to_relay(
     timeout: int = 30,
 ) -> bool:
     """
-    Publish a NIP-91 event to a nostr relay via nostr library.
+    Publish a listing event to a nostr relay via nostr library.
     """
 
     def _sync_publish() -> bool:
@@ -341,7 +341,7 @@ async def publish_to_relay(
             time.sleep(1.0)
             # Publish the event as-is via publish_message to preserve signature
             rm.publish_message(json.dumps(["EVENT", event]))
-            logger.debug(f"Sent NIP-91 event {event.get('id', '')} to {relay_url}")
+            logger.debug(f"Sent listing event {event.get('id', '')} to {relay_url}")
             time.sleep(1.0)
             return True
         except Exception as e:
@@ -364,13 +364,13 @@ async def announce_provider() -> None:
     # Check for NSEC in environment (use NSEC only)
     nsec = settings.nsec
     if not nsec:
-        logger.info("Nostr private key not found (NSEC), skipping NIP-91 announcement")
+        logger.info("Nostr private key not found (NSEC), skipping listing announcement")
         return
 
     # Convert NSEC to keypair
     keypair = nsec_to_keypair(nsec)
     if not keypair:
-        logger.error("Failed to parse NSEC, skipping NIP-91 announcement")
+        logger.error("Failed to parse NSEC, skipping listing announcement")
         return
 
     private_key_hex, public_key_hex = keypair
@@ -409,7 +409,7 @@ async def announce_provider() -> None:
 
     if not endpoint_urls:
         logger.warning(
-            "No valid endpoints configured (HTTP_URL/ONION_URL). Skipping NIP-91 publish."
+            "No valid endpoints configured (HTTP_URL/ONION_URL). Skipping listing publish."
         )
         return
 
@@ -434,7 +434,7 @@ async def announce_provider() -> None:
 
     # Create the candidate event that we would publish
     version_str = get_app_version()
-    candidate_event = create_nip91_event(
+    candidate_event = create_listing_event(
         private_key_hex=private_key_hex,
         provider_id=provider_id,
         endpoint_urls=endpoint_urls,
@@ -474,7 +474,7 @@ async def announce_provider() -> None:
         if _should_skip(relay_url):
             logger.debug(f"Skipping {relay_url} due to backoff")
             continue
-        events, ok = await query_nip91_events(relay_url, public_key_hex, provider_id)
+        events, ok = await query_listing_events(relay_url, public_key_hex, provider_id)
         if ok:
             _register_success(relay_url)
             existing_events.extend(events)
@@ -489,7 +489,7 @@ async def announce_provider() -> None:
 
     if not all_match:
         logger.debug(
-            "No matching NIP-91 announcement found or differences detected; publishing update"
+            "No matching listing announcement found or differences detected; publishing update"
         )
         success_count = 0
         for relay_url in relay_urls:
@@ -502,11 +502,11 @@ async def announce_provider() -> None:
             else:
                 _register_failure(relay_url)
         logger.info(
-            f"Published NIP-91 announcement to {success_count}/{len(relay_urls)} relays"
+            f"Published listing announcement to {success_count}/{len(relay_urls)} relays"
         )
     else:
         logger.debug(
-            "Matching NIP-91 announcement already present; skipping publish on startup"
+            "Matching listing announcement already present; skipping publish on startup"
         )
 
     # Re-announce periodically (every 24 hours)
@@ -518,7 +518,7 @@ async def announce_provider() -> None:
 
             # Build fresh candidate event for comparison
             version_str = get_app_version()
-            candidate_event = create_nip91_event(
+            candidate_event = create_listing_event(
                 private_key_hex=private_key_hex,
                 provider_id=provider_id,
                 endpoint_urls=endpoint_urls,
@@ -533,7 +533,7 @@ async def announce_provider() -> None:
                 if _should_skip(relay_url):
                     logger.debug(f"Skipping {relay_url} due to backoff")
                     continue
-                events, ok = await query_nip91_events(
+                events, ok = await query_listing_events(
                     relay_url, public_key_hex, provider_id
                 )
                 if ok:
@@ -549,7 +549,7 @@ async def announce_provider() -> None:
 
             if all_match:
                 logger.debug(
-                    "Matching NIP-91 announcement already present; skipping periodic re-announce"
+                    "Matching listing announcement already present; skipping periodic re-announce"
                 )
                 continue
 
@@ -567,8 +567,8 @@ async def announce_provider() -> None:
                     _register_failure(relay_url)
 
         except asyncio.CancelledError:
-            logger.info("NIP-91 announcement task cancelled")
+            logger.info("Listing announcement task cancelled")
             break
         except Exception as e:
-            logger.debug(f"Error in NIP-91 announcement loop: {type(e).__name__}")
+            logger.debug(f"Error in listing announcement loop: {type(e).__name__}")
             # Continue running despite errors

routstr/payment/cost_calculation.py

@@ -15,6 +15,9 @@ class CostData(BaseModel):
     input_msats: int
     output_msats: int
     total_msats: int
+    total_usd: float = 0.0
+    input_tokens: int = 0
+    output_tokens: int = 0
 
 
 class MaxCostData(CostData):
@@ -61,17 +64,65 @@ async def calculate_cost(  # todo: can be sync
             input_msats=0,
             output_msats=0,
             total_msats=0,
+            total_usd=0.0,
+            input_tokens=0,
+            output_tokens=0,
         )
 
     usage_data = response_data["usage"]
 
-    usd_cost = 0.0
+    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
 
-    # Prioritize cost_details.upstream_inference_cost
     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:
@@ -80,12 +131,34 @@ async def calculate_cost(  # todo: can be sync
         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
+    )
+
     if usd_cost > 0:
         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={
@@ -97,10 +170,13 @@ async def calculate_cost(  # todo: can be sync
             )
 
             return CostData(
-                base_msats=-1,
-                input_msats=-1,  # Cost field doesn't break down by token type
-                output_msats=-1,
+                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,
             )
         except Exception as e:
             logger.warning(
@@ -113,13 +189,6 @@ async def calculate_cost(  # todo: can be sync
             )
             # Fall through to token-based calculation
 
-    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
-    )
-
     if not settings.fixed_pricing:
         response_model = response_data.get("model", "")
         logger.debug(
@@ -181,51 +250,35 @@ async def calculate_cost(  # todo: can be sync
             input_msats=0,
             output_msats=0,
             total_msats=max_cost,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
         )
 
-    input_tokens = usage_data.get("prompt_tokens", 0)
-    output_tokens = usage_data.get("completion_tokens", 0)
+    calc_input_msats = round(input_tokens / 1000 * MSATS_PER_1K_INPUT_TOKENS, 3)
 
-    # added for response api
-    input_tokens = (
-        input_tokens if input_tokens != 0 else usage_data.get("input_tokens", 0)
-    )
-    output_tokens = (
-        output_tokens if output_tokens != 0 else usage_data.get("output_tokens", 0)
-    )
-
-    # added for response api
-    input_tokens = (
-        input_tokens
-        if input_tokens != 0
-        else response_data.get("usage", {}).get("input_tokens", 0)
-    )
-    output_tokens = (
-        output_tokens
-        if output_tokens != 0
-        else response_data.get("usage", {}).get("output_tokens", 0)
-    )
-
-    input_msats = round(input_tokens / 1000 * MSATS_PER_1K_INPUT_TOKENS, 3)
-
-    output_msats = round(output_tokens / 1000 * MSATS_PER_1K_OUTPUT_TOKENS, 3)
-    token_based_cost = math.ceil(input_msats + output_msats)
+    calc_output_msats = round(output_tokens / 1000 * MSATS_PER_1K_OUTPUT_TOKENS, 3)
+    token_based_cost = math.ceil(calc_input_msats + calc_output_msats)
+    total_usd = (token_based_cost / 1000.0) * sats_usd_price()
 
     logger.info(
         "Calculated token-based cost",
         extra={
             "input_tokens": input_tokens,
             "output_tokens": output_tokens,
-            "input_cost_msats": input_msats,
-            "output_cost_msats": output_msats,
+            "input_cost_msats": calc_input_msats,
+            "output_cost_msats": calc_output_msats,
             "total_cost_msats": token_based_cost,
+            "total_usd": total_usd,
             "model": response_data.get("model", "unknown"),
         },
     )
 
     return CostData(
         base_msats=0,
-        input_msats=int(input_msats),
-        output_msats=int(output_msats),
+        input_msats=int(calc_input_msats),
+        output_msats=int(calc_output_msats),
         total_msats=token_based_cost,
+        total_usd=total_usd,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
     )

routstr/payment/fee_schedule.py

@@ -0,0 +1,113 @@
+"""Dynamic provider fee schedule logic.
+
+Supports time-based fee ranges (HH:MM UTC) with overlap validation and active fee resolution.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+
+from pydantic.v1 import BaseModel, validator
+
+_HH_MM_RE = re.compile(r"^([01]\d|2[0-3]):([0-5]\d)$")
+
+
+class FeeTimeRange(BaseModel):
+    start_time: str  # HH:MM UTC
+    end_time: str  # HH:MM UTC
+    provider_fee: float
+
+    @validator("start_time", "end_time")
+    @classmethod
+    def validate_time_format(cls, v: str) -> str:
+        if not _HH_MM_RE.match(v):
+            raise ValueError(f"Time must be in HH:MM format (00:00–23:59), got: {v!r}")
+        return v
+
+    @validator("provider_fee")
+    @classmethod
+    def validate_fee(cls, v: float) -> float:
+        if v <= 0:
+            raise ValueError(f"provider_fee must be > 0 (got {v})")
+        return v
+
+
+def _to_minutes(t: str) -> int:
+    h, m = map(int, t.split(":"))
+    return h * 60 + m
+
+
+def _range_intervals(r: FeeTimeRange) -> list[tuple[int, int]]:
+    """Return list of [start, end) minute intervals for this range.
+
+    Handles midnight-crossing (e.g. 22:00–06:00 → [(1320,1440),(0,360)]).
+    start == end is treated as a full-day range.
+    """
+    start = _to_minutes(r.start_time)
+    end = _to_minutes(r.end_time)
+    if start < end:
+        return [(start, end)]
+    if start > end:
+        return [(start, 1440), (0, end)]
+    # start == end → full day
+    return [(0, 1440)]
+
+
+def _intervals_overlap(a: tuple[int, int], b: tuple[int, int]) -> bool:
+    return a[0] < b[1] and b[0] < a[1]
+
+
+def ranges_overlap(a: FeeTimeRange, b: FeeTimeRange) -> bool:
+    """Return True if two fee time ranges overlap at any point in the day."""
+    for ia in _range_intervals(a):
+        for ib in _range_intervals(b):
+            if _intervals_overlap(ia, ib):
+                return True
+    return False
+
+
+def validate_no_overlaps(ranges: list[FeeTimeRange]) -> None:
+    """Raise ValueError if any two ranges in the list overlap."""
+    for i in range(len(ranges)):
+        for j in range(i + 1, len(ranges)):
+            if ranges_overlap(ranges[i], ranges[j]):
+                raise ValueError(
+                    f"Fee ranges overlap: [{ranges[i].start_time}–{ranges[i].end_time}]"
+                    f" and [{ranges[j].start_time}–{ranges[j].end_time}]"
+                )
+
+
+def get_active_fee(
+    ranges: list[FeeTimeRange] | None,
+    default_fee: float,
+    *,
+    _now: datetime | None = None,
+) -> float:
+    """Return the provider fee for the current UTC time.
+
+    Falls back to *default_fee* when no range matches or *ranges* is empty/None.
+    The *_now* parameter is for testing only.
+    """
+    if not ranges or not isinstance(ranges, list):
+        return default_fee
+
+    now = _now if _now is not None else datetime.now(timezone.utc)
+    # Normalize to UTC
+    if now.tzinfo is not None:
+        now = now.astimezone(timezone.utc)
+    current = now.hour * 60 + now.minute
+
+    for r in ranges:
+        start = _to_minutes(r.start_time)
+        end = _to_minutes(r.end_time)
+        if start < end:
+            if start <= current < end:
+                return r.provider_fee
+        elif start > end:  # midnight-crossing
+            if current >= start or current < end:
+                return r.provider_fee
+        else:  # full day (start == end)
+            return r.provider_fee
+
+    return default_fee

routstr/payment/helpers.py

@@ -29,15 +29,13 @@ def check_token_balance(headers: dict, body: dict, max_cost_for_model: int) -> N
             },
         )
     elif auth := headers.get("authorization", None):
-        cashu_token = auth.split(" ")[1] if len(auth.split(" ")) > 1 else ""
         logger.debug(
-            "Using Authorization header token",
+            "Skipping preflight token balance check for Authorization header",
             extra={
-                "token_preview": cashu_token[:20] + "..."
-                if len(cashu_token) > 20
-                else cashu_token
+                "auth_preview": auth[:20] + "..." if len(auth) > 20 else auth,
             },
         )
+        return
     else:
         logger.error("No authentication token provided")
         raise HTTPException(status_code=401, detail="Unauthorized")
@@ -75,7 +73,7 @@ def check_token_balance(headers: dict, body: dict, max_cost_for_model: int) -> N
 
     if max_cost_for_model > amount_msat:
         raise HTTPException(
-            status_code=413,
+            status_code=402,
             detail={
                 "reason": "Insufficient balance",
                 "amount_required_msat": max_cost_for_model,
@@ -169,9 +167,32 @@ async def calculate_discounted_max_cost(
 
     tol = settings.tolerance_percentage
     tol_factor = max(0.0, 1 - float(tol) / 100.0)
+
     max_prompt_allowed_sats = model_pricing.max_prompt_cost * tol_factor
     max_completion_allowed_sats = model_pricing.max_completion_cost * tol_factor
 
+    if model_obj:
+        prompt_token_limit: int | None = None
+        if model_obj.top_provider and (
+            model_obj.top_provider.context_length
+            or model_obj.top_provider.max_completion_tokens
+        ):
+            cl = model_obj.top_provider.context_length
+            mct = model_obj.top_provider.max_completion_tokens
+            if cl and mct:
+                prompt_token_limit = max(0, cl - mct)
+            elif cl:
+                prompt_token_limit = cl
+            elif mct:
+                prompt_token_limit = 0
+        elif model_obj.context_length:
+            prompt_token_limit = model_obj.context_length
+
+        if prompt_token_limit is not None:
+            max_prompt_allowed_sats = (
+                prompt_token_limit * model_pricing.prompt * tol_factor
+            )
+
     adjusted = max_cost_for_model
 
     if messages := body.get("messages"):

routstr/payment/lnurl.py

@@ -25,82 +25,6 @@ class LNURLError(Exception):
     """LNURL related errors."""
 
 
-def parse_lightning_invoice_amount(invoice: str, currency: str = "sat") -> int:
-    """Parse Lightning invoice (BOLT-11) to extract amount in specified currency units.
-
-    Args:
-        invoice: BOLT-11 Lightning invoice string
-        currency: Target currency unit ("sat" or "msat")
-
-    Returns:
-        Amount in the specified currency unit
-
-    Raises:
-        LNURLError: If invoice format is invalid or amount cannot be parsed
-    """
-    invoice = invoice.lower().strip()
-
-    if not invoice.startswith("ln"):
-        raise LNURLError("Invalid Lightning invoice format")
-
-    # Find the network part (bc, tb, etc.)
-    network_start = 2
-    while network_start < len(invoice) and invoice[network_start] not in "0123456789":
-        network_start += 1
-
-    if network_start >= len(invoice):
-        raise LNURLError("Invalid Lightning invoice format")
-
-    # Parse amount and multiplier
-    amount_str = ""
-    multiplier = ""
-    i = network_start
-
-    # Extract numeric part
-    while i < len(invoice) and invoice[i].isdigit():
-        amount_str += invoice[i]
-        i += 1
-
-    # Extract multiplier if present
-    if i < len(invoice) and invoice[i] in "munp":
-        multiplier = invoice[i]
-        i += 1
-
-    # Check if we have the required "1" separator
-    if i >= len(invoice) or invoice[i] != "1":
-        raise LNURLError("Invalid Lightning invoice format")
-
-    if not amount_str:
-        raise LNURLError("Lightning invoice amount not specified")
-
-    # Convert to base units
-    try:
-        amount = int(amount_str)
-    except ValueError:
-        raise LNURLError("Invalid Lightning invoice amount")
-
-    # Apply multiplier to get millisatoshis
-    if multiplier == "m":  # milli = 10^-3
-        amount_msat = amount * 100_000_000  # amount is in BTC * 10^-3
-    elif multiplier == "u":  # micro = 10^-6
-        amount_msat = amount * 100_000  # amount is in BTC * 10^-6
-    elif multiplier == "n":  # nano = 10^-9
-        amount_msat = amount * 100  # amount is in BTC * 10^-9
-    elif multiplier == "p":  # pico = 10^-12
-        amount_msat = amount // 10  # amount is in BTC * 10^-12
-    else:
-        # No multiplier means the amount is in BTC
-        amount_msat = amount * 100_000_000_000  # Convert BTC to msat
-
-    # Convert to target currency unit
-    if currency == "msat":
-        return amount_msat
-    elif currency == "sat":
-        return amount_msat // 1000
-    else:
-        raise LNURLError(f"Unsupported currency for Lightning: {currency}")
-
-
 async def decode_lnurl(lnurl: str) -> str:
     """Decode LNURL to get the actual URL.
 
@@ -291,9 +215,7 @@ async def raw_send_to_lnurl(
         lnurl_data["callback_url"], final_amount
     )
 
-    melt_quote_resp = await wallet.melt_quote(
-        invoice=bolt11_invoice, amount_msat=final_amount
-    )
+    melt_quote_resp = await wallet.melt_quote(invoice=bolt11_invoice)
 
     if amount:
         proofs, _ = await wallet.select_to_send(proofs, amount, set_reserved=True)

routstr/payment/models.py

@@ -7,7 +7,7 @@ from fastapi import APIRouter, Depends
 from pydantic.v1 import BaseModel
 from sqlmodel.ext.asyncio.session import AsyncSession
 
-from ..core.db import ModelRow, get_session
+from ..core.db import ModelRow, UpstreamProviderRow, get_session
 from ..core.logging import get_logger
 from ..core.settings import settings
 from .price import sats_usd_price
@@ -60,6 +60,7 @@ class Model(BaseModel):
     upstream_provider_id: int | str | None = None
     canonical_slug: str | None = None
     alias_ids: list[str] | None = None
+    forwarded_model_id: str | None = None
 
     def __hash__(self) -> int:
         return hash(self.id)
@@ -143,14 +144,6 @@ async def async_fetch_openrouter_models(source_filter: str | None = None) -> lis
         return []
 
 
-def is_openrouter_upstream() -> bool:
-    try:
-        base = (settings.upstream_base_url or "").strip().rstrip("/")
-    except Exception:
-        return False
-    return base.lower() == "https://openrouter.ai/api/v1"
-
-
 def _row_to_model(
     row: ModelRow, apply_provider_fee: bool = False, provider_fee: float = 1.01
 ) -> Model:
@@ -185,6 +178,7 @@ def _row_to_model(
         upstream_provider_id=row.upstream_provider_id,
         canonical_slug=getattr(row, "canonical_slug", None),
         alias_ids=json.loads(row.alias_ids) if row.alias_ids else None,
+        forwarded_model_id=getattr(row, "forwarded_model_id", None) or row.id,
     )
 
     if apply_provider_fee:
@@ -203,33 +197,11 @@ def _row_to_model(
     return model
 
 
-def _model_to_row_payload(model: Model) -> dict[str, str | int | bool | None]:
-    return {
-        "id": model.id,
-        "name": model.name,
-        "created": model.created,
-        "description": model.description,
-        "context_length": model.context_length,
-        "architecture": json.dumps(model.architecture.dict()),
-        "pricing": json.dumps(model.pricing.dict()),
-        "sats_pricing": json.dumps(model.sats_pricing.dict())
-        if model.sats_pricing
-        else None,
-        "per_request_limits": json.dumps(model.per_request_limits)
-        if model.per_request_limits is not None
-        else None,
-        "top_provider": json.dumps(model.top_provider.dict())
-        if model.top_provider is not None
-        else None,
-        "enabled": model.enabled,
-        "upstream_provider_id": model.upstream_provider_id,
-    }
-
-
 async def list_models(
     session: AsyncSession,
     upstream_id: int,
     include_disabled: bool = False,
+    apply_fees: bool = True,
 ) -> list[Model]:
     from sqlmodel import select
 
@@ -247,7 +219,7 @@ async def list_models(
     return [
         _row_to_model(
             r,
-            apply_provider_fee=True,
+            apply_provider_fee=apply_fees,
             provider_fee=providers_by_id[r.upstream_provider_id].provider_fee
             if r.upstream_provider_id in providers_by_id
             else 1.01,
@@ -261,21 +233,6 @@ async def list_models(
     ]
 
 
-async def get_model_by_id(
-    model_id: str, provider_id: int, session: AsyncSession
-) -> Model | None:
-    from ..core.db import UpstreamProviderRow
-
-    row = await session.get(ModelRow, (model_id, provider_id))
-    if not row or not row.enabled:
-        return None
-    provider = await session.get(UpstreamProviderRow, provider_id)
-    if not provider or not provider.enabled:
-        return None
-    provider_fee = provider.provider_fee if provider else 1.01
-    return _row_to_model(row, apply_provider_fee=True, provider_fee=provider_fee)
-
-
 def _calculate_usd_max_costs(model: Model) -> tuple[float, float, float]:
     """Calculate max costs in USD based on model context/token limits.
 
@@ -374,6 +331,7 @@ def _update_model_sats_pricing(model: Model, sats_to_usd: float) -> Model:
             upstream_provider_id=model.upstream_provider_id,
             canonical_slug=model.canonical_slug,
             alias_ids=model.alias_ids,
+            forwarded_model_id=model.forwarded_model_id,
         )
     except Exception as e:
         logger.error(
@@ -447,11 +405,89 @@ async def update_sats_pricing() -> None:
             logger.error(f"Error updating sats pricing: {e}")
 
 
+class ModelTestRequest(BaseModel):
+    model_id: str
+    endpoint_type: str
+    request_data: dict
+
+
+@models_router.post("/api/models/test")
+async def test_model(
+    payload: ModelTestRequest,
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    """Test a model by sending a request through its configured upstream provider."""
+    from sqlmodel import select
+
+    result = await session.execute(
+        select(ModelRow).where(ModelRow.id == payload.model_id)
+    )
+    model_row = result.scalars().first()
+
+    if not model_row:
+        return {
+            "success": False,
+            "error": f"Model '{payload.model_id}' not found in database",
+            "status_code": 404,
+        }
+
+    provider = await session.get(UpstreamProviderRow, model_row.upstream_provider_id)
+    if not provider:
+        return {
+            "success": False,
+            "error": "Upstream provider not found",
+            "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}"
+
+    actual_model_id = model_row.forwarded_model_id or model_row.id
+    request_data = dict(payload.request_data)
+    request_data["model"] = actual_model_id
+
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {provider.api_key}",
+    }
+
+    try:
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.post(url, json=request_data, headers=headers)
+            try:
+                response_data = response.json()
+            except Exception:
+                response_data = {"raw": response.text}
+
+            return {
+                "success": response.status_code < 400,
+                "data": response_data,
+                "status_code": response.status_code,
+            }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "status_code": 500,
+        }
+
+
 @models_router.get("/v1/models")
-@models_router.get("/models", include_in_schema=False)
+@models_router.get("/v1/models/", include_in_schema=False)
+@models_router.get("/models")
+@models_router.get("/models/", include_in_schema=False)
 async def models(session: AsyncSession = Depends(get_session)) -> dict:
     """Get all available models from all providers with database overrides applied."""
     from ..proxy import get_unique_models
 
     items = get_unique_models()
-    return {"data": items}
+    data = []
+    for model in items:
+        m = model.dict()
+        if model.forwarded_model_id:
+            m["id"] = model.forwarded_model_id
+        data.append(m)
+    return {"data": data}

routstr/proxy.py

@@ -16,6 +16,8 @@ from .core.db import (
     create_session,
     get_session,
 )
+from .core.exceptions import UpstreamError
+from .core.settings import settings
 from .payment.helpers import (
     calculate_discounted_max_cost,
     check_token_balance,
@@ -31,7 +33,9 @@ proxy_router = APIRouter()
 
 _upstreams: list[BaseUpstreamProvider] = []
 _model_instances: dict[str, Model] = {}  # All aliases -> Model
-_provider_map: dict[str, BaseUpstreamProvider] = {}  # All aliases -> Provider
+_provider_map: dict[
+    str, list[BaseUpstreamProvider]
+] = {}  # All aliases -> List[Provider]
 _unique_models: dict[str, Model] = {}  # Unique model.id -> Model (no duplicates)
 
 
@@ -40,6 +44,7 @@ async def initialize_upstreams() -> None:
     global _upstreams
     _upstreams = await init_upstreams()
     logger.info(f"Initialized {len(_upstreams)} upstream providers")
+    await sync_provider_fees()
     await refresh_model_maps()
 
 
@@ -51,6 +56,7 @@ async def reinitialize_upstreams() -> None:
         "Re-initialized upstream providers from admin action",
         extra={"provider_count": len(_upstreams)},
     )
+    await sync_provider_fees()
     await refresh_model_maps()
 
 
@@ -65,11 +71,29 @@ def get_upstreams() -> list[BaseUpstreamProvider]:
 
 def get_model_instance(model_id: str) -> Model | None:
     """Get Model instance by ID from global cache."""
-    return _model_instances.get(model_id.lower())
+    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
+
+    # 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
+
+    return None
 
 
-def get_provider_for_model(model_id: str) -> BaseUpstreamProvider | None:
-    """Get UpstreamProvider for model ID from global cache."""
+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())
 
 
@@ -96,6 +120,12 @@ async def refresh_model_maps() -> None:
     disabled_model_ids: set[str] = set()
 
     for provider in provider_rows:
+        # Match with instance in _upstreams to update its state from DB
+        for upstream in _upstreams:
+            if getattr(upstream, "db_id", None) == provider.id:
+                # This updates fee and merges DB models WITHOUT hitting network
+                await upstream.refresh_models_cache(skip_network=True)
+
         if not provider.enabled:
             continue
         for model in provider.models:
@@ -111,6 +141,39 @@ async def refresh_model_maps() -> None:
     )
 
 
+async def sync_provider_fees() -> None:
+    """Update active provider_fee in database based on schedules and defaults."""
+    from .payment.fee_schedule import FeeTimeRange, get_active_fee
+
+    async with create_session() as session:
+        result = await session.exec(select(UpstreamProviderRow))
+        provider_rows = result.all()
+
+        updated = False
+        for p in provider_rows:
+            schedules = None
+            if p.provider_fee_schedules:
+                try:
+                    schedules = [
+                        FeeTimeRange(**s) for s in json.loads(p.provider_fee_schedules)
+                    ]
+                except Exception:
+                    pass
+
+            active_fee = get_active_fee(schedules, p.provider_fee_default)
+            if p.provider_fee != active_fee:
+                logger.info(
+                    f"Updating active fee for provider {p.id}: {p.provider_fee} -> {active_fee}",
+                    extra={"provider_id": p.id, "active_fee": active_fee},
+                )
+                p.provider_fee = active_fee
+                session.add(p)
+                updated = True
+
+        if updated:
+            await session.commit()
+
+
 async def refresh_model_maps_periodically() -> None:
     """Background task to refresh model maps every minute."""
     import asyncio
@@ -118,6 +181,7 @@ async def refresh_model_maps_periodically() -> None:
     while True:
         try:
             await asyncio.sleep(60)
+            await sync_provider_fees()
             await refresh_model_maps()
         except asyncio.CancelledError:
             break
@@ -134,11 +198,6 @@ async def proxy(
 ) -> Response | StreamingResponse:
     headers = dict(request.headers)
 
-    if "x-cashu" not in headers and "authorization" not in headers.keys():
-        return create_error_response(
-            "unauthorized", "Unauthorized", 401, request=request
-        )
-
     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)
@@ -149,13 +208,14 @@ async def proxy(
         model_id = request_body_dict.get("model", "unknown")
 
     model_obj = get_model_instance(model_id)
+
     if not model_obj:
         return create_error_response(
             "invalid_model", f"Model '{model_id}' not found", 400, request=request
         )
 
-    upstream = get_provider_for_model(model_id)
-    if not upstream:
+    upstreams = get_provider_for_model(model_id)
+    if not upstreams:
         return create_error_response(
             "invalid_model",
             f"No provider found for model '{model_id}'",
@@ -163,26 +223,52 @@ async def proxy(
             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]
+
     _max_cost_for_model = await get_max_cost_for_model(
         model=model_id, session=session, model_obj=model_obj
     )
     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)
+
     check_token_balance(headers, request_body_dict, max_cost_for_model)
 
     if x_cashu := headers.get("x-cashu", None):
-        if is_responses_api:
-            return await upstream.handle_x_cashu_responses(
-                request, x_cashu, path, max_cost_for_model, model_obj
-            )
-        else:
-            return await upstream.handle_x_cashu(
-                request, x_cashu, path, max_cost_for_model, model_obj
-            )
+        last_error = None
+        for i, upstream in enumerate(upstreams):
+            try:
+                if is_responses_api:
+                    return await upstream.handle_x_cashu_responses(
+                        request, x_cashu, path, max_cost_for_model, model_obj
+                    )
+                else:
+                    return await upstream.handle_x_cashu(
+                        request, x_cashu, path, max_cost_for_model, model_obj
+                    )
+            except UpstreamError as e:
+                logger.warning(
+                    f"Upstream {upstream.provider_type} failed (x-cashu): {e}"
+                )
+                if i == len(upstreams) - 1:
+                    last_error = e
+                continue
+
+        return create_error_response(
+            "upstream_error",
+            str(last_error) if last_error else "All upstreams failed",
+            502,
+            request=request,
+        )
 
     elif auth := headers.get("authorization", None):
-        key = await get_bearer_token_key(headers, path, session, auth)
+        key = await get_bearer_token_key(
+            headers, path, session, auth, max_cost_for_model, model_id
+        )
 
     else:
         if request.method not in ["GET"]:
@@ -194,77 +280,183 @@ async def proxy(
             )
 
         logger.debug("Processing unauthenticated GET request", extra={"path": path})
-        headers = upstream.prepare_headers(dict(request.headers))
-        return await upstream.forward_get_request(request, path, headers)
+
+        last_error_response = None
+        for i, upstream in enumerate(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(upstreams) - 1:
+                    error_message = ""
+                    try:
+                        if hasattr(response, "body"):
+                            body_bytes = response.body
+                            data = json.loads(body_bytes)
+                            if "error" in data:
+                                error_data = data["error"]
+                                if isinstance(error_data, dict):
+                                    error_message = error_data.get("message", "")
+                                elif isinstance(error_data, str):
+                                    error_message = error_data
+                    except Exception:
+                        pass
+
+                    await upstream.on_upstream_error_redirect(
+                        response.status_code, error_message
+                    )
+
+                    logger.warning(
+                        f"Upstream {upstream.provider_type} returned {response.status_code} (GET), trying next provider",
+                        extra={
+                            "status_code": response.status_code,
+                            "upstream": upstream.provider_type,
+                        },
+                    )
+                    continue
+                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
+                    )
+                continue
+        return last_error_response or create_error_response(
+            "upstream_error", "All upstreams failed", 502, request=request
+        )
 
     if request_body_dict:
         await pay_for_request(key, max_cost_for_model, session)
 
-    headers = upstream.prepare_headers(dict(request.headers))
+    for i, upstream in enumerate(upstreams):
+        headers = upstream.prepare_headers(dict(request.headers))
 
-    try:
-        if is_responses_api:
-            response = await upstream.forward_responses_request(
-                request,
-                path,
-                headers,
-                request_body,
-                key,
-                max_cost_for_model,
-                session,
-                model_obj,
+        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,
+                    )
+                else:
+                    response = await upstream.forward_request(
+                        request,
+                        path,
+                        headers,
+                        request_body,
+                        key,
+                        max_cost_for_model,
+                        session,
+                        model_obj,
+                    )
+            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
+
+            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:
+                    error_message = ""
+                    try:
+                        if hasattr(response, "body"):
+                            body_bytes = response.body
+                            data = json.loads(body_bytes)
+                            if "error" in data:
+                                error_data = data["error"]
+                                if isinstance(error_data, dict):
+                                    error_message = error_data.get("message", "")
+                                elif isinstance(error_data, str):
+                                    error_message = error_data
+                    except Exception:
+                        pass
+
+                    await upstream.on_upstream_error_redirect(
+                        response.status_code, error_message
+                    )
+
+                    logger.warning(
+                        f"Upstream {upstream.provider_type} returned {response.status_code}, trying next provider",
+                        extra={
+                            "status_code": response.status_code,
+                            "upstream": upstream.provider_type,
+                        },
+                    )
+                    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)
+                logger.warning(
+                    "Upstream request failed, revert payment",
+                    extra={
+                        "status_code": response.status_code,
+                        "path": path,
+                        "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 UpstreamError as e:
+            logger.warning(
+                f"Upstream {upstream.provider_type} failed: {e}",
+                extra={"retry": i < len(upstreams) - 1},
             )
-        else:
-            response = await upstream.forward_request(
-                request,
-                path,
-                headers,
-                request_body,
-                key,
-                max_cost_for_model,
-                session,
-                model_obj,
-            )
-    except Exception as e:
-        logger.error(
-            "Upstream request failed, ensuring payment is reverted",
-            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
 
-    if response.status_code != 200:
-        await revert_pay_for_request(key, session, max_cost_for_model)
-        logger.warning(
-            "Upstream request failed, revert payment",
-            extra={
-                "status_code": response.status_code,
-                "path": path,
-                "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 the mapped error response generated earlier rather than masking with 502
-        return response
+            # If this was the last provider
+            if i == len(upstreams) - 1:
+                await revert_pay_for_request(key, session, max_cost_for_model)
+                return create_error_response(
+                    "upstream_error", str(e), 502, request=request
+                )
 
-    return response
+            # Otherwise loop continues to next provider
+            continue
+
+    # Should not be reached given logic above
+    return create_error_response(
+        "upstream_error", "All upstreams failed", 502, request=request
+    )
 
 
 async def get_bearer_token_key(
-    headers: dict, path: str, session: AsyncSession, auth: str
+    headers: dict,
+    path: str,
+    session: AsyncSession,
+    auth: str,
+    min_cost: int = 0,
+    model_id: str = "unknown",
 ) -> ApiKey:
     """Handle bearer token authentication proxy requests."""
-    bearer_key = auth.replace("Bearer ", "") if auth.startswith("Bearer ") else ""
+    parts = auth.split()
+    bearer_key = parts[1] if len(parts) > 1 and parts[0].lower() == "bearer" else ""
     refund_address = headers.get("Refund-LNURL", None)
     key_expiry_time = headers.get("Key-Expiry-Time", None)
 
@@ -277,6 +469,7 @@ async def get_bearer_token_key(
             "bearer_key_preview": bearer_key[:20] + "..."
             if len(bearer_key) > 20
             else bearer_key,
+            "min_cost": min_cost,
         },
     )
 
@@ -315,6 +508,7 @@ async def get_bearer_token_key(
             session,
             refund_address,
             key_expiry_time,  # type: ignore
+            min_cost=min_cost,
         )
         logger.info(
             "Bearer token validated successfully",
@@ -326,15 +520,16 @@ 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(
-            "Bearer token validation failed",
+            f"Bearer token validation failed: {type(e).__name__}: {e} path={path} model={model_id!r} min_cost={min_cost} key={key_preview!r}",
             extra={
                 "error": str(e),
                 "error_type": type(e).__name__,
                 "path": path,
-                "bearer_key_preview": bearer_key[:20] + "..."
-                if len(bearer_key) > 20
-                else bearer_key,
+                "model_id": model_id,
+                "min_cost_msat": min_cost,
+                "bearer_key_preview": key_preview,
             },
         )
         raise

routstr/upstream/__init__.py

@@ -10,6 +10,7 @@ from .openai import OpenAIUpstreamProvider
 from .openrouter import OpenRouterUpstreamProvider
 from .perplexity import PerplexityUpstreamProvider
 from .ppqai import PPQAIUpstreamProvider
+from .routstr import RoutstrUpstreamProvider
 from .xai import XAIUpstreamProvider
 
 upstream_provider_classes: list[type[BaseUpstreamProvider]] = [
@@ -24,6 +25,7 @@ upstream_provider_classes: list[type[BaseUpstreamProvider]] = [
     OpenRouterUpstreamProvider,
     PerplexityUpstreamProvider,
     PPQAIUpstreamProvider,
+    RoutstrUpstreamProvider,
     XAIUpstreamProvider,
 ]
 """List of all upstream classes"""

routstr/upstream/auto_topup.py

@@ -0,0 +1,157 @@
+import asyncio
+import json
+
+from sqlmodel import select
+
+from ..core import get_logger
+from ..core.db import UpstreamProviderRow, create_session
+from ..wallet import send_token
+from .routstr import RoutstrUpstreamProvider
+
+logger = get_logger(__name__)
+
+# Check every 60 seconds
+AUTO_TOPUP_INTERVAL_SECONDS = 60
+
+
+async def periodic_auto_topup() -> None:
+    """Background task that monitors Routstr provider balances and auto-tops up when below threshold.
+
+    For each Routstr provider with auto_topup enabled in provider_settings:
+    1. Checks the upstream balance via get_balance()
+    2. If balance < topup_threshold, creates a cashu token from the configured mint
+    3. Sends the token to the upstream provider via topup()
+    """
+    # Wait for initial startup to complete
+    await asyncio.sleep(30)
+    logger.info("Auto top-up worker started")
+
+    while True:
+        try:
+            await _run_auto_topup_cycle()
+        except Exception as e:
+            logger.error(
+                "Auto top-up cycle failed",
+                extra={"error": str(e), "error_type": type(e).__name__},
+            )
+
+        await asyncio.sleep(AUTO_TOPUP_INTERVAL_SECONDS)
+
+
+async def _run_auto_topup_cycle() -> None:
+    """Single cycle: check all eligible providers and top up if needed."""
+    async with create_session() as session:
+        query = select(UpstreamProviderRow).where(
+            UpstreamProviderRow.provider_type == "routstr",
+            UpstreamProviderRow.enabled == True,  # noqa: E712
+        )
+        result = await session.exec(query)
+        providers = result.all()
+
+    for row in providers:
+        try:
+            await _check_and_topup(row)
+        except Exception as e:
+            logger.error(
+                "Auto top-up failed for provider",
+                extra={
+                    "provider_id": row.id,
+                    "base_url": row.base_url,
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                },
+            )
+
+
+async def _check_and_topup(row: UpstreamProviderRow) -> None:
+    """Check a single provider's balance and top up if below threshold."""
+    # Parse provider settings
+    settings: dict = {}
+    if row.provider_settings:
+        try:
+            settings = json.loads(row.provider_settings)
+        except (json.JSONDecodeError, TypeError):
+            return
+
+    if not settings.get("auto_topup"):
+        return
+
+    threshold = settings.get("topup_threshold")
+    amount = settings.get("topup_amount_limit")
+    mint_url = settings.get("topup_mint_url")
+
+    if not threshold or not amount or not mint_url:
+        logger.warning(
+            "Auto top-up enabled but missing configuration",
+            extra={
+                "provider_id": row.id,
+                "has_threshold": bool(threshold),
+                "has_amount": bool(amount),
+                "has_mint": bool(mint_url),
+            },
+        )
+        return
+
+    if not row.api_key:
+        return
+
+    # Instantiate provider and check balance
+    provider = RoutstrUpstreamProvider.from_db_row(row)
+    balance = await provider.get_balance()
+
+    if balance is None:
+        logger.warning(
+            "Could not fetch balance for auto top-up",
+            extra={"provider_id": row.id, "base_url": row.base_url},
+        )
+        return
+
+    if balance >= threshold * 1000:
+        return
+
+    # Balance is below threshold - create token and top up
+    logger.info(
+        "Auto top-up triggered",
+        extra={
+            "provider_id": row.id,
+            "balance": balance,
+            "threshold": threshold,
+            "topup_amount": amount,
+            "mint_url": mint_url,
+        },
+    )
+
+    print(amount, mint_url)
+    try:
+        token = await send_token(amount, "sat", mint_url)
+    except Exception as e:
+        logger.error(
+            "Failed to create cashu token for auto top-up",
+            extra={
+                "provider_id": row.id,
+                "amount": amount,
+                "mint_url": mint_url,
+                "error": str(e),
+            },
+        )
+        return
+
+    result = await provider.topup(token)
+
+    if "error" in result:
+        logger.error(
+            "Auto top-up upstream call failed",
+            extra={
+                "provider_id": row.id,
+                "error": result["error"],
+            },
+        )
+    else:
+        logger.info(
+            "Auto top-up completed successfully",
+            extra={
+                "provider_id": row.id,
+                "amount": amount,
+                "new_balance_approx": balance + amount,
+            },
+        )

routstr/upstream/azure.py

@@ -4,6 +4,7 @@ from .base import BaseUpstreamProvider
 
 if TYPE_CHECKING:
     from ..core.db import UpstreamProviderRow
+    from ..payment.models import Model
 
 
 class AzureUpstreamProvider(BaseUpstreamProvider):
@@ -58,19 +59,52 @@ class AzureUpstreamProvider(BaseUpstreamProvider):
             "platform_url": cls.platform_url,
         }
 
+    def prepare_headers(self, request_headers: dict) -> dict:
+        """Prepare headers for Azure OpenAI, adding api-key."""
+        headers = super().prepare_headers(request_headers)
+        if self.api_key:
+            headers["api-key"] = self.api_key
+            headers.pop("Authorization", None)
+            headers.pop("authorization", None)
+        return headers
+
     def prepare_params(
         self, path: str, query_params: Mapping[str, str] | None
     ) -> Mapping[str, str]:
-        """Prepare query parameters for Azure OpenAI, adding API version.
-
-        Args:
-            path: Request path
-            query_params: Original query parameters from the client
-
-        Returns:
-            Query parameters dict with Azure API version added for chat completions
-        """
+        """Prepare query parameters for Azure OpenAI, adding API version."""
         params = dict(query_params or {})
-        if path.endswith("chat/completions"):
-            params["api-version"] = self.api_version
+        version = (self.api_version or "").replace("\ufeff", "").strip()
+        if not version or version.lower() == "v1":
+            version = "2024-02-15-preview"
+        params["api-version"] = version
         return params
+
+    def normalize_request_path(
+        self, path: str, model_obj: "Model | None" = None
+    ) -> str:
+        """Build Azure deployment-specific request path."""
+        clean_path = super().normalize_request_path(path, model_obj).lstrip("/")
+        if model_obj is None:
+            return clean_path
+
+        deployment_id = getattr(
+            model_obj, "canonical_slug", None
+        ) or self.transform_model_name(model_obj.id)
+        deployment_id = deployment_id.split("/")[-1]
+        return f"openai/deployments/{deployment_id}/{clean_path}"
+
+    def get_request_base_url(
+        self, path: str, model_obj: "Model | None" = None
+    ) -> str:
+        """Use endpoint root, stripping accidental /openai/v1 suffix if present."""
+        base_url = self.base_url.rstrip("/")
+        marker = "/openai/v1"
+        if marker in base_url:
+            base_url = base_url.split(marker, 1)[0].rstrip("/")
+        return base_url
+
+    def transform_model_name(self, model_id: str) -> str:
+        """Extract deployment name from model ID."""
+        if "/" in model_id:
+            return model_id.split("/")[-1]
+        return model_id

routstr/upstream/gemini.py

@@ -259,7 +259,15 @@ class GeminiUpstreamProvider(BaseUpstreamProvider):
                 cost_data = await adjust_payment_for_tokens(
                     key, openai_format_response, session, max_cost_for_model
                 )
+                await session.refresh(key)
+                remaining_balance_msats = key.balance
                 openai_format_response["cost"] = cost_data
+                openai_format_response["cost"]["sats_cost"] = (
+                    cost_data.get("total_msats", 0) // 1000
+                )
+                openai_format_response["cost"]["remaining_balance_msats"] = (
+                    remaining_balance_msats
+                )
 
                 logger.info(
                     "Gemini non-streaming payment completed",

routstr/upstream/helpers.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import asyncio
 import os
 import re
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Callable
 
 if TYPE_CHECKING:
     from ..core.settings import Settings
@@ -122,12 +122,16 @@ async def get_all_models_with_overrides(
 
 
 async def refresh_upstreams_models_periodically(
-    upstreams: list[BaseUpstreamProvider],
+    upstreams_provider: (
+        Callable[[], list[BaseUpstreamProvider]] | list[BaseUpstreamProvider]
+    ),
 ) -> None:
     """Background task to periodically refresh models cache for all providers.
 
     Args:
-        upstreams: List of upstream provider instances
+        upstreams_provider: Either a callable returning the live upstream list
+            (preferred — picks up providers added/changed via reinitialize_upstreams),
+            or a static list (legacy, will go stale after reinitialize_upstreams).
     """
     import asyncio
     import random
@@ -139,9 +143,14 @@ async def refresh_upstreams_models_periodically(
         logger.info("Provider models refresh disabled (interval <= 0)")
         return
 
+    def _resolve_upstreams() -> list[BaseUpstreamProvider]:
+        if callable(upstreams_provider):
+            return upstreams_provider()
+        return upstreams_provider
+
     while True:
         try:
-            for upstream in upstreams:
+            for upstream in _resolve_upstreams():
                 try:
                     await upstream.refresh_models_cache()
                 except Exception as e:
@@ -205,6 +214,9 @@ 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",
@@ -236,7 +248,7 @@ async def _seed_providers_from_settings(
     from . import upstream_provider_classes
 
     providers_to_add: list[UpstreamProviderRow] = []
-    seeded_base_urls: set[str] = set()
+    seeded_provider_keys: set[tuple[str, str]] = set()
 
     provider_classes_by_type = {
         cls.provider_type: cls
@@ -261,7 +273,8 @@ async def _seed_providers_from_settings(
                 base_url = provider_class.default_base_url  # type: ignore[attr-defined]
                 result = await session.exec(
                     select(UpstreamProviderRow).where(
-                        UpstreamProviderRow.base_url == base_url
+                        UpstreamProviderRow.base_url == base_url,
+                        UpstreamProviderRow.api_key == api_key,
                     )
                 )
                 if not result.first():
@@ -273,13 +286,15 @@ async def _seed_providers_from_settings(
                             enabled=True,
                         )
                     )
-                    seeded_base_urls.add(base_url)
+                    seeded_provider_keys.add((base_url, api_key))
 
     ollama_base_url = os.environ.get("OLLAMA_BASE_URL")
     if ollama_base_url:
+        ollama_api_key = os.environ.get("OLLAMA_API_KEY", "")
         result = await session.exec(
             select(UpstreamProviderRow).where(
-                UpstreamProviderRow.base_url == ollama_base_url
+                UpstreamProviderRow.base_url == ollama_base_url,
+                UpstreamProviderRow.api_key == ollama_api_key,
             )
         )
         if not result.first():
@@ -287,18 +302,20 @@ async def _seed_providers_from_settings(
                 UpstreamProviderRow(
                     provider_type="ollama",
                     base_url=ollama_base_url,
-                    api_key=os.environ.get("OLLAMA_API_KEY", ""),
+                    api_key=ollama_api_key,
                     enabled=True,
                 )
             )
-            seeded_base_urls.add(ollama_base_url)
+            seeded_provider_keys.add((ollama_base_url, ollama_api_key))
 
     if settings.chat_completions_api_version and settings.upstream_base_url:
         base_url = settings.upstream_base_url
-        if base_url not in seeded_base_urls:
+        api_key = settings.upstream_api_key
+        if (base_url, api_key) not in seeded_provider_keys:
             result = await session.exec(
                 select(UpstreamProviderRow).where(
-                    UpstreamProviderRow.base_url == base_url
+                    UpstreamProviderRow.base_url == base_url,
+                    UpstreamProviderRow.api_key == api_key,
                 )
             )
             if not result.first():
@@ -306,19 +323,21 @@ async def _seed_providers_from_settings(
                     UpstreamProviderRow(
                         provider_type="azure",
                         base_url=base_url,
-                        api_key=settings.upstream_api_key,
+                        api_key=api_key,
                         api_version=settings.chat_completions_api_version,
                         enabled=True,
                     )
                 )
-                seeded_base_urls.add(base_url)
+                seeded_provider_keys.add((base_url, api_key))
 
     if settings.upstream_base_url and settings.upstream_api_key:
         base_url = settings.upstream_base_url
-        if base_url not in seeded_base_urls:
+        api_key = settings.upstream_api_key
+        if (base_url, api_key) not in seeded_provider_keys:
             result = await session.exec(
                 select(UpstreamProviderRow).where(
-                    UpstreamProviderRow.base_url == base_url
+                    UpstreamProviderRow.base_url == base_url,
+                    UpstreamProviderRow.api_key == api_key,
                 )
             )
             if not result.first():
@@ -326,11 +345,11 @@ async def _seed_providers_from_settings(
                     UpstreamProviderRow(
                         provider_type="custom",
                         base_url=base_url,
-                        api_key=settings.upstream_api_key,
+                        api_key=api_key,
                         enabled=True,
                     )
                 )
-                seeded_base_urls.add(base_url)
+                seeded_provider_keys.add((base_url, api_key))
 
     for provider in providers_to_add:
         session.add(provider)

routstr/upstream/ollama.py

@@ -3,13 +3,11 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 import httpx
-from fastapi import Request
-from fastapi.responses import Response, StreamingResponse
 
 from .base import BaseUpstreamProvider
 
 if TYPE_CHECKING:
-    from ..core.db import ApiKey, AsyncSession, UpstreamProviderRow
+    from ..core.db import UpstreamProviderRow
     from ..payment.models import Model
 
 from ..core.logging import get_logger
@@ -67,38 +65,9 @@ class OllamaUpstreamProvider(BaseUpstreamProvider):
         """Strip 'ollama/' prefix for Ollama API compatibility."""
         return model_id.removeprefix("ollama/")
 
-    async def forward_request(
-        self,
-        request: Request,
-        path: str,
-        headers: dict,
-        request_body: bytes | None,
-        key: ApiKey,
-        max_cost_for_model: int,
-        session: AsyncSession,
-        model_obj: Model,
-    ) -> Response | StreamingResponse:
-        """Override to use OpenAI-compatible endpoint for proxy requests."""
-        if path.startswith("v1/"):
-            path = path.replace("v1/", "")
-
-        original_base_url = self.base_url
-        self.base_url = f"{self.base_url}/v1"
-
-        try:
-            result = await super().forward_request(
-                request,
-                path,
-                headers,
-                request_body,
-                key,
-                max_cost_for_model,
-                session,
-                model_obj,
-            )
-            return result
-        finally:
-            self.base_url = original_base_url
+    def get_request_base_url(self, path: str, model_obj: Model | None = None) -> str:
+        """Route proxy traffic through Ollama's OpenAI-compatible /v1 endpoint."""
+        return f"{self.base_url.rstrip('/')}/v1"
 
     async def fetch_models(self) -> list[Model]:
         """Fetch models from Ollama API using /api/tags endpoint."""
@@ -195,103 +164,3 @@ class OllamaUpstreamProvider(BaseUpstreamProvider):
                 },
             )
             return []
-
-    async def refresh_models_cache(self) -> None:
-        """Refresh the in-memory models cache from upstream API."""
-        try:
-            from ..payment.models import _update_model_sats_pricing
-            from ..payment.price import sats_usd_price
-
-            models = await self.fetch_models()
-            models_with_fees = [self._apply_provider_fee_to_model(m) for m in models]
-
-            try:
-                sats_to_usd = sats_usd_price()
-                self._models_cache = [
-                    _update_model_sats_pricing(m, sats_to_usd) for m in models_with_fees
-                ]
-            except Exception:
-                self._models_cache = models_with_fees
-
-            self._models_by_id = {m.id: m for m in self._models_cache}
-            logger.info(
-                f"Refreshed models cache for {self.base_url}",
-                extra={"model_count": len(models)},
-            )
-        except Exception as e:
-            logger.error(
-                f"Failed to refresh models cache for {self.base_url}",
-                extra={"error": str(e), "error_type": type(e).__name__},
-            )
-
-    def get_cached_models(self) -> list[Model]:
-        """Get cached models for this provider.
-
-        Returns:
-            List of cached Model objects
-        """
-        return self._models_cache
-
-    def get_cached_model_by_id(self, model_id: str) -> Model | None:
-        """Get a specific cached model by ID.
-
-        Args:
-            model_id: Model identifier
-
-        Returns:
-            Model object or None if not found
-        """
-        return self._models_by_id.get(model_id)
-
-    def _apply_provider_fee_to_model(self, model: Model) -> Model:
-        """Apply provider fee to model's USD pricing and calculate max costs.
-
-        Args:
-            model: Model object to update
-
-        Returns:
-            Model with provider fee applied to pricing and max costs calculated
-        """
-        from ..payment.models import Model, Pricing, _calculate_usd_max_costs
-
-        adjusted_pricing = Pricing.parse_obj(
-            {k: v * self.provider_fee for k, v in model.pricing.dict().items()}
-        )
-
-        temp_model = Model(
-            id=model.id,
-            name=model.name,
-            created=model.created,
-            description=model.description,
-            context_length=model.context_length,
-            architecture=model.architecture,
-            pricing=adjusted_pricing,
-            sats_pricing=None,
-            per_request_limits=model.per_request_limits,
-            top_provider=model.top_provider,
-            enabled=model.enabled,
-            upstream_provider_id=model.upstream_provider_id,
-            canonical_slug=model.canonical_slug,
-        )
-
-        (
-            adjusted_pricing.max_prompt_cost,
-            adjusted_pricing.max_completion_cost,
-            adjusted_pricing.max_cost,
-        ) = _calculate_usd_max_costs(temp_model)
-
-        return Model(
-            id=model.id,
-            name=model.name,
-            created=model.created,
-            description=model.description,
-            context_length=model.context_length,
-            architecture=model.architecture,
-            pricing=adjusted_pricing,
-            sats_pricing=model.sats_pricing,
-            per_request_limits=model.per_request_limits,
-            top_provider=model.top_provider,
-            enabled=model.enabled,
-            upstream_provider_id=model.upstream_provider_id,
-            canonical_slug=model.canonical_slug,
-        )

routstr/upstream/ppqai.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 import httpx
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from ..core.logging import get_logger
 from ..payment.models import Architecture, Model, Pricing, async_fetch_openrouter_models
@@ -16,18 +16,20 @@ logger = get_logger(__name__)
 
 
 class PPQAIModelPricing(BaseModel):
-    ui: dict[str, float]
-    api: dict[str, float]
+    ui: Optional[dict[str, float]] = None
+    api: Optional[dict[str, float]] = None
+    input_per_1M_tokens: Optional[float] = Field(None, alias="input_per_1M_tokens")
+    output_per_1M_tokens: Optional[float] = Field(None, alias="output_per_1M_tokens")
 
 
 class PPQAIModel(BaseModel):
     id: str
-    provider: str
+    provider: Optional[str] = None
     name: str
     created_at: int
     context_length: int
     pricing: PPQAIModelPricing
-    popular: bool
+    popular: bool = False
 
 
 class PPQAIUpstreamProvider(BaseUpstreamProvider):
@@ -134,31 +136,54 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
                         )
 
                         if or_model:
-                            if input_price := ppqai_model.pricing.api.get(
-                                "input_per_1M"
-                            ):
+                            input_price = None
+                            if ppqai_model.pricing.api:
+                                input_price = ppqai_model.pricing.api.get(
+                                    "input_per_1M"
+                                )
+                            elif ppqai_model.pricing.input_per_1M_tokens:
+                                input_price = ppqai_model.pricing.input_per_1M_tokens
+
+                            if input_price is not None:
                                 or_model.pricing.prompt = input_price / 1_000_000
-                            if output_price := ppqai_model.pricing.api.get(
-                                "output_per_1M"
-                            ):
+
+                            output_price = None
+                            if ppqai_model.pricing.api:
+                                output_price = ppqai_model.pricing.api.get(
+                                    "output_per_1M"
+                                )
+                            elif ppqai_model.pricing.output_per_1M_tokens:
+                                output_price = ppqai_model.pricing.output_per_1M_tokens
+
+                            if output_price is not None:
                                 or_model.pricing.completion = output_price / 1_000_000
+
                             if cl := ppqai_model.context_length:
                                 or_model.context_length = cl
                             models.append(or_model)
                         else:
-                            input_price = ppqai_model.pricing.api.get(
-                                "input_per_1M", 0.0
-                            )
-                            output_price = ppqai_model.pricing.api.get(
-                                "output_per_1M", 0.0
-                            )
+                            input_price = 0.0
+                            if ppqai_model.pricing.api:
+                                input_price = ppqai_model.pricing.api.get(
+                                    "input_per_1M", 0.0
+                                )
+                            elif ppqai_model.pricing.input_per_1M_tokens:
+                                input_price = ppqai_model.pricing.input_per_1M_tokens
+
+                            output_price = 0.0
+                            if ppqai_model.pricing.api:
+                                output_price = ppqai_model.pricing.api.get(
+                                    "output_per_1M", 0.0
+                                )
+                            elif ppqai_model.pricing.output_per_1M_tokens:
+                                output_price = ppqai_model.pricing.output_per_1M_tokens
 
                             models.append(
                                 Model(
                                     id=ppqai_model.id,
                                     name=ppqai_model.name,
                                     created=ppqai_model.created_at // 1000,
-                                    description=f"{ppqai_model.provider} model",
+                                    description=f"{ppqai_model.provider or 'PPQ.AI'} model",
                                     context_length=ppqai_model.context_length,
                                     architecture=Architecture(
                                         modality="text->text",
@@ -196,6 +221,37 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
             )
             return []
 
+    async def on_upstream_error_redirect(
+        self, status_code: int, error_message: str
+    ) -> None:
+        if "insufficient balance" in error_message.lower():
+            logger.warning(
+                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,
+                )
+                result = await session.exec(statement)
+                provider = result.first()
+
+                if provider:
+                    provider.enabled = False
+                    session.add(provider)
+                    await session.commit()
+
+                    # Trigger re-initialization of providers
+                    # Import here to avoid circular dependency
+                    from ..proxy import reinitialize_upstreams
+
+                    await reinitialize_upstreams()
+
     async def create_account(self) -> dict[str, object]:
         """Create a new PPQ.AI account.
 
@@ -252,7 +308,6 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
         )
 
         async with httpx.AsyncClient(timeout=30.0) as client:
-            print(f"Payload: {payload}", "sending to", url)
             response = await client.post(url, headers=headers, json=payload)
             response.raise_for_status()
             invoice_data = response.json()

routstr/upstream/routstr.py

@@ -0,0 +1,169 @@
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from ..core import get_logger
+from ..payment.models import Model
+from .base import BaseUpstreamProvider
+
+if TYPE_CHECKING:
+    from ..core.db import UpstreamProviderRow
+
+logger = get_logger(__name__)
+
+
+class RoutstrUpstreamProvider(BaseUpstreamProvider):
+    """Upstream provider for communicating with another Routstr instance."""
+
+    provider_type = "routstr"
+    default_base_url = None
+    platform_url = None
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        provider_fee: float = 1.01,
+        provider_settings: dict | None = None,
+    ):
+        """Initialize Routstr provider.
+
+        Args:
+            base_url: Base URL of the upstream Routstr instance
+            api_key: API key for the upstream Routstr instance
+            provider_fee: Provider fee multiplier
+            provider_settings: Provider-specific settings (auto-topup, etc.)
+        """
+        # Ensure base_url doesn't end with /v1 as BaseUpstreamProvider appends it if needed
+        # but Routstr paths are usually absolute from base.
+        super().__init__(
+            base_url=base_url.rstrip("/"),
+            api_key=api_key,
+            provider_fee=provider_fee,
+        )
+        self.settings = provider_settings or {}
+
+    @classmethod
+    def from_db_row(
+        cls, provider_row: "UpstreamProviderRow"
+    ) -> "RoutstrUpstreamProvider":
+        import json
+
+        settings = {}
+        if provider_row.provider_settings:
+            try:
+                settings = json.loads(provider_row.provider_settings)
+            except Exception:
+                pass
+
+        return cls(
+            base_url=provider_row.base_url,
+            api_key=provider_row.api_key,
+            provider_fee=provider_row.provider_fee,
+            provider_settings=settings,
+        )
+
+    @classmethod
+    def get_provider_metadata(cls) -> dict[str, object]:
+        return {
+            "id": cls.provider_type,
+            "name": "Routstr Node",
+            "default_base_url": "",
+            "fixed_base_url": False,
+            "platform_url": cls.platform_url,
+            "can_create_account": False,
+            "can_topup": True,
+            "can_show_balance": True,
+        }
+
+    async def get_balance(self) -> float | None:
+        """Fetch balance from the upstream Routstr node.
+
+        Returns:
+            Balance in satoshis, or None if failed
+        """
+        url = f"{self.base_url}/v1/balance/info"
+        headers = {"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(url, headers=headers, timeout=10.0)
+                response.raise_for_status()
+                data = response.json()
+                # Routstr balance info usually contains 'balance' in msats or sats
+                # Check for msats and convert to sats
+                if "balance_msats" in data:
+                    return float(data["balance_msats"]) / 1000.0
+                return float(data.get("balance", 0))
+            except Exception as e:
+                logger.error(
+                    "Failed to fetch balance from upstream Routstr",
+                    extra={"url": url, "error": str(e)},
+                )
+                return None
+
+    async def topup(self, cashu_token: str) -> dict[str, Any]:
+        """Top up balance on the upstream Routstr node.
+
+        Args:
+            cashu_token: Cashu token to deposit
+
+        Returns:
+            Dict containing top-up result
+        """
+        url = f"{self.base_url}/v1/balance/topup"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        payload = {"cashu_token": cashu_token}
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(
+                    url, headers=headers, json=payload, timeout=30.0
+                )
+                response.raise_for_status()
+                return response.json()
+            except Exception as e:
+                logger.error(
+                    "Failed to topup upstream Routstr",
+                    extra={"url": url, "error": str(e)},
+                )
+                return {"error": str(e)}
+
+    async def fetch_models(self) -> list[Model]:
+        """Fetch models from the upstream Routstr node."""
+        url = f"{self.base_url}/v1/models"
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(url, headers={}, timeout=15.0)
+                response.raise_for_status()
+                data = response.json()
+                models = data.get("data", [])
+                return [Model(**m) for m in models]
+            except Exception as e:
+                logger.error(
+                    "Failed to fetch models from upstream Routstr",
+                    extra={"url": url, "error": str(e)},
+                )
+                return []
+
+    async def refund_balance(self) -> dict[str, Any]:
+        """Request a refund from the upstream Routstr node.
+
+        Returns:
+            Dict containing refund result and token
+        """
+        url = f"{self.base_url}/v1/balance/refund"
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(url, headers=headers, timeout=30.0)
+                response.raise_for_status()
+                return response.json()
+            except Exception as e:
+                logger.error(
+                    "Failed to request refund from upstream Routstr",
+                    extra={"url": url, "error": str(e)},
+                )
+                return {"error": str(e)}

routstr/wallet.py

@@ -1,13 +1,14 @@
 import asyncio
-import math
+import time
 from typing import TypedDict
 
 from cashu.core.base import Proof, Token
 from cashu.wallet.helpers import deserialize_token_from_string
 from cashu.wallet.wallet import Wallet
-from sqlmodel import col, update
+from sqlmodel import col, select, update
 
 from .core import db, get_logger
+from .core.db import store_cashu_transaction
 from .core.settings import settings
 from .payment.lnurl import raw_send_to_lnurl
 
@@ -34,6 +35,7 @@ async def recieve_token(
 
     wallet.verify_proofs_dleq(token_obj.proofs)
     await wallet.split(proofs=token_obj.proofs, amount=0, include_fees=True)
+
     return token_obj.amount, token_obj.unit, token_obj.mint
 
 
@@ -58,15 +60,86 @@ async def send_token(amount: int, unit: str, mint_url: str | None = None) -> str
     return token
 
 
+async def _calculate_swap_amount(
+    amount_msat: int,
+    token_unit: str,
+    token_mint_url: str,
+    token_wallet: Wallet,
+    primary_wallet: Wallet,
+) -> int:
+    """
+    Calculate the amount to mint on the primary mint after accounting for
+    potential swap fees (melt fees) on the foreign mint.
+    """
+    if settings.primary_mint_unit == "sat":
+        receive_amount = amount_msat // 1000
+    else:
+        receive_amount = amount_msat
+
+    if token_mint_url == settings.primary_mint:
+        logger.info(
+            "swap_to_primary_mint: skipping fee estimation (same mint)",
+            extra={"minted_amount": receive_amount},
+        )
+        return int(receive_amount)
+
+    logger.info(
+        "swap_to_primary_mint: estimating fees",
+        extra={
+            "dummy_amount": receive_amount,
+            "unit": settings.primary_mint_unit,
+        },
+    )
+
+    try:
+        dummy_mint_quote = await primary_wallet.request_mint(receive_amount)
+        dummy_melt_quote = await token_wallet.melt_quote(dummy_mint_quote.request)
+
+        fee_reserve = dummy_melt_quote.fee_reserve
+        if token_unit == "sat":
+            fee_msat = fee_reserve * 1000
+        else:
+            fee_msat = fee_reserve
+
+        amount_msat_after_fee = amount_msat - fee_msat
+
+        if settings.primary_mint_unit == "sat":
+            minted_amount = int(amount_msat_after_fee // 1000)
+        else:
+            minted_amount = int(amount_msat_after_fee)
+
+        if minted_amount <= 0:
+            raise ValueError(f"Fees ({fee_reserve} {token_unit}) exceed token amount")
+
+        logger.info(
+            "swap_to_primary_mint: fee estimation result",
+            extra={
+                "token_amount_sat": amount_msat // 1000,
+                "estimated_fee_sat": fee_msat // 1000,
+                "minted_amount": minted_amount,
+                "minted_unit": settings.primary_mint_unit,
+            },
+        )
+        return minted_amount
+
+    except Exception as e:
+        logger.error(
+            "swap_to_primary_mint: fee estimation failed",
+            extra={"error": str(e)},
+        )
+        raise ValueError(f"Failed to estimate fees: {e}") from e
+
+
 async def swap_to_primary_mint(
     token_obj: Token, token_wallet: Wallet
 ) -> tuple[int, str, str]:
     logger.info(
-        "swap_to_primary_mint",
+        "swap_to_primary_mint: starting",
         extra={
-            "mint": token_obj.mint,
-            "amount": token_obj.amount,
+            "foreign_mint": token_obj.mint,
+            "token_amount": token_obj.amount,
             "unit": token_obj.unit,
+            "primary_mint": settings.primary_mint,
         },
     )
     # Ensure amount is an integer
@@ -81,24 +154,118 @@ async def swap_to_primary_mint(
         amount_msat = token_amount
     else:
         raise ValueError("Invalid unit")
-    estimated_fee_sat = math.ceil(max(amount_msat // 1000 * 0.01, 2)) + 1
-    amount_msat_after_fee = amount_msat - estimated_fee_sat * 1000
     primary_wallet = await get_wallet(settings.primary_mint, settings.primary_mint_unit)
 
-    if settings.primary_mint_unit == "sat":
-        minted_amount = int(amount_msat_after_fee // 1000)
-    else:
-        minted_amount = int(amount_msat_after_fee)
+    # If the token is already from the primary mint, we don't need to swap
+    # and we definitely don't want to calculate or pay fees.
+    if token_obj.mint == settings.primary_mint:
+        logger.info(
+            "swap_to_primary_mint: token already on primary mint, skipping swap",
+            extra={
+                "mint": token_obj.mint,
+                "amount": token_amount,
+                "unit": token_obj.unit,
+            },
+        )
+        await token_wallet.split(proofs=token_obj.proofs, amount=0, include_fees=True)
+        return token_amount, token_obj.unit, token_obj.mint
+
+    minted_amount = await _calculate_swap_amount(
+        amount_msat,
+        token_obj.unit,
+        token_obj.mint,
+        token_wallet,
+        primary_wallet,
+    )
+
     mint_quote = await primary_wallet.request_mint(minted_amount)
+    logger.info(
+        "swap_to_primary_mint: mint quote received",
+        extra={"mint_quote_id": mint_quote.quote},
+    )
 
     melt_quote = await token_wallet.melt_quote(mint_quote.request)
-    _ = await token_wallet.melt(
-        proofs=token_obj.proofs,
-        invoice=mint_quote.request,
-        fee_reserve_sat=melt_quote.fee_reserve,
-        quote_id=melt_quote.quote,
+    total_needed = melt_quote.amount + melt_quote.fee_reserve
+    logger.info(
+        "swap_to_primary_mint: melt quote received",
+        extra={
+            "melt_quote_id": melt_quote.quote,
+            "melt_amount": melt_quote.amount,
+            "melt_fee_reserve": melt_quote.fee_reserve,
+            "total_needed": total_needed,
+            "token_amount": token_amount,
+        },
+    )
+
+    if total_needed > token_amount:
+        logger.warning(
+            "swap_to_primary_mint: insufficient token amount for melt fees",
+            extra={
+                "token_amount": token_amount,
+                "melt_amount": melt_quote.amount,
+                "melt_fee_reserve": melt_quote.fee_reserve,
+                "total_needed": total_needed,
+                "shortfall": total_needed - token_amount,
+            },
+        )
+        raise ValueError(
+            f"Token amount ({token_amount} {token_obj.unit}) is insufficient to cover "
+            f"melt fees. Needed: {total_needed} {token_obj.unit} "
+            f"(amount: {melt_quote.amount} + fee: {melt_quote.fee_reserve})"
+        )
+
+    try:
+        _ = await token_wallet.melt(
+            proofs=token_obj.proofs,
+            invoice=mint_quote.request,
+            fee_reserve_sat=melt_quote.fee_reserve,
+            quote_id=melt_quote.quote,
+        )
+    except Exception as e:
+        logger.error(
+            "swap_to_primary_mint: melt failed",
+            extra={
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "foreign_mint": token_obj.mint,
+                "token_amount": token_amount,
+                "melt_quote_id": melt_quote.quote,
+                "total_needed": total_needed,
+            },
+        )
+        raise ValueError(
+            f"Failed to melt token from foreign mint {token_obj.mint}: {e}"
+        ) from e
+
+    logger.info(
+        "swap_to_primary_mint: melt succeeded, minting on primary",
+        extra={"minted_amount": minted_amount, "mint_quote_id": mint_quote.quote},
+    )
+
+    try:
+        _ = await primary_wallet.mint(minted_amount, quote_id=mint_quote.quote)
+    except Exception as e:
+        logger.error(
+            "swap_to_primary_mint: mint on primary failed after successful melt",
+            extra={
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "minted_amount": minted_amount,
+                "mint_quote_id": mint_quote.quote,
+            },
+        )
+        raise
+
+    logger.info(
+        "swap_to_primary_mint: completed successfully",
+        extra={
+            "foreign_mint": token_obj.mint,
+            "primary_mint": settings.primary_mint,
+            "original_amount": token_amount,
+            "minted_amount": minted_amount,
+            "unit": settings.primary_mint_unit,
+        },
     )
-    _ = await primary_wallet.mint(minted_amount, quote_id=mint_quote.quote)
 
     return int(minted_amount), settings.primary_mint_unit, settings.primary_mint
 
@@ -113,6 +280,8 @@ async def credit_balance(
 
     try:
         amount, unit, mint_url = await recieve_token(cashu_token)
+        original_amount = amount
+        original_unit = unit
         logger.info(
             "credit_balance: Token redeemed successfully",
             extra={"amount": amount, "unit": unit, "mint_url": mint_url},
@@ -144,6 +313,19 @@ async def credit_balance(
             extra={"new_balance": key.balance},
         )
 
+        try:
+            await store_cashu_transaction(
+                token=cashu_token,
+                amount=original_amount,
+                unit=original_unit,
+                mint_url=mint_url,
+                typ="in",
+                source="apikey",
+                api_key_hashed_key=key.hashed_key,
+            )
+        except Exception:
+            pass
+
         logger.info(
             "Cashu token successfully redeemed and stored",
             extra={"amount": amount, "unit": unit, "mint_url": mint_url},
@@ -319,6 +501,7 @@ async def periodic_payout() -> None:
                             wallet, mint_url, unit, not_reserved=True
                         )
                         proofs = await slow_filter_spend_proofs(proofs, wallet)
+                        await asyncio.sleep(5)
                         user_balance = await db.balances_for_mint_and_unit(
                             session, mint_url, unit
                         )
@@ -344,8 +527,6 @@ async def periodic_payout() -> None:
                                     "amount_received": amount_received,
                                 },
                             )
-
-                        await asyncio.sleep(5)
         except Exception as e:
             logger.error(
                 f"Error sending payout: {type(e).__name__}",
@@ -353,6 +534,101 @@ async def periodic_payout() -> None:
             )
 
 
+async def periodic_refund_sweep() -> None:
+    while True:
+        await asyncio.sleep(60 * 60)  # every hour
+        try:
+            cutoff = int(time.time()) - settings.refund_sweep_ttl_seconds
+            async with db.create_session() as session:
+                stmt = select(db.CashuTransaction).where(
+                    db.CashuTransaction.type == "out",
+                    db.CashuTransaction.collected == False,  # noqa: E712
+                    db.CashuTransaction.swept == False,  # noqa: E712
+                    db.CashuTransaction.created_at < cutoff,
+                )
+                results = await session.exec(stmt)
+                refunds = results.all()
+
+                for refund in refunds:
+                    try:
+                        await recieve_token(refund.token)
+                        refund.swept = True
+                        session.add(refund)
+                        logger.info(
+                            "Swept uncollected refund",
+                            extra={
+                                "id": refund.id,
+                                "amount": refund.amount,
+                                "unit": refund.unit,
+                            },
+                        )
+                    except Exception as e:
+                        error_msg = str(e).lower()
+                        if "already spent" in error_msg:
+                            refund.collected = True
+                            session.add(refund)
+                            logger.info(
+                                "Refund already spent (client collected), marking swept",
+                                extra={
+                                    "id": refund.id,
+                                },
+                            )
+                        else:
+                            logger.warning(
+                                "Failed to sweep refund",
+                                extra={
+                                    "id": refund.id,
+                                    "error": str(e),
+                                },
+                            )
+                await session.commit()
+        except Exception as e:
+            logger.error(
+                "Error in periodic refund sweep",
+                extra={"error": str(e), "error_type": type(e).__name__},
+            )
+
+
+async def periodic_routstr_fee_payout() -> None:
+    from .auth import (
+        ROUTSTR_FEE_DEFAULT_PAYOUT,
+        ROUTSTR_FEE_PAYOUT_INTERVAL_SECONDS,
+        ROUTSTR_LN_ADDRESS,
+    )
+
+    if not ROUTSTR_LN_ADDRESS:
+        logger.info("ROUTSTR_LN_ADDRESS not set, skipping fee payout")
+        return
+    while True:
+        await asyncio.sleep(ROUTSTR_FEE_PAYOUT_INTERVAL_SECONDS)
+        try:
+            async with db.create_session() as session:
+                fee = await db.get_routstr_fee(session)
+                accumulated_sats = fee.accumulated_msats // 1000
+                if accumulated_sats >= ROUTSTR_FEE_DEFAULT_PAYOUT:
+                    wallet = await get_wallet(settings.primary_mint, "sat")
+                    proofs = get_proofs_per_mint_and_unit(
+                        wallet, settings.primary_mint, "sat", not_reserved=True
+                    )
+                    amount_received = await raw_send_to_lnurl(
+                        wallet, proofs, ROUTSTR_LN_ADDRESS, "sat", amount=accumulated_sats
+                    )
+                    paid_msats = accumulated_sats * 1000
+                    await db.reset_routstr_fee(session, paid_msats)
+                    logger.info(
+                        "Routstr fee payout sent",
+                        extra={
+                            "accumulated_sats": accumulated_sats,
+                            "amount_received": amount_received,
+                        },
+                    )
+        except Exception as e:
+            logger.error(
+                f"Error in Routstr fee payout: {type(e).__name__}",
+                extra={"error": str(e)},
+            )
+
+
 async def send_to_lnurl(amount: int, unit: str, mint: str, address: str) -> int:
     wallet = await get_wallet(mint, unit)
     proofs = wallet._get_proofs_per_keyset(wallet.proofs)[wallet.keyset_id]

tests/integration/conftest.py

@@ -380,6 +380,13 @@ async def integration_session(
         yield session
 
 
+@pytest_asyncio.fixture
+async def patched_db_engine(integration_engine: Any) -> AsyncGenerator[None, None]:
+    """Patch the global db engine so create_session() uses the test engine."""
+    with patch("routstr.core.db.engine", integration_engine):
+        yield
+
+
 class DatabaseSnapshot:
     """Utility to capture and compare database states"""
 

tests/integration/test_admin_provider_balance.py

@@ -0,0 +1,80 @@
+from datetime import datetime, timedelta, timezone
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.admin import admin_sessions
+from routstr.core.db import UpstreamProviderRow
+
+
+async def _create_routstr_provider() -> UpstreamProviderRow:
+    return UpstreamProviderRow(
+        provider_type="routstr",
+        base_url="https://upstream.example",
+        api_key="",
+        enabled=True,
+    )
+
+
+def _admin_headers() -> dict[str, str]:
+    token = "test-admin-token"
+    admin_sessions[token] = int(
+        (datetime.now(timezone.utc) + timedelta(minutes=5)).timestamp()
+    )
+    return {"Authorization": f"Bearer {token}"}
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_admin_routstr_provider_balance_timeout_returns_504(
+    integration_client: httpx.AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    provider = await _create_routstr_provider()
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+
+    request = httpx.Request("GET", f"{provider.base_url}/v1/balance/info")
+    timeout_error = httpx.ConnectTimeout("Connect timeout", request=request)
+
+    with patch(
+        "httpx.AsyncHTTPTransport.handle_async_request",
+        new=AsyncMock(side_effect=timeout_error),
+    ):
+        response = await integration_client.get(
+            f"/admin/api/upstream-providers/{provider.id}/balance",
+            headers=_admin_headers(),
+        )
+
+    assert response.status_code == 504
+    assert response.json()["detail"] == "Timed out contacting upstream Routstr provider"
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_admin_routstr_provider_balance_request_error_returns_502(
+    integration_client: httpx.AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    provider = await _create_routstr_provider()
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+
+    request = httpx.Request("GET", f"{provider.base_url}/v1/balance/info")
+    request_error = httpx.ConnectError("Connection failed", request=request)
+
+    with patch(
+        "httpx.AsyncHTTPTransport.handle_async_request",
+        new=AsyncMock(side_effect=request_error),
+    ):
+        response = await integration_client.get(
+            f"/admin/api/upstream-providers/{provider.id}/balance",
+            headers=_admin_headers(),
+        )
+
+    assert response.status_code == 502
+    assert response.json()["detail"] == "Failed to contact upstream Routstr provider"

tests/integration/test_balance_negative_on_cost_overrun.py

@@ -0,0 +1,369 @@
+"""
+Integration tests for the balance-goes-negative bug in adjust_payment_for_tokens.
+
+Root cause: when actual token cost exceeds the discounted reservation
+(cost_difference > 0, caused by tolerance_percentage discounting the reservation),
+the finalization UPDATE had no WHERE guard on balance, allowing balance to go negative.
+
+Fix: added `.where(col(ApiKey.balance) >= total_cost_msats)` so the UPDATE is a no-op
+when balance is insufficient, then falls back to charging only deducted_max_cost.
+"""
+
+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,
+    )
+
+
+async def _refresh(session: AsyncSession, key: ApiKey) -> ApiKey:
+    await session.refresh(key)
+    return key
+
+
+# ---------------------------------------------------------------------------
+# Helper: build a CostData where token cost > deducted_max_cost
+# ---------------------------------------------------------------------------
+
+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,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Test 1 — exact reproduction of the bug
+#
+# Setup: balance == deducted_max_cost (user has just enough for the reservation,
+#         nothing extra). Actual token cost is 1% higher (tolerance_percentage).
+#
+# Before fix: balance -= total_cost_msats → goes negative.
+# After fix:  WHERE balance >= total_cost_msats fails → fallback charges
+#             deducted_max_cost → balance reaches 0, never negative.
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_balance_never_negative_when_cost_exceeds_reservation(
+    integration_session: AsyncSession,
+) -> None:
+    """Balance must not go negative when actual token cost > discounted reservation."""
+    from routstr.auth import adjust_payment_for_tokens
+
+    deducted_max_cost = 990  # reserved (1% below true max of 1000)
+    actual_token_cost = 1000  # actual cost at true max
+
+    # User has balance exactly equal to the reservation — tight budget
+    key = _make_key(balance=deducted_max_cost, reserved=deducted_max_cost)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    response_data = {"model": "test-model", "usage": {"prompt_tokens": 100, "completion_tokens": 100}}
+
+    with patch(
+        "routstr.auth.calculate_cost",
+        return_value=_cost_data(actual_token_cost),
+    ):
+        await adjust_payment_for_tokens(key, response_data, integration_session, deducted_max_cost)
+
+    await _refresh(integration_session, key)
+
+    assert key.balance >= 0, f"Balance went negative: {key.balance}"
+    assert key.reserved_balance >= 0, f"Reserved balance went negative: {key.reserved_balance}"
+    assert key.reserved_balance == 0, "Reservation must be fully released after finalization"
+
+
+# ---------------------------------------------------------------------------
+# Test 2 — balance is ZERO after the reservation is accounted for
+#           (absolute floor case)
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_balance_floor_at_zero_on_overrun(
+    integration_session: AsyncSession,
+) -> None:
+    """When balance exactly covers deducted_max_cost and cost overruns, balance reaches 0 not negative."""
+    from routstr.auth import adjust_payment_for_tokens
+
+    deducted_max_cost = 500
+    actual_token_cost = 550  # 10% overrun
+
+    key = _make_key(balance=500, reserved=500)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    response_data = {"model": "test-model", "usage": {"prompt_tokens": 50, "completion_tokens": 50}}
+
+    with patch(
+        "routstr.auth.calculate_cost",
+        return_value=_cost_data(actual_token_cost),
+    ):
+        await adjust_payment_for_tokens(key, response_data, integration_session, deducted_max_cost)
+
+    await _refresh(integration_session, key)
+
+    assert key.balance == 0, (
+        f"Expected balance=0 (charged deducted_max_cost fallback), got {key.balance}"
+    )
+    assert key.reserved_balance == 0, f"Reserved balance should be 0, got {key.reserved_balance}"
+    # Fallback charges deducted_max_cost
+    assert key.total_spent == deducted_max_cost, (
+        f"Expected total_spent={deducted_max_cost}, got {key.total_spent}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Test 3 — balance has enough room: full token cost should be charged
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_full_cost_charged_when_balance_sufficient_for_overrun(
+    integration_session: AsyncSession,
+) -> None:
+    """When balance covers total_cost_msats, the full amount is charged (not just deducted_max_cost)."""
+    from routstr.auth import adjust_payment_for_tokens
+
+    deducted_max_cost = 990
+    actual_token_cost = 1000
+
+    # User has extra balance beyond the reservation
+    key = _make_key(balance=2000, reserved=990)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    response_data = {"model": "test-model", "usage": {"prompt_tokens": 100, "completion_tokens": 100}}
+
+    with patch(
+        "routstr.auth.calculate_cost",
+        return_value=_cost_data(actual_token_cost),
+    ):
+        await adjust_payment_for_tokens(key, response_data, integration_session, deducted_max_cost)
+
+    await _refresh(integration_session, key)
+
+    assert key.balance >= 0, f"Balance went negative: {key.balance}"
+    assert key.reserved_balance == 0, f"Reservation not released: {key.reserved_balance}"
+    assert key.total_spent == actual_token_cost, (
+        f"Expected full charge of {actual_token_cost}, got {key.total_spent}"
+    )
+    assert key.balance == 2000 - actual_token_cost, (
+        f"Expected balance={2000 - actual_token_cost}, got {key.balance}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Test 4 — concurrent finalizations with cost overrun
+#
+# Multiple requests finish concurrently. Each has a small overrun.
+# None should drive balance negative.
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_concurrent_cost_overruns_never_negative(
+    integration_session: AsyncSession,
+    patched_db_engine: None,
+) -> None:
+    """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.core.db import create_session
+
+    deducted_max_cost = 990
+    actual_token_cost = 1000
+    n_requests = 5
+
+    # Fund the key with exactly enough for n_requests reservations + a tiny buffer
+    starting_balance = deducted_max_cost * n_requests
+    key_hash = f"test_concurrent_{uuid.uuid4().hex}"
+
+    async with create_session() as session:
+        key = ApiKey(
+            hashed_key=key_hash,
+            balance=starting_balance,
+            reserved_balance=0,
+            total_spent=0,
+            total_requests=0,
+        )
+        session.add(key)
+        await session.commit()
+
+    # Reserve n_requests slots (sequentially, as pay_for_request is atomic)
+    async with create_session() as session:
+        key_to_reserve = await session.get(ApiKey, key_hash)
+        assert key_to_reserve is not None
+        for _ in range(n_requests):
+            await pay_for_request(key_to_reserve, deducted_max_cost, session)
+            await session.refresh(key_to_reserve)
+
+    # Now finalize all concurrently with cost overrun
+    async def finalize() -> None:
+        response_data = {
+            "model": "test-model",
+            "usage": {"prompt_tokens": 100, "completion_tokens": 100},
+        }
+        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 asyncio.gather(*[finalize() for _ in range(n_requests)])
+
+    async with create_session() as session:
+        final_key = await session.get(ApiKey, key_hash)
+        assert final_key is not None
+
+    assert final_key.balance >= 0, (
+        f"Balance went negative after concurrent overruns: {final_key.balance}"
+    )
+    assert final_key.reserved_balance == 0, (
+        f"Reserved balance not fully released: {final_key.reserved_balance}"
+    )
+    assert final_key.total_spent <= starting_balance, (
+        f"Total spent ({final_key.total_spent}) exceeds starting balance ({starting_balance})"
+    )
+    # Every request must have been charged at least deducted_max_cost — no free inference.
+    assert final_key.total_spent == starting_balance, (
+        f"Expected total_spent={starting_balance} (all {n_requests} reservations charged), "
+        f"got {final_key.total_spent} — at least one request got free inference"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Test 5 — overrun with no balance at all (reserved_balance == balance)
+#           simulates a user who topped up to exactly the reservation floor
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_zero_free_balance_overrun_is_safe(
+    integration_session: AsyncSession,
+) -> None:
+    """User with zero free balance (all reserved) should never go negative on overrun."""
+    from routstr.auth import adjust_payment_for_tokens
+
+    deducted_max_cost = 1000
+    actual_token_cost = 1050
+
+    # balance == reserved_balance: zero free balance
+    key = _make_key(balance=1000, reserved=1000)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    response_data = {"model": "test-model", "usage": {"prompt_tokens": 50, "completion_tokens": 100}}
+
+    with patch(
+        "routstr.auth.calculate_cost",
+        return_value=_cost_data(actual_token_cost),
+    ):
+        await adjust_payment_for_tokens(key, response_data, integration_session, deducted_max_cost)
+
+    await _refresh(integration_session, key)
+
+    assert key.balance >= 0, f"Balance went negative: {key.balance}"
+    assert key.reserved_balance >= 0, f"Reserved balance went negative: {key.reserved_balance}"
+
+
+# ---------------------------------------------------------------------------
+# Test 6 — parallel requests: second finalization must not get free inference
+#
+# Root cause of the bug fixed in auth.py:
+#   `.where(col(ApiKey.balance) >= total_cost_msats)` ignores other requests'
+#   reservations, so after Request A charges total_cost_msats, balance can drop
+#   below deducted_max_cost, causing Request B's fallback to release for free.
+#
+# Fix: use `balance - reserved_balance + deducted_max_cost >= total_cost_msats`
+#   so the check accounts for concurrent reservations.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_parallel_requests_no_free_inference(
+    integration_session: AsyncSession,
+    patched_db_engine: None,
+) -> None:
+    """Second parallel finalization must be charged even when first depleted free balance."""
+    import asyncio
+
+    from routstr.auth import adjust_payment_for_tokens
+    from routstr.core.db import create_session
+
+    deducted_max_cost = 100
+    actual_token_cost = 150  # overrun: 50 more than reserved
+
+    # Fund the key with exactly 2 * deducted_max_cost.
+    # Both requests pre-reserved 100 each → balance=200, reserved=200, free=0.
+    # Old check (balance >= total_cost_msats):
+    #   Request A: 200 >= 150 ✓ → charges 150 → balance=50, reserved=100
+    #   Request B: 50 >= 150 ✗ → fallback: 50 >= 100 ✗ → releases FREE
+    # New check (balance - reserved + deducted >= total_cost_msats):
+    #   Both fall to fallback (0 free balance).
+    #   Both charge deducted_max_cost=100 → total_spent=200, balance=0.
+    starting_balance = deducted_max_cost * 2
+    key_hash = f"test_parallel_no_free_{uuid.uuid4().hex}"
+
+    async with create_session() as session:
+        key = ApiKey(
+            hashed_key=key_hash,
+            balance=starting_balance,
+            reserved_balance=deducted_max_cost * 2,  # both slots pre-reserved
+            total_spent=0,
+            total_requests=2,
+        )
+        session.add(key)
+        await session.commit()
+
+    async def finalize() -> None:
+        response_data = {
+            "model": "test-model",
+            "usage": {"prompt_tokens": 50, "completion_tokens": 100},
+        }
+        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 asyncio.gather(finalize(), finalize())
+
+    async with create_session() as session:
+        final_key = await session.get(ApiKey, key_hash)
+        assert final_key is not None
+
+    assert final_key.balance >= 0, f"Balance went negative: {final_key.balance}"
+    assert final_key.reserved_balance == 0, (
+        f"Reserved balance not released: {final_key.reserved_balance}"
+    )
+    # Both requests must have been charged — no free inference.
+    assert final_key.total_spent == starting_balance, (
+        f"Expected total_spent={starting_balance} (both reservations charged), "
+        f"got {final_key.total_spent} — one request got free inference"
+    )

tests/integration/test_child_keys.py

@@ -0,0 +1,141 @@
+import secrets
+from typing import Any
+
+import pytest
+from fastapi import HTTPException
+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.settings import settings
+
+
+@pytest.mark.asyncio
+async def test_child_key_flow(integration_session: AsyncSession) -> None:
+    # 1. Create a parent key with balance
+    parent_raw = "parent_test_key_" + secrets.token_hex(4)
+    parent_key = ApiKey(
+        hashed_key=parent_raw,
+        balance=10000,  # 10 sats
+    )
+    integration_session.add(parent_key)
+    await integration_session.commit()
+    await integration_session.refresh(parent_key)
+
+    # Mock settings
+    settings.child_key_cost = 1000  # 1 sat
+
+    # 2. Call create_child_key
+    result = await create_child_key(
+        ChildKeyRequest(count=1), parent_key, integration_session
+    )
+
+    assert "api_keys" in result
+    assert result["cost_msats"] == 1000
+    assert result["parent_balance"] == 9000
+
+    child_key_raw = result["api_keys"][0][3:]  # remove sk-
+
+    # 3. Verify child key exists in DB
+    child_key_db = await integration_session.get(ApiKey, child_key_raw)
+    assert child_key_db is not None
+    assert child_key_db.parent_key_hash == parent_key.hashed_key
+    assert child_key_db.balance == 0
+
+    # 4. Test payment with child key
+    cost = 500
+    await pay_for_request(child_key_db, cost, integration_session)
+
+    # Refresh keys
+    await integration_session.refresh(parent_key)
+    await integration_session.refresh(child_key_db)
+
+    # Parent should be charged
+    assert parent_key.reserved_balance == 500
+    assert parent_key.total_requests == 1
+
+    # Child should have total_requests incremented
+    assert child_key_db.total_requests == 1
+
+    # 5. Test adjustment
+    response_data = {"model": "test-model", "usage": {"total_tokens": 10}}
+
+    # Mock calculate_cost
+    import routstr.auth
+    from routstr.payment.cost_calculation import CostData
+
+    async def mock_calculate_cost(*args: Any, **kwargs: Any) -> CostData:
+        return CostData(
+            base_msats=0, input_msats=200, output_msats=200, total_msats=400
+        )
+
+    # Patch calculate_cost
+    original_calculate_cost = routstr.auth.calculate_cost
+    routstr.auth.calculate_cost = mock_calculate_cost
+
+    try:
+        adjustment = await adjust_payment_for_tokens(
+            child_key_db, response_data, integration_session, 500
+        )
+        assert adjustment["total_msats"] == 400
+
+        # Refresh keys
+        await integration_session.refresh(parent_key)
+        await integration_session.refresh(child_key_db)
+
+        # Parent should have updated balance and total_spent
+        assert parent_key.reserved_balance == 0
+        assert parent_key.balance == 9000 - 400
+        assert (
+            parent_key.total_spent == 1400
+        )  # 1000 for child key creation + 400 for request
+
+        # Child should also have total_spent updated
+        assert child_key_db.total_spent == 400
+
+    finally:
+        routstr.auth.calculate_cost = original_calculate_cost
+
+
+@pytest.mark.asyncio
+async def test_child_key_insufficient_balance(
+    integration_session: AsyncSession,
+) -> None:
+    parent_key = ApiKey(
+        hashed_key="poor_parent_" + secrets.token_hex(4),
+        balance=500,
+    )
+    integration_session.add(parent_key)
+    await integration_session.commit()
+    await integration_session.refresh(parent_key)
+
+    settings.child_key_cost = 1000
+
+    with pytest.raises(HTTPException) as exc:
+        await create_child_key(
+            ChildKeyRequest(count=1), parent_key, integration_session
+        )
+    assert exc.value.status_code == 402
+
+
+@pytest.mark.asyncio
+async def test_child_key_cannot_create_child(integration_session: AsyncSession) -> None:
+    parent_key = ApiKey(
+        hashed_key="parent_" + secrets.token_hex(4),
+        balance=10000,
+    )
+    child_key = ApiKey(
+        hashed_key="child_" + secrets.token_hex(4),
+        balance=0,
+        parent_key_hash=parent_key.hashed_key,
+    )
+    integration_session.add(parent_key)
+    integration_session.add(child_key)
+    await integration_session.commit()
+    await integration_session.refresh(child_key)
+
+    with pytest.raises(HTTPException) as exc:
+        await create_child_key(ChildKeyRequest(count=1), child_key, integration_session)
+    assert exc.value.status_code == 400
+    assert "Cannot create a child key for another child key" in str(exc.value.detail)

tests/integration/test_child_keys_api.py

@@ -0,0 +1,97 @@
+from typing import Any
+
+import pytest
+from httpx import AsyncClient
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_wallet_info_returns_child_keys(
+    integration_client: AsyncClient,
+    authenticated_client: AsyncClient,
+    integration_session: Any,
+) -> None:
+    """Test that GET /v1/wallet/info returns child keys for a parent key"""
+
+    # 1. Get parent info to find its hashed_key
+    response = await authenticated_client.get("/v1/wallet/info")
+    assert response.status_code == 200
+    parent_data = response.json()
+    parent_data["api_key"]
+
+    # 2. Create child keys for this parent
+    # We need to use the parent's authentication for this
+    child_payload = {"count": 2, "balance_limit": 1000, "balance_limit_reset": "daily"}
+    create_response = await authenticated_client.post(
+        "/v1/wallet/child-key", json=child_payload
+    )
+    assert create_response.status_code == 200
+    create_data = create_response.json()
+    child_keys = create_data["api_keys"]
+    assert len(child_keys) == 2
+
+    # 3. Call /info again and check for child_keys
+    info_response = await authenticated_client.get("/v1/wallet/info")
+    assert info_response.status_code == 200
+    info_data = info_response.json()
+
+    assert "child_keys" in info_data
+    assert len(info_data["child_keys"]) == 2
+
+    # Verify child key details
+    for ck in info_data["child_keys"]:
+        assert ck["api_key"] in child_keys
+        assert ck["balance_limit"] == 1000
+        assert ck["balance_limit_reset"] == "daily"
+        assert "total_spent" in ck
+        assert "total_requests" in ck
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_wallet_info_child_key_no_child_keys(
+    integration_client: AsyncClient,
+    authenticated_client: AsyncClient,
+    integration_session: Any,
+) -> None:
+    """Test that GET /v1/wallet/info for a child key does NOT return child_keys"""
+
+    # 1. Create a child key
+    child_payload = {"count": 1}
+    create_response = await authenticated_client.post(
+        "/v1/wallet/child-key", json=child_payload
+    )
+    assert create_response.status_code == 200
+    child_key = create_response.json()["api_keys"][0]
+
+    # 2. Use the child key to get its info
+    integration_client.headers["Authorization"] = f"Bearer {child_key}"
+    info_response = await integration_client.get("/v1/wallet/info")
+    assert info_response.status_code == 200
+    info_data = info_response.json()
+
+    assert info_data["is_child"] is True
+    assert "child_keys" not in info_data
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_account_info_root_returns_child_keys(
+    authenticated_client: AsyncClient,
+) -> None:
+    """Test that GET / returns child keys for a parent key (root endpoint)"""
+
+    # 1. Create a child key
+    child_payload = {"count": 1}
+    await authenticated_client.post("/v1/wallet/child-key", json=child_payload)
+
+    # 2. Call root endpoint /v1/balance/
+    # Note: routstr/balance.py defines router = APIRouter()
+    # and it is included in balance_router with prefix /v1/balance
+    # The endpoint is @router.get("/")
+    response = await authenticated_client.get("/v1/balance/")
+    assert response.status_code == 200
+    data = response.json()
+
+    assert "child_keys" in data
+    assert len(data["child_keys"]) >= 1

tests/integration/test_cli_tokens.py

@@ -0,0 +1,302 @@
+"""Integration tests for CLI token management (/admin/api/cli-tokens).
+
+Covers:
+- GET    /admin/api/cli-tokens           — list (preview only, no full token)
+- POST   /admin/api/cli-tokens           — create (returns full token once)
+- DELETE /admin/api/cli-tokens/{id}      — revoke
+- Using a CLI token as Bearer auth against admin endpoints
+- Expiry enforcement (expired tokens are rejected by require_admin_api)
+- last_used_at bump on successful use
+- Auth failures: missing token, wrong token, revoked token
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from typing import AsyncGenerator
+
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+from sqlmodel import select
+
+from routstr.core.admin import admin_sessions
+from routstr.core.db import AsyncSession, CliToken
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Fixtures
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest_asyncio.fixture
+async def admin_session_token() -> AsyncGenerator[str, None]:
+    """Inject a short-lived admin session token into admin_sessions."""
+    token = secrets.token_urlsafe(24)
+    admin_sessions[token] = int(time.time()) + 3600
+    yield token
+    admin_sessions.pop(token, None)
+
+
+@pytest_asyncio.fixture
+async def admin_client(
+    integration_client: AsyncClient, admin_session_token: str
+) -> AsyncClient:
+    """An integration_client pre-authenticated with an admin session token."""
+    integration_client.headers["Authorization"] = f"Bearer {admin_session_token}"
+    return integration_client
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Creation
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_create_cli_token_returns_full_token_once(
+    admin_client: AsyncClient,
+) -> None:
+    """POST /admin/api/cli-tokens returns the raw token only on creation."""
+    resp = await admin_client.post(
+        "/admin/api/cli-tokens",
+        json={"name": "my-laptop"},
+    )
+    assert resp.status_code == 200
+    body = resp.json()
+
+    assert body["name"] == "my-laptop"
+    assert isinstance(body["id"], str) and body["id"]
+    assert isinstance(body["token"], str) and len(body["token"]) >= 32
+    assert body["expires_at"] is None
+    assert isinstance(body["created_at"], int)
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_create_cli_token_with_expiry(admin_client: AsyncClient) -> None:
+    """expires_in_days sets expires_at ~= now + days * 86400."""
+    before = int(time.time())
+    resp = await admin_client.post(
+        "/admin/api/cli-tokens",
+        json={"name": "ci-runner", "expires_in_days": 7},
+    )
+    assert resp.status_code == 200
+    body = resp.json()
+
+    assert body["expires_at"] is not None
+    delta = body["expires_at"] - before
+    # Allow 10s jitter around 7 * 86400
+    assert 7 * 86400 - 10 <= delta <= 7 * 86400 + 10
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_create_cli_token_rejects_empty_name(
+    admin_client: AsyncClient,
+) -> None:
+    resp = await admin_client.post(
+        "/admin/api/cli-tokens", json={"name": "   "}
+    )
+    assert resp.status_code == 400
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_create_cli_token_requires_admin(
+    integration_client: AsyncClient,
+) -> None:
+    """No admin token / no bearer → 403."""
+    resp = await integration_client.post(
+        "/admin/api/cli-tokens", json={"name": "no-auth"}
+    )
+    assert resp.status_code == 403
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Listing
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_list_cli_tokens_returns_preview_not_full_token(
+    admin_client: AsyncClient,
+) -> None:
+    """Listing never leaks the raw token."""
+    create = await admin_client.post(
+        "/admin/api/cli-tokens", json={"name": "secret-keeper"}
+    )
+    assert create.status_code == 200
+    full_token = create.json()["token"]
+
+    resp = await admin_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 200
+    items = resp.json()
+    assert any(t["name"] == "secret-keeper" for t in items)
+
+    for t in items:
+        # No 'token' field, only 'token_preview'
+        assert "token" not in t
+        assert "token_preview" in t
+        assert full_token not in t["token_preview"]
+        assert "..." in t["token_preview"]
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_list_cli_tokens_requires_admin(
+    integration_client: AsyncClient,
+) -> None:
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 403
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Using a CLI token as admin auth
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_cli_token_authorizes_admin_endpoints(
+    admin_client: AsyncClient,
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """A freshly-created CLI token can be used as Bearer on admin endpoints."""
+    create = await admin_client.post(
+        "/admin/api/cli-tokens", json={"name": "cli-auth"}
+    )
+    assert create.status_code == 200
+    cli_token = create.json()["token"]
+    token_id = create.json()["id"]
+
+    # Use a NEW client to isolate the header from admin_session_token
+    integration_client.headers["Authorization"] = f"Bearer {cli_token}"
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 200
+
+    # last_used_at should be populated after use
+    row = await integration_session.get(CliToken, token_id)
+    assert row is not None
+    assert row.last_used_at is not None
+    assert row.last_used_at >= row.created_at
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_expired_cli_token_is_rejected(
+    admin_client: AsyncClient,
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """A CLI token with expires_at in the past → 403."""
+    create = await admin_client.post(
+        "/admin/api/cli-tokens",
+        json={"name": "will-expire", "expires_in_days": 1},
+    )
+    assert create.status_code == 200
+    cli_token = create.json()["token"]
+    token_id = create.json()["id"]
+
+    # Force-expire it in the DB
+    row = await integration_session.get(CliToken, token_id)
+    assert row is not None
+    row.expires_at = int(time.time()) - 1
+    integration_session.add(row)
+    await integration_session.commit()
+
+    integration_client.headers["Authorization"] = f"Bearer {cli_token}"
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 403
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_invalid_bearer_token_is_rejected(
+    integration_client: AsyncClient,
+) -> None:
+    integration_client.headers["Authorization"] = "Bearer not-a-real-token"
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 403
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Revocation
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_revoke_cli_token_removes_auth(
+    admin_client: AsyncClient,
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """After DELETE, the token no longer authorizes."""
+    create = await admin_client.post(
+        "/admin/api/cli-tokens", json={"name": "to-revoke"}
+    )
+    token_id = create.json()["id"]
+    cli_token = create.json()["token"]
+
+    revoke = await admin_client.delete(f"/admin/api/cli-tokens/{token_id}")
+    assert revoke.status_code == 200
+    assert revoke.json() == {"ok": True, "deleted_id": token_id}
+
+    # Row is gone
+    row = await integration_session.get(CliToken, token_id)
+    assert row is None
+
+    # Can no longer be used for auth
+    integration_client.headers["Authorization"] = f"Bearer {cli_token}"
+    resp = await integration_client.get("/admin/api/cli-tokens")
+    assert resp.status_code == 403
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_revoke_unknown_cli_token_returns_404(
+    admin_client: AsyncClient,
+) -> None:
+    resp = await admin_client.delete("/admin/api/cli-tokens/does-not-exist")
+    assert resp.status_code == 404
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_revoke_cli_token_requires_admin(
+    integration_client: AsyncClient,
+) -> None:
+    resp = await integration_client.delete("/admin/api/cli-tokens/anything")
+    assert resp.status_code == 403
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Lifecycle / uniqueness
+# ──────────────────────────────────────────────────────────────────────────────
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_multiple_tokens_are_independent(
+    admin_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """Creating N tokens yields N unique tokens that all live in DB."""
+    names = ["dev-a", "dev-b", "dev-c"]
+    raw_tokens: list[str] = []
+    ids: list[str] = []
+    for name in names:
+        r = await admin_client.post(
+            "/admin/api/cli-tokens", json={"name": name}
+        )
+        assert r.status_code == 200
+        raw_tokens.append(r.json()["token"])
+        ids.append(r.json()["id"])
+
+    # All unique
+    assert len(set(raw_tokens)) == len(raw_tokens)
+    assert len(set(ids)) == len(ids)
+
+    # All in DB
+    result = await integration_session.exec(
+        select(CliToken).where(CliToken.name.in_(names))  # type: ignore[attr-defined]
+    )
+    rows = result.all()
+    assert {r.name for r in rows} == set(names)

tests/integration/test_general_info_endpoints.py

@@ -267,10 +267,9 @@ async def test_admin_endpoint_unauthenticated(
     """Test GET /admin/ endpoint redirects to /"""
     await db_snapshot.capture()
 
-    response = await integration_client.get("/admin/")
+    response = await integration_client.get("/admin/api/settings")
 
-    assert response.status_code == 307
-    assert response.headers.get("location") == "/"
+    assert response.status_code == 403
 
     diff = await db_snapshot.diff()
     assert len(diff["api_keys"]["added"]) == 0

tests/integration/test_insufficient_balance.py

@@ -0,0 +1,240 @@
+"""
+Tests showing how a user hits "Insufficient balance: X mSats required for this model"
+when their balance is too low for the model's cost.
+
+The log line that triggered this:
+  WARNING  Insufficient billing balance during validation
+  ERROR    Bearer token validation failed: HTTPException: 402:
+           {'error': {'message': 'Insufficient balance: 622888 mSats required
+           for this model. 20320 available.', ...}}
+
+This happens in validate_bearer_key (auth.py) when:
+  billing_key.total_balance < min_cost   (model's max cost)
+
+and also in pay_for_request when the atomic UPDATE finds no available balance.
+"""
+
+import uuid
+from unittest.mock import patch
+
+import pytest
+from fastapi import HTTPException
+from httpx import AsyncClient
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.db import ApiKey
+
+
+def _key(balance: int, reserved: int = 0) -> ApiKey:
+    return ApiKey(
+        hashed_key=f"test_{uuid.uuid4().hex}",
+        balance=balance,
+        reserved_balance=reserved,
+        total_spent=0,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Test 1 — simplest case: balance < model cost → pay_for_request raises 402
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_pay_for_request_raises_402_when_balance_too_low(
+    integration_session: AsyncSession,
+) -> None:
+    """
+    User has 20_000 msats. Model costs 622_888 msats.
+    pay_for_request must raise HTTP 402 with a clear message.
+    """
+    from routstr.auth import pay_for_request
+
+    model_cost = 622_888
+    user_balance = 20_000
+
+    key = _key(balance=user_balance)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    with pytest.raises(HTTPException) as exc_info:
+        await pay_for_request(key, model_cost, integration_session)
+
+    assert exc_info.value.status_code == 402
+    detail = exc_info.value.detail
+    assert isinstance(detail, dict)
+    error = detail["error"]
+    assert error["code"] == "insufficient_balance"
+    assert str(model_cost) in error["message"]
+    assert str(user_balance) in error["message"]
+
+    # Balance must be untouched
+    await integration_session.refresh(key)
+    assert key.balance == user_balance
+    assert key.reserved_balance == 0
+
+
+# ---------------------------------------------------------------------------
+# Test 2 — balance is zero
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_pay_for_request_raises_402_on_zero_balance(
+    integration_session: AsyncSession,
+) -> None:
+    """User with zero balance cannot make any request."""
+    from routstr.auth import pay_for_request
+
+    key = _key(balance=0)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    with pytest.raises(HTTPException) as exc_info:
+        await pay_for_request(key, 1_000, integration_session)
+
+    assert exc_info.value.status_code == 402
+    detail = exc_info.value.detail
+    assert isinstance(detail, dict)
+    assert detail["error"]["code"] == "insufficient_balance"
+
+
+# ---------------------------------------------------------------------------
+# Test 3 — all balance is reserved (total_balance = balance - reserved = 0)
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_pay_for_request_raises_402_when_all_balance_reserved(
+    integration_session: AsyncSession,
+) -> None:
+    """
+    User has 50_000 msats balance but 50_000 is already reserved for in-flight
+    requests. Free balance (total_balance) = 0. Should get 402.
+    """
+    from routstr.auth import pay_for_request
+
+    key = _key(balance=50_000, reserved=50_000)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    with pytest.raises(HTTPException) as exc_info:
+        await pay_for_request(key, 1_000, integration_session)
+
+    assert exc_info.value.status_code == 402
+    # Balance and reserved must be untouched
+    await integration_session.refresh(key)
+    assert key.balance == 50_000
+    assert key.reserved_balance == 50_000
+
+
+# ---------------------------------------------------------------------------
+# Test 4 — balance just one msat below model cost
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_pay_for_request_raises_402_one_msat_short(
+    integration_session: AsyncSession,
+) -> None:
+    """Off-by-one: balance is exactly model_cost - 1."""
+    from routstr.auth import pay_for_request
+
+    model_cost = 10_000
+    key = _key(balance=model_cost - 1)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    with pytest.raises(HTTPException) as exc_info:
+        await pay_for_request(key, model_cost, integration_session)
+
+    assert exc_info.value.status_code == 402
+    await integration_session.refresh(key)
+    assert key.balance == model_cost - 1   # untouched
+    assert key.reserved_balance == 0
+
+
+# ---------------------------------------------------------------------------
+# Test 5 — balance exactly equal to model cost → succeeds
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_pay_for_request_succeeds_when_balance_equals_cost(
+    integration_session: AsyncSession,
+) -> None:
+    """Balance == model cost: the request should be reserved successfully."""
+    from routstr.auth import pay_for_request
+
+    model_cost = 10_000
+    key = _key(balance=model_cost)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    # Should not raise
+    await pay_for_request(key, model_cost, integration_session)
+
+    await integration_session.refresh(key)
+    assert key.reserved_balance == model_cost
+    assert key.balance == model_cost   # balance unchanged, only reserved goes up
+
+
+# ---------------------------------------------------------------------------
+# Test 6 — HTTP layer returns 402 JSON with the right shape
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_http_402_response_shape_on_insufficient_balance(
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    """
+    End-to-end: POST /v1/chat/completions with a key whose balance is far below
+    the mocked model cost returns HTTP 402 with the expected JSON error body.
+
+    Matches exactly the log snippet in the bug report:
+      'Insufficient balance: X mSats required for this model. Y available.'
+    """
+    from unittest.mock import AsyncMock, MagicMock
+
+    model_cost = 622_888
+    user_balance = 20_320
+
+    key = _key(balance=user_balance)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    # Minimal model stub so proxy routing doesn't 400 before reaching balance check
+    mock_model = MagicMock()
+    mock_model.sats_pricing = None
+
+    # Upstream stub — never reached because balance check fires first
+    mock_upstream = MagicMock()
+    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 where it is used (proxy imports it at module level)
+        patch(
+            "routstr.proxy.get_max_cost_for_model",
+            new=AsyncMock(return_value=model_cost),
+        ),
+    ):
+        response = await integration_client.post(
+            "/v1/chat/completions",
+            headers={"Authorization": f"Bearer sk-{key.hashed_key}"},
+            json={
+                "model": "gpt-4o",
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+
+    assert response.status_code == 402
+    body = response.json()
+    # FastAPI wraps HTTPException detail under "detail"
+    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"]
+
+    # Balance must be completely untouched
+    await integration_session.refresh(key)
+    assert key.balance == user_balance
+    assert key.reserved_balance == 0
+    assert key.total_spent == 0

tests/integration/test_key_logic.py

@@ -0,0 +1,142 @@
+import time
+from datetime import datetime, timedelta
+
+import pytest
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.auth import pay_for_request
+from routstr.core.db import ApiKey
+
+
+@pytest.mark.asyncio
+async def test_key_validity_date(integration_session: AsyncSession) -> None:
+    # 1. Create a key that is expired
+    expired_time = int(time.time()) - 3600
+    key = ApiKey(hashed_key="expired_key", balance=1000, validity_date=expired_time)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    # 2. Try to pay for a request - should fail
+    with pytest.raises(Exception) as excinfo:
+        await pay_for_request(key, 100, integration_session)
+    assert "expired" in str(excinfo.value).lower()
+
+
+@pytest.mark.asyncio
+async def test_key_balance_limit(integration_session: AsyncSession) -> None:
+    # 1. Create a key with a balance limit
+    key = ApiKey(
+        hashed_key="limited_key", balance=10000, balance_limit=500, total_spent=450
+    )
+    integration_session.add(key)
+    await integration_session.commit()
+
+    # 2. Try to pay for a request that exceeds the limit
+    with pytest.raises(Exception) as excinfo:
+        await pay_for_request(key, 100, integration_session)
+    assert "limit exceeded" in str(excinfo.value).lower()
+
+    # 3. Try to pay for a request that fits
+    await pay_for_request(key, 50, integration_session)
+    await integration_session.refresh(key)
+    # Note: total_spent is updated in adjust_payment_for_tokens,
+    # but pay_for_request checks it.
+    # In our current logic, pay_for_request checks (total_spent + cost) > balance_limit.
+
+
+@pytest.mark.asyncio
+async def test_key_daily_reset_policy(integration_session: AsyncSession) -> None:
+    # 1. Create a key with a daily reset policy and old reset date
+    yesterday = int((datetime.now() - timedelta(days=1)).timestamp())
+    key = ApiKey(
+        hashed_key="daily_reset_key",
+        balance=10000,
+        balance_limit=1000,
+        balance_limit_reset="daily",
+        balance_limit_reset_date=yesterday,
+        total_spent=900,
+    )
+    integration_session.add(key)
+    await integration_session.commit()
+
+    # 2. Pay for a request - should trigger reset first because it's a new day
+    # Request is 200, total_spent is 900. 900+200 > 1000,
+    # but reset should happen making total_spent 0, then 0+200 < 1000.
+    await pay_for_request(key, 200, integration_session)
+
+    await integration_session.refresh(key)
+    assert key.total_spent == 0  # Reset in pay_for_request happens before charging
+    # Wait, the charging logic in pay_for_request increments parent/billing_key's total_requests,
+    # but total_spent is updated in adjust_payment_for_tokens.
+    # However, the reset logic sets total_spent to 0.
+    assert key.balance_limit_reset_date is not None
+    assert key.balance_limit_reset_date > yesterday
+
+
+@pytest.mark.asyncio
+async def test_periodic_key_reset_job(integration_session: AsyncSession) -> None:
+    # 1. Create multiple keys needing reset
+    yesterday = int((datetime.now() - timedelta(days=1)).timestamp())
+    key1 = ApiKey(
+        hashed_key="job_reset_key_1",
+        balance=1000,
+        balance_limit=1000,
+        balance_limit_reset="daily",
+        balance_limit_reset_date=yesterday,
+        total_spent=500,
+    )
+    key2 = ApiKey(
+        hashed_key="job_reset_key_2",
+        balance=1000,
+        balance_limit=1000,
+        balance_limit_reset="daily",
+        balance_limit_reset_date=yesterday,
+        total_spent=800,
+    )
+    integration_session.add(key1)
+    integration_session.add(key2)
+    await integration_session.commit()
+
+    # 2. Run the periodic reset logic manually (mocking the background task loop)
+    # We can't easily run the actual loop because it has a sleep,
+    # but we can test the logic inside.
+
+    # Implementation of periodic_key_reset logic for testing:
+    stmt = select(ApiKey).where(ApiKey.balance_limit_reset != None)  # noqa: E711
+    keys = (await integration_session.exec(stmt)).all()
+    now = int(time.time())
+    for k in keys:
+        if k.hashed_key in ["job_reset_key_1", "job_reset_key_2"]:
+            k.total_spent = 0
+            k.balance_limit_reset_date = now
+            integration_session.add(k)
+    await integration_session.commit()
+
+    # 3. Verify resets
+    await integration_session.refresh(key1)
+    await integration_session.refresh(key2)
+    assert key1.total_spent == 0
+    assert key2.total_spent == 0
+
+
+@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
+    from routstr.balance import ApiKey
+
+    key = ApiKey(hashed_key="refund_test_key", balance=1000, reserved_balance=100)
+    integration_session.add(key)
+    await integration_session.commit()
+
+    # Logic from refund_wallet_endpoint:
+    key.balance = 0
+    key.reserved_balance = 0
+    integration_session.add(key)
+    await integration_session.commit()
+
+    # Verify key still exists
+    fetched_key = await integration_session.get(ApiKey, "refund_test_key")
+    assert fetched_key is not None
+    assert fetched_key.balance == 0
+    assert fetched_key.reserved_balance == 0

tests/integration/test_model_price_sync.py

@@ -0,0 +1,190 @@
+"""Integration tests for model price updates when provider fee schedules change."""
+
+import time
+from typing import Any, Generator
+
+import pytest
+from httpx import AsyncClient
+
+from routstr.core.admin import admin_sessions
+
+ADMIN_TOKEN = "test-admin-token"
+
+
+def _auth_header() -> dict[str, str]:
+    return {"Authorization": f"Bearer {ADMIN_TOKEN}"}
+
+
+@pytest.fixture(autouse=True)
+def _inject_admin_session() -> Generator[None, None, None]:
+    admin_sessions[ADMIN_TOKEN] = int(time.time()) + 3600
+    yield
+    admin_sessions.pop(ADMIN_TOKEN, None)
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_model_price_updates_on_fee_schedule_change(
+    integration_client: AsyncClient,
+    patched_db_engine: Any,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Patch fetch_models to return empty list to avoid network errors
+    # and allow DB models to be used
+    from routstr.upstream.base import BaseUpstreamProvider
+
+    async def mock_fetch_models(self: BaseUpstreamProvider) -> list:
+        return []
+
+    monkeypatch.setattr(BaseUpstreamProvider, "fetch_models", mock_fetch_models)
+
+    # 1. Create a provider
+    provider_resp = await integration_client.post(
+        "/admin/api/upstream-providers",
+        json={
+            "provider_type": "custom",
+            "base_url": "https://api.example.com/v1",
+            "api_key": "test-key",
+            "enabled": True,
+            "provider_fee": 1.0,
+        },
+        headers=_auth_header(),
+    )
+    provider_id = provider_resp.json()["id"]
+
+    # 2. Add a model to this provider
+    model_id = "test-model-price-update"
+    await integration_client.post(
+        f"/admin/api/upstream-providers/{provider_id}/models",
+        json={
+            "id": model_id,
+            "name": "Test Model",
+            "created": int(time.time()),
+            "description": "Test",
+            "context_length": 4096,
+            "architecture": {
+                "modality": "text",
+                "input_modalities": ["text"],
+                "output_modalities": ["text"],
+                "tokenizer": "gpt2",
+                "instruct_type": "none",
+            },
+            "pricing": {"prompt": 1.0, "completion": 2.0},
+            "enabled": True,
+        },
+        headers=_auth_header(),
+    )
+
+    # 3. Check initial price (should be prompt=1.0 * fee=1.0 = 1.0)
+    # We use /models endpoint
+    resp = await integration_client.get("/models")
+    models = resp.json()["data"]
+    target = next((m for m in models if m["id"] == model_id), None)
+    assert target is not None
+    assert target["pricing"]["prompt"] == 1.0
+
+    # 4. Update provider fee schedule to a very high value for the current time
+    # We'll use a range that covers the whole day to be safe
+    schedules = [
+        {"start_time": "00:00", "end_time": "23:59", "provider_fee": 2.5},
+    ]
+    await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={"schedules": schedules},
+        headers=_auth_header(),
+    )
+
+    # 5. Check price again - should be updated instantly
+    resp = await integration_client.get("/models")
+    models = resp.json()["data"]
+    target = next((m for m in models if m["id"] == model_id), None)
+    assert target is not None
+    # 1.0 * 2.5 = 2.5
+    assert target["pricing"]["prompt"] == 2.5
+
+    # 6. Delete schedules
+    await integration_client.delete(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        headers=_auth_header(),
+    )
+
+    # 7. Should revert to default fee (1.0)
+    resp = await integration_client.get("/models")
+    models = resp.json()["data"]
+    target = next((m for m in models if m["id"] == model_id), None)
+    assert target is not None
+    assert target["pricing"]["prompt"] == 1.0
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_upstream_model_price_updates_on_fee_schedule_change(
+    integration_client: AsyncClient,
+    patched_db_engine: Any,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from routstr.payment.models import Architecture, Model, Pricing
+    from routstr.upstream.base import BaseUpstreamProvider
+
+    upstream_model_id = "upstream-model-only"
+
+    # Mock fetch_models to return a model
+    async def mock_fetch_models(self: BaseUpstreamProvider) -> list[Model]:
+        return [
+            Model(
+                id=upstream_model_id,
+                name="Upstream Model",
+                created=int(time.time()),
+                description="Test",
+                context_length=4096,
+                architecture=Architecture(
+                    modality="text",
+                    input_modalities=["text"],
+                    output_modalities=["text"],
+                    tokenizer="gpt2",
+                    instruct_type="none",
+                ),
+                pricing=Pricing(prompt=1.0, completion=2.0),
+                enabled=True,
+            )
+        ]
+
+    monkeypatch.setattr(BaseUpstreamProvider, "fetch_models", mock_fetch_models)
+
+    # 1. Create a provider
+    provider_resp = await integration_client.post(
+        "/admin/api/upstream-providers",
+        json={
+            "provider_type": "custom",
+            "base_url": "https://api.example.com/v1",
+            "api_key": "test-key-2",
+            "enabled": True,
+            "provider_fee": 1.0,
+        },
+        headers=_auth_header(),
+    )
+    provider_id = provider_resp.json()["id"]
+
+    # 2. Check initial price (should be prompt=1.0 * fee=1.0 = 1.0)
+    resp = await integration_client.get("/models")
+    models = resp.json()["data"]
+    target = next((m for m in models if m["id"] == upstream_model_id), None)
+    assert target is not None
+    assert target["pricing"]["prompt"] == 1.0
+
+    # 3. Update provider fee schedule
+    schedules = [
+        {"start_time": "00:00", "end_time": "23:59", "provider_fee": 3.0},
+    ]
+    await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={"schedules": schedules},
+        headers=_auth_header(),
+    )
+
+    # 4. Check price again - I expect this to FAIL (still 1.0 instead of 3.0)
+    resp = await integration_client.get("/models")
+    models = resp.json()["data"]
+    target = next((m for m in models if m["id"] == upstream_model_id), None)
+    assert target is not None
+    assert target["pricing"]["prompt"] == 3.0

tests/integration/test_provider_fee_enforcement.py

@@ -0,0 +1,143 @@
+from contextlib import asynccontextmanager
+from typing import Any, AsyncGenerator, cast
+from unittest.mock import patch
+
+import pytest
+
+from routstr.core.db import AsyncSession, ModelRow, UpstreamProviderRow
+from routstr.payment.models import Architecture, Model, Pricing
+from routstr.proxy import refresh_model_maps
+from routstr.upstream.base import BaseUpstreamProvider
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_enforce_lowest_provider_fee_for_same_url(
+    integration_session: Any,
+) -> None:
+    """Test that the algorithm selects the provider with the lowest fee when URLs match."""
+
+    # 1. Create two providers with the same URL but different fees
+    url = "https://api.example.com"
+    p1 = UpstreamProviderRow(
+        provider_type="custom",
+        base_url=url,
+        api_key="key1",
+        enabled=True,
+        provider_fee=1.01,
+    )
+    p2 = UpstreamProviderRow(
+        provider_type="custom",
+        base_url=url,
+        api_key="key2",
+        enabled=True,
+        provider_fee=1.05,
+    )
+
+    integration_session.add(p1)
+    integration_session.add(p2)
+    await integration_session.commit()
+    await integration_session.refresh(p1)
+    await integration_session.refresh(p2)
+
+    assert p1.id is not None
+    assert p2.id is not None
+
+    # 2. Add a model for each provider
+    m1 = 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=p1.id,
+        enabled=True,
+    )
+    m2 = 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=p2.id,
+        enabled=True,
+    )
+
+    integration_session.add(m1)
+    integration_session.add(m2)
+    await integration_session.commit()
+
+    # 3. Create mock provider instances
+    class MockProvider(BaseUpstreamProvider):
+        db_id: int
+
+        def __init__(self, db_id: int, base_url: str, api_key: str, fee: float):
+            super().__init__(base_url, api_key, fee)
+            self.db_id = db_id
+            self.provider_type = "custom"
+
+        def get_cached_models(self) -> list[Model]:
+            return [
+                Model(
+                    id="model-a",
+                    name="Model A",
+                    created=1,
+                    description="desc",
+                    context_length=100,
+                    architecture=Architecture(
+                        modality="text",
+                        input_modalities=["text"],
+                        output_modalities=["text"],
+                        tokenizer="tiktoken",
+                        instruct_type="chat",
+                    ),
+                    pricing=Pricing(prompt=1.0, completion=1.0),
+                    enabled=True,
+                    upstream_provider_id=self.db_id,
+                )
+            ]
+
+        async def refresh_models_cache(self, skip_network: bool = False) -> None:
+            pass
+
+        def prepare_headers(self, request_headers: dict[str, str]) -> dict[str, str]:
+            return request_headers
+
+    # 4. Inject mock providers into the proxy
+    from routstr import proxy
+
+    assert p1.id is not None
+    assert p2.id is not None
+
+    # Need to patch proxy._upstreams and proxy.create_session
+    mp1: MockProvider = MockProvider(p1.id, url, "key1", 1.01)
+    mp2: MockProvider = MockProvider(p2.id, url, "key2", 1.05)
+
+    with (
+        patch("routstr.proxy._upstreams", [mp1, mp2]),
+        patch("routstr.proxy.create_session") as mock_session_factory,
+    ):
+        # Configure mock_session_factory to return a session that uses the test engine
+        @asynccontextmanager
+        async def mock_create_session() -> AsyncGenerator[AsyncSession, None]:
+            yield integration_session
+
+        mock_session_factory.return_value = mock_create_session()
+
+        await refresh_model_maps()
+
+        # 5. Check which provider is selected for 'model-a'
+        provider_map = proxy.get_provider_for_model("model-a")
+
+        # Assertions
+        assert provider_map is not None
+        assert len(provider_map) >= 1
+
+        # Check the first one, cast to MockProvider to access db_id
+        best_provider = cast(MockProvider, provider_map[0])
+        assert best_provider.db_id == p1.id
+        assert best_provider.provider_fee == 1.01

tests/integration/test_provider_fee_schedules.py

@@ -0,0 +1,402 @@
+"""Integration tests for provider fee schedule API endpoints."""
+
+from typing import Any, Generator
+
+import pytest
+from httpx import AsyncClient
+
+from routstr.core.admin import admin_sessions
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+ADMIN_TOKEN = "test-admin-token"
+
+
+def _auth_header() -> dict[str, str]:
+    return {"Authorization": f"Bearer {ADMIN_TOKEN}"}
+
+
+async def _create_provider(client: AsyncClient, *, fee: float = 1.02) -> int:
+    """Create a test provider and return its ID."""
+    resp = await client.post(
+        "/admin/api/upstream-providers",
+        json={
+            "provider_type": "custom",
+            "base_url": "https://api.example.com/v1",
+            "api_key": "test-key",
+            "enabled": True,
+            "provider_fee": fee,
+        },
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 200, resp.text
+    return resp.json()["id"]
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def _inject_admin_session() -> Generator[None, None, None]:
+    """Inject a valid admin session token for all tests."""
+    import time
+
+    admin_sessions[ADMIN_TOKEN] = int(time.time()) + 3600
+    yield
+    admin_sessions.pop(ADMIN_TOKEN, None)
+
+
+@pytest.fixture(autouse=True)
+def _patch_reinitialize(monkeypatch: Any) -> None:
+    async def _noop(*args: Any, **kwargs: Any) -> None:
+        pass
+
+    monkeypatch.setattr("routstr.core.admin.reinitialize_upstreams", _noop)
+    monkeypatch.setattr("routstr.core.admin.refresh_model_maps", _noop)
+
+
+# ---------------------------------------------------------------------------
+# GET fee schedules
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_get_fee_schedules_empty_for_new_provider(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    resp = await integration_client.get(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 200
+    assert resp.json() == []
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_get_fee_schedules_404_for_missing_provider(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    resp = await integration_client.get(
+        "/admin/api/upstream-providers/99999/fee-schedules",
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# PUT fee schedules
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_put_fee_schedules_success(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    schedules = [
+        {"start_time": "08:00", "end_time": "18:00", "provider_fee": 1.05},
+        {"start_time": "18:00", "end_time": "08:00", "provider_fee": 1.02},
+    ]
+    resp = await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={"schedules": schedules},
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 200
+    data = resp.json()
+    assert len(data) == 2
+    assert data[0]["start_time"] == "08:00"
+    assert data[0]["provider_fee"] == 1.05
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_put_fee_schedules_persisted(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    """Saved schedules are returned by a subsequent GET."""
+    provider_id = await _create_provider(integration_client)
+    schedules = [{"start_time": "09:00", "end_time": "17:00", "provider_fee": 1.07}]
+    await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={"schedules": schedules},
+        headers=_auth_header(),
+    )
+    get_resp = await integration_client.get(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        headers=_auth_header(),
+    )
+    assert get_resp.status_code == 200
+    assert get_resp.json()[0]["provider_fee"] == 1.07
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_put_fee_schedules_replaces_existing(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    # Set initial schedule
+    await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={
+            "schedules": [
+                {"start_time": "08:00", "end_time": "12:00", "provider_fee": 1.03}
+            ]
+        },
+        headers=_auth_header(),
+    )
+    # Replace with different schedule
+    resp = await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={
+            "schedules": [
+                {"start_time": "14:00", "end_time": "20:00", "provider_fee": 1.08}
+            ]
+        },
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 200
+    data = resp.json()
+    assert len(data) == 1
+    assert data[0]["start_time"] == "14:00"
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_put_fee_schedules_overlap_rejected(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    schedules = [
+        {"start_time": "08:00", "end_time": "14:00", "provider_fee": 1.05},
+        {"start_time": "12:00", "end_time": "18:00", "provider_fee": 1.03},
+    ]
+    resp = await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={"schedules": schedules},
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 400
+    assert "overlap" in resp.json()["detail"].lower()
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_put_fee_schedules_invalid_time_format_rejected(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    resp = await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={
+            "schedules": [
+                {"start_time": "8:00", "end_time": "18:00", "provider_fee": 1.05}
+            ]
+        },
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 400
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_put_fee_schedules_invalid_fee_rejected(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    resp = await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={
+            "schedules": [
+                {"start_time": "08:00", "end_time": "18:00", "provider_fee": -0.5}
+            ]
+        },
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 400
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_put_fee_schedules_empty_clears_schedules(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    # Set a schedule
+    await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={
+            "schedules": [
+                {"start_time": "08:00", "end_time": "18:00", "provider_fee": 1.05}
+            ]
+        },
+        headers=_auth_header(),
+    )
+    # Clear with empty list
+    resp = await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={"schedules": []},
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 200
+    assert resp.json() == []
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_put_fee_schedules_404_for_missing_provider(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    resp = await integration_client.put(
+        "/admin/api/upstream-providers/99999/fee-schedules",
+        json={"schedules": []},
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# DELETE fee schedules
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_delete_fee_schedules(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    # Add schedules
+    await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={
+            "schedules": [
+                {"start_time": "08:00", "end_time": "18:00", "provider_fee": 1.05}
+            ]
+        },
+        headers=_auth_header(),
+    )
+    # Delete
+    del_resp = await integration_client.delete(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        headers=_auth_header(),
+    )
+    assert del_resp.status_code == 200
+    assert del_resp.json()["ok"] is True
+
+    # Verify schedules are gone
+    get_resp = await integration_client.get(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        headers=_auth_header(),
+    )
+    assert get_resp.json() == []
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_delete_fee_schedules_404_for_missing_provider(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    resp = await integration_client.delete(
+        "/admin/api/upstream-providers/99999/fee-schedules",
+        headers=_auth_header(),
+    )
+    assert resp.status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Fee schedules appear in provider list and detail
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_fee_schedules_in_provider_list(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={
+            "schedules": [
+                {"start_time": "08:00", "end_time": "18:00", "provider_fee": 1.05}
+            ]
+        },
+        headers=_auth_header(),
+    )
+    list_resp = await integration_client.get(
+        "/admin/api/upstream-providers", headers=_auth_header()
+    )
+    assert list_resp.status_code == 200
+    providers = list_resp.json()
+    target = next((p for p in providers if p["id"] == provider_id), None)
+    assert target is not None
+    assert len(target["provider_fee_schedules"]) == 1
+    assert target["provider_fee_schedules"][0]["provider_fee"] == 1.05
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_fee_schedules_in_provider_detail(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={
+            "schedules": [
+                {"start_time": "10:00", "end_time": "22:00", "provider_fee": 1.06}
+            ]
+        },
+        headers=_auth_header(),
+    )
+    detail_resp = await integration_client.get(
+        f"/admin/api/upstream-providers/{provider_id}", headers=_auth_header()
+    )
+    assert detail_resp.status_code == 200
+    data = detail_resp.json()
+    assert len(data["provider_fee_schedules"]) == 1
+    assert data["provider_fee_schedules"][0]["start_time"] == "10:00"
+
+
+# ---------------------------------------------------------------------------
+# Provider deletion clears fee schedules
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_provider_delete_clears_fee_schedules(
+    integration_client: AsyncClient, patched_db_engine: Any
+) -> None:
+    provider_id = await _create_provider(integration_client)
+    await integration_client.put(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        json={
+            "schedules": [
+                {"start_time": "08:00", "end_time": "18:00", "provider_fee": 1.05}
+            ]
+        },
+        headers=_auth_header(),
+    )
+    # Delete provider
+    del_resp = await integration_client.delete(
+        f"/admin/api/upstream-providers/{provider_id}", headers=_auth_header()
+    )
+    assert del_resp.status_code == 200
+
+    # Provider is gone → schedule endpoint returns 404
+    get_resp = await integration_client.get(
+        f"/admin/api/upstream-providers/{provider_id}/fee-schedules",
+        headers=_auth_header(),
+    )
+    assert get_resp.status_code == 404

tests/integration/test_provider_management.py

@@ -3,13 +3,17 @@ Integration tests for provider management functionality.
 Tests GET /v1/providers/ endpoint for listing and managing providers.
 """
 
+import time
+from types import TracebackType
 from typing import Any, Generator
 from unittest.mock import patch
 
 import pytest
 from httpx import AsyncClient
 
-from routstr.discovery import _PROVIDERS_CACHE
+from routstr.core.admin import admin_sessions
+from routstr.core.db import UpstreamProviderRow
+from routstr.nostr.discovery import _PROVIDERS_CACHE
 
 from .utils import ResponseValidator
 
@@ -71,9 +75,10 @@ async def test_providers_endpoint_default_response(
     }
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
-        with patch("routstr.discovery.fetch_provider_health") as mock_fetch:
+        with patch("routstr.nostr.discovery.fetch_provider_health") as mock_fetch:
             # Configure mock to return appropriate responses
             mock_fetch.side_effect = lambda url: mock_fetch_responses.get(
                 url, {"status_code": 500, "json": {"error": "Unknown provider"}}
@@ -135,9 +140,10 @@ async def test_providers_endpoint_with_include_json(
     }
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
-        with patch("routstr.discovery.fetch_provider_health") as mock_fetch:
+        with patch("routstr.nostr.discovery.fetch_provider_health") as mock_fetch:
             mock_fetch.return_value = {
                 "status_code": 200,
                 "json": mock_provider_response,
@@ -209,9 +215,10 @@ async def test_providers_data_structure_validation(
     }
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
-        with patch("routstr.discovery.fetch_provider_health") as mock_fetch:
+        with patch("routstr.nostr.discovery.fetch_provider_health") as mock_fetch:
             mock_fetch.return_value = mock_health_response
 
             response = await integration_client.get("/v1/providers/?include_json=true")
@@ -256,7 +263,8 @@ async def test_providers_endpoint_no_providers_found(
     ]
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
         response = await integration_client.get("/v1/providers/")
 
@@ -317,10 +325,11 @@ async def test_providers_endpoint_offline_providers(
             }
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
         with patch(
-            "routstr.discovery.fetch_provider_health",
+            "routstr.nostr.discovery.fetch_provider_health",
             side_effect=mock_fetch_provider_health,
         ):
             response = await integration_client.get("/v1/providers/?include_json=true")
@@ -386,9 +395,10 @@ async def test_providers_endpoint_duplicate_urls(
     ]
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
-        with patch("routstr.discovery.fetch_provider_health") as mock_fetch:
+        with patch("routstr.nostr.discovery.fetch_provider_health") as mock_fetch:
             mock_fetch.return_value = {
                 "status_code": 200,
                 "endpoint": "root",
@@ -425,7 +435,8 @@ async def test_providers_endpoint_nostr_relay_failures(
         raise Exception("Connection to relay failed")
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", side_effect=failing_query
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        side_effect=failing_query,
     ):
         response = await integration_client.get("/v1/providers/")
 
@@ -463,9 +474,10 @@ async def test_providers_endpoint_malformed_urls(
     ]
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
-        with patch("routstr.discovery.fetch_provider_health") as mock_fetch:
+        with patch("routstr.nostr.discovery.fetch_provider_health") as mock_fetch:
             mock_fetch.return_value = {"status_code": 200, "json": {"status": "online"}}
 
             response = await integration_client.get("/v1/providers/")
@@ -495,9 +507,10 @@ async def test_providers_endpoint_response_format(
     ]
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
-        with patch("routstr.discovery.fetch_provider_health") as mock_fetch:
+        with patch("routstr.nostr.discovery.fetch_provider_health") as mock_fetch:
             mock_fetch.return_value = {"status_code": 200, "json": {"status": "online"}}
 
             # Test default format
@@ -545,9 +558,10 @@ async def test_providers_endpoint_concurrent_requests(
     ]
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
-        with patch("routstr.discovery.fetch_provider_health") as mock_fetch:
+        with patch("routstr.nostr.discovery.fetch_provider_health") as mock_fetch:
             mock_fetch.return_value = {"status_code": 200, "json": {"status": "online"}}
 
             # Create concurrent requests
@@ -587,9 +601,10 @@ async def test_providers_endpoint_parameter_validation(
     ]
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
-        with patch("routstr.discovery.fetch_provider_health") as mock_fetch:
+        with patch("routstr.nostr.discovery.fetch_provider_health") as mock_fetch:
             mock_fetch.return_value = {"status_code": 200, "json": {"status": "online"}}
 
             # Test various parameter values
@@ -639,9 +654,10 @@ async def test_no_database_changes_during_provider_operations(
     ]
 
     with patch(
-        "routstr.discovery.query_nostr_relay_for_providers", return_value=mock_events
+        "routstr.nostr.discovery.query_nostr_relay_for_providers",
+        return_value=mock_events,
     ):
-        with patch("routstr.discovery.fetch_provider_health") as mock_fetch:
+        with patch("routstr.nostr.discovery.fetch_provider_health") as mock_fetch:
             mock_fetch.return_value = {"status_code": 200, "json": {"status": "online"}}
 
             # Make multiple requests with different parameters
@@ -666,3 +682,88 @@ async def test_no_database_changes_during_provider_operations(
     assert final_diff["api_keys"]["added"] == []
     assert final_diff["api_keys"]["modified"] == []
     assert final_diff["api_keys"]["removed"] == []
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_admin_routstr_topup_retries_transient_upstream_failure(
+    integration_client: AsyncClient,
+    integration_session: Any,
+) -> None:
+    admin_token = "test-admin-token"
+    admin_sessions[admin_token] = int(time.time()) + 3600
+    integration_client.headers["Authorization"] = f"Bearer {admin_token}"
+
+    provider = UpstreamProviderRow(
+        provider_type="routstr",
+        base_url="https://node.example",
+        api_key="sk-upstream-test",
+        enabled=True,
+        provider_fee=1.01,
+    )
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+
+    class MockResponse:
+        def __init__(self, status_code: int, data: dict[str, Any] | None = None):
+            self.status_code = status_code
+            self._data = data or {}
+            self.text = str(self._data)
+
+        def json(self) -> dict[str, Any]:
+            return self._data
+
+    class MockAsyncClient:
+        def __init__(self) -> None:
+            self.calls = 0
+
+        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:
+            self.calls += 1
+            assert url == "https://node.example/v1/balance/lightning/invoice"
+            assert json["amount_sats"] == 10
+            assert json["purpose"] == "topup"
+            assert json["api_key"] == "sk-upstream-test"
+            assert headers["Authorization"] == "Bearer sk-upstream-test"
+
+            if self.calls == 1:
+                return MockResponse(500, {"detail": "warmup failure"})
+
+            return MockResponse(
+                200,
+                {
+                    "bolt11": "lnbc1testinvoice",
+                    "invoice_id": "invoice-123",
+                },
+            )
+
+    mock_client = MockAsyncClient()
+
+    try:
+        with patch("httpx.AsyncClient", return_value=mock_client):
+            response = await integration_client.post(
+                f"/admin/api/upstream-providers/{provider.id}/topup",
+                json={"amount": 10},
+            )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["ok"] is True
+        assert data["topup_data"]["payment_request"] == "lnbc1testinvoice"
+        assert data["topup_data"]["invoice_id"] == "invoice-123"
+        assert mock_client.calls == 2
+    finally:
+        admin_sessions.pop(admin_token, None)

tests/integration/test_proxy_get_endpoints.py

@@ -171,10 +171,11 @@ async def test_proxy_get_unauthorized_access(integration_client: AsyncClient) ->
         assert response.status_code == 200  # GET requests are allowed
 
     # Test 2: POST requests without auth should return 401
+    # Note: Model validation happens before auth, so missing model returns 400
     response = await integration_client.post(
         "/v1/chat/completions", json={"test": "data"}
     )
-    assert response.status_code == 401
+    assert response.status_code in [400, 401]  # Accept both for now
 
     # Test 3: POST with invalid API key
     # Note: After refactor, model validation may happen before auth validation
@@ -550,9 +551,6 @@ async def test_proxy_get_concurrent_requests(
             assert response.status_code == 200
 
 
-
-
-
 @pytest.mark.integration
 @pytest.mark.asyncio
 async def test_proxy_get_response_format_preservation(

tests/integration/test_reservation_lifecycle.py

@@ -0,0 +1,268 @@
+"""
+Tests for the reservation lifecycle:
+
+  1. Reserve  → reserved_balance increases, available (total_balance) decreases.
+  2. Reserve  → revert  → reserved_balance restored, balance untouched.
+  3. Reserve  → finalise → reserved_balance released, balance charged.
+  4. Two parallel reserves, only one fits → second blocked with 402.
+  5. Three parallel reserves, two fit, third blocked with 402.
+  6. Sequential reserves until balance exhausted → next request blocked.
+
+Reservation invariant enforced by the atomic WHERE clause in pay_for_request:
+    balance - reserved_balance >= cost_per_request
+"""
+
+import asyncio
+import uuid
+
+import pytest
+from fastapi import HTTPException
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.auth import pay_for_request, revert_pay_for_request
+from routstr.core.db import ApiKey, create_session
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_key(balance: int, reserved: int = 0) -> ApiKey:
+    return ApiKey(
+        hashed_key=f"test_{uuid.uuid4().hex}",
+        balance=balance,
+        reserved_balance=reserved,
+        total_spent=0,
+        total_requests=0,
+    )
+
+
+async def _persist(session: AsyncSession, key: ApiKey) -> ApiKey:
+    session.add(key)
+    await session.commit()
+    await session.refresh(key)
+    return key
+
+
+# ---------------------------------------------------------------------------
+# Test 1 — Reserve: reserved_balance increases, available balance decreases
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_reserve_increases_reserved_balance(
+    integration_session: AsyncSession,
+) -> None:
+    """pay_for_request must increment reserved_balance by cost_per_request."""
+    cost = 100
+    key = await _persist(integration_session, _make_key(balance=500))
+
+    await pay_for_request(key, cost, integration_session)
+    await integration_session.refresh(key)
+
+    assert key.reserved_balance == cost
+    assert key.balance == 500  # balance column is NOT decremented on reserve
+    assert key.total_balance == 500 - cost  # available = balance - reserved
+
+
+# ---------------------------------------------------------------------------
+# Test 2 — Revert: reserved_balance restored, balance untouched
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_revert_releases_reservation(
+    integration_session: AsyncSession,
+) -> None:
+    """revert_pay_for_request must release the reservation without touching balance."""
+    cost = 150
+    key = await _persist(integration_session, _make_key(balance=300))
+
+    await pay_for_request(key, cost, integration_session)
+    await integration_session.refresh(key)
+    assert key.reserved_balance == cost
+
+    await revert_pay_for_request(key, integration_session, cost)
+    await integration_session.refresh(key)
+
+    assert key.reserved_balance == 0
+    assert key.balance == 300  # balance unchanged after revert
+
+
+# ---------------------------------------------------------------------------
+# Test 3 — Finalise: reservation released + balance charged
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_finalise_releases_reservation_and_charges_balance(
+    integration_session: AsyncSession,
+) -> None:
+    """adjust_payment_for_tokens must zero reserved_balance and deduct actual cost."""
+    from unittest.mock import patch
+
+    from routstr.auth import adjust_payment_for_tokens
+    from routstr.payment.cost_calculation import CostData
+
+    cost = 100
+    actual = 80  # actual < reserved → refund path
+    key = await _persist(integration_session, _make_key(balance=500))
+
+    await pay_for_request(key, cost, integration_session)
+    await integration_session.refresh(key)
+    assert key.reserved_balance == cost
+
+    cost_data = CostData(
+        base_msats=0,
+        input_msats=40,
+        output_msats=40,
+        total_msats=actual,
+        total_usd=0.0,
+        input_tokens=50,
+        output_tokens=50,
+    )
+    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 integration_session.refresh(key)
+
+    assert key.reserved_balance == 0
+    assert key.balance == 500 - actual
+    assert key.total_spent == actual
+
+
+# ---------------------------------------------------------------------------
+# Test 4 — Concurrent: second parallel reserve blocked when balance exhausted
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_concurrent_second_reserve_blocked_when_balance_exhausted(
+    patched_db_engine: None,
+) -> None:
+    """When two requests race for the same balance, only one succeeds; the other gets 402."""
+    cost = 300
+    key_hash = f"test_concurrent_{uuid.uuid4().hex}"
+
+    async with create_session() as session:
+        key = ApiKey(
+            hashed_key=key_hash,
+            balance=300,       # exactly enough for ONE reservation
+            reserved_balance=0,
+            total_spent=0,
+            total_requests=0,
+        )
+        session.add(key)
+        await session.commit()
+
+    results: list[str] = []
+
+    async def attempt_reserve() -> None:
+        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)
+                results.append("success")
+            except HTTPException as exc:
+                assert exc.status_code == 402
+                results.append("blocked")
+
+    await asyncio.gather(attempt_reserve(), attempt_reserve())
+
+    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, key_hash)
+        assert final is not None
+
+    # reserved_balance must equal exactly one reservation (not two)
+    assert final.reserved_balance == cost, (
+        f"Expected reserved_balance={cost}, got {final.reserved_balance}"
+    )
+    assert final.balance == 300, "Balance column must not be modified by reservation"
+
+
+# ---------------------------------------------------------------------------
+# Test 5 — Concurrent: three requests, two fit, third blocked
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_three_parallel_reserves_third_blocked(
+    patched_db_engine: None,
+) -> None:
+    """Balance covers two reservations exactly; the third concurrent request must be blocked."""
+    cost = 100
+    key_hash = f"test_three_parallel_{uuid.uuid4().hex}"
+
+    async with create_session() as session:
+        key = ApiKey(
+            hashed_key=key_hash,
+            balance=200,       # fits exactly 2 reservations of 100
+            reserved_balance=0,
+            total_spent=0,
+            total_requests=0,
+        )
+        session.add(key)
+        await session.commit()
+
+    results: list[str] = []
+
+    async def attempt_reserve() -> None:
+        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)
+                results.append("success")
+            except HTTPException as exc:
+                assert exc.status_code == 402
+                results.append("blocked")
+
+    await asyncio.gather(
+        attempt_reserve(),
+        attempt_reserve(),
+        attempt_reserve(),
+    )
+
+    successes = results.count("success")
+    blocked = results.count("blocked")
+
+    assert successes == 2, f"Expected 2 successes, got {successes}: {results}"
+    assert blocked == 1, f"Expected 1 blocked, got {blocked}: {results}"
+
+    async with create_session() as session:
+        final = await session.get(ApiKey, key_hash)
+        assert final is not None
+
+    assert final.reserved_balance == cost * 2, (
+        f"Expected reserved_balance={cost * 2}, got {final.reserved_balance}"
+    )
+    assert final.balance == 200, "Balance column must not be modified by reservation"
+
+
+# ---------------------------------------------------------------------------
+# Test 6 — Sequential exhaustion: reserve until empty, next request blocked
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_sequential_reserves_block_when_balance_exhausted(
+    integration_session: AsyncSession,
+) -> None:
+    """Repeated reservations should block as soon as available balance drops below cost."""
+    cost = 100
+    key = await _persist(integration_session, _make_key(balance=250))
+
+    # First two succeed (100 + 100 = 200 ≤ 250)
+    await pay_for_request(key, cost, integration_session)
+    await pay_for_request(key, cost, integration_session)
+    await integration_session.refresh(key)
+    assert key.reserved_balance == 200
+    assert key.total_balance == 50  # 250 - 200
+
+    # Third: only 50 available, need 100 → blocked
+    with pytest.raises(HTTPException) as exc_info:
+        await pay_for_request(key, cost, integration_session)
+
+    assert exc_info.value.status_code == 402
+    await integration_session.refresh(key)
+    assert key.reserved_balance == 200  # unchanged after failed reserve

tests/integration/test_reserved_balance_negative.py

@@ -133,13 +133,16 @@ async def test_reserved_balance_with_successful_requests(
 
 
 @pytest.mark.asyncio
-async def test_insufficient_reserved_balance_for_revert(
+async def test_revert_with_zero_reserved_balance_is_noop(
     integration_session: AsyncSession,
 ) -> None:
-    """Test revert_pay_for_request behavior with insufficient reserved balance."""
+    """Test that revert_pay_for_request is a no-op when reserved_balance is 0.
+
+    Previously this would drive reserved_balance negative. With the floor guard,
+    it should return False and leave reserved_balance at 0.
+    """
     from routstr.auth import revert_pay_for_request
 
-    # Create key with zero reserved balance
     unique_key = f"test_revert_key_{uuid.uuid4().hex[:8]}"
     test_key = ApiKey(
         hashed_key=unique_key,
@@ -149,17 +152,211 @@ async def test_insufficient_reserved_balance_for_revert(
     integration_session.add(test_key)
     await integration_session.commit()
 
-    # Try to revert more than available
-    # Note: Current implementation allows reserved_balance to go negative
-    await revert_pay_for_request(test_key, integration_session, 100)
+    # Try to revert more than available — should be a no-op
+    result = await revert_pay_for_request(test_key, integration_session, 100)
 
-    # Refresh to get updated values
     await integration_session.refresh(test_key)
 
-    # Current implementation allows negative reserved balance
-    assert test_key.reserved_balance == -100, (
-        f"Expected reserved_balance to be -100, got: {test_key.reserved_balance}"
+    assert result is False, "Revert should return False when reservation already released"
+    assert test_key.reserved_balance == 0, (
+        f"Reserved balance should remain 0, got: {test_key.reserved_balance}"
     )
-    assert test_key.total_requests == -1, (
-        f"Expected total_requests to be -1, got: {test_key.total_requests}"
+    assert test_key.total_requests == 0, (
+        f"Total requests should remain 0, got: {test_key.total_requests}"
+    )
+
+
+@pytest.mark.asyncio
+async def test_revert_with_sufficient_reserved_balance_succeeds(
+    integration_session: AsyncSession,
+) -> None:
+    """Test that revert_pay_for_request works correctly when there is enough reserved balance."""
+    from routstr.auth import revert_pay_for_request
+
+    unique_key = f"test_revert_ok_{uuid.uuid4().hex[:8]}"
+    test_key = ApiKey(
+        hashed_key=unique_key,
+        balance=5000,
+        reserved_balance=500,
+        total_requests=3,
+    )
+    integration_session.add(test_key)
+    await integration_session.commit()
+
+    result = await revert_pay_for_request(test_key, integration_session, 500)
+
+    await integration_session.refresh(test_key)
+
+    assert result is True, "Revert should return True on success"
+    assert test_key.reserved_balance == 0, (
+        f"Reserved balance should be 0, got: {test_key.reserved_balance}"
+    )
+    assert test_key.total_requests == 2, (
+        f"Total requests should be 2, got: {test_key.total_requests}"
+    )
+    assert test_key.balance == 5000, "Balance should not change on revert"
+
+
+@pytest.mark.asyncio
+async def test_revert_partial_reserved_balance_is_noop(
+    integration_session: AsyncSession,
+) -> None:
+    """Test that reverting more than the current reserved_balance is a no-op."""
+    from routstr.auth import revert_pay_for_request
+
+    unique_key = f"test_revert_partial_{uuid.uuid4().hex[:8]}"
+    test_key = ApiKey(
+        hashed_key=unique_key,
+        balance=5000,
+        reserved_balance=50,
+        total_requests=1,
+    )
+    integration_session.add(test_key)
+    await integration_session.commit()
+
+    # Try to revert 500 when only 50 is reserved — should be no-op
+    result = await revert_pay_for_request(test_key, integration_session, 500)
+
+    await integration_session.refresh(test_key)
+
+    assert result is False, "Revert should fail when cost > reserved_balance"
+    assert test_key.reserved_balance == 50, (
+        f"Reserved balance should stay at 50, got: {test_key.reserved_balance}"
+    )
+    assert test_key.total_requests == 1, (
+        f"Total requests should stay at 1, got: {test_key.total_requests}"
+    )
+
+
+@pytest.mark.asyncio
+async def test_double_revert_prevented(
+    integration_session: AsyncSession,
+) -> None:
+    """Test that calling revert twice doesn't drive reserved_balance negative.
+
+    This simulates the double-revert scenario where both upstream/base.py
+    and proxy.py attempt to revert the same reservation.
+    """
+    from routstr.auth import revert_pay_for_request
+
+    unique_key = f"test_double_revert_{uuid.uuid4().hex[:8]}"
+    test_key = ApiKey(
+        hashed_key=unique_key,
+        balance=10000,
+        reserved_balance=500,
+        total_requests=5,
+    )
+    integration_session.add(test_key)
+    await integration_session.commit()
+
+    # First revert — should succeed
+    result1 = await revert_pay_for_request(test_key, integration_session, 500)
+    await integration_session.refresh(test_key)
+
+    assert result1 is True
+    assert test_key.reserved_balance == 0
+    assert test_key.total_requests == 4
+
+    # Second revert of the same amount — should be no-op
+    result2 = await revert_pay_for_request(test_key, integration_session, 500)
+    await integration_session.refresh(test_key)
+
+    assert result2 is False, "Second revert should be a no-op"
+    assert test_key.reserved_balance == 0, (
+        f"Reserved balance should stay 0, got: {test_key.reserved_balance}"
+    )
+    assert test_key.total_requests == 4, (
+        f"Total requests should stay 4, got: {test_key.total_requests}"
+    )
+
+
+@pytest.mark.asyncio
+async def test_sequential_reverts_never_go_negative(
+    integration_session: AsyncSession,
+) -> None:
+    """Test that multiple reverts don't cause negative reserved_balance.
+
+    Simulates the double-revert scenario where multiple code paths
+    attempt to revert the same reservation.
+    """
+    from routstr.auth import revert_pay_for_request
+
+    unique_key = f"test_multi_revert_{uuid.uuid4().hex[:8]}"
+    test_key = ApiKey(
+        hashed_key=unique_key,
+        balance=10000,
+        reserved_balance=500,
+        total_requests=5,
+    )
+    integration_session.add(test_key)
+    await integration_session.commit()
+
+    # Run 5 sequential reverts for the same 500 reservation
+    results = []
+    for _ in range(5):
+        r = await revert_pay_for_request(test_key, integration_session, 500)
+        results.append(r)
+
+    await integration_session.refresh(test_key)
+
+    # Exactly one should succeed, rest should be no-ops
+    success_count = sum(1 for r in results if r is True)
+    assert success_count == 1, (
+        f"Exactly one revert should succeed, got {success_count} successes"
+    )
+    assert test_key.reserved_balance == 0, (
+        f"Reserved balance should be 0, got: {test_key.reserved_balance}"
+    )
+    assert test_key.reserved_balance >= 0, (
+        f"Reserved balance went negative: {test_key.reserved_balance}"
+    )
+
+
+@pytest.mark.asyncio
+async def test_child_key_revert_floor_guard(
+    integration_session: AsyncSession,
+) -> None:
+    """Test that child key reserved_balance also has floor guard on revert."""
+    from routstr.auth import revert_pay_for_request
+
+    parent_key_hash = f"test_parent_{uuid.uuid4().hex[:8]}"
+    child_key_hash = f"test_child_{uuid.uuid4().hex[:8]}"
+
+    parent_key = ApiKey(
+        hashed_key=parent_key_hash,
+        balance=10000,
+        reserved_balance=500,
+        total_requests=3,
+    )
+    child_key = ApiKey(
+        hashed_key=child_key_hash,
+        balance=0,
+        reserved_balance=500,
+        total_requests=3,
+        parent_key_hash=parent_key_hash,
+    )
+    integration_session.add(parent_key)
+    integration_session.add(child_key)
+    await integration_session.commit()
+
+    # First revert succeeds
+    result1 = await revert_pay_for_request(child_key, integration_session, 500)
+    await integration_session.refresh(parent_key)
+    await integration_session.refresh(child_key)
+
+    assert result1 is True
+    assert parent_key.reserved_balance == 0
+    assert child_key.reserved_balance == 0
+
+    # Second revert is a no-op for both parent and child
+    result2 = await revert_pay_for_request(child_key, integration_session, 500)
+    await integration_session.refresh(parent_key)
+    await integration_session.refresh(child_key)
+
+    assert result2 is False
+    assert parent_key.reserved_balance == 0, (
+        f"Parent reserved_balance should stay 0, got: {parent_key.reserved_balance}"
+    )
+    assert child_key.reserved_balance == 0, (
+        f"Child reserved_balance should stay 0, got: {child_key.reserved_balance}"
     )

tests/integration/test_wallet_refund.py

@@ -13,7 +13,7 @@ import pytest
 from httpx import AsyncClient
 from sqlmodel import select
 
-from routstr.core.db import ApiKey
+from routstr.core.db import ApiKey, CashuTransaction
 
 
 @pytest.mark.integration
@@ -65,9 +65,10 @@ async def test_full_balance_refund_returns_cashu_token(
     except Exception as e:
         pytest.fail(f"Invalid Cashu token format: {e}")
 
-    # Try to use the API key - should fail since it's been deleted
+    # Try to use the API key - should still work but have 0 balance
     response = await authenticated_client.get("/v1/wallet/")
-    assert response.status_code == 401
+    assert response.status_code == 200
+    assert response.json()["balance"] == 0
 
     # The refund token has been validated above by decoding it
     # The API key deletion has been verified by the 401 response
@@ -261,17 +262,16 @@ async def test_database_state_after_refund(
     response = await authenticated_client.post("/v1/wallet/refund")
     assert response.status_code == 200
 
-    # Verify key is deleted after refund
-    result = await integration_session.execute(
-        select(ApiKey).where(ApiKey.hashed_key == hashed_key)  # type: ignore[arg-type]
-    )
-    assert result.scalar_one_or_none() is None
+    # Refresh the key to get the updated balance from the database
+    await integration_session.refresh(key_before)
 
-    # Count total keys to ensure only the specific one was deleted
+    # Verify key balance is 0 after refund
+    assert key_before.balance == 0
+
+    # Count total keys to ensure it wasn't deleted
     result = await integration_session.execute(select(ApiKey))
     remaining_keys = result.scalars().all()
-    # Should have no keys left (assuming clean test environment)
-    assert len(remaining_keys) == 0
+    assert len(remaining_keys) == 1
 
 
 @pytest.mark.integration
@@ -356,6 +356,70 @@ async def test_concurrent_refund_requests(
     assert len(successful) + len(failed) == 5
 
 
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_refund_rejects_concurrent_topup_on_same_key(
+    authenticated_client: AsyncClient,
+    testmint_wallet: Any,
+) -> None:
+    """Test refund returns 409 when a concurrent topup changes the balance first."""
+    from routstr import balance as balance_module
+
+    wallet_response = await authenticated_client.get("/v1/wallet/")
+    assert wallet_response.status_code == 200
+    initial_balance = wallet_response.json()["balance"]
+
+    topup_amount_sat = 500
+    topup_token = await testmint_wallet.mint_tokens(topup_amount_sat)
+
+    validate_called = asyncio.Event()
+    allow_refund_to_continue = asyncio.Event()
+    original_validate_bearer_key = balance_module.validate_bearer_key
+    delayed_once = False
+
+    async def delayed_validate_bearer_key(*args: Any, **kwargs: Any) -> ApiKey:
+        nonlocal delayed_once
+        key = await original_validate_bearer_key(*args, **kwargs)
+        if not delayed_once:
+            delayed_once = True
+            validate_called.set()
+            await allow_refund_to_continue.wait()
+        return key
+
+    async def issue_refund() -> Any:
+        return await authenticated_client.post("/v1/wallet/refund")
+
+    async def issue_topup() -> Any:
+        await validate_called.wait()
+        try:
+            return await authenticated_client.post(
+                "/v1/wallet/topup", params={"cashu_token": topup_token}
+            )
+        finally:
+            allow_refund_to_continue.set()
+
+    with patch(
+        "routstr.balance.validate_bearer_key", new=delayed_validate_bearer_key
+    ):
+        refund_response, topup_response = await asyncio.gather(
+            issue_refund(), issue_topup()
+        )
+
+    assert topup_response.status_code == 200
+    assert topup_response.json()["msats"] == topup_amount_sat * 1000
+    assert refund_response.status_code == 409
+    assert (
+        refund_response.json()["detail"]
+        == "Balance changed concurrently. Please retry the refund."
+    )
+
+    final_balance_response = await authenticated_client.get("/v1/wallet/")
+    assert final_balance_response.status_code == 200
+    assert final_balance_response.json()["balance"] == (
+        initial_balance + topup_amount_sat * 1000
+    )
+
+
 @pytest.mark.integration
 @pytest.mark.asyncio
 async def test_refund_during_active_usage(
@@ -388,9 +452,46 @@ async def test_refund_during_active_usage(
     # Refund should succeed
     assert refund_response.status_code == 200
 
-    # Further usage should fail
+    # Further usage should return 200 but with 0 balance
     response = await authenticated_client.get("/v1/wallet/")
-    assert response.status_code == 401
+    assert response.status_code == 200
+    assert response.json()["balance"] == 0
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_wallet_history_returns_apikey_transactions(
+    authenticated_client: AsyncClient,
+    testmint_wallet: Any,
+    integration_session: Any,
+) -> None:
+    wallet_response = await authenticated_client.get("/v1/wallet/")
+    api_key = wallet_response.json()["api_key"]
+    hashed_key = api_key[3:] if api_key.startswith("sk-") else api_key
+
+    topup_token = await testmint_wallet.mint_tokens(250)
+    topup_response = await authenticated_client.post(
+        "/v1/wallet/topup", params={"cashu_token": topup_token}
+    )
+    assert topup_response.status_code == 200
+
+    refund_response = await authenticated_client.post("/v1/wallet/refund")
+    assert refund_response.status_code == 200
+
+    history_response = await authenticated_client.get("/v1/wallet/history")
+    assert history_response.status_code == 200
+    transactions = history_response.json()["transactions"]
+    assert len(transactions) >= 2
+    assert all("api_key_hashed_key" not in tx for tx in transactions)
+    assert {tx["type"] for tx in transactions} >= {"in", "out"}
+
+    db_result = await integration_session.execute(
+        select(CashuTransaction).where(
+            CashuTransaction.api_key_hashed_key == hashed_key
+        )
+    )
+    db_transactions = db_result.scalars().all()
+    assert len(db_transactions) >= 2
 
 
 @pytest.mark.integration
@@ -535,6 +636,3 @@ async def test_refund_with_expired_key(
         # Should still allow manual refund
         assert response.status_code == 200
         assert response.json()["recipient"] == "expired@ln.address"
-
-
-

tests/integration/test_wallet_topup.py

@@ -11,7 +11,7 @@ import pytest
 from httpx import AsyncClient
 from sqlmodel import select
 
-from routstr.core.db import ApiKey
+from routstr.core.db import ApiKey, CashuTransaction
 
 from .utils import (
     CashuTokenGenerator,
@@ -71,6 +71,16 @@ async def test_topup_with_valid_token(  # type: ignore[no-untyped-def]
     assert db_key.balance == new_balance
     assert db_key.balance == initial_balance + (topup_amount * 1000)
 
+    tx_result = await integration_session.execute(
+        select(CashuTransaction).where(
+            CashuTransaction.token == token,
+            CashuTransaction.type == "in",
+        )
+    )
+    tx = tx_result.scalar_one()
+    assert tx.api_key_hashed_key == hashed_key
+    assert tx.source == "apikey"
+
 
 @pytest.mark.integration
 @pytest.mark.asyncio

tests/unit/test_algorithm.py

@@ -1,16 +1,19 @@
 """Tests for the model prioritization algorithm."""
 
 import os
+from types import SimpleNamespace
 from unittest.mock import Mock
 
+import pytest
+
 # Set required env vars before importing
 os.environ["UPSTREAM_BASE_URL"] = "http://test"
 os.environ["UPSTREAM_API_KEY"] = "test"
 
 from routstr.algorithm import (  # noqa: E402
     calculate_model_cost_score,
+    create_model_mappings,
     get_provider_penalty,
-    should_prefer_model,
 )
 from routstr.payment.models import Architecture, Model, Pricing  # noqa: E402
 
@@ -46,11 +49,21 @@ def create_test_model(
     )
 
 
-def create_test_provider(name: str, base_url: str = "http://test.com") -> Mock:
+def create_test_provider(
+    name: str,
+    base_url: str = "http://test.com",
+    *,
+    db_id: int | None = None,
+    models: list[Model] | None = None,
+    upstream_name: str | None = None,
+) -> Mock:
     """Helper to create a test provider mock."""
     provider = Mock()
     provider.provider_type = name
     provider.base_url = base_url
+    provider.db_id = db_id
+    provider.upstream_name = upstream_name or name
+    provider.get_cached_models.return_value = models or []
     return provider
 
 
@@ -102,98 +115,78 @@ def test_get_provider_penalty_openrouter() -> None:
     assert penalty == 1.001
 
 
-def test_should_prefer_model_cheaper_wins() -> None:
-    """Test that cheaper model is preferred."""
-    cheap_model = create_test_model("cheap", prompt_price=0.001, completion_price=0.002)
-    expensive_model = create_test_model(
-        "expensive", prompt_price=0.03, completion_price=0.06
+def test_create_model_mappings_includes_db_override_for_missing_cached_model(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Model overrides should still map when provider discovery misses the model."""
+    provider = create_test_provider(
+        "azure",
+        "https://example.openai.azure.com/openai/v1",
+        db_id=7,
+        models=[],
+    )
+    override_model = create_test_model("azure/gpt-4o")
+    override_model.canonical_slug = "azure-deployment"
+
+    def fake_row_to_model(*args, **kwargs) -> Model:  # type: ignore[no-untyped-def]
+        return override_model
+
+    monkeypatch.setattr("routstr.payment.models._row_to_model", fake_row_to_model)
+
+    override_row = SimpleNamespace(id="azure/gpt-4o", upstream_provider_id=7, enabled=True)
+
+    model_instances, provider_map, unique_models = create_model_mappings(
+        upstreams=[provider],
+        overrides_by_id={"azure/gpt-4o": (override_row, 1.01)},
+        disabled_model_ids=set(),
     )
 
-    provider1 = create_test_provider("provider1")
-    provider2 = create_test_provider("provider2")
+    assert "azure/gpt-4o" in model_instances
+    assert provider_map["azure/gpt-4o"] == [provider]
+    assert "gpt-4o" in unique_models
 
-    # Cheaper model should win
-    assert should_prefer_model(
-        cheap_model, provider1, expensive_model, provider2, "test-alias"
+
+def test_create_model_mappings_dedupes_with_provider_identity_not_provider_type(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Different provider instances of same type should both survive dedupe."""
+    provider_a_model = create_test_model(
+        "azure/gpt-4o", prompt_price=0.01, completion_price=0.01
+    )
+    provider_a = create_test_provider(
+        "azure",
+        "https://a.openai.azure.com/openai/v1",
+        db_id=1,
+        models=[provider_a_model],
+        upstream_name="azure-a",
+    )
+    provider_b = create_test_provider(
+        "azure",
+        "https://b.openai.azure.com/openai/v1",
+        db_id=2,
+        models=[],
+        upstream_name="azure-b",
     )
 
-    # More expensive model should not win
-    assert not should_prefer_model(
-        expensive_model, provider2, cheap_model, provider1, "test-alias"
+    override_model = create_test_model(
+        "azure/gpt-4o", prompt_price=0.001, completion_price=0.001
+    )
+    override_model.canonical_slug = "azure-b-deployment"
+
+    def fake_row_to_model(*args, **kwargs) -> Model:  # type: ignore[no-untyped-def]
+        return override_model
+
+    monkeypatch.setattr("routstr.payment.models._row_to_model", fake_row_to_model)
+
+    override_row = SimpleNamespace(id="azure/gpt-4o", upstream_provider_id=2, enabled=True)
+
+    _, provider_map, _ = create_model_mappings(
+        upstreams=[provider_a, provider_b],
+        overrides_by_id={"azure/gpt-4o": (override_row, 1.01)},
+        disabled_model_ids=set(),
     )
 
-
-def test_should_prefer_model_exact_match_wins() -> None:
-    """Test that exact alias match beats cheaper price."""
-    # Make model IDs match the alias differently
-    exact_match = create_test_model(
-        "test-model", prompt_price=0.03, completion_price=0.06
-    )
-    no_match = create_test_model(
-        "other-model", prompt_price=0.001, completion_price=0.002
-    )
-
-    provider1 = create_test_provider("provider1")
-    provider2 = create_test_provider("provider2")
-
-    # Exact match should win even though it's more expensive
-    assert should_prefer_model(
-        exact_match, provider1, no_match, provider2, "test-model"
-    )
-
-
-def test_should_prefer_model_openrouter_slight_penalty() -> None:
-    """Test that OpenRouter has slight penalty compared to other providers."""
-    model1 = create_test_model("model1", prompt_price=0.001, completion_price=0.002)
-    model2 = create_test_model("model2", prompt_price=0.001, completion_price=0.002)
-
-    regular_provider = create_test_provider("regular", "http://provider.com")
-    openrouter_provider = create_test_provider(
-        "openrouter", "https://openrouter.ai/api/v1"
-    )
-
-    # Regular provider should be preferred over OpenRouter at same cost
-    assert should_prefer_model(
-        model1, regular_provider, model2, openrouter_provider, "test-alias"
-    )
-
-    # OpenRouter should not replace regular provider at same cost
-    assert not should_prefer_model(
-        model2, openrouter_provider, model1, regular_provider, "test-alias"
-    )
-
-
-def test_should_prefer_model_openrouter_can_win_if_cheaper() -> None:
-    """Test that OpenRouter can still win if significantly cheaper."""
-    cheap_model = create_test_model(
-        "cheap", prompt_price=0.0001, completion_price=0.0002
-    )
-    expensive_model = create_test_model(
-        "expensive", prompt_price=0.03, completion_price=0.06
-    )
-
-    regular_provider = create_test_provider("regular", "http://provider.com")
-    openrouter_provider = create_test_provider(
-        "openrouter", "https://openrouter.ai/api/v1"
-    )
-
-    # OpenRouter should win if it's much cheaper (even with penalty)
-    assert should_prefer_model(
-        cheap_model,
-        openrouter_provider,
-        expensive_model,
-        regular_provider,
-        "test-alias",
-    )
-
-
-def test_should_prefer_model_same_cost_first_wins() -> None:
-    """Test that when costs are identical, current model is kept."""
-    model1 = create_test_model("model1", prompt_price=0.001, completion_price=0.002)
-    model2 = create_test_model("model2", prompt_price=0.001, completion_price=0.002)
-
-    provider1 = create_test_provider("provider1")
-    provider2 = create_test_provider("provider2")
-
-    # When costs are equal, should not replace
-    assert not should_prefer_model(model2, provider2, model1, provider1, "test-alias")
+    providers_for_alias = provider_map["azure/gpt-4o"]
+    assert provider_a in providers_for_alias
+    assert provider_b in providers_for_alias
+    assert len(providers_for_alias) == 2

tests/unit/test_balance.py

@@ -0,0 +1,357 @@
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from fastapi.responses import JSONResponse
+
+from routstr.balance import refund_wallet_endpoint
+from routstr.core.db import ApiKey, CashuTransaction
+from routstr.wallet import credit_balance
+
+
+def _make_cashu_tx(
+    token: str,
+    amount: int,
+    unit: str,
+    type: str = "out",
+    request_id: str | None = "req-abc",
+    swept: bool = False,
+    collected: bool = False,
+) -> CashuTransaction:
+    tx = CashuTransaction(token=token, amount=amount, unit=unit, type=type, request_id=request_id)
+    tx.swept = swept
+    tx.collected = collected
+    return tx
+
+
+def _exec_result(tx: CashuTransaction | None) -> MagicMock:
+    result = MagicMock()
+    result.first.return_value = tx
+    return result
+
+
+def _update_result(rowcount: int) -> MagicMock:
+    result = MagicMock()
+    result.rowcount = rowcount
+    return result
+
+
+@pytest.mark.asyncio
+async def test_refund_x_cashu_returns_token() -> None:
+    x_cashu_token = "cashuAtest_token_value"
+    in_tx = _make_cashu_tx(token=x_cashu_token, amount=0, unit="msat", type="in", request_id="req-abc")
+    out_tx = _make_cashu_tx(token="cashuArefund_token", amount=1000, unit="msat", type="out", request_id="req-abc")
+
+    session = MagicMock()
+    session.exec = AsyncMock(side_effect=[_exec_result(in_tx), _exec_result(out_tx)])
+    session.add = MagicMock()
+    session.commit = AsyncMock()
+
+    result = await refund_wallet_endpoint(
+        authorization="Bearer sk-somekey",
+        x_cashu=x_cashu_token,
+        session=session,
+    )
+
+    assert isinstance(result, JSONResponse)
+    body = json.loads(result.body)
+    assert body["token"] == "cashuArefund_token"
+    assert body["msats"] == "1000"
+    assert result.headers["X-Cashu"] == "cashuArefund_token"
+    assert out_tx.collected is True
+
+
+@pytest.mark.asyncio
+async def test_refund_x_cashu_sat_unit() -> None:
+    x_cashu_token = "cashuAsat_token"
+    in_tx = _make_cashu_tx(token=x_cashu_token, amount=0, unit="sat", type="in", request_id="req-sat")
+    out_tx = _make_cashu_tx(token="cashuArefund_sat", amount=500, unit="sat", type="out", request_id="req-sat")
+
+    session = MagicMock()
+    session.exec = AsyncMock(side_effect=[_exec_result(in_tx), _exec_result(out_tx)])
+    session.add = MagicMock()
+    session.commit = AsyncMock()
+
+    result = await refund_wallet_endpoint(
+        authorization="Bearer sk-somekey",
+        x_cashu=x_cashu_token,
+        session=session,
+    )
+
+    assert isinstance(result, JSONResponse)
+    body = json.loads(result.body)
+    assert body["token"] == "cashuArefund_sat"
+    assert body["sats"] == "500"
+    assert "msats" not in body
+    assert result.headers["X-Cashu"] == "cashuArefund_sat"
+
+
+@pytest.mark.asyncio
+async def test_refund_x_cashu_not_found_raises_404() -> None:
+    from fastapi import HTTPException
+
+    session = MagicMock()
+    session.exec = AsyncMock(return_value=_exec_result(None))
+
+    with pytest.raises(HTTPException) as exc_info:
+        await refund_wallet_endpoint(
+            authorization="Bearer sk-somekey",
+            x_cashu="cashuAmissing_token",
+            session=session,
+        )
+
+    assert exc_info.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_refund_x_cashu_swept_raises_410() -> None:
+    from fastapi import HTTPException
+
+    in_tx = _make_cashu_tx(token="cashuAswept_token", amount=0, unit="msat", type="in", request_id="req-swept")
+    out_tx = _make_cashu_tx(token="cashuAswept", amount=100, unit="msat", type="out", request_id="req-swept", swept=True)
+
+    session = MagicMock()
+    session.exec = AsyncMock(side_effect=[_exec_result(in_tx), _exec_result(out_tx)])
+
+    with pytest.raises(HTTPException) as exc_info:
+        await refund_wallet_endpoint(
+            authorization="Bearer sk-somekey",
+            x_cashu="cashuAswept_token",
+            session=session,
+        )
+
+    assert exc_info.value.status_code == 410
+
+
+# ---------------------------------------------------------------------------
+# source field defaults
+# ---------------------------------------------------------------------------
+
+
+def test_cashu_transaction_source_defaults_to_x_cashu() -> None:
+    tx = CashuTransaction(token="cashuAtest", amount=100, unit="msat")
+    assert tx.source == "x-cashu"
+
+
+def test_cashu_transaction_source_can_be_apikey() -> None:
+    tx = CashuTransaction(token="cashuAtest", amount=100, unit="msat", source="apikey")
+    assert tx.source == "apikey"
+
+
+# ---------------------------------------------------------------------------
+# apikey-based refund: token logging and CashuTransaction storage
+# ---------------------------------------------------------------------------
+
+
+def _make_api_key(
+    balance: int = 5000,
+    refund_currency: str | None = "sat",
+    refund_mint_url: str | None = "https://mint.example.com",
+    refund_address: str | None = None,
+    parent_key_hash: str | None = None,
+) -> ApiKey:
+    key = ApiKey(hashed_key="testhash")
+    key.balance = balance
+    key.reserved_balance = 0
+    key.refund_currency = refund_currency
+    key.refund_mint_url = refund_mint_url
+    key.refund_address = refund_address
+    key.parent_key_hash = parent_key_hash
+    key.total_spent = 0
+    key.total_requests = 0
+    return key
+
+
+@pytest.mark.asyncio
+async def test_apikey_refund_stores_cashu_transaction_with_apikey_source() -> None:
+    key = _make_api_key(balance=5000, refund_currency="sat")
+    refund_token = "cashuArefund_apikey_token"
+
+    session = MagicMock()
+    session.exec = AsyncMock(return_value=_update_result(1))
+    session.add = MagicMock()
+    session.commit = AsyncMock()
+
+    with (
+        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.send_token", AsyncMock(return_value=refund_token)),
+        patch("routstr.balance.store_cashu_transaction", AsyncMock()) as mock_store,
+        patch("routstr.balance._refund_cache_get", AsyncMock(return_value=None)),
+        patch("routstr.balance._refund_cache_set", AsyncMock()),
+    ):
+        result = await refund_wallet_endpoint(
+            authorization="Bearer sk-testhash",
+            x_cashu=None,
+            session=session,
+        )
+
+    assert isinstance(result, dict)
+    assert result["token"] == refund_token
+
+    mock_store.assert_awaited_once()
+    call_kwargs = mock_store.call_args.kwargs
+    assert call_kwargs["source"] == "apikey"
+    assert call_kwargs["token"] == refund_token
+    assert call_kwargs["typ"] == "out"
+    assert call_kwargs["api_key_hashed_key"] == key.hashed_key
+
+
+@pytest.mark.asyncio
+async def test_apikey_refund_logs_token() -> None:
+    key = _make_api_key(balance=5000, refund_currency="sat")
+    refund_token = "cashuAlogged_token"
+
+    session = MagicMock()
+    session.exec = AsyncMock(return_value=_update_result(1))
+    session.add = MagicMock()
+    session.commit = AsyncMock()
+
+    with (
+        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.send_token", AsyncMock(return_value=refund_token)),
+        patch("routstr.balance.store_cashu_transaction", AsyncMock()),
+        patch("routstr.balance._refund_cache_get", AsyncMock(return_value=None)),
+        patch("routstr.balance._refund_cache_set", AsyncMock()),
+        patch("routstr.balance.logger") as mock_logger,
+    ):
+        await refund_wallet_endpoint(
+            authorization="Bearer sk-testhash",
+            x_cashu=None,
+            session=session,
+        )
+
+    calls = [str(c) for c in mock_logger.info.call_args_list]
+    assert any("cashu token issued" in c for c in calls)
+
+
+@pytest.mark.asyncio
+async def test_apikey_refund_log_includes_path() -> None:
+    key = _make_api_key(balance=5000, refund_currency="sat")
+    refund_token = "cashuApath_token"
+
+    session = MagicMock()
+    session.exec = AsyncMock(return_value=_update_result(1))
+    session.add = MagicMock()
+    session.commit = AsyncMock()
+
+    with (
+        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.send_token", AsyncMock(return_value=refund_token)),
+        patch("routstr.balance.store_cashu_transaction", AsyncMock()),
+        patch("routstr.balance._refund_cache_get", AsyncMock(return_value=None)),
+        patch("routstr.balance._refund_cache_set", AsyncMock()),
+        patch("routstr.balance.logger") as mock_logger,
+    ):
+        await refund_wallet_endpoint(
+            authorization="Bearer sk-testhash",
+            x_cashu=None,
+            session=session,
+        )
+
+    # Find the "cashu token issued" call and verify extra contains the path
+    token_issued_calls = [
+        c for c in mock_logger.info.call_args_list
+        if c.args and "cashu token issued" in c.args[0]
+    ]
+    assert len(token_issued_calls) == 1
+    extra = token_issued_calls[0].kwargs.get("extra", {})
+    assert extra.get("path") == "/v1/wallet/refund"
+
+
+@pytest.mark.asyncio
+async def test_apikey_refund_rejects_on_concurrent_balance_change() -> None:
+    """When the debit CAS fails (rowcount=0), no token is minted and 409 is returned."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=5000, refund_currency="sat")
+
+    session = MagicMock()
+    # Debit returns rowcount=0 → balance changed concurrently
+    session.exec = AsyncMock(return_value=_update_result(0))
+    session.commit = AsyncMock()
+
+    mock_send_token = AsyncMock(return_value="cashuAshould_not_be_minted")
+
+    with (
+        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.send_token", mock_send_token),
+        patch("routstr.balance.store_cashu_transaction", AsyncMock()),
+        patch("routstr.balance._refund_cache_get", AsyncMock(return_value=None)),
+        patch("routstr.balance._refund_cache_set", AsyncMock()),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await refund_wallet_endpoint(
+                authorization="Bearer sk-testhash",
+                x_cashu=None,
+                session=session,
+            )
+
+    assert exc_info.value.status_code == 409
+    # Crucially: send_token must NOT have been called
+    mock_send_token.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_credit_balance_stores_apikey_transaction_history() -> None:
+    key = _make_api_key(balance=1000)
+    session = MagicMock()
+    session.exec = AsyncMock(return_value=_update_result(1))
+    session.commit = AsyncMock()
+    session.refresh = AsyncMock()
+
+    with (
+        patch(
+            "routstr.wallet.recieve_token",
+            AsyncMock(return_value=(100, "sat", "https://mint.example")),
+        ),
+        patch("routstr.wallet.store_cashu_transaction", AsyncMock()) as mock_store,
+    ):
+        amount = await credit_balance("cashuAtopup_token", key, session)
+
+    assert amount == 100_000
+    mock_store.assert_awaited_once()
+    call_kwargs = mock_store.call_args.kwargs
+    assert call_kwargs["typ"] == "in"
+    assert call_kwargs["source"] == "apikey"
+    assert call_kwargs["api_key_hashed_key"] == key.hashed_key
+    assert call_kwargs["amount"] == 100
+    assert call_kwargs["unit"] == "sat"
+    assert call_kwargs["token"] == "cashuAtopup_token"
+    assert call_kwargs["mint_url"] == "https://mint.example"
+
+
+@pytest.mark.asyncio
+async def test_apikey_refund_restores_balance_on_mint_failure() -> None:
+    """When debit succeeds but minting fails, balance must be restored."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=5000, refund_currency="sat")
+
+    # First exec call = debit (succeeds), second = restore
+    session = MagicMock()
+    session.exec = AsyncMock(side_effect=[_update_result(1), _update_result(1)])
+    session.commit = AsyncMock()
+
+    with (
+        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.send_token", AsyncMock(side_effect=Exception("mint down"))),
+        patch("routstr.balance.store_cashu_transaction", AsyncMock()),
+        patch("routstr.balance._refund_cache_get", AsyncMock(return_value=None)),
+        patch("routstr.balance._refund_cache_set", AsyncMock()),
+        patch("routstr.balance.logger"),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await refund_wallet_endpoint(
+                authorization="Bearer sk-testhash",
+                x_cashu=None,
+                session=session,
+            )
+
+    assert exc_info.value.status_code == 503
+    # Verify two exec calls: debit + restore
+    assert session.exec.await_count == 2

tests/unit/test_fee_consistency.py

@@ -1,155 +0,0 @@
-"""Unit tests for model row payload conversion.
-
-This module tests that _model_to_row_payload correctly serializes model data
-for database storage. Pricing is stored as-is without fee application.
-Fees are now applied per-provider when reading from the database.
-
-Key behaviors tested:
-1. Pricing is stored as-is without fee application
-2. All model fields are correctly serialized to JSON
-3. Optional fields are handled correctly (None values)
-4. Pricing structure is preserved
-5. Original model objects are not mutated
-"""
-
-import json
-import os
-
-import pytest
-
-# Set required env vars before importing
-os.environ["UPSTREAM_BASE_URL"] = "http://test"
-os.environ["UPSTREAM_API_KEY"] = "test"
-
-from routstr.payment.models import (  # noqa: E402
-    Architecture,
-    Model,
-    Pricing,
-    _model_to_row_payload,
-)
-
-
-@pytest.fixture
-def base_architecture() -> Architecture:
-    """Provide standard architecture for test models."""
-    return Architecture(
-        modality="text",
-        input_modalities=["text"],
-        output_modalities=["text"],
-        tokenizer="gpt",
-        instruct_type="chat",
-    )
-
-
-@pytest.fixture
-def standard_pricing() -> Pricing:
-    """Provide standard USD pricing with known values for testing."""
-    return Pricing(
-        prompt=0.001,
-        completion=0.002,
-        request=0.01,
-        image=0.05,
-        web_search=0.03,
-        internal_reasoning=0.015,
-        max_prompt_cost=10.0,
-        max_completion_cost=20.0,
-        max_cost=30.0,
-    )
-
-
-@pytest.fixture
-def standard_model(base_architecture: Architecture, standard_pricing: Pricing) -> Model:
-    """Create a standard test model with known pricing."""
-    return Model(
-        id="test-model-standard",
-        name="Test Model Standard",
-        created=1234567890,
-        description="A standard test model",
-        context_length=8192,
-        architecture=base_architecture,
-        pricing=standard_pricing,
-    )
-
-
-def test_pricing_stored_without_fees(standard_model: Model) -> None:
-    """Verify pricing is stored as-is without any fee application."""
-    payload = _model_to_row_payload(standard_model)
-    pricing_str = payload["pricing"]
-    assert isinstance(pricing_str, str)
-    pricing = json.loads(pricing_str)
-
-    assert pricing["prompt"] == pytest.approx(0.001, rel=1e-9)
-    assert pricing["completion"] == pytest.approx(0.002, rel=1e-9)
-    assert pricing["request"] == pytest.approx(0.01, rel=1e-9)
-    assert pricing["image"] == pytest.approx(0.05, rel=1e-9)
-    assert pricing["web_search"] == pytest.approx(0.03, rel=1e-9)
-    assert pricing["internal_reasoning"] == pytest.approx(0.015, rel=1e-9)
-    assert pricing["max_prompt_cost"] == pytest.approx(10.0, rel=1e-9)
-    assert pricing["max_completion_cost"] == pytest.approx(20.0, rel=1e-9)
-    assert pricing["max_cost"] == pytest.approx(30.0, rel=1e-9)
-
-
-def test_zero_value_pricing_fields(base_architecture: Architecture) -> None:
-    """Verify that zero-value pricing fields are stored correctly."""
-    zero_pricing = Pricing(
-        prompt=0.0,
-        completion=0.0,
-        request=0.0,
-        image=0.0,
-        web_search=0.0,
-        internal_reasoning=0.0,
-        max_prompt_cost=0.0,
-        max_completion_cost=0.0,
-        max_cost=0.0,
-    )
-
-    model = Model(
-        id="test-model-zero",
-        name="Test Model Zero",
-        created=1234567890,
-        description="A model with zero pricing",
-        context_length=8192,
-        architecture=base_architecture,
-        pricing=zero_pricing,
-    )
-
-    payload = _model_to_row_payload(model)
-    pricing_str = payload["pricing"]
-    assert isinstance(pricing_str, str)
-    pricing = json.loads(pricing_str)
-
-    assert pricing["prompt"] == pytest.approx(0.0, rel=1e-9)
-    assert pricing["completion"] == pytest.approx(0.0, rel=1e-9)
-    assert pricing["request"] == pytest.approx(0.0, rel=1e-9)
-
-
-def test_payload_structure_unchanged(standard_model: Model) -> None:
-    """Verify that payload structure matches expectations."""
-    payload = _model_to_row_payload(standard_model)
-
-    assert "id" in payload
-    assert "name" in payload
-    assert "created" in payload
-    assert "description" in payload
-    assert "context_length" in payload
-    assert "architecture" in payload
-    assert "pricing" in payload
-    assert "sats_pricing" in payload
-    assert "per_request_limits" in payload
-    assert "top_provider" in payload
-    assert "enabled" in payload
-    assert "upstream_provider_id" in payload
-
-    assert isinstance(payload["architecture"], str)
-    assert isinstance(payload["pricing"], str)
-
-
-def test_original_model_not_mutated(standard_model: Model) -> None:
-    """Verify that the original model object is not mutated."""
-    original_prompt = standard_model.pricing.prompt
-    original_completion = standard_model.pricing.completion
-
-    _model_to_row_payload(standard_model)
-
-    assert standard_model.pricing.prompt == original_prompt
-    assert standard_model.pricing.completion == original_completion

tests/unit/test_fee_schedule.py

@@ -0,0 +1,256 @@
+"""Unit tests for routstr.payment.fee_schedule."""
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from pydantic.v1 import ValidationError
+
+from routstr.payment.fee_schedule import (
+    FeeTimeRange,
+    get_active_fee,
+    ranges_overlap,
+    validate_no_overlaps,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _r(start: str, end: str, fee: float = 1.05) -> FeeTimeRange:
+    return FeeTimeRange(start_time=start, end_time=end, provider_fee=fee)
+
+
+def _now(h: int, m: int = 0) -> datetime:
+    return datetime(2026, 1, 1, h, m, tzinfo=timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# FeeTimeRange validation
+# ---------------------------------------------------------------------------
+
+
+class TestFeeTimeRangeValidation:
+    def test_valid_range(self) -> None:
+        r = _r("08:00", "18:00", 1.05)
+        assert r.start_time == "08:00"
+        assert r.end_time == "18:00"
+        assert r.provider_fee == 1.05
+
+    def test_invalid_start_time_format(self) -> None:
+        with pytest.raises(ValidationError, match="HH:MM"):
+            _r("8:00", "18:00")
+
+    def test_invalid_end_time_hour_out_of_range(self) -> None:
+        with pytest.raises(ValidationError):
+            _r("08:00", "24:00")
+
+    def test_invalid_end_time_minute_out_of_range(self) -> None:
+        with pytest.raises(ValidationError):
+            _r("08:00", "18:60")
+
+    def test_invalid_time_letters(self) -> None:
+        with pytest.raises(ValidationError):
+            _r("ab:cd", "18:00")
+
+    def test_fee_must_be_positive(self) -> None:
+        with pytest.raises(ValidationError, match="provider_fee must be > 0"):
+            _r("08:00", "18:00", fee=0.0)
+
+    def test_fee_negative_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            _r("08:00", "18:00", fee=-0.5)
+
+    def test_fee_below_one_allowed(self) -> None:
+        r = _r("08:00", "18:00", fee=0.95)
+        assert r.provider_fee == 0.95
+
+    def test_boundary_times_valid(self) -> None:
+        r = _r("00:00", "23:59")
+        assert r.start_time == "00:00"
+        assert r.end_time == "23:59"
+
+
+# ---------------------------------------------------------------------------
+# ranges_overlap
+# ---------------------------------------------------------------------------
+
+
+class TestRangesOverlap:
+    def test_non_overlapping_ranges(self) -> None:
+        assert not ranges_overlap(_r("08:00", "12:00"), _r("12:00", "18:00"))
+
+    def test_overlapping_ranges(self) -> None:
+        assert ranges_overlap(_r("08:00", "14:00"), _r("12:00", "18:00"))
+
+    def test_one_contains_the_other(self) -> None:
+        assert ranges_overlap(_r("08:00", "20:00"), _r("10:00", "18:00"))
+
+    def test_identical_ranges_overlap(self) -> None:
+        assert ranges_overlap(_r("08:00", "12:00"), _r("08:00", "12:00"))
+
+    def test_adjacent_non_overlapping(self) -> None:
+        # end of first == start of second → no overlap (open interval [start, end))
+        assert not ranges_overlap(_r("06:00", "12:00"), _r("12:00", "18:00"))
+
+    def test_midnight_crossing_vs_day_range_overlap(self) -> None:
+        # 22:00–06:00 crosses midnight; 04:00–08:00 should overlap (both cover 04:00–06:00)
+        assert ranges_overlap(_r("22:00", "06:00"), _r("04:00", "08:00"))
+
+    def test_midnight_crossing_vs_non_overlapping_day_range(self) -> None:
+        # 22:00–06:00 does NOT cover 10:00–18:00
+        assert not ranges_overlap(_r("22:00", "06:00"), _r("10:00", "18:00"))
+
+    def test_two_midnight_crossing_ranges_overlap(self) -> None:
+        assert ranges_overlap(_r("20:00", "04:00"), _r("22:00", "06:00"))
+
+    def test_two_midnight_crossing_ranges_non_overlap(self) -> None:
+        # 21:00–23:00 and 23:00–21:00 (full day minus one hour): they do overlap
+        # Let's use a case that genuinely doesn't: 21:00–22:00 adjacent
+        # Actually for two midnight-crossing ranges it's hard to not overlap—let's test equal endpoints
+        assert not ranges_overlap(_r("22:00", "23:00"), _r("23:00", "01:00"))
+
+
+# ---------------------------------------------------------------------------
+# validate_no_overlaps
+# ---------------------------------------------------------------------------
+
+
+class TestValidateNoOverlaps:
+    def test_no_overlaps_passes(self) -> None:
+        validate_no_overlaps(
+            [_r("00:00", "08:00"), _r("08:00", "16:00"), _r("16:00", "23:59")]
+        )
+
+    def test_overlap_raises(self) -> None:
+        with pytest.raises(ValueError, match="overlap"):
+            validate_no_overlaps([_r("08:00", "14:00"), _r("12:00", "18:00")])
+
+    def test_single_range_passes(self) -> None:
+        validate_no_overlaps([_r("08:00", "18:00")])
+
+    def test_empty_list_passes(self) -> None:
+        validate_no_overlaps([])
+
+    def test_midnight_crossing_overlap_detected(self) -> None:
+        with pytest.raises(ValueError, match="overlap"):
+            validate_no_overlaps([_r("22:00", "06:00"), _r("04:00", "08:00")])
+
+
+# ---------------------------------------------------------------------------
+# get_active_fee
+# ---------------------------------------------------------------------------
+
+
+class TestGetActiveFee:
+    def test_returns_default_when_no_ranges(self) -> None:
+        assert get_active_fee(None, 1.01) == 1.01
+
+    def test_returns_default_for_empty_list(self) -> None:
+        assert get_active_fee([], 1.01) == 1.01
+
+    def test_returns_matching_fee(self) -> None:
+        ranges = [_r("08:00", "18:00", fee=1.05)]
+        assert get_active_fee(ranges, 1.01, _now=_now(12)) == 1.05
+
+    def test_returns_default_when_no_match(self) -> None:
+        ranges = [_r("08:00", "18:00", fee=1.05)]
+        assert get_active_fee(ranges, 1.01, _now=_now(20)) == 1.01
+
+    def test_boundary_start_inclusive(self) -> None:
+        ranges = [_r("08:00", "18:00", fee=1.05)]
+        assert get_active_fee(ranges, 1.01, _now=_now(8, 0)) == 1.05
+
+    def test_boundary_end_exclusive(self) -> None:
+        ranges = [_r("08:00", "18:00", fee=1.05)]
+        assert get_active_fee(ranges, 1.01, _now=_now(18, 0)) == 1.01
+
+    def test_midnight_crossing_before_midnight(self) -> None:
+        ranges = [_r("22:00", "06:00", fee=1.03)]
+        assert get_active_fee(ranges, 1.01, _now=_now(23)) == 1.03
+
+    def test_midnight_crossing_after_midnight(self) -> None:
+        ranges = [_r("22:00", "06:00", fee=1.03)]
+        assert get_active_fee(ranges, 1.01, _now=_now(3)) == 1.03
+
+    def test_midnight_crossing_outside_range(self) -> None:
+        ranges = [_r("22:00", "06:00", fee=1.03)]
+        assert get_active_fee(ranges, 1.01, _now=_now(12)) == 1.01
+
+    def test_multiple_ranges_correct_match(self) -> None:
+        ranges = [
+            _r("00:00", "08:00", fee=1.02),
+            _r("08:00", "16:00", fee=1.05),
+            _r("16:00", "23:59", fee=1.03),
+        ]
+        assert get_active_fee(ranges, 1.01, _now=_now(10)) == 1.05
+        assert get_active_fee(ranges, 1.01, _now=_now(2)) == 1.02
+        assert get_active_fee(ranges, 1.01, _now=_now(20)) == 1.03
+
+    def test_first_matching_range_wins(self) -> None:
+        # When multiple ranges could match (should not happen if validated),
+        # the first one wins.
+        ranges = [_r("08:00", "20:00", fee=1.05), _r("10:00", "12:00", fee=1.02)]
+        assert get_active_fee(ranges, 1.01, _now=_now(11)) == 1.05
+
+
+# ---------------------------------------------------------------------------
+# Timezone-aware inputs (CEST / CET)
+# ---------------------------------------------------------------------------
+
+
+class TestGetActiveFeeTimezones:
+    """Verify that tz-aware datetimes are normalised to UTC before matching."""
+
+    # CEST = UTC+2 (Central European Summer Time, used ~late March – late Oct)
+    CEST = timezone(timedelta(hours=2))
+    # CET = UTC+1 (Central European Time, used the rest of the year)
+    CET = timezone(timedelta(hours=1))
+
+    def test_cest_datetime_normalised_to_utc_matches(self) -> None:
+        # 10:00 CEST == 08:00 UTC — schedule 08:00–18:00 should match
+        now_cest = datetime(2026, 7, 1, 10, 0, tzinfo=self.CEST)
+        ranges = [_r("08:00", "18:00", fee=1.05)]
+        assert get_active_fee(ranges, 1.01, _now=now_cest) == 1.05
+
+    def test_cest_datetime_normalised_to_utc_no_match(self) -> None:
+        # 06:00 CEST == 04:00 UTC — schedule 08:00–18:00 should NOT match
+        now_cest = datetime(2026, 7, 1, 6, 0, tzinfo=self.CEST)
+        ranges = [_r("08:00", "18:00", fee=1.05)]
+        assert get_active_fee(ranges, 1.01, _now=now_cest) == 1.01
+
+    def test_cet_datetime_normalised_to_utc_matches(self) -> None:
+        # 09:00 CET == 08:00 UTC — schedule 08:00–18:00 should match
+        now_cet = datetime(2026, 1, 15, 9, 0, tzinfo=self.CET)
+        ranges = [_r("08:00", "18:00", fee=1.05)]
+        assert get_active_fee(ranges, 1.01, _now=now_cet) == 1.05
+
+    def test_cet_datetime_before_utc_range(self) -> None:
+        # 08:30 CET == 07:30 UTC — schedule 08:00–18:00 should NOT match
+        now_cet = datetime(2026, 1, 15, 8, 30, tzinfo=self.CET)
+        ranges = [_r("08:00", "18:00", fee=1.05)]
+        assert get_active_fee(ranges, 1.01, _now=now_cet) == 1.01
+
+    def test_cest_midnight_crossing_before_midnight(self) -> None:
+        # 00:30 CEST == 22:30 UTC — schedule 22:00–06:00 UTC should match
+        now_cest = datetime(2026, 7, 2, 0, 30, tzinfo=self.CEST)
+        ranges = [_r("22:00", "06:00", fee=1.03)]
+        assert get_active_fee(ranges, 1.01, _now=now_cest) == 1.03
+
+    def test_cest_midnight_crossing_after_midnight(self) -> None:
+        # 05:00 CEST == 03:00 UTC — schedule 22:00–06:00 UTC should match
+        now_cest = datetime(2026, 7, 2, 5, 0, tzinfo=self.CEST)
+        ranges = [_r("22:00", "06:00", fee=1.03)]
+        assert get_active_fee(ranges, 1.01, _now=now_cest) == 1.03
+
+    def test_cest_midnight_crossing_outside_range(self) -> None:
+        # 14:00 CEST == 12:00 UTC — schedule 22:00–06:00 UTC should NOT match
+        now_cest = datetime(2026, 7, 2, 14, 0, tzinfo=self.CEST)
+        ranges = [_r("22:00", "06:00", fee=1.03)]
+        assert get_active_fee(ranges, 1.01, _now=now_cest) == 1.01
+
+    def test_naive_utc_datetime_still_works(self) -> None:
+        # Naive datetimes are treated as UTC (defensive fallback path)
+        now_naive = datetime(2026, 1, 1, 12, 0)  # no tzinfo
+        ranges = [_r("08:00", "18:00", fee=1.05)]
+        assert get_active_fee(ranges, 1.01, _now=now_naive) == 1.05

tests/unit/test_models_refresh_loop.py

@@ -0,0 +1,117 @@
+"""Regression tests for the periodic upstream models refresh loop."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import cast
+from unittest.mock import AsyncMock
+
+import pytest
+
+os.environ.setdefault("UPSTREAM_BASE_URL", "http://test")
+os.environ.setdefault("UPSTREAM_API_KEY", "test")
+
+from routstr.upstream.base import BaseUpstreamProvider  # noqa: E402
+
+
+class _FakeUpstream:
+    """Minimal stand-in for BaseUpstreamProvider used by the refresh loop.
+
+    Only ``base_url`` (for error logging) and ``refresh_models_cache`` (the call
+    under test) are exercised; everything else stays unused.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.base_url = f"http://{name}"
+        self.refresh_models_cache = AsyncMock()
+
+
+def _make_fake_upstream(name: str) -> BaseUpstreamProvider:
+    # The loop only uses duck-typed attributes — cast keeps the test type-clean
+    # without dragging in BaseUpstreamProvider's full constructor.
+    return cast(BaseUpstreamProvider, _FakeUpstream(name))
+
+
+@pytest.mark.asyncio
+async def test_refresh_loop_picks_up_providers_added_after_startup(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """If a provider is added after the loop starts (e.g. via reinitialize_upstreams),
+    the next loop iteration must refresh it. Previously the loop captured the upstream
+    list at startup and missed any later additions."""
+    from routstr.core.settings import settings as global_settings
+    from routstr.upstream.helpers import refresh_upstreams_models_periodically
+
+    # Tight interval so the test finishes quickly.
+    monkeypatch.setattr(
+        global_settings, "models_refresh_interval_seconds", 1, raising=False
+    )
+
+    initial_upstream = _make_fake_upstream("initial")
+    live_list: list[BaseUpstreamProvider] = [initial_upstream]
+
+    # Stub out the post-iteration sats-pricing refresh so the loop body has no DB deps.
+    async def _noop_pricing_refresh() -> None:  # pragma: no cover - trivial stub
+        return None
+
+    monkeypatch.setattr(
+        "routstr.payment.models._update_sats_pricing_once",
+        _noop_pricing_refresh,
+    )
+
+    task = asyncio.create_task(
+        refresh_upstreams_models_periodically(lambda: live_list)
+    )
+
+    try:
+        # Wait for the first iteration to refresh the initial upstream.
+        for _ in range(40):
+            if initial_upstream.refresh_models_cache.await_count >= 1:  # type: ignore[attr-defined]
+                break
+            await asyncio.sleep(0.05)
+        assert initial_upstream.refresh_models_cache.await_count >= 1, (  # type: ignore[attr-defined]
+            "loop did not refresh the initial upstream within the timeout"
+        )
+
+        # Simulate reinitialize_upstreams: replace the live list contents with new
+        # provider instances. The loop must observe the swap on its next tick.
+        new_upstream = _make_fake_upstream("added-after-startup")
+        live_list[:] = [new_upstream]
+
+        for _ in range(60):
+            if new_upstream.refresh_models_cache.await_count >= 1:  # type: ignore[attr-defined]
+                break
+            await asyncio.sleep(0.05)
+
+        assert new_upstream.refresh_models_cache.await_count >= 1, (  # type: ignore[attr-defined]
+            "loop did not refresh the upstream added after startup — "
+            "regression: list snapshot captured at startup"
+        )
+    finally:
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+
+
+@pytest.mark.asyncio
+async def test_refresh_loop_disabled_when_interval_non_positive(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from routstr.core.settings import settings as global_settings
+    from routstr.upstream.helpers import refresh_upstreams_models_periodically
+
+    monkeypatch.setattr(
+        global_settings, "models_refresh_interval_seconds", 0, raising=False
+    )
+
+    upstream = _make_fake_upstream("never-refreshed")
+
+    # Loop must return immediately without ever touching the upstream.
+    await asyncio.wait_for(
+        refresh_upstreams_models_periodically(lambda: [upstream]),
+        timeout=1.0,
+    )
+    upstream.refresh_models_cache.assert_not_awaited()  # type: ignore[attr-defined]

tests/unit/test_nostr_analytics.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import pytest
+
+from routstr.nostr import analytics
+
+
+def test_aggregate_top_model_usage_sums_metrics() -> None:
+    model_usage_mix = {
+        "top_models": ["openai/gpt-4o", "anthropic/claude-3.5-sonnet"],
+        "metrics": [
+            {
+                "model_counts": {
+                    "openai/gpt-4o": 4,
+                    "anthropic/claude-3.5-sonnet": 2,
+                },
+                "model_revenue_msats": {
+                    "openai/gpt-4o": 1500,
+                    "anthropic/claude-3.5-sonnet": 700,
+                },
+                "model_tokens": {
+                    "openai/gpt-4o": 1200,
+                    "anthropic/claude-3.5-sonnet": 600,
+                },
+                "others": 1,
+                "others_revenue_msats": 300,
+                "others_tokens": 200,
+            },
+            {
+                "model_counts": {
+                    "openai/gpt-4o": 3,
+                    "anthropic/claude-3.5-sonnet": 1,
+                },
+                "model_revenue_msats": {
+                    "openai/gpt-4o": 1000,
+                    "anthropic/claude-3.5-sonnet": 500,
+                },
+                "model_tokens": {
+                    "openai/gpt-4o": 800,
+                    "anthropic/claude-3.5-sonnet": 300,
+                },
+                "others": 2,
+                "others_revenue_msats": 450,
+                "others_tokens": 350,
+            },
+        ],
+    }
+
+    rows, others = analytics._aggregate_top_model_usage(model_usage_mix)
+    assert rows == [
+        {
+            "model": "openai/gpt-4o",
+            "successful_requests": 7,
+            "revenue_msats": 2500.0,
+            "total_tokens": 2000,
+        },
+        {
+            "model": "anthropic/claude-3.5-sonnet",
+            "successful_requests": 3,
+            "revenue_msats": 1200.0,
+            "total_tokens": 900,
+        },
+    ]
+    assert others == {
+        "successful_requests": 3,
+        "revenue_msats": 750.0,
+        "total_tokens": 550,
+    }
+
+
+def test_build_stats_snapshot_payload_schema_and_shape(monkeypatch: Any) -> None:
+    seen_windows: set[tuple[int, int]] = set()
+
+    def fake_usage_dashboard(
+        *, interval: int, hours: int, error_limit: int, model_limit: int
+    ) -> dict[str, Any]:
+        seen_windows.add((hours, interval))
+        assert error_limit == 1
+        assert model_limit == 20
+        return {
+            "summary": {
+                "total_requests": hours,
+                "successful_chat_completions": max(1, hours - 1),
+                "failed_requests": 2,
+                "success_rate": 90.0,
+                "unique_models_count": 2,
+                "input_tokens": 2000,
+                "output_tokens": 1000,
+                "total_tokens": 3000,
+                "revenue_msats": 9000.0,
+                "refunds_msats": 1000.0,
+                "net_revenue_msats": 8000.0,
+                "revenue_sats": 9.0,
+                "refunds_sats": 1.0,
+                "net_revenue_sats": 8.0,
+            },
+            "model_usage_mix": {
+                "top_models": ["openai/gpt-4o"],
+                "metrics": [
+                    {
+                        "timestamp": "2026-03-02 10:00:00",
+                        "model_counts": {"openai/gpt-4o": hours},
+                        "model_revenue_msats": {"openai/gpt-4o": float(hours * 100)},
+                        "model_tokens": {"openai/gpt-4o": hours * 10},
+                        "others": 4,
+                        "others_revenue_msats": 1800.0,
+                        "others_tokens": 400,
+                    }
+                ],
+            },
+        }
+
+    monkeypatch.setattr(
+        analytics.log_manager, "get_usage_dashboard", fake_usage_dashboard
+    )
+    monkeypatch.setattr(analytics.settings, "npub", "npub1example")
+    monkeypatch.setattr(analytics.settings, "http_url", "https://node.example.com")
+    monkeypatch.setattr(analytics.settings, "onion_url", "")
+
+    payload = analytics.build_stats_snapshot_payload(
+        "provider123",
+        public_key_hex="ab" * 32,
+        generated_at=1772451600,
+    )
+
+    assert payload["schema"] == analytics.ANALYTICS_SCHEMA
+    assert payload["provider_id"] == "provider123"
+    assert payload["window_hours"] == 24
+    assert payload["interval_minutes"] == 60
+    assert payload["endpoint_urls"] == ["https://node.example.com"]
+    assert seen_windows == {
+        (24, 60),
+        (7 * 24, 6 * 60),
+        (30 * 24, 24 * 60),
+        (90 * 24, 24 * 60),
+        (365 * 24, 7 * 24 * 60),
+    }
+    assert set(payload["windows"].keys()) == {"24h", "7d", "30d", "3m", "1y"}
+    assert payload["windows"]["1y"]["interval_minutes"] == 7 * 24 * 60
+    assert payload["summary"]["total_requests"] == 24
+    assert payload["top_model_usage"] == [
+        {
+            "model": "openai/gpt-4o",
+            "successful_requests": 24,
+            "revenue_msats": 2400.0,
+            "total_tokens": 240,
+        }
+    ]
+    assert payload["others_usage"] == {
+        "successful_requests": 4,
+        "revenue_msats": 1800.0,
+        "total_tokens": 400,
+    }
+
+
+def test_create_stats_snapshot_event_tags() -> None:
+    private_key_hex = "11" * 32
+    event = analytics.create_stats_snapshot_event(
+        private_key_hex,
+        "provider123",
+        payload_json='{"schema":"routstr.analytics.snapshot.v1"}',
+        d_tag="provider123:stats",
+    )
+
+    tags = event["tags"]
+    assert ["d", "provider123:stats"] in tags
+    assert ["provider", "provider123"] in tags
+    assert ["schema", analytics.ANALYTICS_SCHEMA] in tags
+    assert all(tag[0] != "period" for tag in tags)
+
+
+def test_fingerprint_payload_ignores_generated_at() -> None:
+    a = {"schema": analytics.ANALYTICS_SCHEMA, "generated_at": 1000, "summary": {"x": 1}}
+    b = {"schema": analytics.ANALYTICS_SCHEMA, "generated_at": 2000, "summary": {"x": 1}}
+
+    assert analytics._fingerprint_payload(a) == analytics._fingerprint_payload(b)
+
+
+@pytest.mark.asyncio
+async def test_publish_usage_analytics_skips_when_disabled(monkeypatch: Any) -> None:
+    delays: list[int] = []
+
+    async def fake_sleep(seconds: int) -> None:
+        delays.append(seconds)
+        raise asyncio.CancelledError()
+
+    def fail_build(*args: Any, **kwargs: Any) -> dict[str, Any]:
+        raise AssertionError("build_stats_snapshot_payload should not be called")
+
+    monkeypatch.setattr(analytics.settings, "enable_analytics_sharing", False)
+    monkeypatch.setattr(analytics, "build_stats_snapshot_payload", fail_build)
+    monkeypatch.setattr(analytics.asyncio, "sleep", fake_sleep)
+
+    await analytics.publish_usage_analytics()
+
+    assert delays == [analytics.DISABLED_POLL_SECONDS]
+
+
+@pytest.mark.asyncio
+async def test_publish_usage_analytics_skips_without_nsec(monkeypatch: Any) -> None:
+    delays: list[int] = []
+
+    async def fake_sleep(seconds: int) -> None:
+        delays.append(seconds)
+        raise asyncio.CancelledError()
+
+    def fail_build(*args: Any, **kwargs: Any) -> dict[str, Any]:
+        raise AssertionError("build_stats_snapshot_payload should not be called")
+
+    monkeypatch.setattr(analytics.settings, "enable_analytics_sharing", True)
+    monkeypatch.setattr(analytics.settings, "nsec", "")
+    monkeypatch.setattr(analytics, "build_stats_snapshot_payload", fail_build)
+    monkeypatch.setattr(analytics.asyncio, "sleep", fake_sleep)
+
+    await analytics.publish_usage_analytics()
+
+    assert delays == [analytics.DISABLED_POLL_SECONDS]
+
+
+@pytest.mark.asyncio
+async def test_publish_usage_analytics_dedupes_unchanged_payload(monkeypatch: Any) -> None:
+    published_events: list[dict[str, Any]] = []
+    sleep_calls = 0
+
+    async def fake_sleep(seconds: int) -> None:
+        nonlocal sleep_calls
+        sleep_calls += 1
+        if sleep_calls >= 2:
+            raise asyncio.CancelledError()
+
+    def fake_build_payload(
+        provider_id: str,
+        *,
+        public_key_hex: str,
+        generated_at: int,
+        window_hours: int = 24,
+        interval_minutes: int = 60,
+        model_limit: int = 10,
+    ) -> dict[str, Any]:
+        _ = (public_key_hex, generated_at, window_hours, interval_minutes, model_limit)
+        return {
+            "schema": analytics.ANALYTICS_SCHEMA,
+            "generated_at": generated_at,
+            "provider_id": provider_id,
+            "summary": {"total_requests": 1},
+        }
+
+    async def fake_publish(relay_url: str, event: dict[str, Any]) -> bool:
+        _ = relay_url
+        published_events.append(event)
+        return True
+
+    monkeypatch.setattr(analytics.settings, "enable_analytics_sharing", True)
+    monkeypatch.setattr(analytics.settings, "nsec", "11" * 32)
+    monkeypatch.setattr(analytics.settings, "relays", ["wss://relay.example.com"])
+    monkeypatch.setattr(analytics.settings, "provider_id", "")
+    monkeypatch.setattr(analytics, "build_stats_snapshot_payload", fake_build_payload)
+    monkeypatch.setattr(analytics, "publish_to_relay", fake_publish)
+    monkeypatch.setattr(analytics.asyncio, "sleep", fake_sleep)
+
+    await analytics.publish_usage_analytics()
+
+    assert len(published_events) == 1
+    assert ["schema", analytics.ANALYTICS_SCHEMA] in published_events[0].get("tags", [])

tests/unit/test_settings.py

@@ -2,6 +2,7 @@ import os
 
 import pytest
 from sqlalchemy.ext.asyncio import create_async_engine
+from sqlmodel import text
 from sqlmodel.ext.asyncio.session import AsyncSession
 
 from routstr.core.settings import SettingsService
@@ -11,6 +12,7 @@ from routstr.core.settings import SettingsService
 async def test_settings_seed_from_env_and_persist() -> None:
     os.environ["UPSTREAM_BASE_URL"] = "https://api.test/v1"
     os.environ.pop("ONION_URL", None)
+    os.environ.pop("ENABLE_ANALYTICS_SHARING", None)
 
     engine = create_async_engine("sqlite+aiosqlite:///:memory:")
     async with AsyncSession(engine, expire_on_commit=False) as session:
@@ -19,19 +21,53 @@ async def test_settings_seed_from_env_and_persist() -> None:
         assert settings.upstream_base_url == "https://api.test/v1"
         # ONION_URL may be empty if not discoverable
         assert isinstance(settings.onion_url, str)
+        assert settings.enable_analytics_sharing is True
 
 
 @pytest.mark.asyncio
 async def test_settings_db_precedence_over_env() -> None:
     os.environ["UPSTREAM_BASE_URL"] = "https://api.env/v1"
+    os.environ["ENABLE_ANALYTICS_SHARING"] = "true"
 
     engine = create_async_engine("sqlite+aiosqlite:///:memory:")
     async with AsyncSession(engine, expire_on_commit=False) as session:
         _ = await SettingsService.initialize(session)
-        updated = await SettingsService.update({"name": "DBName"}, session)
+        updated = await SettingsService.update(
+            {"name": "DBName", "enable_analytics_sharing": False}, session
+        )
         assert updated.name == "DBName"
+        assert updated.enable_analytics_sharing is False
 
         # Change env and re-initialize; DB should still win
         os.environ["NAME"] = "EnvName"
+        os.environ["ENABLE_ANALYTICS_SHARING"] = "true"
         again = await SettingsService.initialize(session)
         assert again.name == "DBName"
+        assert again.enable_analytics_sharing is False
+
+
+@pytest.mark.asyncio
+async def test_settings_initialize_discards_unknown_keys() -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with AsyncSession(engine, expire_on_commit=False) as session:
+        _ = await SettingsService.initialize(session)
+
+        # Simulate older persisted key name and an unknown key.
+        await session.exec(  # type: ignore
+            text(
+                "UPDATE settings SET data = :data WHERE id = 1"
+            ).bindparams(
+                data='{"name":"LegacyNode","nostr_analytics_enabled":false,"unknown_key":123}'
+            )
+        )
+        await session.commit()
+
+        reloaded = await SettingsService.initialize(session)
+        assert reloaded.name == "LegacyNode"
+        assert reloaded.enable_analytics_sharing is True
+
+        row = await session.exec(text("SELECT data FROM settings WHERE id = 1"))  # type: ignore
+        stored_data = row.first()[0]
+        assert '"enable_analytics_sharing": true' in stored_data
+        assert "nostr_analytics_enabled" not in stored_data
+        assert "unknown_key" not in stored_data

tests/unit/test_stream_id_injection.py

@@ -0,0 +1,117 @@
+import json
+from collections.abc import AsyncGenerator
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from routstr.core.db import ApiKey
+from routstr.upstream.base import BaseUpstreamProvider
+
+
+@pytest.mark.asyncio
+async def test_stream_with_id_injection() -> None:
+    """Test that stream_with_cost correctly injects IDs into complete JSON chunks but skips partials."""
+    provider = BaseUpstreamProvider(
+        base_url="https://api.example.com", api_key="test_key"
+    )
+
+    # Mock response with mixed chunks:
+    # 1. Complete JSON without ID
+    # 2. Partial JSON (should be passed through)
+    # 3. Complete JSON with ID (should be preserved or updated if requested_model is set)
+    # 4. [DONE] message
+    chunks = [
+        b'data: {"choices": [{"delta": {"content": "Hello"}}]}\n\n',
+        b'data: {"choices": [{"delta": {"content": "',  # Partial
+        b'world"}}]}\n\n',
+        b'data: {"id": "existing-id", "choices": [{"delta": {"content": "!"}}]}\n\n',
+        b"data: [DONE]\n\n",
+    ]
+
+    async def aiter_bytes() -> AsyncGenerator[bytes, None]:
+        for chunk in chunks:
+            yield chunk
+
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.headers = {"content-type": "text/event-stream"}
+    mock_response.aiter_bytes = aiter_bytes
+
+    key = MagicMock(spec=ApiKey)
+    key.hashed_key = "test_hash"
+    key.balance = 1000
+
+    background_tasks = MagicMock()
+
+    # We need to mock adjust_payment_for_tokens since it's called at the end
+    with MagicMock():
+        from routstr.upstream import base
+
+        # Mocking the module-level function used in the generator
+        base.adjust_payment_for_tokens = AsyncMock(
+            return_value={"total_usd": 0.1, "total_msats": 100}
+        )
+        # create_session() is used as an async context manager whose entered
+        # value exposes an awaitable .get(). Build a mock that behaves that
+        # way so the post-stream cost-chunk emission can run.
+        mock_session = MagicMock()
+        mock_session.get = AsyncMock(return_value=key)
+        mock_ctx = MagicMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_session)
+        mock_ctx.__aexit__ = AsyncMock(return_value=None)
+        base.create_session = MagicMock(return_value=mock_ctx)
+
+        streaming_response = await provider.handle_streaming_chat_completion(
+            response=mock_response,
+            key=key,
+            max_cost_for_model=100,
+            background_tasks=background_tasks,
+            requested_model="test-model",
+        )
+
+        results = []
+        async for chunk in streaming_response.body_iterator:
+            results.append(chunk)
+
+        # Parse results
+        parsed_results = []
+        for r in results:
+            if isinstance(r, bytes) and r.startswith(b"data: "):
+                data = r[6:].decode().strip()
+                if data == "[DONE]":
+                    parsed_results.append(data)
+                else:
+                    try:
+                        parsed_results.append(json.loads(data))
+                    except (json.JSONDecodeError, UnicodeDecodeError):
+                        parsed_results.append(
+                            data
+                        )  # Keep as string if it failed to parse
+
+        # Verifications
+        # 1. First chunk should have an injected ID and the requested model
+        assert isinstance(parsed_results[0], dict)
+        assert "id" in parsed_results[0]
+        assert parsed_results[0]["id"].startswith("chatcmpl-")
+        assert parsed_results[0]["model"] == "test-model"
+
+        # 2. Second chunk was partial, should be passed as-is
+        # In current implementation, re.split(b"data: ", b'data: {...') gives ['', '{...']
+        # The first empty part is skipped. The second part is processed.
+
+        # Check that we have results
+        assert len(parsed_results) >= 4
+
+        # Find the chunk that was "existing-id"
+        id_chunk = next(
+            r
+            for r in parsed_results
+            if isinstance(r, dict)
+            and "choices" in r
+            and r["choices"][0]["delta"].get("content") == "!"
+        )
+        assert id_chunk["id"] == parsed_results[0]["id"]
+        assert id_chunk["model"] == "test-model"
+
+        # 4. [DONE] should be there
+        assert "[DONE]" in parsed_results

tests/unit/test_upstream_azure.py

@@ -0,0 +1,82 @@
+"""Tests for Azure upstream provider request normalization."""
+
+from routstr.payment.models import Architecture, Model, Pricing
+from routstr.upstream.azure import AzureUpstreamProvider
+
+
+def create_test_model(model_id: str, canonical_slug: str | None = None) -> Model:
+    return Model(
+        id=model_id,
+        name=model_id,
+        created=0,
+        description="test",
+        context_length=8192,
+        architecture=Architecture(
+            modality="text",
+            input_modalities=["text"],
+            output_modalities=["text"],
+            tokenizer="test",
+            instruct_type=None,
+        ),
+        pricing=Pricing(
+            prompt=0.001,
+            completion=0.001,
+            request=0.0,
+            image=0.0,
+            web_search=0.0,
+            internal_reasoning=0.0,
+        ),
+        canonical_slug=canonical_slug,
+    )
+
+
+def test_prepare_headers_uses_azure_api_key_header() -> None:
+    provider = AzureUpstreamProvider(
+        base_url="https://example.openai.azure.com",
+        api_key="azure-key",
+        api_version="2024-02-15-preview",
+    )
+
+    headers = provider.prepare_headers({"Authorization": "Bearer user-token"})
+
+    assert headers["api-key"] == "azure-key"
+    assert "Authorization" not in headers
+    assert "authorization" not in headers
+
+
+def test_prepare_params_normalizes_azure_api_version() -> None:
+    provider = AzureUpstreamProvider(
+        base_url="https://example.openai.azure.com",
+        api_key="azure-key",
+        api_version="\ufeff v1 ",
+    )
+
+    params = provider.prepare_params("chat/completions", {})
+
+    assert params["api-version"] == "2024-02-15-preview"
+
+
+def test_normalize_request_path_includes_deployment_id() -> None:
+    provider = AzureUpstreamProvider(
+        base_url="https://example.openai.azure.com/openai/v1",
+        api_key="azure-key",
+        api_version="2024-02-15-preview",
+    )
+    model = create_test_model("azure/gpt-4o", canonical_slug="deploy-gpt4o")
+
+    path = provider.normalize_request_path("v1/chat/completions", model)
+
+    assert path == "openai/deployments/deploy-gpt4o/chat/completions"
+
+
+def test_get_request_base_url_strips_openai_v1_suffix() -> None:
+    provider = AzureUpstreamProvider(
+        base_url="https://example.openai.azure.com/openai/v1",
+        api_key="azure-key",
+        api_version="2024-02-15-preview",
+    )
+    model = create_test_model("azure/gpt-4o")
+
+    base_url = provider.get_request_base_url("chat/completions", model)
+
+    assert base_url == "https://example.openai.azure.com"

tests/unit/test_upstream_routstr.py

@@ -0,0 +1,76 @@
+from types import TracebackType
+from unittest.mock import Mock
+
+import httpx
+import pytest
+
+from routstr.upstream.routstr import RoutstrUpstreamProvider
+
+
+class DummyAsyncClient:
+    def __init__(self, response: Mock | None = None, error: Exception | None = None):
+        self.response = response
+        self.error = error
+        self.calls: list[dict[str, object]] = []
+
+    async def __aenter__(self) -> "DummyAsyncClient":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> bool:
+        return False
+
+    async def get(
+        self, url: str, headers: dict[str, str], timeout: float
+    ) -> Mock:
+        self.calls.append({"url": url, "headers": headers, "timeout": timeout})
+        if self.error is not None:
+            raise self.error
+        assert self.response is not None
+        return self.response
+
+
+@pytest.mark.asyncio
+async def test_get_balance_omits_auth_header_when_api_key_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    response = Mock()
+    response.json.return_value = {"balance_msats": 42000}
+    response.raise_for_status.return_value = None
+
+    client = DummyAsyncClient(response=response)
+    monkeypatch.setattr("routstr.upstream.routstr.httpx.AsyncClient", lambda: client)
+
+    provider = RoutstrUpstreamProvider(base_url="https://node.example", api_key="")
+
+    balance = await provider.get_balance()
+
+    assert balance == 42.0
+    assert client.calls == [
+        {
+            "url": "https://node.example/v1/balance/info",
+            "headers": {},
+            "timeout": 10.0,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_get_balance_returns_none_on_connect_timeout(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = DummyAsyncClient(error=httpx.ConnectTimeout("timed out"))
+    monkeypatch.setattr("routstr.upstream.routstr.httpx.AsyncClient", lambda: client)
+
+    provider = RoutstrUpstreamProvider(
+        base_url="https://node.example",
+        api_key="secret",
+    )
+
+    balance = await provider.get_balance()
+
+    assert balance is None

tests/unit/test_wallet.py

@@ -108,6 +108,92 @@ async def test_credit_balance() -> None:
             assert mock_session.refresh.called
 
 
+@pytest.mark.asyncio
+async def test_swap_to_primary_mint_insufficient_for_fees() -> None:
+    """Token amount is less than melt_quote.amount + melt_quote.fee_reserve."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token = Mock()
+    mock_token.mint = "http://foreign:3338"
+    mock_token.unit = "sat"
+    mock_token.amount = 404
+    mock_token.keysets = ["keyset1"]
+    mock_token.proofs = [{"amount": 404}]
+
+    mock_token_wallet = Mock()
+    mock_token_wallet.load_mint = AsyncMock()
+    mock_token_wallet.load_proofs = AsyncMock()
+
+    mock_primary_wallet = Mock()
+    mock_primary_wallet.load_mint = AsyncMock()
+    mock_primary_wallet.load_proofs = AsyncMock()
+
+    mock_mint_quote = Mock()
+    mock_mint_quote.quote = "mint_quote_123"
+    mock_mint_quote.request = "lnbc1..."
+    mock_primary_wallet.request_mint = AsyncMock(return_value=mock_mint_quote)
+
+    mock_melt_quote = Mock()
+    mock_melt_quote.quote = "melt_quote_123"
+    mock_melt_quote.amount = 400
+    mock_melt_quote.fee_reserve = 12  # total needed: 412 > 404
+    mock_token_wallet.melt_quote = AsyncMock(return_value=mock_melt_quote)
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                with pytest.raises(ValueError, match="insufficient to cover melt fees"):
+                    await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+    # melt should never have been called
+    mock_token_wallet.melt.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_swap_to_primary_mint_melt_error_wrapped() -> None:
+    """Melt failure from cashu lib is wrapped as ValueError."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token = Mock()
+    mock_token.mint = "http://foreign:3338"
+    mock_token.unit = "sat"
+    mock_token.amount = 5000
+    mock_token.keysets = ["keyset1"]
+    mock_token.proofs = [{"amount": 5000}]
+
+    mock_token_wallet = Mock()
+    mock_token_wallet.load_mint = AsyncMock()
+    mock_token_wallet.load_proofs = AsyncMock()
+
+    mock_primary_wallet = Mock()
+    mock_primary_wallet.load_mint = AsyncMock()
+    mock_primary_wallet.load_proofs = AsyncMock()
+
+    mock_mint_quote = Mock()
+    mock_mint_quote.quote = "mint_quote_456"
+    mock_mint_quote.request = "lnbc1..."
+    mock_primary_wallet.request_mint = AsyncMock(return_value=mock_mint_quote)
+
+    mock_melt_quote = Mock()
+    mock_melt_quote.quote = "melt_quote_456"
+    mock_melt_quote.amount = 4940
+    mock_melt_quote.fee_reserve = 50  # total 4990 < 5000, passes fee check
+    mock_token_wallet.melt_quote = AsyncMock(return_value=mock_melt_quote)
+    mock_token_wallet.melt = AsyncMock(
+        side_effect=Exception("Provided: 5000, needed: 5100 (Code: 11000)")
+    )
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                with pytest.raises(ValueError, match="Failed to melt token"):
+                    await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+
 @pytest.mark.asyncio
 async def test_recieve_token_untrusted_mint() -> None:
     mock_wallet = Mock()
@@ -131,3 +217,104 @@ async def test_recieve_token_untrusted_mint() -> None:
                 assert amount == 900
                 assert unit == "sat"
                 assert mint == "http://mint:3338"
+
+
+@pytest.mark.asyncio
+@pytest.mark.asyncio
+async def test_swap_to_primary_mint_already_on_primary() -> None:
+    from routstr.core.settings import settings
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token = Mock()
+    mock_token.mint = settings.primary_mint
+    mock_token.amount = 1000
+    mock_token.unit = "sat"
+    mock_token.proofs = []
+
+    mock_token_wallet = Mock()
+    mock_token_wallet.split = AsyncMock(return_value=None)
+    mock_token_wallet.request_mint = AsyncMock()
+    mock_token_wallet.melt_quote = AsyncMock()
+
+    with patch("routstr.wallet.get_wallet", AsyncMock(return_value=mock_token_wallet)):
+        amount, unit, mint = await swap_to_primary_mint(mock_token, mock_token_wallet)
+
+    assert amount == 1000
+    assert unit == "sat"
+    assert mint == settings.primary_mint
+    mock_token_wallet.split.assert_called_once()
+    mock_token_wallet.request_mint.assert_not_called()
+    mock_token_wallet.melt_quote.assert_not_called()
+
+
+async def test_swap_to_primary_mint_success() -> None:
+    """Test successful swap with dynamic fee calculation."""
+    from routstr.wallet import swap_to_primary_mint
+
+    mock_token = Mock()
+    mock_token.mint = "http://foreign:3338"
+    mock_token.unit = "sat"
+    mock_token.amount = 1000
+    mock_token.keysets = ["keyset1"]
+    mock_token.proofs = [{"amount": 1000}]
+
+    mock_token_wallet = Mock()
+    mock_token_wallet.load_mint = AsyncMock()
+    mock_token_wallet.load_proofs = AsyncMock()
+
+    mock_primary_wallet = Mock()
+    mock_primary_wallet.load_mint = AsyncMock()
+    mock_primary_wallet.load_proofs = AsyncMock()
+
+    # Mocks for the estimation phase
+    # 1. request_mint(dummy_amount=1000) -> invoice_dummy
+    # 2. melt_quote(invoice_dummy) -> fee=10
+
+    # Mocks for the execution phase
+    # 3. request_mint(minted_amount=990) -> invoice_real
+    # 4. melt_quote(invoice_real) -> amount=990, fee=10
+    # 5. melt() -> success
+    # 6. mint() -> success
+
+    mock_mint_quote_dummy = Mock(quote="dummy_quote", request="lnbc_dummy")
+    mock_mint_quote_real = Mock(quote="real_quote", request="lnbc_real")
+
+    # side_effect for request_mint to return dummy then real
+    mock_primary_wallet.request_mint = AsyncMock(
+        side_effect=[mock_mint_quote_dummy, mock_mint_quote_real]
+    )
+
+    mock_melt_quote_dummy = Mock(amount=1000, fee_reserve=10)
+    mock_melt_quote_real = Mock(amount=990, fee_reserve=10)
+
+    # side_effect for melt_quote
+    mock_token_wallet.melt_quote = AsyncMock(
+        side_effect=[mock_melt_quote_dummy, mock_melt_quote_real]
+    )
+
+    mock_token_wallet.melt = AsyncMock(return_value="melted_proofs")
+    mock_primary_wallet.mint = AsyncMock(return_value="minted_proofs")
+
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "primary_mint", "http://primary:3338"):
+        with patch.object(settings, "primary_mint_unit", "sat"):
+            with patch("routstr.wallet.get_wallet", return_value=mock_primary_wallet):
+                amount, unit, mint = await swap_to_primary_mint(
+                    mock_token, mock_token_wallet
+                )
+
+                assert amount == 990  # 1000 - 10
+                assert unit == "sat"
+                assert mint == "http://primary:3338"
+
+                # Verify call order/counts
+                assert mock_primary_wallet.request_mint.call_count == 2
+                # First call with full amount for estimation
+                mock_primary_wallet.request_mint.assert_any_call(1000)
+                # Second call with calculated amount
+                mock_primary_wallet.request_mint.assert_any_call(990)
+
+                assert mock_token_wallet.melt_quote.call_count == 2
+                assert mock_token_wallet.melt.called
+                assert mock_primary_wallet.mint.called

tests/unit/test_x_cashu_cost_sats.py

@@ -0,0 +1,216 @@
+import json
+import os
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+
+os.environ.setdefault("UPSTREAM_BASE_URL", "http://test")
+os.environ.setdefault("UPSTREAM_API_KEY", "test")
+
+from routstr.payment.cost_calculation import CostData  # noqa: E402
+from routstr.upstream.base import BaseUpstreamProvider  # noqa: E402
+
+
+def _make_provider() -> BaseUpstreamProvider:
+    return BaseUpstreamProvider(base_url="http://test", api_key="test-key")
+
+
+def _make_httpx_response(status_code: int = 200) -> httpx.Response:
+    return httpx.Response(status_code, headers={})
+
+
+def _make_cost_data(total_msats: int = 5000) -> CostData:
+    return CostData(
+        base_msats=0,
+        input_msats=3000,
+        output_msats=2000,
+        total_msats=total_msats,
+        total_usd=0.00025,
+        input_tokens=100,
+        output_tokens=50,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming (chat completions)
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_non_streaming_includes_cost_sats() -> None:
+    provider = _make_provider()
+    cost_data = _make_cost_data(total_msats=5000)
+
+    response_body = {
+        "model": "gpt-4o",
+        "usage": {
+            "prompt_tokens": 100,
+            "completion_tokens": 50,
+            "total_tokens": 150,
+            "cost": 0.00025,
+        },
+    }
+    content_str = json.dumps(response_body)
+    httpx_response = _make_httpx_response()
+
+    with (
+        patch.object(provider, "get_x_cashu_cost", new=AsyncMock(return_value=cost_data)),
+        patch.object(provider, "send_refund", new=AsyncMock(return_value="cashuA_refund_token")),
+    ):
+        response = await provider.handle_x_cashu_non_streaming_response(
+            content_str=content_str,
+            response=httpx_response,
+            amount=10000,
+            unit="msat",
+            max_cost_for_model=10000,
+            mint=None,
+            payment_token_hash=None,
+        )
+
+    body = json.loads(response.body)
+    assert "cost_sats" in body["usage"]
+    assert body["usage"]["cost_sats"] == 5  # 5000 msats // 1000
+
+
+@pytest.mark.asyncio
+async def test_non_streaming_cost_sats_value_rounds_down() -> None:
+    provider = _make_provider()
+    cost_data = _make_cost_data(total_msats=1999)
+
+    response_body = {"model": "gpt-4o", "usage": {"prompt_tokens": 10}}
+    content_str = json.dumps(response_body)
+
+    with (
+        patch.object(provider, "get_x_cashu_cost", new=AsyncMock(return_value=cost_data)),
+        patch.object(provider, "send_refund", new=AsyncMock(return_value="cashuA_refund_token")),
+    ):
+        response = await provider.handle_x_cashu_non_streaming_response(
+            content_str=content_str,
+            response=_make_httpx_response(),
+            amount=10000,
+            unit="msat",
+            max_cost_for_model=10000,
+        )
+
+    body = json.loads(response.body)
+    assert body["usage"]["cost_sats"] == 1  # 1999 // 1000
+
+
+@pytest.mark.asyncio
+async def test_non_streaming_preserves_existing_usage_fields() -> None:
+    provider = _make_provider()
+    cost_data = _make_cost_data(total_msats=3000)
+
+    response_body = {
+        "model": "gpt-4o",
+        "usage": {
+            "prompt_tokens": 100,
+            "completion_tokens": 50,
+            "total_tokens": 150,
+            "cost": 0.00015,
+        },
+    }
+
+    with (
+        patch.object(provider, "get_x_cashu_cost", new=AsyncMock(return_value=cost_data)),
+        patch.object(provider, "send_refund", new=AsyncMock(return_value="cashuA_refund_token")),
+    ):
+        response = await provider.handle_x_cashu_non_streaming_response(
+            content_str=json.dumps(response_body),
+            response=_make_httpx_response(),
+            amount=10000,
+            unit="msat",
+            max_cost_for_model=10000,
+        )
+
+    body = json.loads(response.body)
+    usage = body["usage"]
+    assert usage["prompt_tokens"] == 100
+    assert usage["completion_tokens"] == 50
+    assert usage["total_tokens"] == 150
+    assert usage["cost"] == 0.00015
+    assert usage["cost_sats"] == 3
+
+
+# ---------------------------------------------------------------------------
+# Streaming (chat completions)
+# ---------------------------------------------------------------------------
+
+async def _collect_streaming(response: object) -> list[str]:
+    chunks: list[str] = []
+    async for chunk in response.body_iterator:  # type: ignore[attr-defined]
+        if isinstance(chunk, bytes):
+            chunks.append(chunk.decode("utf-8"))
+        else:
+            chunks.append(str(chunk))
+    return chunks
+
+
+@pytest.mark.asyncio
+async def test_streaming_includes_cost_sats_in_usage_chunk() -> None:
+    provider = _make_provider()
+    cost_data = _make_cost_data(total_msats=7000)
+
+    usage_chunk = {
+        "id": "chatcmpl-123",
+        "model": "gpt-4o",
+        "usage": {"prompt_tokens": 100, "completion_tokens": 50, "total_tokens": 150},
+    }
+    content_str = "\n".join([
+        'data: {"id":"chatcmpl-123","model":"gpt-4o","choices":[]}',
+        f"data: {json.dumps(usage_chunk)}",
+        "data: [DONE]",
+    ])
+
+    with patch.object(provider, "get_x_cashu_cost", new=AsyncMock(return_value=cost_data)):
+        response = await provider.handle_x_cashu_streaming_response(
+            content_str=content_str,
+            response=_make_httpx_response(),
+            amount=10000,
+            unit="msat",
+            max_cost_for_model=10000,
+            mint=None,
+            payment_token_hash=None,
+        )
+
+    chunks = await _collect_streaming(response)
+
+    full_output = "".join(chunks)
+    usage_line = next(
+        line for line in full_output.split("\n") if '"usage"' in line and "cost_sats" in line
+    )
+    data_json = json.loads(usage_line.lstrip("data: ").strip())
+    assert data_json["usage"]["cost_sats"] == 7  # 7000 // 1000
+
+
+@pytest.mark.asyncio
+async def test_streaming_non_usage_chunks_unmodified() -> None:
+    provider = _make_provider()
+    cost_data = _make_cost_data(total_msats=2000)
+
+    regular_chunk = {"id": "chatcmpl-123", "model": "gpt-4o", "choices": [{"delta": {"content": "hi"}}]}
+    usage_chunk = {"id": "chatcmpl-123", "model": "gpt-4o", "usage": {"prompt_tokens": 10}}
+    content_str = "\n".join([
+        f"data: {json.dumps(regular_chunk)}",
+        f"data: {json.dumps(usage_chunk)}",
+        "data: [DONE]",
+    ])
+
+    with patch.object(provider, "get_x_cashu_cost", new=AsyncMock(return_value=cost_data)):
+        response = await provider.handle_x_cashu_streaming_response(
+            content_str=content_str,
+            response=_make_httpx_response(),
+            amount=10000,
+            unit="msat",
+            max_cost_for_model=10000,
+        )
+
+    chunks = await _collect_streaming(response)
+
+    lines = [
+        line for line in "".join(chunks).split("\n")
+        if line.startswith("data: ") and line != "data: [DONE]"
+    ]
+    regular_line_data = json.loads(lines[0][6:])
+    # regular chunk should not have cost_sats injected
+    assert "cost_sats" not in regular_line_data.get("usage", {})

ui/.eslintrc.json

@@ -1,11 +0,0 @@
-{
-  "extends": [
-    "next",
-    "next/core-web-vitals",
-    "eslint:recommended",
-    "plugin:react/recommended",
-    "plugin:@typescript-eslint/recommended",
-    "prettier"
-  ],
-  "plugins": ["react", "@typescript-eslint"]
-}

ui/.gitignore

@@ -42,3 +42,4 @@ next-env.d.ts
 
 # favicon conflicts
 /app/favicon.ico
+.pnpm-store/

ui/.prettierignore

@@ -0,0 +1,5 @@
+pnpm-lock.yaml
+.next
+node_modules
+out
+next-env.d.ts

ui/app/balances/page.tsx

@@ -2,12 +2,11 @@
 
 import { useCurrencyStore } from '@/lib/stores/currency';
 import { useQuery } from '@tanstack/react-query';
-import { AppSidebar } from '@/components/app-sidebar';
-import { SiteHeader } from '@/components/site-header';
-import { SidebarInset, SidebarProvider } from '@/components/ui/sidebar';
 import { DetailedWalletBalance } from '@/components/detailed-wallet-balance';
 import { TemporaryBalances } from '@/components/temporary-balances';
 import { fetchBtcUsdPrice, btcToSatsRate } from '@/lib/exchange-rate';
+import { AppPageShell } from '@/components/app-page-shell';
+import { PageHeader } from '@/components/page-header';
 
 export default function BalancesPage() {
   const { displayUnit } = useCurrencyStore();
@@ -22,39 +21,26 @@ export default function BalancesPage() {
   const usdPerSat = btcUsdPrice ? btcToSatsRate(btcUsdPrice) : null;
 
   return (
-    <SidebarProvider>
-      <AppSidebar variant='inset' />
-      <SidebarInset className='p-0'>
-        <SiteHeader />
-        <div className='container max-w-6xl px-4 py-8 md:px-6 lg:px-8'>
-          <div className='mb-8 flex flex-col gap-4 lg:flex-row lg:items-start lg:justify-between'>
-            <div>
-              <h1 className='text-3xl font-bold tracking-tight'>Balances</h1>
-              <p className='text-muted-foreground mt-2'>
-                Monitor and manage wallet balances
-              </p>
-            </div>
-            {/* Global currency toggle is now in SiteHeader */}
-          </div>
+    <AppPageShell contentClassName='mx-auto w-full max-w-5xl'>
+      <div className='space-y-6'>
+        <PageHeader
+          title='Balances'
+          description='Monitor and manage wallet balances across cashu mints and temporary stores.'
+        />
 
-          <div className='grid gap-6'>
-            <div className='col-span-full'>
-              <DetailedWalletBalance
-                refreshInterval={30000}
-                displayUnit={displayUnit}
-                usdPerSat={usdPerSat}
-              />
-            </div>
-            <div className='col-span-full'>
-              <TemporaryBalances
-                refreshInterval={60000}
-                displayUnit={displayUnit}
-                usdPerSat={usdPerSat}
-              />
-            </div>
-          </div>
+        <div className='grid gap-6'>
+          <DetailedWalletBalance
+            refreshInterval={30000}
+            displayUnit={displayUnit}
+            usdPerSat={usdPerSat}
+          />
+          <TemporaryBalances
+            refreshInterval={60000}
+            displayUnit={displayUnit}
+            usdPerSat={usdPerSat}
+          />
         </div>
-      </SidebarInset>
-    </SidebarProvider>
+      </div>
+    </AppPageShell>
   );
 }

ui/app/globals.css

@@ -1,13 +1,133 @@
 @import 'tailwindcss';
 @import 'tw-animate-css';
 
-@custom-variant dark (&:is(.dark *));
+@custom-variant dark (&:is(.dark *, .red *));
+
+:root {
+  --radius: 0.625rem;
+  --font-geist-sans:
+    ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica,
+    Arial, 'Apple Color Emoji', 'Segoe UI Emoji';
+  --font-geist-mono:
+    ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
+    'Courier New', monospace;
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+.red {
+  --background: oklch(0.14 0.03 24);
+  --foreground: oklch(0.9 0.05 28);
+  --card: oklch(0.17 0.04 24);
+  --card-foreground: oklch(0.9 0.05 28);
+  --popover: oklch(0.17 0.04 24);
+  --popover-foreground: oklch(0.9 0.05 28);
+  --primary: oklch(0.78 0.14 25);
+  --primary-foreground: oklch(0.14 0.03 24);
+  --secondary: oklch(0.22 0.05 24);
+  --secondary-foreground: oklch(0.9 0.05 28);
+  --muted: oklch(0.22 0.05 24);
+  --muted-foreground: oklch(0.72 0.04 26);
+  --accent: oklch(0.25 0.08 25);
+  --accent-foreground: oklch(0.92 0.05 28);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(0.72 0.11 25 / 24%);
+  --input: oklch(0.75 0.12 25 / 28%);
+  --ring: oklch(0.62 0.12 24);
+}
+
+html.red {
+  color-scheme: dark;
+}
 
 @theme inline {
   --color-background: var(--background);
   --color-foreground: var(--foreground);
-  --font-sans: Geist, sans-serif;
-  --font-mono: Geist Mono, monospace;
+  --color-muted: var(--muted);
+  --color-accent: var(--accent);
+  --color-border: var(--border);
+  --color-card: var(--card);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
   --color-sidebar-ring: var(--sidebar-ring);
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
@@ -21,194 +141,34 @@
   --color-chart-3: var(--chart-3);
   --color-chart-2: var(--chart-2);
   --color-chart-1: var(--chart-1);
-  --color-ring: var(--ring);
-  --color-input: var(--input);
-  --color-border: var(--border);
-  --color-destructive: var(--destructive);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-accent: var(--accent);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-muted: var(--muted);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-secondary: var(--secondary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-primary: var(--primary);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-popover: var(--popover);
-  --color-card-foreground: var(--card-foreground);
-  --color-card: var(--card);
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-  --font-serif: Georgia, serif;
-  --radius: 0.5rem;
-  --tracking-tighter: calc(var(--tracking-normal) - 0.05em);
-  --tracking-tight: calc(var(--tracking-normal) - 0.025em);
-  --tracking-wide: calc(var(--tracking-normal) + 0.025em);
-  --tracking-wider: calc(var(--tracking-normal) + 0.05em);
-  --tracking-widest: calc(var(--tracking-normal) + 0.1em);
-  --tracking-normal: var(--tracking-normal);
-  --shadow-2xl: var(--shadow-2xl);
-  --shadow-xl: var(--shadow-xl);
-  --shadow-lg: var(--shadow-lg);
-  --shadow-md: var(--shadow-md);
-  --shadow: var(--shadow);
-  --shadow-sm: var(--shadow-sm);
-  --shadow-xs: var(--shadow-xs);
-  --shadow-2xs: var(--shadow-2xs);
-  --spacing: var(--spacing);
-  --letter-spacing: var(--letter-spacing);
-  --shadow-offset-y: var(--shadow-offset-y);
-  --shadow-offset-x: var(--shadow-offset-x);
-  --shadow-spread: var(--shadow-spread);
-  --shadow-blur: var(--shadow-blur);
-  --shadow-opacity: var(--shadow-opacity);
-  --color-shadow-color: var(--shadow-color);
-  --color-destructive-foreground: var(--destructive-foreground);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --radius-3xl: calc(var(--radius) + 12px);
+  --radius-4xl: calc(var(--radius) + 16px);
 }
 
-:root {
-  --radius: 0.5rem;
-  --background: oklch(0.99 0 0);
-  --foreground: oklch(0 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0 0 0);
-  --popover: oklch(0.99 0 0);
-  --popover-foreground: oklch(0 0 0);
-  --primary: oklch(0 0 0);
-  --primary-foreground: oklch(1 0 0);
-  --secondary: oklch(0.94 0 0);
-  --secondary-foreground: oklch(0 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.44 0 0);
-  --accent: oklch(0.94 0 0);
-  --accent-foreground: oklch(0 0 0);
-  --destructive: oklch(0.63 0.19 23.03);
-  --border: oklch(0.92 0 0);
-  --input: oklch(0.94 0 0);
-  --ring: oklch(0 0 0);
-  --chart-1: oklch(0.81 0.17 75.35);
-  --chart-2: oklch(0.55 0.22 264.53);
-  --chart-3: oklch(0.72 0 0);
-  --chart-4: oklch(0.92 0 0);
-  --chart-5: oklch(0.56 0 0);
-  --sidebar: oklch(0.99 0 0);
-  --sidebar-foreground: oklch(0 0 0);
-  --sidebar-primary: oklch(0 0 0);
-  --sidebar-primary-foreground: oklch(1 0 0);
-  --sidebar-accent: oklch(0.94 0 0);
-  --sidebar-accent-foreground: oklch(0 0 0);
-  --sidebar-border: oklch(0.94 0 0);
-  --sidebar-ring: oklch(0 0 0);
-  --destructive-foreground: oklch(1 0 0);
-  --font-sans: Geist, sans-serif;
-  --font-serif: Georgia, serif;
-  --font-mono: Geist Mono, monospace;
-  --shadow-color: hsl(0 0% 0%);
-  --shadow-opacity: 0.18;
-  --shadow-blur: 2px;
-  --shadow-spread: 0px;
-  --shadow-offset-x: 0px;
-  --shadow-offset-y: 1px;
-  --letter-spacing: 0em;
-  --spacing: 0.25rem;
-  --shadow-2xs: 0px 1px 2px 0px hsl(0 0% 0% / 0.09);
-  --shadow-xs: 0px 1px 2px 0px hsl(0 0% 0% / 0.09);
-  --shadow-sm:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 1px 2px -1px hsl(0 0% 0% / 0.18);
-  --shadow:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 1px 2px -1px hsl(0 0% 0% / 0.18);
-  --shadow-md:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 2px 4px -1px hsl(0 0% 0% / 0.18);
-  --shadow-lg:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 4px 6px -1px hsl(0 0% 0% / 0.18);
-  --shadow-xl:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 8px 10px -1px hsl(0 0% 0% / 0.18);
-  --shadow-2xl: 0px 1px 2px 0px hsl(0 0% 0% / 0.45);
-  --tracking-normal: 0em;
+body {
+  font-family: var(--font-sans);
 }
 
-.dark {
-  --background: oklch(0 0 0);
-  --foreground: oklch(1 0 0);
-  --card: oklch(0.14 0 0);
-  --card-foreground: oklch(1 0 0);
-  --popover: oklch(0.18 0 0);
-  --popover-foreground: oklch(1 0 0);
-  --primary: oklch(1 0 0);
-  --primary-foreground: oklch(0 0 0);
-  --secondary: oklch(0.25 0 0);
-  --secondary-foreground: oklch(1 0 0);
-  --muted: oklch(0.23 0 0);
-  --muted-foreground: oklch(0.72 0 0);
-  --accent: oklch(0.32 0 0);
-  --accent-foreground: oklch(1 0 0);
-  --destructive: oklch(0.69 0.2 23.91);
-  --border: oklch(0.26 0 0);
-  --input: oklch(0.32 0 0);
-  --ring: oklch(0.72 0 0);
-  --chart-1: oklch(0.81 0.17 75.35);
-  --chart-2: oklch(0.58 0.21 260.84);
-  --chart-3: oklch(0.56 0 0);
-  --chart-4: oklch(0.44 0 0);
-  --chart-5: oklch(0.92 0 0);
-  --sidebar: oklch(0.18 0 0);
-  --sidebar-foreground: oklch(1 0 0);
-  --sidebar-primary: oklch(1 0 0);
-  --sidebar-primary-foreground: oklch(0 0 0);
-  --sidebar-accent: oklch(0.32 0 0);
-  --sidebar-accent-foreground: oklch(1 0 0);
-  --sidebar-border: oklch(0.32 0 0);
-  --sidebar-ring: oklch(0.72 0 0);
-  --destructive-foreground: oklch(0 0 0);
-  --radius: 0.5rem;
-  --font-sans: Geist, sans-serif;
-  --font-serif: Georgia, serif;
-  --font-mono: Geist Mono, monospace;
-  --shadow-color: hsl(0 0% 0%);
-  --shadow-opacity: 0.18;
-  --shadow-blur: 2px;
-  --shadow-spread: 0px;
-  --shadow-offset-x: 0px;
-  --shadow-offset-y: 1px;
-  --letter-spacing: 0em;
-  --spacing: 0.25rem;
-  --shadow-2xs: 0px 1px 2px 0px hsl(0 0% 0% / 0.09);
-  --shadow-xs: 0px 1px 2px 0px hsl(0 0% 0% / 0.09);
-  --shadow-sm:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 1px 2px -1px hsl(0 0% 0% / 0.18);
-  --shadow:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 1px 2px -1px hsl(0 0% 0% / 0.18);
-  --shadow-md:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 2px 4px -1px hsl(0 0% 0% / 0.18);
-  --shadow-lg:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 4px 6px -1px hsl(0 0% 0% / 0.18);
-  --shadow-xl:
-    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 8px 10px -1px hsl(0 0% 0% / 0.18);
-  --shadow-2xl: 0px 1px 2px 0px hsl(0 0% 0% / 0.45);
+html,
+body {
+  max-width: 100%;
 }
 
 @layer base {
   * {
     @apply border-border outline-ring/50;
   }
+
   body {
     @apply bg-background text-foreground;
-    letter-spacing: var(--tracking-normal);
   }
-}
 
-/* Custom animations */
-@keyframes shimmer {
-  0% {
-    transform: translateX(-100%);
-  }
-  100% {
-    transform: translateX(100%);
+  button,
+  [type='button'],
+  [type='submit'],
+  [type='reset'],
+  [role='button'] {
+    cursor: pointer;
   }
 }
-
-.animate-shimmer {
-  animation: shimmer 2s infinite;
-}

ui/app/layout.tsx

@@ -1,23 +1,10 @@
 import type { Metadata } from 'next';
-import { Geist, Geist_Mono } from 'next/font/google';
+import { GeistMono } from 'geist/font/mono';
+import { GeistSans } from 'geist/font/sans';
 import './globals.css';
 import { Providers } from './providers';
 import { SuppressHydrationWarning } from '@/components/suppress-hydration-warning';
 
-const geistSans = Geist({
-  variable: '--font-geist-sans',
-  subsets: ['latin'],
-  preload: false,
-  display: 'swap',
-});
-
-const geistMono = Geist_Mono({
-  variable: '--font-geist-mono',
-  subsets: ['latin'],
-  preload: false,
-  display: 'swap',
-});
-
 export const metadata: Metadata = {
   title: 'Routstr',
   description: 'Routstr model management',
@@ -34,7 +21,7 @@ export default function RootLayout({
   return (
     <html lang='en' suppressHydrationWarning>
       <body
-        className={`${geistSans.variable} ${geistMono.variable} font-sans antialiased`}
+        className={`${GeistSans.variable} ${GeistMono.variable} font-sans antialiased`}
       >
         <SuppressHydrationWarning>
           <Providers>{children}</Providers>

ui/app/login/page.tsx

@@ -5,16 +5,10 @@ import type { ChangeEvent, FormEvent, ReactElement } from 'react';
 import { useRouter } from 'next/navigation';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from '@/components/ui/card';
 import { adminLogin } from '@/lib/api/services/auth';
 import { ConfigurationService } from '@/lib/api/services/configuration';
 import { toast } from 'sonner';
+import { AuthPageShell } from '@/components/auth-page-shell';
 
 export default function AdminLoginPage(): ReactElement {
   const router = useRouter();
@@ -78,51 +72,42 @@ export default function AdminLoginPage(): ReactElement {
   };
 
   return (
-    <div className='bg-background text-foreground flex min-h-screen items-center justify-center px-4 py-12'>
-      <Card className='border-border/60 bg-card/90 w-full max-w-md border shadow-2xl shadow-black/30 backdrop-blur'>
-        <CardHeader className='space-y-1'>
-          <CardTitle className='text-center text-2xl font-bold'>
-            Admin Login
-          </CardTitle>
-          <CardDescription className='text-center'>
-            Enter your admin password to access the dashboard
-          </CardDescription>
-        </CardHeader>
-        <CardContent>
-          <form onSubmit={handleSubmit} className='space-y-4'>
-            {allowCustomBaseUrl && (
-              <div className='space-y-2'>
-                <Input
-                  type='text'
-                  placeholder='API URL (https://api.example.com)'
-                  value={baseUrl}
-                  onChange={(event: ChangeEvent<HTMLInputElement>) =>
-                    setBaseUrl(event.target.value)
-                  }
-                  disabled={isLoading}
-                  required
-                />
-              </div>
-            )}
-            <div className='space-y-2'>
-              <Input
-                type='password'
-                placeholder='Admin Password'
-                value={password}
-                onChange={(event: ChangeEvent<HTMLInputElement>) =>
-                  setPassword(event.target.value)
-                }
-                disabled={isLoading}
-                autoFocus
-                required
-              />
-            </div>
-            <Button type='submit' className='w-full' disabled={isLoading}>
-              {isLoading ? 'Logging in...' : 'Login'}
-            </Button>
-          </form>
-        </CardContent>
-      </Card>
-    </div>
+    <AuthPageShell
+      title='Admin Login'
+      description='Enter your admin password to access the dashboard.'
+    >
+      <form onSubmit={handleSubmit} className='space-y-4'>
+        {allowCustomBaseUrl && (
+          <div className='space-y-2'>
+            <Input
+              type='text'
+              placeholder='API URL (https://api.example.com)'
+              value={baseUrl}
+              onChange={(event: ChangeEvent<HTMLInputElement>) =>
+                setBaseUrl(event.target.value)
+              }
+              disabled={isLoading}
+              required
+            />
+          </div>
+        )}
+        <div className='space-y-2'>
+          <Input
+            type='password'
+            placeholder='Admin Password'
+            value={password}
+            onChange={(event: ChangeEvent<HTMLInputElement>) =>
+              setPassword(event.target.value)
+            }
+            disabled={isLoading}
+            autoFocus
+            required
+          />
+        </div>
+        <Button type='submit' className='w-full' disabled={isLoading}>
+          {isLoading ? 'Logging in...' : 'Login'}
+        </Button>
+      </form>
+    </AuthPageShell>
   );
 }

ui/app/logs/log-details-dialog.tsx

@@ -10,18 +10,8 @@ import {
 } from '@/components/ui/dialog';
 import { Copy, Check } from 'lucide-react';
 import { useState } from 'react';
-
-interface LogEntry {
-  asctime: string;
-  name: string;
-  levelname: string;
-  message: string;
-  pathname: string;
-  lineno: number;
-  version: string;
-  request_id: string;
-  [key: string]: string | number | object | undefined;
-}
+import { getLogLevelBadgeVariant } from '@/lib/utils/log-level';
+import type { LogEntry } from './types';
 
 interface LogDetailsDialogProps {
   log: LogEntry | null;
@@ -29,24 +19,6 @@ interface LogDetailsDialogProps {
   onClose: () => void;
 }
 
-const getLevelColor = (level: string): string => {
-  switch (level.toUpperCase()) {
-    case 'TRACE':
-    case 'DEBUG':
-      return 'bg-gray-100 text-gray-800 border-gray-200';
-    case 'INFO':
-      return 'bg-blue-100 text-blue-800 border-blue-200';
-    case 'WARNING':
-      return 'bg-yellow-100 text-yellow-800 border-yellow-200';
-    case 'ERROR':
-      return 'bg-red-100 text-red-800 border-red-200';
-    case 'CRITICAL':
-      return 'bg-purple-100 text-purple-800 border-purple-200';
-    default:
-      return 'bg-gray-100 text-gray-800 border-gray-200';
-  }
-};
-
 export function LogDetailsDialog({
   log,
   isOpen,
@@ -79,10 +51,13 @@ export function LogDetailsDialog({
 
   return (
     <Dialog open={isOpen} onOpenChange={onClose}>
-      <DialogContent className='max-h-[90vh] w-[95vw] max-w-[95vw] overflow-hidden'>
+      <DialogContent className='max-h-[92svh] w-full max-w-none overflow-hidden md:max-w-4xl'>
         <DialogHeader>
           <DialogTitle className='flex items-center gap-2'>
-            <Badge variant='outline' className={getLevelColor(log.levelname)}>
+            <Badge
+              variant={getLogLevelBadgeVariant(log.levelname)}
+              className='uppercase'
+            >
               {log.levelname}
             </Badge>
             <span>Log Entry Details</span>
@@ -92,7 +67,7 @@ export function LogDetailsDialog({
           </DialogDescription>
         </DialogHeader>
 
-        <ScrollArea className='h-[75vh] w-full overflow-x-auto'>
+        <ScrollArea className='h-[70svh] w-full overflow-x-auto sm:h-[75vh]'>
           <div className='space-y-6'>
             <div>
               <h4 className='mb-2 text-sm font-medium'>Message</h4>

ui/app/logs/log-entry-card.tsx

@@ -1,41 +1,13 @@
 import { Badge } from '@/components/ui/badge';
-import { Eye } from 'lucide-react';
-
-interface LogEntry {
-  asctime: string;
-  name: string;
-  levelname: string;
-  message: string;
-  pathname: string;
-  lineno: number;
-  version: string;
-  request_id: string;
-  [key: string]: string | number | object | undefined;
-}
+import { ChevronRight } from 'lucide-react';
+import { getLogLevelBadgeVariant } from '@/lib/utils/log-level';
+import type { LogEntry } from './types';
 
 interface LogEntryCardProps {
   entry: LogEntry;
   onClick: (entry: LogEntry) => void;
 }
 
-const getLevelColor = (level: string): string => {
-  switch (level.toUpperCase()) {
-    case 'TRACE':
-    case 'DEBUG':
-      return 'bg-gray-100 text-gray-800 border-gray-200';
-    case 'INFO':
-      return 'bg-blue-100 text-blue-800 border-blue-200';
-    case 'WARNING':
-      return 'bg-yellow-100 text-yellow-800 border-yellow-200';
-    case 'ERROR':
-      return 'bg-red-100 text-red-800 border-red-200';
-    case 'CRITICAL':
-      return 'bg-purple-100 text-purple-800 border-purple-200';
-    default:
-      return 'bg-gray-100 text-gray-800 border-gray-200';
-  }
-};
-
 export function LogEntryCard({ entry, onClick }: LogEntryCardProps) {
   const extraFields = Object.keys(entry).filter(
     (key) =>
@@ -50,73 +22,58 @@ export function LogEntryCard({ entry, onClick }: LogEntryCardProps) {
         'request_id',
       ].includes(key)
   );
+  const hasRequestId =
+    Boolean(entry.request_id) && entry.request_id !== 'no-request-id';
+  const shortPath = entry.pathname.split('/').pop() || entry.pathname;
 
   return (
     <div
-      className='bg-card hover:bg-accent/50 group mb-4 cursor-pointer overflow-hidden rounded-lg border p-3 transition-colors duration-200 sm:p-4'
+      className='bg-card hover:bg-accent/35 group mb-2 cursor-pointer rounded-lg border p-2.5 transition-colors duration-150 sm:p-3'
       onClick={() => onClick(entry)}
     >
-      <div className='mb-3 flex min-w-0 flex-col gap-2 sm:flex-row sm:items-center sm:justify-between'>
-        <div className='flex min-w-0 flex-wrap items-center gap-2'>
-          <Badge variant='outline' className={getLevelColor(entry.levelname)}>
-            {entry.levelname}
-          </Badge>
-          <span className='text-muted-foreground truncate text-xs sm:text-sm'>
-            {entry.asctime}
-          </span>
-          <Badge variant='secondary' className='truncate text-xs'>
-            {entry.name}
-          </Badge>
-        </div>
-        <div className='flex min-w-0 items-center gap-2'>
-          <div className='text-muted-foreground truncate text-xs'>
-            {entry.pathname}:{entry.lineno}
-          </div>
-          <Eye className='text-muted-foreground h-4 w-4 flex-shrink-0 opacity-0 transition-opacity group-hover:opacity-100' />
-        </div>
-      </div>
-
-      <div className='mb-2 line-clamp-3 overflow-hidden font-mono text-xs break-words sm:text-sm'>
-        {entry.message}
-      </div>
-
-      {entry.request_id && entry.request_id !== 'no-request-id' && (
-        <div className='mb-2 min-w-0'>
-          <div className='inline-block max-w-full'>
-            <Badge variant='outline' className='text-xs'>
-              <span className='inline-block max-w-[250px] truncate sm:max-w-[400px]'>
-                Request ID: {entry.request_id}
-              </span>
+      <div className='flex min-w-0 items-start justify-between gap-2'>
+        <div className='min-w-0 flex-1 space-y-1.5'>
+          <div className='flex min-w-0 flex-wrap items-center gap-1.5'>
+            <Badge
+              variant={getLogLevelBadgeVariant(entry.levelname)}
+              className='h-5 px-1.5 text-[10px] uppercase'
+            >
+              {entry.levelname}
+            </Badge>
+            <span className='text-muted-foreground text-[11px]'>
+              {entry.asctime}
+            </span>
+            <Badge
+              variant='secondary'
+              className='h-5 max-w-[11rem] truncate px-1.5 text-[10px]'
+            >
+              {entry.name}
             </Badge>
           </div>
-        </div>
-      )}
 
-      {extraFields.length > 0 && (
-        <div className='mt-3 min-w-0 border-t pt-3'>
-          <div className='mb-2 text-xs font-medium'>Additional Fields:</div>
-          <div className='grid grid-cols-1 gap-2'>
-            {extraFields.slice(0, 4).map((key) => (
-              <div
-                key={key}
-                className='min-w-0 overflow-hidden text-xs break-words'
-              >
-                <span className='font-medium break-all'>{key}:</span>{' '}
-                <span className='text-muted-foreground break-all'>
-                  {typeof entry[key] === 'object'
-                    ? JSON.stringify(entry[key])
-                    : String(entry[key])}
-                </span>
-              </div>
-            ))}
-            {extraFields.length > 4 && (
-              <div className='text-muted-foreground text-xs'>
-                ...and {extraFields.length - 4} more fields
-              </div>
-            )}
+          <p className='line-clamp-1 font-mono text-xs break-words sm:text-sm'>
+            {entry.message}
+          </p>
+
+          <div className='text-muted-foreground flex min-w-0 flex-wrap items-center gap-1.5 text-[11px]'>
+            {hasRequestId ? (
+              <span className='inline-block max-w-[14rem] truncate rounded border px-1.5 py-0.5 font-mono text-[10px] sm:max-w-[20rem]'>
+                {entry.request_id}
+              </span>
+            ) : null}
+            <span className='truncate'>
+              {shortPath}:{entry.lineno}
+            </span>
+            {extraFields.length > 0 ? (
+              <span>{extraFields.length} extra</span>
+            ) : null}
           </div>
         </div>
-      )}
+
+        <div className='pt-0.5'>
+          <ChevronRight className='text-muted-foreground h-4 w-4 opacity-50 transition-opacity group-hover:opacity-90' />
+        </div>
+      </div>
     </div>
   );
 }

ui/app/logs/log-filters.tsx

@@ -1,3 +1,11 @@
+import {
+  useEffect,
+  useState,
+  type ChangeEvent,
+  type KeyboardEvent,
+} from 'react';
+import { format } from 'date-fns';
+import { CalendarIcon, X } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import {
   Card,
@@ -21,20 +29,8 @@ import {
   PopoverTrigger,
 } from '@/components/ui/popover';
 import { Calendar } from '@/components/ui/calendar';
-import { Badge } from '@/components/ui/badge';
-import {
-  Command,
-  CommandEmpty,
-  CommandGroup,
-  CommandInput,
-  CommandItem,
-  CommandList,
-} from '@/components/ui/command';
-import { Checkbox } from '@/components/ui/checkbox';
-import { CalendarIcon, Filter, X, Plus } from 'lucide-react';
-import { useState, useEffect } from 'react';
-import { format } from 'date-fns';
 import { cn } from '@/lib/utils';
+import { MultiSelectCommandFilter } from './multi-select-command-filter';
 
 interface LogFiltersProps {
   selectedDate: string;
@@ -97,32 +93,12 @@ const ENDPOINT_OPTIONS = [
   '/embeddings/models',
 ];
 
-interface FilterBadgeProps {
-  value: string;
-  onRemove: (value: string) => void;
-}
-
-function FilterBadge({ value, onRemove }: FilterBadgeProps) {
-  return (
-    <Badge
-      variant='secondary'
-      className='flex items-center gap-1 px-1 font-normal'
-    >
-      {value}
-      <button
-        type='button'
-        onClick={(e) => {
-          e.preventDefault();
-          e.stopPropagation();
-          onRemove(value);
-        }}
-        className='hover:bg-muted-foreground/20 rounded-full'
-      >
-        <X className='h-3 w-3' />
-      </button>
-    </Badge>
-  );
-}
+const STATUS_4XX_CODES = STATUS_CODE_OPTIONS.filter((code) =>
+  code.startsWith('4')
+);
+const STATUS_5XX_CODES = STATUS_CODE_OPTIONS.filter((code) =>
+  code.startsWith('5')
+);
 
 export function LogFilters({
   selectedDate,
@@ -151,7 +127,7 @@ export function LogFilters({
   const [isCustom, setIsCustom] = useState<boolean>(!isPreset);
   const [date, setDate] = useState<Date | undefined>(
     selectedDate && selectedDate !== 'all'
-      ? new Date(selectedDate + 'T00:00:00')
+      ? new Date(`${selectedDate}T00:00:00`)
       : undefined
   );
 
@@ -162,6 +138,7 @@ export function LogFilters({
   useEffect(() => {
     const currentIsPreset = PRESET_LIMITS.includes(limit.toString());
     setIsCustom(!currentIsPreset);
+
     if (!currentIsPreset) {
       setCustomLimit(limit.toString());
     }
@@ -170,88 +147,79 @@ export function LogFilters({
   useEffect(() => {
     if (selectedDate === 'all' || !selectedDate) {
       setDate(undefined);
-    } else {
-      const d = new Date(selectedDate + 'T00:00:00');
-      setDate(isNaN(d.getTime()) ? undefined : d);
+      return;
     }
+
+    const parsedDate = new Date(`${selectedDate}T00:00:00`);
+    setDate(Number.isNaN(parsedDate.getTime()) ? undefined : parsedDate);
   }, [selectedDate]);
 
   const handleLimitChange = (value: string) => {
     if (value === 'custom') {
       setIsCustom(true);
       setCustomLimit(limit.toString());
-    } else {
-      setIsCustom(false);
-      setCustomLimit('');
-      onLimitChange(Number(value));
+      return;
     }
+
+    setIsCustom(false);
+    setCustomLimit('');
+    onLimitChange(Number(value));
   };
 
-  const handleCustomLimitChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const value = e.target.value;
-    setCustomLimit(value);
+  const handleCustomLimitChange = (event: ChangeEvent<HTMLInputElement>) => {
+    setCustomLimit(event.target.value);
   };
 
   const handleCustomLimitApply = () => {
-    const numValue = parseInt(customLimit);
-    if (!isNaN(numValue) && numValue > 0) {
-      onLimitChange(numValue);
-    } else {
-      setIsCustom(false);
-      setCustomLimit('');
-      onLimitChange(100);
+    const numericValue = Number.parseInt(customLimit, 10);
+
+    if (!Number.isNaN(numericValue) && numericValue > 0) {
+      onLimitChange(numericValue);
+      return;
     }
+
+    setIsCustom(false);
+    setCustomLimit('');
+    onLimitChange(100);
   };
 
-  const handleCustomLimitKeyDown = (
-    e: React.KeyboardEvent<HTMLInputElement>
-  ) => {
-    if (e.key === 'Enter') {
+  const handleCustomLimitKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'Enter') {
       handleCustomLimitApply();
     }
   };
 
-  const handleDateSelect = (selectedDate: Date | undefined) => {
-    setDate(selectedDate);
-    if (selectedDate) {
-      onDateChange(format(selectedDate, 'yyyy-MM-dd'));
-    } else {
-      onDateChange('all');
-    }
-  };
+  const handleDateSelect = (nextDate: Date | undefined) => {
+    setDate(nextDate);
 
-  const toggleSelection = (
-    current: string[],
-    value: string,
-    onChange: (val: string[]) => void
-  ) => {
-    if (current.includes(value)) {
-      onChange(current.filter((v) => v !== value));
-    } else {
-      onChange([...current, value]);
+    if (nextDate) {
+      onDateChange(format(nextDate, 'yyyy-MM-dd'));
+      return;
     }
+
+    onDateChange('all');
   };
 
   const handleQuickStatusCode = (range: '4xx' | '5xx') => {
-    const codes = STATUS_CODE_OPTIONS.filter((c) => c.startsWith(range[0]));
-    const newSelection = new Set([...selectedStatusCodes]);
-    const allIncluded = codes.every((c) => selectedStatusCodes.includes(c));
+    const rangeCodes = range === '4xx' ? STATUS_4XX_CODES : STATUS_5XX_CODES;
+    const nextSelection = new Set(selectedStatusCodes);
+    const allSelected = rangeCodes.every((code) =>
+      selectedStatusCodes.includes(code)
+    );
 
-    if (allIncluded) {
-      codes.forEach((c) => newSelection.delete(c));
+    if (allSelected) {
+      rangeCodes.forEach((code) => nextSelection.delete(code));
     } else {
-      codes.forEach((c) => newSelection.add(c));
+      rangeCodes.forEach((code) => nextSelection.add(code));
     }
-    onStatusCodesChange(Array.from(newSelection));
+
+    onStatusCodesChange(Array.from(nextSelection));
   };
 
   return (
     <Card className='mb-6'>
       <CardHeader>
-        <CardTitle className='flex items-center gap-2'>
-          <Filter className='h-5 w-5' />
-          Filters
-        </CardTitle>
+        <CardTitle>Filters</CardTitle>
         <CardDescription>
           Filter logs by date, level, request ID, text search, status code,
           method, endpoint and limit
@@ -314,336 +282,62 @@ export function LogFilters({
             </Select>
           </div>
 
-          <div className='space-y-2'>
-            <Label>Status Codes</Label>
-            <Popover>
-              <PopoverTrigger asChild>
-                <Button
-                  variant='outline'
-                  className='w-full justify-start text-left font-normal'
-                >
-                  <div className='flex flex-wrap gap-1'>
-                    {selectedStatusCodes.length > 0 ? (
-                      selectedStatusCodes.map((code) => (
-                        <FilterBadge
-                          key={code}
-                          value={code}
-                          onRemove={(val) =>
-                            toggleSelection(
-                              selectedStatusCodes,
-                              val,
-                              onStatusCodesChange
-                            )
-                          }
-                        />
-                      ))
-                    ) : (
-                      <span className='text-muted-foreground'>All codes</span>
-                    )}
-                  </div>
-                </Button>
-              </PopoverTrigger>
-              <PopoverContent className='w-64 p-0' align='start'>
-                <Command>
-                  <CommandInput
-                    placeholder='Search or add status code...'
-                    value={statusSearch}
-                    onValueChange={setStatusSearch}
-                  />
-                  <CommandList>
-                    {selectedStatusCodes.length > 0 && (
-                      <CommandGroup heading='Selected'>
-                        {selectedStatusCodes.map((code) => (
-                          <CommandItem
-                            key={`selected-${code}`}
-                            onSelect={() =>
-                              toggleSelection(
-                                selectedStatusCodes,
-                                code,
-                                onStatusCodesChange
-                              )
-                            }
-                          >
-                            <Checkbox checked={true} className='mr-2' />
-                            {code}
-                          </CommandItem>
-                        ))}
-                      </CommandGroup>
-                    )}
-                    {statusSearch &&
-                      !STATUS_CODE_OPTIONS.includes(statusSearch) &&
-                      !selectedStatusCodes.includes(statusSearch) && (
-                        <CommandGroup heading='Custom'>
-                          <CommandItem
-                            onSelect={() => {
-                              if (/^\d+$/.test(statusSearch)) {
-                                toggleSelection(
-                                  selectedStatusCodes,
-                                  statusSearch,
-                                  onStatusCodesChange
-                                );
-                                setStatusSearch('');
-                              }
-                            }}
-                          >
-                            <Plus className='mr-2 h-4 w-4' />
-                            Add &quot;{statusSearch}&quot;
-                          </CommandItem>
-                        </CommandGroup>
-                      )}
-                    <CommandEmpty>No results found.</CommandEmpty>
-                    <CommandGroup heading='Quick Filters'>
-                      <CommandItem
-                        onSelect={() => handleQuickStatusCode('4xx')}
-                      >
-                        <Checkbox
-                          checked={STATUS_CODE_OPTIONS.filter((c) =>
-                            c.startsWith('4')
-                          ).every((c) => selectedStatusCodes.includes(c))}
-                          className='mr-2'
-                        />
-                        4xx Errors
-                      </CommandItem>
-                      <CommandItem
-                        onSelect={() => handleQuickStatusCode('5xx')}
-                      >
-                        <Checkbox
-                          checked={STATUS_CODE_OPTIONS.filter((c) =>
-                            c.startsWith('5')
-                          ).every((c) => selectedStatusCodes.includes(c))}
-                          className='mr-2'
-                        />
-                        5xx Errors
-                      </CommandItem>
-                    </CommandGroup>
-                    <CommandGroup heading='Common Codes'>
-                      {STATUS_CODE_OPTIONS.filter(
-                        (code) => !selectedStatusCodes.includes(code)
-                      ).map((code) => (
-                        <CommandItem
-                          key={code}
-                          onSelect={() =>
-                            toggleSelection(
-                              selectedStatusCodes,
-                              code,
-                              onStatusCodesChange
-                            )
-                          }
-                        >
-                          <Checkbox checked={false} className='mr-2' />
-                          {code}
-                        </CommandItem>
-                      ))}
-                    </CommandGroup>
-                  </CommandList>
-                </Command>
-              </PopoverContent>
-            </Popover>
-          </div>
+          <MultiSelectCommandFilter
+            label='Status Codes'
+            emptyLabel='All codes'
+            selectedValues={selectedStatusCodes}
+            onSelectedValuesChange={onStatusCodesChange}
+            options={STATUS_CODE_OPTIONS}
+            searchValue={statusSearch}
+            onSearchValueChange={setStatusSearch}
+            searchPlaceholder='Search or add status code...'
+            popoverClassName='w-[min(16rem,calc(100vw-2rem))] p-0'
+            optionsGroupLabel='Common Codes'
+            canAddCustom={(value) => /^\d+$/.test(value)}
+            quickFilters={[
+              {
+                label: '4xx Errors',
+                checked: STATUS_4XX_CODES.every((code) =>
+                  selectedStatusCodes.includes(code)
+                ),
+                onSelect: () => handleQuickStatusCode('4xx'),
+              },
+              {
+                label: '5xx Errors',
+                checked: STATUS_5XX_CODES.every((code) =>
+                  selectedStatusCodes.includes(code)
+                ),
+                onSelect: () => handleQuickStatusCode('5xx'),
+              },
+            ]}
+          />
 
-          <div className='space-y-2'>
-            <Label>HTTP Methods</Label>
-            <Popover>
-              <PopoverTrigger asChild>
-                <Button
-                  variant='outline'
-                  className='w-full justify-start text-left font-normal'
-                >
-                  <div className='flex flex-wrap gap-1'>
-                    {selectedMethods.length > 0 ? (
-                      selectedMethods.map((method) => (
-                        <FilterBadge
-                          key={method}
-                          value={method}
-                          onRemove={(val) =>
-                            toggleSelection(
-                              selectedMethods,
-                              val,
-                              onMethodsChange
-                            )
-                          }
-                        />
-                      ))
-                    ) : (
-                      <span className='text-muted-foreground'>All methods</span>
-                    )}
-                  </div>
-                </Button>
-              </PopoverTrigger>
-              <PopoverContent className='w-64 p-0' align='start'>
-                <Command>
-                  <CommandInput
-                    placeholder='Search or add method...'
-                    value={methodSearch}
-                    onValueChange={setMethodSearch}
-                  />
-                  <CommandList>
-                    {selectedMethods.length > 0 && (
-                      <CommandGroup heading='Selected'>
-                        {selectedMethods.map((method) => (
-                          <CommandItem
-                            key={`selected-${method}`}
-                            onSelect={() =>
-                              toggleSelection(
-                                selectedMethods,
-                                method,
-                                onMethodsChange
-                              )
-                            }
-                          >
-                            <Checkbox checked={true} className='mr-2' />
-                            {method}
-                          </CommandItem>
-                        ))}
-                      </CommandGroup>
-                    )}
-                    {methodSearch &&
-                      !METHOD_OPTIONS.includes(methodSearch.toUpperCase()) &&
-                      !selectedMethods.includes(methodSearch.toUpperCase()) && (
-                        <CommandGroup heading='Custom'>
-                          <CommandItem
-                            onSelect={() => {
-                              toggleSelection(
-                                selectedMethods,
-                                methodSearch.toUpperCase(),
-                                onMethodsChange
-                              );
-                              setMethodSearch('');
-                            }}
-                          >
-                            <Plus className='mr-2 h-4 w-4' />
-                            Add &quot;{methodSearch.toUpperCase()}&quot;
-                          </CommandItem>
-                        </CommandGroup>
-                      )}
-                    <CommandEmpty>No results found.</CommandEmpty>
-                    <CommandGroup>
-                      {METHOD_OPTIONS.filter(
-                        (method) => !selectedMethods.includes(method)
-                      ).map((method) => (
-                        <CommandItem
-                          key={method}
-                          onSelect={() =>
-                            toggleSelection(
-                              selectedMethods,
-                              method,
-                              onMethodsChange
-                            )
-                          }
-                        >
-                          <Checkbox checked={false} className='mr-2' />
-                          {method}
-                        </CommandItem>
-                      ))}
-                    </CommandGroup>
-                  </CommandList>
-                </Command>
-              </PopoverContent>
-            </Popover>
-          </div>
+          <MultiSelectCommandFilter
+            label='HTTP Methods'
+            emptyLabel='All methods'
+            selectedValues={selectedMethods}
+            onSelectedValuesChange={onMethodsChange}
+            options={METHOD_OPTIONS}
+            searchValue={methodSearch}
+            onSearchValueChange={setMethodSearch}
+            searchPlaceholder='Search or add method...'
+            popoverClassName='w-[min(16rem,calc(100vw-2rem))] p-0'
+            optionsGroupLabel='Methods'
+            normalizeCustomValue={(value) => value.toUpperCase()}
+          />
 
-          <div className='space-y-2'>
-            <Label>Endpoints</Label>
-            <Popover>
-              <PopoverTrigger asChild>
-                <Button
-                  variant='outline'
-                  className='w-full justify-start text-left font-normal'
-                >
-                  <div className='flex flex-wrap gap-1 overflow-hidden'>
-                    {selectedEndpoints.length > 0 ? (
-                      selectedEndpoints.map((endpoint) => (
-                        <FilterBadge
-                          key={endpoint}
-                          value={endpoint}
-                          onRemove={(val) =>
-                            toggleSelection(
-                              selectedEndpoints,
-                              val,
-                              onEndpointsChange
-                            )
-                          }
-                        />
-                      ))
-                    ) : (
-                      <span className='text-muted-foreground'>
-                        All endpoints
-                      </span>
-                    )}
-                  </div>
-                </Button>
-              </PopoverTrigger>
-              <PopoverContent className='w-80 p-0' align='start'>
-                <Command>
-                  <CommandInput
-                    placeholder='Search or add endpoint pattern...'
-                    value={endpointSearch}
-                    onValueChange={setEndpointSearch}
-                  />
-                  <CommandList>
-                    {selectedEndpoints.length > 0 && (
-                      <CommandGroup heading='Selected'>
-                        {selectedEndpoints.map((endpoint) => (
-                          <CommandItem
-                            key={`selected-${endpoint}`}
-                            onSelect={() =>
-                              toggleSelection(
-                                selectedEndpoints,
-                                endpoint,
-                                onEndpointsChange
-                              )
-                            }
-                          >
-                            <Checkbox checked={true} className='mr-2' />
-                            {endpoint}
-                          </CommandItem>
-                        ))}
-                      </CommandGroup>
-                    )}
-                    {endpointSearch &&
-                      !ENDPOINT_OPTIONS.includes(endpointSearch) &&
-                      !selectedEndpoints.includes(endpointSearch) && (
-                        <CommandGroup heading='Custom'>
-                          <CommandItem
-                            onSelect={() => {
-                              toggleSelection(
-                                selectedEndpoints,
-                                endpointSearch,
-                                onEndpointsChange
-                              );
-                              setEndpointSearch('');
-                            }}
-                          >
-                            <Plus className='mr-2 h-4 w-4' />
-                            Add &quot;{endpointSearch}&quot;
-                          </CommandItem>
-                        </CommandGroup>
-                      )}
-                    <CommandEmpty>No results found.</CommandEmpty>
-                    <CommandGroup heading='Common Endpoints'>
-                      {ENDPOINT_OPTIONS.filter(
-                        (endpoint) => !selectedEndpoints.includes(endpoint)
-                      ).map((endpoint) => (
-                        <CommandItem
-                          key={endpoint}
-                          onSelect={() =>
-                            toggleSelection(
-                              selectedEndpoints,
-                              endpoint,
-                              onEndpointsChange
-                            )
-                          }
-                        >
-                          <Checkbox checked={false} className='mr-2' />
-                          {endpoint}
-                        </CommandItem>
-                      ))}
-                    </CommandGroup>
-                  </CommandList>
-                </Command>
-              </PopoverContent>
-            </Popover>
-          </div>
+          <MultiSelectCommandFilter
+            label='Endpoints'
+            emptyLabel='All endpoints'
+            selectedValues={selectedEndpoints}
+            onSelectedValuesChange={onEndpointsChange}
+            options={ENDPOINT_OPTIONS}
+            searchValue={endpointSearch}
+            onSearchValueChange={setEndpointSearch}
+            searchPlaceholder='Search or add endpoint pattern...'
+            popoverClassName='w-[min(20rem,calc(100vw-2rem))] p-0'
+            optionsGroupLabel='Common Endpoints'
+          />
 
           <div className='space-y-2'>
             <Label htmlFor='request-id'>Request ID</Label>
@@ -652,7 +346,7 @@ export function LogFilters({
               type='text'
               placeholder='Search by request ID'
               value={requestId}
-              onChange={(e) => onRequestIdChange(e.target.value)}
+              onChange={(event) => onRequestIdChange(event.target.value)}
             />
           </div>
 
@@ -668,14 +362,14 @@ export function LogFilters({
               type='text'
               placeholder='Search in message and name'
               value={searchText}
-              onChange={(e) => onSearchTextChange(e.target.value)}
+              onChange={(event) => onSearchTextChange(event.target.value)}
             />
           </div>
 
           <div className='space-y-2'>
             <Label htmlFor='limit'>Limit</Label>
             {isCustom ? (
-              <div className='flex gap-2'>
+              <div className='flex flex-col gap-2 sm:flex-row'>
                 <Input
                   id='limit'
                   type='number'
@@ -686,7 +380,7 @@ export function LogFilters({
                   onKeyDown={handleCustomLimitKeyDown}
                   onBlur={handleCustomLimitApply}
                   autoFocus
-                  className='flex-1'
+                  className='flex-1 sm:flex-auto'
                 />
                 <Button
                   type='button'
@@ -695,6 +389,7 @@ export function LogFilters({
                   onClick={() => {
                     setIsCustom(false);
                     setCustomLimit('');
+
                     if (!isPreset) {
                       onLimitChange(100);
                     }
@@ -712,12 +407,11 @@ export function LogFilters({
                   <SelectValue placeholder='Select limit' />
                 </SelectTrigger>
                 <SelectContent>
-                  <SelectItem value='25'>25</SelectItem>
-                  <SelectItem value='50'>50</SelectItem>
-                  <SelectItem value='100'>100</SelectItem>
-                  <SelectItem value='200'>200</SelectItem>
-                  <SelectItem value='500'>500</SelectItem>
-                  <SelectItem value='1000'>1000</SelectItem>
+                  {PRESET_LIMITS.map((preset) => (
+                    <SelectItem key={preset} value={preset}>
+                      {preset}
+                    </SelectItem>
+                  ))}
                   <SelectItem value='custom'>Custom...</SelectItem>
                 </SelectContent>
               </Select>
@@ -727,8 +421,7 @@ export function LogFilters({
             )}
           </div>
 
-          <div className='space-y-2'>
-            <Label>&nbsp;</Label>
+          <div className='flex items-end sm:col-span-2 lg:col-span-1'>
             <Button
               onClick={onClearFilters}
               variant='outline'

ui/app/logs/multi-select-command-filter.tsx

@@ -0,0 +1,182 @@
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/ui/popover';
+import { Badge } from '@/components/ui/badge';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command';
+import { Checkbox } from '@/components/ui/checkbox';
+import { Plus, X } from 'lucide-react';
+
+interface QuickFilterOption {
+  label: string;
+  checked: boolean;
+  onSelect: () => void;
+}
+
+interface MultiSelectCommandFilterProps {
+  label: string;
+  emptyLabel: string;
+  selectedValues: string[];
+  onSelectedValuesChange: (values: string[]) => void;
+  options: string[];
+  searchValue: string;
+  onSearchValueChange: (value: string) => void;
+  searchPlaceholder: string;
+  popoverClassName?: string;
+  selectedGroupLabel?: string;
+  customGroupLabel?: string;
+  quickGroupLabel?: string;
+  optionsGroupLabel?: string;
+  quickFilters?: QuickFilterOption[];
+  normalizeCustomValue?: (value: string) => string;
+  canAddCustom?: (value: string) => boolean;
+}
+
+function FilterBadge({ value }: { value: string }) {
+  return (
+    <Badge
+      variant='secondary'
+      className='flex items-center gap-1 px-1 font-normal'
+    >
+      {value}
+      <X className='h-3 w-3 opacity-70' aria-hidden='true' />
+    </Badge>
+  );
+}
+
+export function MultiSelectCommandFilter({
+  label,
+  emptyLabel,
+  selectedValues,
+  onSelectedValuesChange,
+  options,
+  searchValue,
+  onSearchValueChange,
+  searchPlaceholder,
+  popoverClassName = 'w-64 p-0',
+  selectedGroupLabel = 'Selected',
+  customGroupLabel = 'Custom',
+  quickGroupLabel = 'Quick Filters',
+  optionsGroupLabel = 'Options',
+  quickFilters = [],
+  normalizeCustomValue,
+  canAddCustom,
+}: MultiSelectCommandFilterProps) {
+  const toggleSelection = (value: string) => {
+    if (selectedValues.includes(value)) {
+      onSelectedValuesChange(selectedValues.filter((item) => item !== value));
+      return;
+    }
+
+    onSelectedValuesChange([...selectedValues, value]);
+  };
+
+  const normalizedSearch = normalizeCustomValue
+    ? normalizeCustomValue(searchValue)
+    : searchValue;
+
+  const canShowCustomAction =
+    normalizedSearch.length > 0 &&
+    !options.includes(normalizedSearch) &&
+    !selectedValues.includes(normalizedSearch) &&
+    (canAddCustom ? canAddCustom(normalizedSearch) : true);
+
+  return (
+    <div className='space-y-2'>
+      <Label>{label}</Label>
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button
+            variant='outline'
+            className='w-full justify-start text-left font-normal'
+          >
+            <div className='flex flex-wrap gap-1 overflow-hidden'>
+              {selectedValues.length > 0 ? (
+                selectedValues.map((value) => (
+                  <FilterBadge key={value} value={value} />
+                ))
+              ) : (
+                <span className='text-muted-foreground'>{emptyLabel}</span>
+              )}
+            </div>
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className={popoverClassName} align='start'>
+          <Command>
+            <CommandInput
+              placeholder={searchPlaceholder}
+              value={searchValue}
+              onValueChange={onSearchValueChange}
+            />
+            <CommandList>
+              {selectedValues.length > 0 && (
+                <CommandGroup heading={selectedGroupLabel}>
+                  {selectedValues.map((value) => (
+                    <CommandItem
+                      key={`selected-${value}`}
+                      onSelect={() => toggleSelection(value)}
+                    >
+                      <Checkbox checked={true} className='mr-2' />
+                      {value}
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              )}
+
+              {canShowCustomAction && (
+                <CommandGroup heading={customGroupLabel}>
+                  <CommandItem
+                    onSelect={() => {
+                      toggleSelection(normalizedSearch);
+                      onSearchValueChange('');
+                    }}
+                  >
+                    <Plus className='mr-2 h-4 w-4' />
+                    Add &quot;{normalizedSearch}&quot;
+                  </CommandItem>
+                </CommandGroup>
+              )}
+
+              <CommandEmpty>No results found.</CommandEmpty>
+
+              {quickFilters.length > 0 && (
+                <CommandGroup heading={quickGroupLabel}>
+                  {quickFilters.map((filter) => (
+                    <CommandItem key={filter.label} onSelect={filter.onSelect}>
+                      <Checkbox checked={filter.checked} className='mr-2' />
+                      {filter.label}
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              )}
+
+              <CommandGroup heading={optionsGroupLabel}>
+                {options
+                  .filter((option) => !selectedValues.includes(option))
+                  .map((option) => (
+                    <CommandItem
+                      key={option}
+                      onSelect={() => toggleSelection(option)}
+                    >
+                      <Checkbox checked={false} className='mr-2' />
+                      {option}
+                    </CommandItem>
+                  ))}
+              </CommandGroup>
+            </CommandList>
+          </Command>
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+}