Merge branch 'dynamic-prices' into litellm

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=
 

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
 

docs/provider/configuration.md

@@ -97,6 +97,7 @@ Announce your node on the network:
 | **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.
 
@@ -122,6 +123,7 @@ Use environment variables for:
 | `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`            |

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,16 +6,7 @@ Production deployment guide for Routstr Provider nodes.
 
 For production, use Docker Compose with persistent storage and optional Tor support.
 
-### Unified Setup (All-in-one)
-To build and run the node with the UI integrated in a single container using the multi-stage build:
-
-```bash
-docker build -f Dockerfile.full -t routstr-full .
-docker run -d -p 8000:8000 --env-file .env routstr-full
-```
-
-### Advanced Setup (Separated UI & Node)
-Use the included `compose.yml` for a more flexible setup that separates the UI build process from the node execution. This is useful for development or when you want to manage Tor as a separate service.
+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
@@ -184,20 +175,16 @@ docker compose up -d
 
 ## Building from Source
 
-### Unified Image (UI + Node)
-The easiest way to build everything from source into a single production-ready image:
+### Using Docker Compose
+The easiest way to build everything from source:
 
 ```bash
-docker build -f Dockerfile.full -t routstr-full .
+docker compose build
 ```
 
 ### Individual Components
-If you prefer building them separately or using Docker Compose:
+If you prefer building the node only (requires manual UI build first):
 
 ```bash
-# Build using compose
-docker compose build
-
-# Or build the node only (requires manual UI build first)
 docker build -t routstr-node .
 ```

docs/provider/quickstart.md

@@ -35,6 +35,7 @@ ADMIN_PASSWORD=mysecretpassword
 # Node Identity
 NAME="My AI Node"
 DESCRIPTION="Fast access to models"
+NSEC=yournsec
 
 # Lightning Payouts
 RECEIVE_LN_ADDRESS=yourname@wallet.com
@@ -43,32 +44,10 @@ RECEIVE_LN_ADDRESS=yourname@wallet.com
 
 ## 2. Start the Node
 
-You can run the pre-built image directly:
+The recommended way to run Routstr is using Docker Compose, which handles the node, the UI, and optional services like Tor.
 
 ```bash
-docker run -d \
-  --name routstr \
-  -p 8000:8000 \
-  --env-file .env \
-  -v routstr-data:/app/data \
-  ghcr.io/routstr/proxy:latest
-```
-
-*Note: The pre-built image does not contain the UI. For the all-in-one experience with the Admin Dashboard, use the Build from Source instructions below.*
-
-### Build from Source (Recommended)
-
-If you want to build the node and UI yourself from source, use the unified Dockerfile:
-
-```bash
-git clone https://github.com/routstr/routstr-core.git
-cd routstr-core
-# Edit your .env with ADMIN_PASSWORD and API keys
-cp .env.example .env
-nano .env
-
-docker build -f Dockerfile.full -t routstr-local .
-docker run -d -p 8000:8000 --env-file .env --name routstr routstr-local
+docker compose up -d
 ```
 
 Verify it's running:
@@ -77,6 +56,15 @@ 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
+```
+
 ---
 
 ## 3. Configure via Dashboard

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

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "routstr"
-version = "0.3.0"
+version = "0.4.3"
 description = "Payment proxy for your LLM endpoint using cashu and nostr."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -13,7 +13,7 @@ dependencies = [
     "greenlet>=3.2.1",
     "alembic>=1.13",
     "python-json-logger>=2.0.0",
-    "cashu",
+    "cashu>=0.20",
     "secp256k1",
     "marshmallow>=3.13,<4.0",
     "websockets>=12.0",
@@ -21,6 +21,7 @@ dependencies = [
     "mdurl==0.1.2",
     "pillow>=10",
     "openai>=1.98.0",
+    "litellm>=1.55.0",
 ]
 
 [dependency-groups]

routstr/algorithm.py

@@ -126,11 +126,24 @@ def create_model_mappings(
         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
@@ -204,6 +217,10 @@ 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:
                 _add_candidate(alias, model_to_use, upstream)
@@ -292,6 +309,10 @@ 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)
+
         for alias in aliases:
             _add_candidate(alias, model_to_use, upstream_for_override)
         seen_model_provider.add(dedupe_key)

routstr/auth.py

@@ -7,11 +7,12 @@ from datetime import datetime
 from typing import Optional
 
 from fastapi import HTTPException
+from sqlalchemy import case
 from sqlalchemy.exc import IntegrityError
 from sqlmodel import col, select, update
 
 from .core import get_logger
-from .core.db import ApiKey, AsyncSession
+from .core.db import ApiKey, AsyncSession, accumulate_routstr_fee
 from .core.settings import settings
 from .payment.cost_calculation import (
     CostData,
@@ -22,6 +23,13 @@ from .payment.cost_calculation import (
 from .wallet import credit_balance, deserialize_token_from_string
 
 logger = get_logger(__name__)
+payments_logger = get_logger("routstr.payments")
+
+# Routstr platform fee constants
+ROUTSTR_FEE_PERCENT: float = 2.1
+ROUTSTR_LN_ADDRESS: str = "npub130mznv74rxs032peqym6g3wqavh472623mt3z5w73xq9r6qqdufs7ql29s@npub.cash"
+ROUTSTR_FEE_PAYOUT_INTERVAL_SECONDS: int = 900
+ROUTSTR_FEE_DEFAULT_PAYOUT: int = 200
 
 # TODO: implement prepaid api key (not like it was before)
 # PREPAID_API_KEY = os.environ.get("PREPAID_API_KEY", None)
@@ -372,12 +380,12 @@ async def validate_bearer_key(
                 },
             )
 
+    key_preview = bearer_key[:10] + "..." if len(bearer_key) > 10 else bearer_key
     logger.error(
-        "Invalid API key format",
+        f"Invalid API key format: preview={key_preview!r} length={len(bearer_key)} "
+        f"(expected 'sk-...' or 'cashu...' token)",
         extra={
-            "key_preview": bearer_key[:10] + "..."
-            if len(bearer_key) > 10
-            else bearer_key,
+            "key_preview": key_preview,
             "key_length": len(bearer_key),
         },
     )
@@ -386,7 +394,7 @@ async def validate_bearer_key(
         status_code=401,
         detail={
             "error": {
-                "message": "Invalid API key",
+                "message": "Invalid API key format. Expected an 'sk-...' API key or a 'cashu...' token.",
                 "type": "invalid_request_error",
                 "code": "invalid_api_key",
             }
@@ -584,6 +592,18 @@ async def pay_for_request(
             "total_requests": billing_key.total_requests,
         },
     )
+    payments_logger.info(
+        "RESERVE",
+        extra={
+            "event": "reserve",
+            "key_hash": key.hashed_key[:8] + "...",
+            "billing_key_hash": billing_key.hashed_key[:8] + "...",
+            "cost_reserved": cost_per_request,
+            "balance": billing_key.balance,
+            "reserved_balance": billing_key.reserved_balance,
+            "total_spent": billing_key.total_spent,
+        },
+    )
 
     return cost_per_request
 
@@ -635,6 +655,17 @@ async def revert_pay_for_request(
     await session.refresh(billing_key)
     if billing_key.hashed_key != key.hashed_key:
         await session.refresh(key)
+    payments_logger.info(
+        "REVERT",
+        extra={
+            "event": "revert",
+            "key_hash": key.hashed_key[:8] + "...",
+            "billing_key_hash": billing_key.hashed_key[:8] + "...",
+            "cost_reverted": cost_per_request,
+            "balance": billing_key.balance,
+            "reserved_balance": billing_key.reserved_balance,
+        },
+    )
     return True
 
 
@@ -716,6 +747,17 @@ async def adjust_payment_for_tokens(
                 },
             )
 
+    async def _accumulate_fee(total_cost_msats: int) -> None:
+        if total_cost_msats > 0 and ROUTSTR_FEE_PERCENT > 0:
+            fee_msats = math.ceil(total_cost_msats * ROUTSTR_FEE_PERCENT / 100)
+            try:
+                await accumulate_routstr_fee(session, fee_msats)
+            except Exception as e:
+                logger.warning(
+                    "Failed to accumulate Routstr fee",
+                    extra={"error": str(e), "fee_msats": fee_msats},
+                )
+
     match await calculate_cost(response_data, deducted_max_cost, session):
         case MaxCostData() as cost:
             logger.debug(
@@ -728,11 +770,32 @@ async def adjust_payment_for_tokens(
                 },
             )
             # Finalize by releasing reservation and charging max cost
+            if billing_key.reserved_balance < deducted_max_cost:
+                logger.error(
+                    "reserved_balance below deducted_max_cost before MaxCost finalization — clamping to 0",
+                    extra={
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                        "reserved_balance": billing_key.reserved_balance,
+                        "deducted_max_cost": deducted_max_cost,
+                        "total_cost_msats": cost.total_msats,
+                        "balance": billing_key.balance,
+                        "total_spent": billing_key.total_spent,
+                        "model": model,
+                    },
+                )
+
+            safe_reserved = case(
+                (col(ApiKey.reserved_balance) >= deducted_max_cost,
+                 col(ApiKey.reserved_balance) - deducted_max_cost),
+                else_=0,
+            )
+
             finalize_stmt = (
                 update(ApiKey)
                 .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
                 .values(
-                    reserved_balance=col(ApiKey.reserved_balance) - deducted_max_cost,
+                    reserved_balance=safe_reserved,
                     balance=col(ApiKey.balance) - cost.total_msats,
                     total_spent=col(ApiKey.total_spent) + cost.total_msats,
                 )
@@ -741,13 +804,17 @@ async def adjust_payment_for_tokens(
 
             # Also update total_spent and reserved_balance on the child key if it's different
             if billing_key.hashed_key != key.hashed_key:
+                child_safe_reserved = case(
+                    (col(ApiKey.reserved_balance) >= deducted_max_cost,
+                     col(ApiKey.reserved_balance) - deducted_max_cost),
+                    else_=0,
+                )
                 child_stmt = (
                     update(ApiKey)
                     .where(col(ApiKey.hashed_key) == key.hashed_key)
                     .values(
                         total_spent=col(ApiKey.total_spent) + cost.total_msats,
-                        reserved_balance=col(ApiKey.reserved_balance)
-                        - deducted_max_cost,
+                        reserved_balance=child_safe_reserved,
                     )
                 )
                 await session.exec(child_stmt)  # type: ignore[call-overload]
@@ -776,10 +843,30 @@ async def adjust_payment_for_tokens(
                         "key_hash": key.hashed_key[:8] + "...",
                         "billing_key_hash": billing_key.hashed_key[:8] + "...",
                         "charged_amount": cost.total_msats,
+                        "input_tokens": cost.input_tokens,
+                        "output_tokens": cost.output_tokens,
                         "new_balance": billing_key.balance,
                         "model": model,
                     },
                 )
+                await _accumulate_fee(cost.total_msats)
+                payments_logger.info(
+                    "FINALIZE",
+                    extra={
+                        "event": "finalize",
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                        "model": model,
+                        "cost_reserved": deducted_max_cost,
+                        "cost_charged": cost.total_msats,
+                        "input_tokens": cost.input_tokens,
+                        "output_tokens": cost.output_tokens,
+                        "balance": billing_key.balance,
+                        "reserved_balance": billing_key.reserved_balance,
+                        "total_spent": billing_key.total_spent,
+                        "finalize_type": "max_cost",
+                    },
+                )
             return cost.dict()
 
         case CostData() as cost:
@@ -799,6 +886,8 @@ async def adjust_payment_for_tokens(
                     "cost_difference": cost_difference,
                     "input_msats": cost.input_msats,
                     "output_msats": cost.output_msats,
+                    "input_tokens": cost.input_tokens,
+                    "output_tokens": cost.output_tokens,
                 },
             )
 
@@ -811,12 +900,32 @@ async def adjust_payment_for_tokens(
                         "model": model,
                     },
                 )
+                if billing_key.reserved_balance < deducted_max_cost:
+                    logger.error(
+                        "reserved_balance below deducted_max_cost on exact-cost finalization — clamping to 0",
+                        extra={
+                            "key_hash": key.hashed_key[:8] + "...",
+                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                            "reserved_balance": billing_key.reserved_balance,
+                            "deducted_max_cost": deducted_max_cost,
+                            "total_cost_msats": total_cost_msats,
+                            "balance": billing_key.balance,
+                            "total_spent": billing_key.total_spent,
+                            "model": model,
+                        },
+                    )
+
+                exact_safe_reserved = case(
+                    (col(ApiKey.reserved_balance) >= deducted_max_cost,
+                     col(ApiKey.reserved_balance) - deducted_max_cost),
+                    else_=0,
+                )
+
                 finalize_stmt = (
                     update(ApiKey)
                     .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
                     .values(
-                        reserved_balance=col(ApiKey.reserved_balance)
-                        - deducted_max_cost,
+                        reserved_balance=exact_safe_reserved,
                         balance=col(ApiKey.balance) - total_cost_msats,
                         total_spent=col(ApiKey.total_spent) + total_cost_msats,
                     )
@@ -825,13 +934,17 @@ async def adjust_payment_for_tokens(
 
                 # Also update total_spent and reserved_balance on the child key if it's different
                 if billing_key.hashed_key != key.hashed_key:
+                    child_exact_safe_reserved = case(
+                        (col(ApiKey.reserved_balance) >= deducted_max_cost,
+                         col(ApiKey.reserved_balance) - deducted_max_cost),
+                        else_=0,
+                    )
                     child_stmt = (
                         update(ApiKey)
                         .where(col(ApiKey.hashed_key) == key.hashed_key)
                         .values(
                             total_spent=col(ApiKey.total_spent) + total_cost_msats,
-                            reserved_balance=col(ApiKey.reserved_balance)
-                            - deducted_max_cost,
+                            reserved_balance=child_exact_safe_reserved,
                         )
                     )
                     await session.exec(child_stmt)  # type: ignore[call-overload]
@@ -840,44 +953,56 @@ async def adjust_payment_for_tokens(
                 await session.refresh(billing_key)
                 if billing_key.hashed_key != key.hashed_key:
                     await session.refresh(key)
-                return cost.dict()
-
-            # this should never happen why do we handle this???
-            if cost_difference > 0:
-                # Need to charge more than reserved, finalize by releasing reservation and charging total
-                logger.info(
-                    "Additional charge required for token usage",
+                await _accumulate_fee(total_cost_msats)
+                payments_logger.info(
+                    "FINALIZE",
                     extra={
+                        "event": "finalize",
                         "key_hash": key.hashed_key[:8] + "...",
                         "billing_key_hash": billing_key.hashed_key[:8] + "...",
-                        "additional_charge": cost_difference,
-                        "current_balance": billing_key.balance,
-                        "sufficient_balance": billing_key.balance >= cost_difference,
                         "model": model,
+                        "cost_reserved": deducted_max_cost,
+                        "cost_charged": total_cost_msats,
+                        "input_tokens": cost.input_tokens,
+                        "output_tokens": cost.output_tokens,
+                        "balance": billing_key.balance,
+                        "reserved_balance": billing_key.reserved_balance,
+                        "total_spent": billing_key.total_spent,
+                        "finalize_type": "exact",
                     },
                 )
+                return cost.dict()
+
+            # actual cost exceeded discounted reservation (due to tolerance_percentage)
+            if cost_difference > 0:
+                # Always release the reservation and charge min(actual_cost, balance).
+                # Using a CASE expression makes this a single atomic UPDATE — no
+                # multi-level fallback needed and balance can never go negative.
+                chargeable = case(
+                    (col(ApiKey.balance) >= total_cost_msats, total_cost_msats),
+                    else_=col(ApiKey.balance),
+                )
 
                 finalize_stmt = (
                     update(ApiKey)
                     .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
+                    .where(col(ApiKey.reserved_balance) >= deducted_max_cost)
                     .values(
-                        reserved_balance=col(ApiKey.reserved_balance)
-                        - deducted_max_cost,
-                        balance=col(ApiKey.balance) - total_cost_msats,
-                        total_spent=col(ApiKey.total_spent) + total_cost_msats,
+                        reserved_balance=col(ApiKey.reserved_balance) - deducted_max_cost,
+                        balance=col(ApiKey.balance) - chargeable,
+                        total_spent=col(ApiKey.total_spent) + chargeable,
                     )
                 )
                 result = await session.exec(finalize_stmt)  # type: ignore[call-overload]
 
-                # Also update total_spent and reserved_balance on the child key if it's different
                 if billing_key.hashed_key != key.hashed_key:
                     child_stmt = (
                         update(ApiKey)
                         .where(col(ApiKey.hashed_key) == key.hashed_key)
+                        .where(col(ApiKey.reserved_balance) >= deducted_max_cost)
                         .values(
-                            total_spent=col(ApiKey.total_spent) + total_cost_msats,
-                            reserved_balance=col(ApiKey.reserved_balance)
-                            - deducted_max_cost,
+                            reserved_balance=col(ApiKey.reserved_balance) - deducted_max_cost,
+                            total_spent=col(ApiKey.total_spent) + min(billing_key.balance, total_cost_msats),
                         )
                     )
                     await session.exec(child_stmt)  # type: ignore[call-overload]
@@ -885,11 +1010,10 @@ async def adjust_payment_for_tokens(
                 await session.commit()
 
                 if result.rowcount:
-                    cost.total_msats = total_cost_msats
                     await session.refresh(billing_key)
                     if billing_key.hashed_key != key.hashed_key:
                         await session.refresh(key)
-
+                    cost.total_msats = total_cost_msats
                     logger.info(
                         "Finalized payment with additional charge",
                         extra={
@@ -900,9 +1024,29 @@ async def adjust_payment_for_tokens(
                             "model": model,
                         },
                     )
+                    await _accumulate_fee(total_cost_msats)
+                    payments_logger.info(
+                        "FINALIZE",
+                        extra={
+                            "event": "finalize",
+                            "key_hash": key.hashed_key[:8] + "...",
+                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                            "model": model,
+                            "cost_reserved": deducted_max_cost,
+                            "cost_charged": total_cost_msats,
+                            "input_tokens": cost.input_tokens,
+                            "output_tokens": cost.output_tokens,
+                            "balance": billing_key.balance,
+                            "reserved_balance": billing_key.reserved_balance,
+                            "total_spent": billing_key.total_spent,
+                            "finalize_type": "overrun",
+                        },
+                    )
                 else:
+                    # Guard fired: reservation was already released by a concurrent
+                    # finalization for this key. Nothing left to do.
                     logger.warning(
-                        "Failed to finalize additional charge - releasing reservation",
+                        "Finalization skipped - reservation already released",
                         extra={
                             "key_hash": key.hashed_key[:8] + "...",
                             "billing_key_hash": billing_key.hashed_key[:8] + "...",
@@ -910,7 +1054,6 @@ async def adjust_payment_for_tokens(
                             "model": model,
                         },
                     )
-                    await release_reservation_only()
             else:
                 # Refund some of the base cost
                 refund = abs(cost_difference)
@@ -925,12 +1068,33 @@ async def adjust_payment_for_tokens(
                     },
                 )
 
+                if billing_key.reserved_balance < deducted_max_cost:
+                    logger.error(
+                        "reserved_balance below deducted_max_cost on refund finalization — clamping to 0",
+                        extra={
+                            "key_hash": key.hashed_key[:8] + "...",
+                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                            "reserved_balance": billing_key.reserved_balance,
+                            "deducted_max_cost": deducted_max_cost,
+                            "total_cost_msats": total_cost_msats,
+                            "refund_amount": refund,
+                            "balance": billing_key.balance,
+                            "total_spent": billing_key.total_spent,
+                            "model": model,
+                        },
+                    )
+
+                refund_safe_reserved = case(
+                    (col(ApiKey.reserved_balance) >= deducted_max_cost,
+                     col(ApiKey.reserved_balance) - deducted_max_cost),
+                    else_=0,
+                )
+
                 refund_stmt = (
                     update(ApiKey)
                     .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
                     .values(
-                        reserved_balance=col(ApiKey.reserved_balance)
-                        - deducted_max_cost,
+                        reserved_balance=refund_safe_reserved,
                         balance=col(ApiKey.balance) - total_cost_msats,
                         total_spent=col(ApiKey.total_spent) + total_cost_msats,
                     )
@@ -939,13 +1103,17 @@ async def adjust_payment_for_tokens(
 
                 # Also update total_spent and reserved_balance on the child key if it's different
                 if billing_key.hashed_key != key.hashed_key:
+                    child_refund_safe_reserved = case(
+                        (col(ApiKey.reserved_balance) >= deducted_max_cost,
+                         col(ApiKey.reserved_balance) - deducted_max_cost),
+                        else_=0,
+                    )
                     child_stmt = (
                         update(ApiKey)
                         .where(col(ApiKey.hashed_key) == key.hashed_key)
                         .values(
                             total_spent=col(ApiKey.total_spent) + total_cost_msats,
-                            reserved_balance=col(ApiKey.reserved_balance)
-                            - deducted_max_cost,
+                            reserved_balance=child_refund_safe_reserved,
                         )
                     )
                     await session.exec(child_stmt)  # type: ignore[call-overload]
@@ -982,6 +1150,25 @@ async def adjust_payment_for_tokens(
                             "model": model,
                         },
                     )
+                    await _accumulate_fee(total_cost_msats)
+                    payments_logger.info(
+                        "FINALIZE",
+                        extra={
+                            "event": "finalize",
+                            "key_hash": key.hashed_key[:8] + "...",
+                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                            "model": model,
+                            "cost_reserved": deducted_max_cost,
+                            "cost_charged": total_cost_msats,
+                            "refunded": refund,
+                            "input_tokens": cost.input_tokens,
+                            "output_tokens": cost.output_tokens,
+                            "balance": billing_key.balance,
+                            "reserved_balance": billing_key.reserved_balance,
+                            "total_spent": billing_key.total_spent,
+                            "finalize_type": "refund",
+                        },
+                    )
 
             return cost.dict()
 

routstr/balance.py

@@ -5,11 +5,18 @@ 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 select
+from sqlmodel import col, select, update
 
 from .auth import get_billing_key, validate_bearer_key
-from .core.db import ApiKey, AsyncSession, get_session
+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
@@ -154,9 +161,23 @@ async def topup_wallet_endpoint(
             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}
 
@@ -190,19 +211,77 @@ 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:]
-
     key: ApiKey = await validate_bearer_key(bearer_value, session)
 
     if key.total_balance <= 0:
@@ -215,6 +294,12 @@ async def refund_wallet_endpoint(
             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":
@@ -227,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
@@ -251,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()
@@ -269,14 +391,67 @@ async def refund_wallet_endpoint(
 
     await _refund_cache_set(bearer_value, result)
 
-    key.balance = 0
-    key.reserved_balance = 0
-    session.add(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:
@@ -401,6 +576,27 @@ async def reset_child_key_spent(
     return {"success": True, "message": "Child key balance reset successfully."}
 
 
+@router.get("/cashu-refund/{payment_token_hash}")
+async def get_cashu_refund(
+    payment_token_hash: str,
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    """Retrieve a stored Cashu refund token by the hash of the original payment token."""
+    result = await session.get(CashuTransaction, payment_token_hash)
+    if result is None:
+        raise HTTPException(status_code=404, detail="Refund not found")
+    if result.swept:
+        raise HTTPException(status_code=410, detail="Refund has been swept")
+    result.collected = True
+    session.add(result)
+    await session.commit()
+    return {
+        "refund_token": result.token,
+        "amount": result.amount,
+        "unit": result.unit,
+    }
+
+
 @router.api_route(
     "/{path:path}",
     methods=["GET", "POST", "PUT", "DELETE"],

routstr/core/admin.py

@@ -5,11 +5,11 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
-from pydantic import BaseModel
+from pydantic import BaseModel, RootModel
 from sqlmodel import select
 
 from ..payment.models import _row_to_model, list_models
-from ..proxy import refresh_model_maps, reinitialize_upstreams
+from ..proxy import refresh_model_maps, reinitialize_upstreams, sync_provider_fees
 from ..wallet import (
     fetch_all_balances,
     get_proofs_per_mint_and_unit,
@@ -17,7 +17,14 @@ from ..wallet import (
     send_token,
     slow_filter_spend_proofs,
 )
-from .db import ApiKey, ModelRow, UpstreamProviderRow, create_session
+from .db import (
+    ApiKey,
+    CashuTransaction,
+    CliToken,
+    ModelRow,
+    UpstreamProviderRow,
+    create_session,
+)
 from .log_manager import log_manager
 from .logging import get_logger
 from .settings import SettingsService, settings
@@ -28,14 +35,31 @@ admin_router = APIRouter(prefix="/admin", include_in_schema=False)
 
 admin_sessions: dict[str, int] = {}
 ADMIN_SESSION_DURATION = 3600
+# Usage analytics remain queryable up to 12 months.
+MAX_USAGE_ANALYTICS_HOURS = 365 * 24
 
 
-def require_admin_api(request: Request) -> None:
+async def require_admin_api(request: Request) -> None:
     auth_header = request.headers.get("Authorization")
-    if auth_header and auth_header.startswith("Bearer "):
-        token = auth_header.split(" ", 1)[1]
-        expiry = admin_sessions.get(token)
-        if expiry and expiry > int(datetime.now(timezone.utc).timestamp()):
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(status_code=403, detail="Unauthorized")
+
+    token = auth_header.split(" ", 1)[1]
+    now_ts = int(datetime.now(timezone.utc).timestamp())
+
+    # 1) Short-lived session token (in-memory)
+    expiry = admin_sessions.get(token)
+    if expiry and expiry > now_ts:
+        return
+
+    # 2) Long-lived CLI token (DB-backed)
+    async with create_session() as session:
+        result = await session.exec(select(CliToken).where(CliToken.token == token))
+        cli_token = result.first()
+        if cli_token and (cli_token.expires_at is None or cli_token.expires_at > now_ts):
+            cli_token.last_used_at = now_ts
+            session.add(cli_token)
+            await session.commit()
             return
 
     raise HTTPException(status_code=403, detail="Unauthorized")
@@ -118,8 +142,8 @@ async def get_settings(request: Request) -> dict:
     return data
 
 
-class SettingsUpdate(BaseModel):
-    __root__: dict[str, object]
+class SettingsUpdate(RootModel[dict[str, object]]):
+    pass
 
 
 class PasswordUpdate(BaseModel):
@@ -130,7 +154,7 @@ class PasswordUpdate(BaseModel):
 @admin_router.patch("/api/settings", dependencies=[Depends(require_admin_api)])
 async def update_settings(request: Request, update: SettingsUpdate) -> dict:
     # Remove sensitive fields from general settings update
-    settings_data = update.__root__.copy()
+    settings_data = update.root.copy()
     sensitive_fields = ["admin_password", "upstream_api_key", "nsec"]
     for field in sensitive_fields:
         if field in settings_data:
@@ -234,6 +258,73 @@ async def admin_logout(request: Request) -> dict[str, object]:
     return {"ok": True}
 
 
+# ─── CLI Tokens (long-lived bearer tokens for CLI/agent use) ───
+
+
+class CliTokenCreate(BaseModel):
+    name: str
+    expires_in_days: int | None = None
+
+
+@admin_router.get("/api/cli-tokens", dependencies=[Depends(require_admin_api)])
+async def list_cli_tokens() -> list[dict[str, object]]:
+    async with create_session() as session:
+        result = await session.exec(select(CliToken))
+        tokens = result.all()
+    return [
+        {
+            "id": t.id,
+            "name": t.name,
+            "token_preview": f"{t.token[:8]}...{t.token[-4:]}",
+            "created_at": t.created_at,
+            "last_used_at": t.last_used_at,
+            "expires_at": t.expires_at,
+        }
+        for t in tokens
+    ]
+
+
+@admin_router.post("/api/cli-tokens", dependencies=[Depends(require_admin_api)])
+async def create_cli_token(payload: CliTokenCreate) -> dict[str, object]:
+    name = (payload.name or "").strip()
+    if not name:
+        raise HTTPException(status_code=400, detail="Name is required")
+
+    raw_token = secrets.token_urlsafe(32)
+    expires_at: int | None = None
+    if payload.expires_in_days is not None and payload.expires_in_days > 0:
+        expires_at = int(datetime.now(timezone.utc).timestamp()) + (
+            payload.expires_in_days * 86400
+        )
+
+    async with create_session() as session:
+        cli_token = CliToken(token=raw_token, name=name, expires_at=expires_at)
+        session.add(cli_token)
+        await session.commit()
+        await session.refresh(cli_token)
+
+    return {
+        "id": cli_token.id,
+        "name": cli_token.name,
+        "token": raw_token,  # full token returned only on creation
+        "created_at": cli_token.created_at,
+        "expires_at": cli_token.expires_at,
+    }
+
+
+@admin_router.delete(
+    "/api/cli-tokens/{token_id}", dependencies=[Depends(require_admin_api)]
+)
+async def revoke_cli_token(token_id: str) -> dict[str, object]:
+    async with create_session() as session:
+        cli_token = await session.get(CliToken, token_id)
+        if not cli_token:
+            raise HTTPException(status_code=404, detail="Token not found")
+        await session.delete(cli_token)
+        await session.commit()
+    return {"ok": True, "deleted_id": token_id}
+
+
 class WithdrawRequest(BaseModel):
     amount: int
     mint_url: str | None = None
@@ -287,6 +378,7 @@ class ModelCreate(BaseModel):
     canonical_slug: str | None = None
     alias_ids: list[str] | None = None
     enabled: bool = True
+    forwarded_model_id: str | None = None
 
 
 @admin_router.post(
@@ -331,6 +423,7 @@ async def upsert_provider_model(
                 json.dumps(payload.alias_ids) if payload.alias_ids else None
             )
             existing_row.enabled = payload.enabled
+            existing_row.forwarded_model_id = payload.forwarded_model_id or payload.id
 
             session.add(existing_row)
             await session.commit()
@@ -363,6 +456,7 @@ async def upsert_provider_model(
                 ),
                 upstream_provider_id=provider_id,
                 enabled=payload.enabled,
+                forwarded_model_id=payload.forwarded_model_id or payload.id,
             )
             session.add(row)
             await session.commit()
@@ -545,6 +639,7 @@ class UpstreamProviderCreate(BaseModel):
     api_version: str | None = None
     enabled: bool = True
     provider_fee: float = 1.01
+    provider_fee_default: float | None = None
     provider_settings: dict | None = None
 
 
@@ -555,29 +650,37 @@ class UpstreamProviderUpdate(BaseModel):
     api_version: str | None = None
     enabled: bool | None = None
     provider_fee: float | None = None
+    provider_fee_default: float | None = None
     provider_settings: dict | None = None
 
 
+def _provider_to_dict(
+    p: UpstreamProviderRow, redact_key: bool = True
+) -> dict[str, object]:
+    return {
+        "id": p.id,
+        "provider_type": p.provider_type,
+        "base_url": p.base_url,
+        "api_key": "[REDACTED]" if (redact_key and p.api_key) else (p.api_key or ""),
+        "api_version": p.api_version,
+        "enabled": p.enabled,
+        "provider_fee": p.provider_fee,
+        "provider_fee_default": p.provider_fee_default,
+        "provider_settings": json.loads(p.provider_settings)
+        if p.provider_settings
+        else None,
+        "provider_fee_schedules": json.loads(p.provider_fee_schedules)
+        if p.provider_fee_schedules
+        else [],
+    }
+
+
 @admin_router.get("/api/upstream-providers", dependencies=[Depends(require_admin_api)])
 async def get_upstream_providers() -> list[dict[str, object]]:
     async with create_session() as session:
         result = await session.exec(select(UpstreamProviderRow))
         providers = result.all()
-        return [
-            {
-                "id": p.id,
-                "provider_type": p.provider_type,
-                "base_url": p.base_url,
-                "api_key": "[REDACTED]" if p.api_key else "",
-                "api_version": p.api_version,
-                "enabled": p.enabled,
-                "provider_fee": p.provider_fee,
-                "provider_settings": json.loads(p.provider_settings)
-                if p.provider_settings
-                else None,
-            }
-            for p in providers
-        ]
+        return [_provider_to_dict(p) for p in providers]
 
 
 @admin_router.post("/api/upstream-providers", dependencies=[Depends(require_admin_api)])
@@ -604,6 +707,9 @@ async def create_upstream_provider(
             api_version=payload.api_version,
             enabled=payload.enabled,
             provider_fee=payload.provider_fee,
+            provider_fee_default=payload.provider_fee_default
+            if payload.provider_fee_default is not None
+            else payload.provider_fee,
             provider_settings=json.dumps(payload.provider_settings)
             if payload.provider_settings
             else None,
@@ -613,17 +719,7 @@ async def create_upstream_provider(
         await session.refresh(provider)
 
     await reinitialize_upstreams()
-    await refresh_model_maps()
-    return {
-        "id": provider.id,
-        "provider_type": provider.provider_type,
-        "base_url": provider.base_url,
-        "api_key": "[REDACTED]",
-        "api_version": provider.api_version,
-        "enabled": provider.enabled,
-        "provider_fee": provider.provider_fee,
-        "provider_settings": payload.provider_settings,
-    }
+    return _provider_to_dict(provider)
 
 
 @admin_router.get(
@@ -634,18 +730,7 @@ async def get_upstream_provider(provider_id: int) -> dict[str, object]:
         provider = await session.get(UpstreamProviderRow, provider_id)
         if not provider:
             raise HTTPException(status_code=404, detail="Provider not found")
-        return {
-            "id": provider.id,
-            "provider_type": provider.provider_type,
-            "base_url": provider.base_url,
-            "api_key": "[REDACTED]" if provider.api_key else "",
-            "api_version": provider.api_version,
-            "enabled": provider.enabled,
-            "provider_fee": provider.provider_fee,
-            "provider_settings": json.loads(provider.provider_settings)
-            if provider.provider_settings
-            else None,
-        }
+        return _provider_to_dict(provider)
 
 
 @admin_router.patch(
@@ -671,6 +756,8 @@ async def update_upstream_provider(
             provider.enabled = payload.enabled
         if payload.provider_fee is not None:
             provider.provider_fee = payload.provider_fee
+        if payload.provider_fee_default is not None:
+            provider.provider_fee_default = payload.provider_fee_default
         if payload.provider_settings is not None:
             provider.provider_settings = json.dumps(payload.provider_settings)
 
@@ -679,19 +766,7 @@ async def update_upstream_provider(
         await session.refresh(provider)
 
     await reinitialize_upstreams()
-    await refresh_model_maps()
-    return {
-        "id": provider.id,
-        "provider_type": provider.provider_type,
-        "base_url": provider.base_url,
-        "api_key": "[REDACTED]",
-        "api_version": provider.api_version,
-        "enabled": provider.enabled,
-        "provider_fee": provider.provider_fee,
-        "provider_settings": json.loads(provider.provider_settings)
-        if provider.provider_settings
-        else None,
-    }
+    return _provider_to_dict(provider)
 
 
 @admin_router.delete(
@@ -709,6 +784,78 @@ async def delete_upstream_provider(provider_id: int) -> dict[str, object]:
     return {"ok": True, "deleted_id": provider_id}
 
 
+@admin_router.get(
+    "/api/upstream-providers/{provider_id}/fee-schedules",
+    dependencies=[Depends(require_admin_api)],
+)
+async def get_fee_schedules(provider_id: int) -> list[dict]:
+    async with create_session() as session:
+        provider = await session.get(UpstreamProviderRow, provider_id)
+        if not provider:
+            raise HTTPException(status_code=404, detail="Provider not found")
+        return (
+            json.loads(provider.provider_fee_schedules)
+            if provider.provider_fee_schedules
+            else []
+        )
+
+
+class FeeScheduleUpdate(BaseModel):
+    schedules: list[dict]
+
+
+@admin_router.put(
+    "/api/upstream-providers/{provider_id}/fee-schedules",
+    dependencies=[Depends(require_admin_api)],
+)
+async def update_fee_schedules(
+    provider_id: int, payload: FeeScheduleUpdate
+) -> list[dict]:
+    from ..payment.fee_schedule import FeeTimeRange, validate_no_overlaps
+
+    try:
+        ranges = [FeeTimeRange(**s) for s in payload.schedules]
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Invalid schedule data: {e}")
+
+    try:
+        validate_no_overlaps(ranges)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    serialized = [r.dict() for r in ranges]
+
+    async with create_session() as session:
+        provider = await session.get(UpstreamProviderRow, provider_id)
+        if not provider:
+            raise HTTPException(status_code=404, detail="Provider not found")
+        provider.provider_fee_schedules = json.dumps(serialized)
+        session.add(provider)
+        await session.commit()
+
+    await sync_provider_fees()
+    await refresh_model_maps()
+    return serialized
+
+
+@admin_router.delete(
+    "/api/upstream-providers/{provider_id}/fee-schedules",
+    dependencies=[Depends(require_admin_api)],
+)
+async def delete_fee_schedules(provider_id: int) -> dict:
+    async with create_session() as session:
+        provider = await session.get(UpstreamProviderRow, provider_id)
+        if not provider:
+            raise HTTPException(status_code=404, detail="Provider not found")
+        provider.provider_fee_schedules = None
+        session.add(provider)
+        await session.commit()
+
+    await sync_provider_fees()
+    await refresh_model_maps()
+    return {"ok": True}
+
+
 @admin_router.get("/api/provider-types", dependencies=[Depends(require_admin_api)])
 async def get_provider_types() -> list[dict[str, object]]:
     """Get metadata about available provider types including default URLs and whether they're fixed."""
@@ -748,7 +895,9 @@ async def get_provider_models(provider_id: int) -> dict[str, object]:
                 )
 
         db_model_ids = {model.id for model in db_models}
-        filtered_remote_models = [m for m in upstream_models if m.id not in db_model_ids]
+        filtered_remote_models = [
+            m for m in upstream_models if m.id not in db_model_ids
+        ]
 
         return {
             "provider": {
@@ -1002,7 +1151,9 @@ async def check_topup_status(provider_id: int, invoice_id: str) -> dict[str, obj
                 clean_url = provider.base_url.rstrip("/")
                 resp = await client.get(
                     f"{clean_url}/v1/balance/lightning/invoice/{invoice_id}/status",
-                    headers={"Authorization": f"Bearer {provider.api_key}"} if provider.api_key else {},
+                    headers={"Authorization": f"Bearer {provider.api_key}"}
+                    if provider.api_key
+                    else {},
                 )
                 if resp.status_code == 200:
                     status_data = resp.json()
@@ -1137,16 +1288,57 @@ async def get_usage_metrics(
     interval: int = Query(
         default=15, ge=1, le=1440, description="Time interval in minutes"
     ),
-    hours: int = Query(default=24, ge=1, description="Hours of history to analyze"),
+    hours: int = Query(
+        default=24,
+        ge=1,
+        le=MAX_USAGE_ANALYTICS_HOURS,
+        description="Hours of history to analyze",
+    ),
 ) -> dict:
     """Get usage metrics aggregated by time interval."""
     return log_manager.get_usage_metrics(interval=interval, hours=hours)
 
 
+@admin_router.get("/api/usage/dashboard", dependencies=[Depends(require_admin_api)])
+async def get_usage_dashboard(
+    request: Request,
+    interval: int = Query(
+        default=15, ge=1, le=1440, description="Time interval in minutes"
+    ),
+    hours: int = Query(
+        default=24,
+        ge=1,
+        le=MAX_USAGE_ANALYTICS_HOURS,
+        description="Hours of history to analyze",
+    ),
+    error_limit: int = Query(
+        default=100, ge=1, le=1000, description="Maximum number of errors to return"
+    ),
+    model_limit: int = Query(
+        default=20, ge=1, le=100, description="Maximum number of models to return"
+    ),
+) -> dict:
+    """
+    Get all dashboard analytics in one request.
+    This runs one combined aggregation pass and avoids repeated scans.
+    """
+    return log_manager.get_usage_dashboard(
+        interval=interval,
+        hours=hours,
+        error_limit=error_limit,
+        model_limit=model_limit,
+    )
+
+
 @admin_router.get("/api/usage/summary", dependencies=[Depends(require_admin_api)])
 async def get_usage_summary(
     request: Request,
-    hours: int = Query(default=24, ge=1, description="Hours of history to analyze"),
+    hours: int = Query(
+        default=24,
+        ge=1,
+        le=MAX_USAGE_ANALYTICS_HOURS,
+        description="Hours of history to analyze",
+    ),
 ) -> dict:
     """Get summary statistics for the specified time period."""
     return log_manager.get_usage_summary(hours=hours)
@@ -1155,7 +1347,12 @@ async def get_usage_summary(
 @admin_router.get("/api/usage/error-details", dependencies=[Depends(require_admin_api)])
 async def get_error_details(
     request: Request,
-    hours: int = Query(default=24, ge=1, description="Hours of history to analyze"),
+    hours: int = Query(
+        default=24,
+        ge=1,
+        le=MAX_USAGE_ANALYTICS_HOURS,
+        description="Hours of history to analyze",
+    ),
     limit: int = Query(
         default=100, ge=1, le=1000, description="Maximum number of errors to return"
     ),
@@ -1169,7 +1366,12 @@ async def get_error_details(
 )
 async def get_revenue_by_model(
     request: Request,
-    hours: int = Query(default=24, ge=1, description="Hours of history to analyze"),
+    hours: int = Query(
+        default=24,
+        ge=1,
+        le=MAX_USAGE_ANALYTICS_HOURS,
+        description="Hours of history to analyze",
+    ),
     limit: int = Query(
         default=20, ge=1, le=100, description="Maximum number of models to return"
     ),
@@ -1264,6 +1466,64 @@ async def get_log_dates_api(request: Request) -> dict[str, object]:
     return {"dates": dates}
 
 
+@admin_router.get("/api/transactions", dependencies=[Depends(require_admin_api)])
+async def get_transactions_api(
+    type: str | None = None,
+    status: str | None = None,
+    search: str | None = None,
+    source: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> dict:
+    async with create_session() as session:
+        from sqlmodel import col, func
+
+        base = select(CashuTransaction)
+        if type:
+            base = base.where(CashuTransaction.type == type)
+        if source:
+            if source == "x-cashu":
+                base = base.where(
+                    (CashuTransaction.source == "x-cashu")
+                    | (CashuTransaction.source == None)  # noqa: E711
+                )
+            else:
+                base = base.where(CashuTransaction.source == source)
+        if status:
+            if status == "collected":
+                base = base.where(CashuTransaction.collected == True)  # noqa: E712
+            elif status == "swept":
+                base = base.where(CashuTransaction.swept == True)  # noqa: E712
+            elif status == "pending":
+                base = base.where(
+                    CashuTransaction.collected == False,  # noqa: E712
+                    CashuTransaction.swept == False,  # noqa: E712
+                )
+
+        if search:
+            search_pattern = f"%{search}%"
+            base = base.where(
+                (col(CashuTransaction.id).like(search_pattern))
+                | (col(CashuTransaction.token).like(search_pattern))
+                | (col(CashuTransaction.request_id).like(search_pattern))
+                | (col(CashuTransaction.api_key_hashed_key).like(search_pattern))
+            )
+
+        count_result = await session.exec(
+            select(func.count()).select_from(base.subquery())
+        )
+        total = count_result.one()
+
+        stmt = base.order_by(col(CashuTransaction.created_at).desc()).offset(offset).limit(limit)
+        results = await session.exec(stmt)
+        transactions = results.all()
+
+        return {
+            "transactions": [tx.dict() for tx in transactions],
+            "total": total,
+        }
+
+
 @admin_router.post(
     "/api/upstream-providers/{provider_id}/routstr/refund",
     dependencies=[Depends(require_admin_api)],

routstr/core/db.py

@@ -2,14 +2,17 @@ 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
@@ -103,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")
 
 
@@ -128,6 +135,73 @@ 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__ = (
@@ -146,17 +220,83 @@ class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
     )
     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",
         sa_relationship_kwargs={"cascade": "all, delete-orphan"},
     )
 
 
+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:
@@ -227,6 +367,17 @@ def fix_cashu_migrations() -> None:
             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."""
     try:
@@ -248,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/log_manager.py

@@ -1,17 +1,73 @@
 import json
+import time
 from collections import defaultdict
 from datetime import datetime, timedelta, timezone
+from heapq import heappush, heapreplace
 from pathlib import Path
-from typing import Any, Iterator
+from threading import Lock
+from typing import Any, Callable, Iterator, TypeVar
 
 from .logging import get_logger
+from .usage_analytics_store import UsageAnalyticsStore
 
 logger = get_logger(__name__)
+T = TypeVar("T")
 
 
 class LogManager:
     def __init__(self, logs_dir: Path = Path("logs")):
         self.logs_dir = logs_dir
+        self._usage_store = UsageAnalyticsStore(logs_dir=logs_dir)
+        self._analytics_cache_ttl_seconds = 30.0
+        self._analytics_cache: dict[tuple[Any, ...], tuple[float, Any]] = {}
+        self._analytics_cache_lock = Lock()
+        self._cache_miss = object()
+
+    def _get_cached(self, key: tuple[Any, ...]) -> Any:
+        now = time.time()
+        with self._analytics_cache_lock:
+            cached = self._analytics_cache.get(key)
+            if cached is None:
+                return self._cache_miss
+
+            expires_at, value = cached
+            if expires_at <= now:
+                self._analytics_cache.pop(key, None)
+                return self._cache_miss
+
+            return value
+
+    def _set_cached(
+        self, key: tuple[Any, ...], value: Any, ttl_seconds: float | None = None
+    ) -> None:
+        ttl = (
+            self._analytics_cache_ttl_seconds
+            if ttl_seconds is None
+            else max(1.0, ttl_seconds)
+        )
+        expires_at = time.time() + ttl
+        with self._analytics_cache_lock:
+            self._analytics_cache[key] = (expires_at, value)
+
+    def _cache_call(
+        self,
+        key: tuple[Any, ...],
+        compute: Callable[[], T],
+        ttl_seconds: float | None = None,
+    ) -> T:
+        cached = self._get_cached(key)
+        if cached is not self._cache_miss:
+            return cached
+
+        value = compute()
+        self._set_cached(key, value, ttl_seconds=ttl_seconds)
+        return value
+
+    def _get_cached_entries(self, hours: int) -> list[dict[str, Any]]:
+        return self._cache_call(
+            ("usage_entries", hours),
+            lambda: list(self._yield_log_entries(hours_back=hours)),
+        )
 
     def _yield_log_entries(
         self,
@@ -19,7 +75,6 @@ class LogManager:
         specific_date: str | None = None,
         reverse_files: bool = False,
         max_files: int | None = None,
-        window_center: datetime | None = None,
     ) -> Iterator[dict[str, Any]]:
         """
         Yields log entries from files.
@@ -29,7 +84,6 @@ class LogManager:
             specific_date: specific date string (YYYY-MM-DD) to look at.
             reverse_files: if True, process files in reverse order (newest first).
             max_files: maximum number of log files to process (most recent if reverse_files is True).
-            window_center: datetime object to center a 5-month window around.
         """
         if not self.logs_dir.exists():
             return
@@ -44,36 +98,6 @@ class LogManager:
                 log_files.append(log_file)
         else:
             log_files = sorted(self.logs_dir.glob("app_*.log"))
-
-            if window_center:
-                # Calculate the 5 months: [center-2, center-1, center, center+1, center+2]
-                allowed_month_years = []
-                cur_m = window_center.month
-                cur_y = window_center.year
-
-                for offset in range(-2, 3):
-                    m = cur_m + offset
-                    y = cur_y
-                    while m <= 0:
-                        m += 12
-                        y -= 1
-                    while m > 12:
-                        m -= 12
-                        y += 1
-                    allowed_month_years.append(f"{y}-{m:02d}")
-
-                filtered_files = []
-                for log_path in log_files:
-                    try:
-                        # Stem is "app_YYYY-MM-DD"
-                        file_date_str = log_path.stem.split("_")[1]
-                        file_month_year = file_date_str[:7]  # YYYY-MM
-                        if file_month_year in allowed_month_years:
-                            filtered_files.append(log_path)
-                    except Exception:
-                        continue
-                log_files = filtered_files
-
             if reverse_files:
                 log_files.reverse()
 
@@ -303,128 +327,208 @@ class LogManager:
         return 0
 
     def get_usage_summary(self, hours: int = 24) -> dict:
-        entries = list(
-            self._yield_log_entries(
-                hours_back=hours, window_center=datetime.now(timezone.utc)
-            )
+        def compute() -> dict:
+            try:
+                return self._usage_store.get_summary(hours_back=hours)
+            except Exception as e:
+                logger.error(
+                    f"Usage analytics index failed, falling back to log scan: {e}"
+                )
+                return self._calculate_summary_stats(self._get_cached_entries(hours))
+
+        return self._cache_call(
+            ("usage_summary", hours),
+            compute,
         )
-        return self._calculate_summary_stats(entries)
 
     def get_usage_metrics(self, interval: int = 15, hours: int = 24) -> dict:
-        entries = list(
-            self._yield_log_entries(
-                hours_back=hours, window_center=datetime.now(timezone.utc)
-            )
+        def compute() -> dict:
+            try:
+                return self._usage_store.get_metrics(
+                    interval_minutes=interval,
+                    hours_back=hours,
+                )
+            except Exception as e:
+                logger.error(
+                    f"Usage analytics index failed, falling back to log scan: {e}"
+                )
+                return self._aggregate_metrics_by_time(
+                    self._get_cached_entries(hours), interval, hours
+                )
+
+        return self._cache_call(
+            ("usage_metrics", interval, hours),
+            compute,
+        )
+
+    def get_usage_dashboard(
+        self,
+        interval: int = 15,
+        hours: int = 24,
+        error_limit: int = 100,
+        model_limit: int = 20,
+    ) -> dict:
+        # Large ranges are expensive to scan; keep cached longer.
+        if hours <= 24:
+            cache_ttl = 60.0
+        elif hours <= 7 * 24:
+            cache_ttl = 300.0
+        elif hours <= 30 * 24:
+            cache_ttl = 1800.0
+        elif hours <= 90 * 24:
+            cache_ttl = 7200.0
+        else:
+            cache_ttl = 21600.0
+
+        def compute() -> dict:
+            try:
+                return self._usage_store.get_dashboard(
+                    interval_minutes=interval,
+                    hours_back=hours,
+                    error_limit=error_limit,
+                    model_limit=model_limit,
+                )
+            except Exception as e:
+                logger.error(
+                    f"Usage analytics index failed, falling back to log scan: {e}"
+                )
+                return self._aggregate_dashboard(
+                    interval_minutes=interval,
+                    hours_back=hours,
+                    error_limit=error_limit,
+                    model_limit=model_limit,
+                )
+
+        return self._cache_call(
+            ("usage_dashboard", interval, hours, error_limit, model_limit),
+            compute,
+            ttl_seconds=cache_ttl,
         )
-        return self._aggregate_metrics_by_time(entries, interval, hours)
 
     def get_error_details(self, hours: int = 24, limit: int = 100) -> dict:
-        errors: list[dict[str, Any]] = []
+        def compute() -> dict:
+            try:
+                return self._usage_store.get_error_details(hours_back=hours, limit=limit)
+            except Exception as e:
+                logger.error(
+                    f"Usage analytics index failed, falling back to log scan: {e}"
+                )
 
-        for entry in self._yield_log_entries(hours_back=hours):
-            if str(entry.get("levelname", "")).upper() != "ERROR":
-                continue
+            errors: list[dict] = []
+            for entry in self._get_cached_entries(hours):
+                if str(entry.get("levelname", "")).upper() == "ERROR":
+                    timestamp_str = entry.get("asctime", "")
+                    errors.append(
+                        {
+                            "timestamp": timestamp_str,
+                            "message": entry.get("message", ""),
+                            "error_type": entry.get("error_type", "unknown"),
+                            "pathname": entry.get("pathname", ""),
+                            "lineno": entry.get("lineno", 0),
+                            "request_id": entry.get("request_id", ""),
+                        }
+                    )
 
-            errors.append(
-                {
-                    "timestamp": entry.get("asctime", ""),
-                    "message": entry.get("message", ""),
-                    "error_type": entry.get("error_type", "unknown"),
-                    "pathname": entry.get("pathname", ""),
-                    "lineno": entry.get("lineno", 0),
-                    "request_id": entry.get("request_id", ""),
-                }
-            )
+            errors.sort(key=lambda x: x["timestamp"], reverse=True)
+            return {"errors": errors[:limit], "total_count": len(errors)}
 
-        errors.sort(key=lambda x: str(x["timestamp"]), reverse=True)
-        return {"errors": errors[:limit], "total_count": len(errors)}
+        return self._cache_call(("error_details", hours, limit), compute)
 
     def get_revenue_by_model(self, hours: int = 24, limit: int = 20) -> dict:
-        entries = list(
-            self._yield_log_entries(
-                hours_back=hours, window_center=datetime.now(timezone.utc)
-            )
-        )
-
-        model_stats: dict[str, dict[str, int | float]] = defaultdict(
-            lambda: {
-                "revenue_msats": 0,
-                "refunds_msats": 0,
-                "requests": 0,
-                "successful": 0,
-                "failed": 0,
-            }
-        )
-
-        for entry in entries:
+        def compute() -> dict:
             try:
-                model = entry.get("model", "unknown")
-                if not isinstance(model, str):
-                    model = "unknown"
-
-                message = str(entry.get("message", "")).lower()
-
-                completed, revenue_msats, _, _ = self._extract_success_metrics(
-                    entry, message
+                return self._usage_store.get_revenue_by_model(
+                    hours_back=hours, limit=limit
                 )
-                if completed:
-                    model_stats[model]["requests"] += 1
-                    model_stats[model]["successful"] += 1
-                    if revenue_msats > 0:
-                        model_stats[model]["revenue_msats"] += revenue_msats
-
-                failed = (
-                    "revert payment" in message or "upstream request failed" in message
+            except Exception as e:
+                logger.error(
+                    f"Usage analytics index failed, falling back to log scan: {e}"
                 )
-                if failed:
-                    model_stats[model]["requests"] += 1
-                    model_stats[model]["failed"] += 1
-                    if "revert payment" in message:
-                        max_cost = entry.get("max_cost_for_model", 0)
-                        if isinstance(max_cost, (int, float)) and max_cost > 0:
-                            model_stats[model]["refunds_msats"] += max_cost
 
-            except Exception:
-                continue
+            entries = self._get_cached_entries(hours)
 
-        models: list[dict[str, Any]] = []
-        total_revenue = 0.0
-
-        for model, stats in model_stats.items():
-            revenue_msats = float(stats["revenue_msats"])
-            refunds_msats = float(stats["refunds_msats"])
-
-            revenue_sats = revenue_msats / 1000
-            refunds_sats = refunds_msats / 1000
-            net_revenue_sats = revenue_sats - refunds_sats
-
-            total_revenue += net_revenue_sats
-
-            requests = int(stats["requests"])
-            successful = int(stats["successful"])
-
-            models.append(
-                {
-                    "model": model,
-                    "revenue_sats": revenue_sats,
-                    "refunds_sats": refunds_sats,
-                    "net_revenue_sats": net_revenue_sats,
-                    "requests": requests,
-                    "successful": successful,
-                    "failed": int(stats["failed"]),
-                    "avg_revenue_per_request": (
-                        revenue_sats / successful if successful > 0 else 0
-                    ),
+            model_stats: dict[str, dict[str, int | float]] = defaultdict(
+                lambda: {
+                    "revenue_msats": 0,
+                    "refunds_msats": 0,
+                    "requests": 0,
+                    "successful": 0,
+                    "failed": 0,
                 }
             )
 
-        models.sort(key=lambda x: float(x["net_revenue_sats"]), reverse=True)
+            for entry in entries:
+                try:
+                    model = entry.get("model", "unknown")
+                    if not isinstance(model, str):
+                        model = "unknown"
 
-        return {
-            "models": models[:limit],
-            "total_revenue_sats": total_revenue,
-            "total_models": len(models),
-        }
+                    message = str(entry.get("message", "")).lower()
+
+                    completed, revenue_msats, _, _ = self._extract_success_metrics(
+                        entry, message
+                    )
+                    if completed:
+                        model_stats[model]["requests"] += 1
+                        model_stats[model]["successful"] += 1
+                        if revenue_msats > 0:
+                            model_stats[model]["revenue_msats"] += revenue_msats
+
+                    failed = (
+                        "revert payment" in message
+                        or "upstream request failed" in message
+                    )
+                    if failed:
+                        model_stats[model]["requests"] += 1
+                        model_stats[model]["failed"] += 1
+                        if "revert payment" in message:
+                            max_cost = entry.get("max_cost_for_model", 0)
+                            if isinstance(max_cost, (int, float)) and max_cost > 0:
+                                model_stats[model]["refunds_msats"] += max_cost
+
+                except Exception:
+                    continue
+
+            models: list[dict[str, Any]] = []
+            total_revenue = 0.0
+
+            for model, stats in model_stats.items():
+                revenue_msats = float(stats["revenue_msats"])
+                refunds_msats = float(stats["refunds_msats"])
+
+                revenue_sats = revenue_msats / 1000
+                refunds_sats = refunds_msats / 1000
+                net_revenue_sats = revenue_sats - refunds_sats
+
+                total_revenue += net_revenue_sats
+
+                requests = int(stats["requests"])
+                successful = int(stats["successful"])
+
+                models.append(
+                    {
+                        "model": model,
+                        "revenue_sats": revenue_sats,
+                        "refunds_sats": refunds_sats,
+                        "net_revenue_sats": net_revenue_sats,
+                        "requests": requests,
+                        "successful": successful,
+                        "failed": int(stats["failed"]),
+                        "avg_revenue_per_request": (
+                            revenue_sats / successful if successful > 0 else 0
+                        ),
+                    }
+                )
+
+            models.sort(key=lambda x: float(x["net_revenue_sats"]), reverse=True)
+
+            return {
+                "models": models[:limit],
+                "total_revenue_sats": total_revenue,
+                "total_models": len(models),
+            }
+
+        return self._cache_call(("revenue_by_model", hours, limit), compute)
 
     def _build_summary_response(self, stats: dict[str, Any]) -> dict[str, Any]:
         revenue_sats = stats["revenue_msats"] / 1000
@@ -555,6 +659,344 @@ class LogManager:
 
         return self._build_summary_response(stats)
 
+    def _aggregate_dashboard(
+        self,
+        interval_minutes: int,
+        hours_back: int,
+        error_limit: int,
+        model_limit: int,
+    ) -> dict[str, Any]:
+        time_buckets: dict[str, dict[str, Any]] = defaultdict(
+            lambda: {
+                "total_requests": 0,
+                "successful_chat_completions": 0,
+                "failed_requests": 0,
+                "errors": 0,
+                "warnings": 0,
+                "payment_processed": 0,
+                "upstream_errors": 0,
+                "revenue_msats": 0.0,
+                "refunds_msats": 0.0,
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "total_tokens": 0,
+            }
+        )
+        summary_stats: dict[str, Any] = {
+            "total_entries": 0,
+            "total_requests": 0,
+            "successful_chat_completions": 0,
+            "failed_requests": 0,
+            "total_errors": 0,
+            "total_warnings": 0,
+            "payment_processed": 0,
+            "upstream_errors": 0,
+            "unique_models": set(),
+            "error_types": defaultdict(int),
+            "revenue_msats": 0.0,
+            "refunds_msats": 0.0,
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "total_tokens": 0,
+        }
+        model_stats: dict[str, dict[str, int | float]] = defaultdict(
+            lambda: {
+                "revenue_msats": 0,
+                "refunds_msats": 0,
+                "requests": 0,
+                "successful": 0,
+                "failed": 0,
+            }
+        )
+        model_mix_buckets: dict[str, dict[str, int]] = defaultdict(
+            lambda: defaultdict(int)
+        )
+        model_mix_revenue_buckets: dict[str, dict[str, float]] = defaultdict(
+            lambda: defaultdict(float)
+        )
+        model_mix_token_buckets: dict[str, dict[str, int]] = defaultdict(
+            lambda: defaultdict(int)
+        )
+        model_mix_totals: dict[str, int] = defaultdict(int)
+        model_mix_revenue_totals: dict[str, float] = defaultdict(float)
+        model_mix_token_totals: dict[str, int] = defaultdict(int)
+        latest_errors_heap: list[tuple[str, dict[str, Any]]] = []
+        total_error_count = 0
+
+        for entry in self._yield_log_entries(hours_back=hours_back):
+            try:
+                summary_stats["total_entries"] += 1
+
+                timestamp_str = entry.get("asctime", "")
+                message = str(entry.get("message", "")).lower()
+                level = str(entry.get("levelname", "")).upper()
+                model = entry.get("model", "unknown")
+                if not isinstance(model, str):
+                    model = "unknown"
+
+                bucket_key = (
+                    self._bucket_key_for_timestamp(timestamp_str, interval_minutes)
+                    if isinstance(timestamp_str, str)
+                    else None
+                )
+                bucket = time_buckets[bucket_key] if bucket_key else None
+
+                if level == "ERROR":
+                    summary_stats["total_errors"] += 1
+                    if bucket:
+                        bucket["errors"] += 1
+                    if "error_type" in entry:
+                        summary_stats["error_types"][str(entry["error_type"])] += 1
+
+                    total_error_count += 1
+                    error_item = {
+                        "timestamp": timestamp_str,
+                        "message": entry.get("message", ""),
+                        "error_type": entry.get("error_type", "unknown"),
+                        "pathname": entry.get("pathname", ""),
+                        "lineno": entry.get("lineno", 0),
+                        "request_id": entry.get("request_id", ""),
+                    }
+                    if len(latest_errors_heap) < error_limit:
+                        heappush(latest_errors_heap, (timestamp_str, error_item))
+                    elif timestamp_str > latest_errors_heap[0][0]:
+                        heapreplace(latest_errors_heap, (timestamp_str, error_item))
+                elif level == "WARNING":
+                    summary_stats["total_warnings"] += 1
+                    if bucket:
+                        bucket["warnings"] += 1
+
+                completed, revenue_msats, input_tokens, output_tokens = (
+                    self._extract_success_metrics(entry, message)
+                )
+                if completed:
+                    summary_stats["total_requests"] += 1
+                    summary_stats["successful_chat_completions"] += 1
+                    summary_stats["input_tokens"] += input_tokens
+                    summary_stats["output_tokens"] += output_tokens
+                    summary_stats["total_tokens"] += input_tokens + output_tokens
+                    model_stats[model]["requests"] += 1
+                    model_stats[model]["successful"] += 1
+                    model_mix_totals[model] += 1
+                    if bucket:
+                        bucket["total_requests"] += 1
+                        bucket["successful_chat_completions"] += 1
+                        bucket["input_tokens"] += input_tokens
+                        bucket["output_tokens"] += output_tokens
+                        bucket["total_tokens"] += input_tokens + output_tokens
+                    if bucket_key:
+                        model_mix_buckets[bucket_key][model] += 1
+                        if revenue_msats > 0:
+                            model_mix_revenue_buckets[bucket_key][model] += revenue_msats
+                            model_mix_revenue_totals[model] += revenue_msats
+                        if input_tokens > 0 or output_tokens > 0:
+                            token_total = input_tokens + output_tokens
+                            model_mix_token_buckets[bucket_key][model] += token_total
+                            model_mix_token_totals[model] += token_total
+
+                    if revenue_msats > 0:
+                        summary_stats["revenue_msats"] += revenue_msats
+                        model_stats[model]["revenue_msats"] += revenue_msats
+                        if bucket:
+                            bucket["revenue_msats"] += revenue_msats
+
+                failed = (
+                    "upstream request failed" in message
+                    or "revert payment" in message
+                )
+                if failed:
+                    summary_stats["total_requests"] += 1
+                    summary_stats["failed_requests"] += 1
+                    model_stats[model]["requests"] += 1
+                    model_stats[model]["failed"] += 1
+                    if bucket:
+                        bucket["total_requests"] += 1
+                        bucket["failed_requests"] += 1
+
+                if "payment processed successfully" in message:
+                    summary_stats["payment_processed"] += 1
+                    if bucket:
+                        bucket["payment_processed"] += 1
+
+                if "upstream" in message and level == "ERROR":
+                    summary_stats["upstream_errors"] += 1
+                    if bucket:
+                        bucket["upstream_errors"] += 1
+
+                if model != "unknown":
+                    summary_stats["unique_models"].add(model)
+
+                if "revert payment" in message:
+                    max_cost = entry.get("max_cost_for_model", 0)
+                    if isinstance(max_cost, (int, float)) and max_cost > 0:
+                        max_cost_float = float(max_cost)
+                        summary_stats["refunds_msats"] += max_cost_float
+                        model_stats[model]["refunds_msats"] += max_cost_float
+                        if bucket:
+                            bucket["refunds_msats"] += max_cost_float
+            except Exception:
+                continue
+
+        metrics_result = []
+        for bucket_key in sorted(time_buckets.keys()):
+            bucket = dict(time_buckets[bucket_key])
+            bucket["requests"] = bucket["total_requests"]
+            metrics_result.append({"timestamp": bucket_key, **bucket})
+
+        models: list[dict[str, Any]] = []
+        total_revenue = 0.0
+        for model_name, stats in model_stats.items():
+            revenue_msats = float(stats["revenue_msats"])
+            refunds_msats = float(stats["refunds_msats"])
+            revenue_sats = revenue_msats / 1000
+            refunds_sats = refunds_msats / 1000
+            net_revenue_sats = revenue_sats - refunds_sats
+            total_revenue += net_revenue_sats
+
+            successful = int(stats["successful"])
+            models.append(
+                {
+                    "model": model_name,
+                    "revenue_sats": revenue_sats,
+                    "refunds_sats": refunds_sats,
+                    "net_revenue_sats": net_revenue_sats,
+                    "requests": int(stats["requests"]),
+                    "successful": successful,
+                    "failed": int(stats["failed"]),
+                    "avg_revenue_per_request": (
+                        revenue_sats / successful if successful > 0 else 0
+                    ),
+                }
+            )
+
+        models.sort(key=lambda x: float(x["net_revenue_sats"]), reverse=True)
+        latest_errors = [
+            item
+            for _, item in sorted(
+                latest_errors_heap, key=lambda x: x[0], reverse=True
+            )
+        ]
+        top_model_limit = max(1, min(model_limit, 20))
+        top_models_requests = [
+            model_name
+            for model_name, _ in sorted(
+                (
+                    (name, count)
+                    for name, count in model_mix_totals.items()
+                    if name != "unknown"
+                ),
+                key=lambda item: item[1],
+                reverse=True,
+            )[:top_model_limit]
+        ]
+        top_models_revenue = [
+            model_name
+            for model_name, _ in sorted(
+                (
+                    (name, amount)
+                    for name, amount in model_mix_revenue_totals.items()
+                    if name != "unknown"
+                ),
+                key=lambda item: item[1],
+                reverse=True,
+            )[:top_model_limit]
+        ]
+        top_models_tokens = [
+            model_name
+            for model_name, _ in sorted(
+                (
+                    (name, token_count)
+                    for name, token_count in model_mix_token_totals.items()
+                    if name != "unknown"
+                ),
+                key=lambda item: item[1],
+                reverse=True,
+            )[:top_model_limit]
+        ]
+        selected_models: list[str] = []
+        for model in top_models_requests + top_models_revenue + top_models_tokens:
+            if model not in selected_models:
+                selected_models.append(model)
+        top_model_set = set(selected_models)
+
+        model_usage_mix_metrics: list[dict[str, Any]] = []
+        mix_bucket_keys = sorted(
+            set(model_mix_buckets.keys())
+            | set(model_mix_revenue_buckets.keys())
+            | set(model_mix_token_buckets.keys())
+        )
+        for bucket_key in mix_bucket_keys:
+            counts = model_mix_buckets.get(bucket_key, {})
+            revenue_counts = model_mix_revenue_buckets.get(bucket_key, {})
+            token_counts = model_mix_token_buckets.get(bucket_key, {})
+            others = 0
+            others_revenue_msats = 0.0
+            others_tokens = 0
+            model_counts: dict[str, int] = {}
+            model_revenue_msats: dict[str, float] = {}
+            model_tokens: dict[str, int] = {}
+            for model_name, successful_count in counts.items():
+                if model_name in top_model_set:
+                    model_counts[model_name] = int(successful_count)
+                else:
+                    others += int(successful_count)
+            for model_name, revenue_value in revenue_counts.items():
+                if model_name in top_model_set:
+                    model_revenue_msats[model_name] = float(revenue_value)
+                else:
+                    others_revenue_msats += float(revenue_value)
+            for model_name, token_value in token_counts.items():
+                if model_name in top_model_set:
+                    model_tokens[model_name] = int(token_value)
+                else:
+                    others_tokens += int(token_value)
+
+            model_usage_mix_metrics.append(
+                {
+                    "timestamp": bucket_key,
+                    "total_successful": int(sum(counts.values())),
+                    "total_revenue_msats": float(sum(revenue_counts.values())),
+                    "total_tokens": int(sum(token_counts.values())),
+                    "others": others,
+                    "others_revenue_msats": others_revenue_msats,
+                    "others_tokens": others_tokens,
+                    "model_counts": model_counts,
+                    "model_revenue_msats": model_revenue_msats,
+                    "model_tokens": model_tokens,
+                }
+            )
+
+        return {
+            "metrics": {
+                "metrics": metrics_result,
+                "interval_minutes": interval_minutes,
+                "hours_back": hours_back,
+                "total_buckets": len(metrics_result),
+            },
+            "summary": self._build_summary_response(summary_stats),
+            "error_details": {
+                "errors": latest_errors,
+                "total_count": total_error_count,
+            },
+            "revenue_by_model": {
+                "models": models[:model_limit],
+                "total_revenue_sats": total_revenue,
+                "total_models": len(models),
+            },
+            "model_usage_mix": {
+                "top_models": top_models_requests,
+                "top_models_by_metric": {
+                    "requests": top_models_requests,
+                    "revenue": top_models_revenue,
+                    "tokens": top_models_tokens,
+                },
+                "metrics": model_usage_mix_metrics,
+                "interval_minutes": interval_minutes,
+                "hours_back": hours_back,
+                "total_buckets": len(model_usage_mix_metrics),
+            },
+        }
+
     def _aggregate_metrics_by_time(
         self, entries: list[dict], interval_minutes: int, hours_back: int
     ) -> dict:

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

@@ -12,13 +12,17 @@ from starlette.exceptions import HTTPException
 
 from ..auth import periodic_key_reset
 from ..balance import balance_router, deprecated_wallet_router
-from ..nostr import announce_provider, providers_cache_refresher
+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 ..upstream.auto_topup import periodic_auto_topup
-from ..wallet import periodic_payout
+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
@@ -32,9 +36,9 @@ setup_logging()
 logger = get_logger(__name__)
 
 if os.getenv("VERSION_SUFFIX") is not None:
-    __version__ = f"0.3.0-{os.getenv('VERSION_SUFFIX')}"
+    __version__ = f"0.4.3-{os.getenv('VERSION_SUFFIX')}"
 else:
-    __version__ = "0.3.0"
+    __version__ = "0.4.3"
 
 
 @asynccontextmanager
@@ -45,11 +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
@@ -96,17 +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
 
@@ -130,6 +143,8 @@ 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:
@@ -140,6 +155,10 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, 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 = []
@@ -151,6 +170,8 @@ 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:
@@ -161,6 +182,10 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, 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)
@@ -181,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

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

@@ -74,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")
@@ -92,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:
@@ -231,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"):
@@ -248,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"
@@ -271,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
 
@@ -305,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/nostr/__init__.py

@@ -1,4 +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"]
+__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/payment/cost_calculation.py

@@ -16,6 +16,8 @@ class CostData(BaseModel):
     output_msats: int
     total_msats: int
     total_usd: float = 0.0
+    input_tokens: int = 0
+    output_tokens: int = 0
 
 
 class MaxCostData(CostData):
@@ -63,17 +65,64 @@ async def calculate_cost(  # todo: can be sync
             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:
@@ -82,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={
@@ -99,11 +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(
@@ -116,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(
@@ -184,35 +250,14 @@ 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(
@@ -220,8 +265,8 @@ async def calculate_cost(  # todo: can be sync
         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"),
@@ -230,8 +275,10 @@ async def calculate_cost(  # todo: can be sync
 
     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/models.py

@@ -4,10 +4,11 @@ import random
 
 import httpx
 from fastapi import APIRouter, Depends
+from pydantic import BaseModel as V2BaseModel
 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 +61,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)
@@ -177,6 +179,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:
@@ -329,6 +332,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(
@@ -402,11 +406,89 @@ async def update_sats_pricing() -> None:
             logger.error(f"Error updating sats pricing: {e}")
 
 
+class ModelTestRequest(V2BaseModel):
+    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

@@ -44,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()
 
 
@@ -55,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()
 
 
@@ -69,7 +71,25 @@ 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) -> list[BaseUpstreamProvider] | None:
@@ -100,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:
@@ -115,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
@@ -122,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
@@ -207,7 +267,7 @@ async def proxy(
 
     elif auth := headers.get("authorization", None):
         key = await get_bearer_token_key(
-            headers, path, session, auth, max_cost_for_model
+            headers, path, session, auth, max_cost_for_model, model_id
         )
 
     else:
@@ -387,7 +447,12 @@ async def proxy(
 
 
 async def get_bearer_token_key(
-    headers: dict, path: str, session: AsyncSession, auth: str, min_cost: int = 0
+    headers: dict,
+    path: str,
+    session: AsyncSession,
+    auth: str,
+    min_cost: int = 0,
+    model_id: str = "unknown",
 ) -> ApiKey:
     """Handle bearer token authentication proxy requests."""
     parts = auth.split()
@@ -455,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/anthropic.py

@@ -13,6 +13,8 @@ class AnthropicUpstreamProvider(BaseUpstreamProvider):
     provider_type = "anthropic"
     default_base_url = "https://api.anthropic.com/v1"
     platform_url = "https://console.anthropic.com/settings/keys"
+    supports_anthropic_messages = True
+    litellm_provider_prefix = "anthropic/"
 
     def __init__(self, api_key: str, provider_fee: float = 1.01):
         super().__init__(

routstr/upstream/azure.py

@@ -13,6 +13,7 @@ class AzureUpstreamProvider(BaseUpstreamProvider):
     provider_type = "azure"
     default_base_url = None
     platform_url = "https://portal.azure.com/"
+    litellm_provider_prefix = "azure/"
 
     def __init__(
         self,

routstr/upstream/clients/gemini.py

@@ -26,14 +26,14 @@ class GeminiClient(BaseAPIClient):
         max_tokens: int | None = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
-        from openai import NOT_GIVEN
+        from openai import omit
 
         response = await self.client.chat.completions.create(
             model=model,
             messages=messages,  # type: ignore
-            temperature=temperature if temperature is not None else NOT_GIVEN,
-            max_tokens=max_tokens if max_tokens is not None else NOT_GIVEN,
-            top_p=kwargs.get("top_p", NOT_GIVEN),
+            temperature=temperature if temperature is not None else omit,
+            max_tokens=max_tokens if max_tokens is not None else omit,
+            top_p=kwargs.get("top_p", omit),
         )
         return response.model_dump()
 
@@ -45,7 +45,7 @@ class GeminiClient(BaseAPIClient):
         max_tokens: int | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[dict[str, Any], None]:
-        from openai import NOT_GIVEN
+        from openai import omit
 
         usage_callback = kwargs.get("usage_callback")
         completion_callback = kwargs.get("completion_callback")
@@ -55,9 +55,9 @@ class GeminiClient(BaseAPIClient):
             messages=messages,  # type: ignore
             stream=True,
             stream_options={"include_usage": True},
-            temperature=temperature if temperature is not None else NOT_GIVEN,
-            max_tokens=max_tokens if max_tokens is not None else NOT_GIVEN,
-            top_p=kwargs.get("top_p", NOT_GIVEN),
+            temperature=temperature if temperature is not None else omit,
+            max_tokens=max_tokens if max_tokens is not None else omit,
+            top_p=kwargs.get("top_p", omit),
         )
 
         final_usage = None

routstr/upstream/fireworks.py

@@ -12,6 +12,7 @@ class FireworksUpstreamProvider(BaseUpstreamProvider):
     provider_type = "fireworks"
     default_base_url = "https://api.fireworks.ai/inference/v1"
     platform_url = "https://app.fireworks.ai/settings/users/api-keys"
+    litellm_provider_prefix = "fireworks_ai/"
 
     def __init__(self, api_key: str, provider_fee: float = 1.01):
         super().__init__(

routstr/upstream/gemini.py

@@ -23,6 +23,7 @@ class GeminiUpstreamProvider(BaseUpstreamProvider):
     provider_type = "gemini"
     default_base_url = "https://generativelanguage.googleapis.com/v1beta"
     platform_url = "https://aistudio.google.com/app/apikey"
+    litellm_provider_prefix = "gemini/"
 
     def __init__(
         self,

routstr/upstream/groq.py

@@ -12,6 +12,7 @@ class GroqUpstreamProvider(BaseUpstreamProvider):
     provider_type = "groq"
     default_base_url = "https://api.groq.com/openai/v1"
     platform_url = "https://console.groq.com/keys"
+    litellm_provider_prefix = "groq/"
 
     def __init__(self, api_key: str, provider_fee: float = 1.01):
         super().__init__(

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:

routstr/upstream/ollama.py

@@ -21,6 +21,7 @@ class OllamaUpstreamProvider(BaseUpstreamProvider):
     provider_type = "ollama"
     default_base_url = "http://localhost:11434"
     platform_url = None
+    litellm_provider_prefix = "ollama_chat/"
 
     def __init__(
         self,
@@ -65,9 +66,7 @@ class OllamaUpstreamProvider(BaseUpstreamProvider):
         """Strip 'ollama/' prefix for Ollama API compatibility."""
         return model_id.removeprefix("ollama/")
 
-    def get_request_base_url(
-        self, path: str, model_obj: Model | None = None
-    ) -> str:
+    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"
 
@@ -166,103 +165,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/openrouter.py

@@ -15,6 +15,8 @@ class OpenRouterUpstreamProvider(BaseUpstreamProvider):
     provider_type = "openrouter"
     default_base_url = "https://openrouter.ai/api/v1"
     platform_url = "https://openrouter.ai/settings/keys"
+    supports_anthropic_messages = True
+    litellm_provider_prefix = "openrouter/"
 
     def __init__(self, api_key: str, provider_fee: float = 1.06):
         """Initialize OpenRouter provider with API key.

routstr/upstream/perplexity.py

@@ -13,6 +13,7 @@ class PerplexityUpstreamProvider(BaseUpstreamProvider):
     provider_type = "perplexity"
     default_base_url = "https://api.perplexity.ai/"
     platform_url = "https://www.perplexity.ai/account/api/keys"
+    litellm_provider_prefix = "perplexity/"
 
     def __init__(self, api_key: str, provider_fee: float = 1.01):
         super().__init__(

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.v1 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",

routstr/upstream/xai.py

@@ -13,6 +13,7 @@ class XAIUpstreamProvider(BaseUpstreamProvider):
     provider_type = "x-ai"
     default_base_url = "https://api.x.ai/v1"
     platform_url = "https://console.x.ai/"
+    litellm_provider_prefix = "xai/"
 
     def __init__(self, api_key: str, provider_fee: float = 1.01):
         super().__init__(

routstr/wallet.py

@@ -1,16 +1,32 @@
 import asyncio
-import math
+import time
+import typing
 from typing import TypedDict
 
 from cashu.core.base import Proof, Token
+from cashu.core.mint_info import MintInfo as _CashuMintInfo
 from cashu.wallet.helpers import deserialize_token_from_string
 from cashu.wallet.wallet import Wallet
-from sqlmodel import col, update
+from pydantic_core import PydanticUndefined
+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
 
+# cashu still declares Optional[X] without explicit defaults on MintInfo.
+# Under pydantic v2 those are required, but real mints omit many of them.
+# Default Optional fields to None at import time so balance fetches don't 422.
+for _name, _field in _CashuMintInfo.model_fields.items():
+    _annot = _field.annotation
+    _is_optional = typing.get_origin(_annot) is typing.Union and type(
+        None
+    ) in typing.get_args(_annot)
+    if _is_optional and _field.default is PydanticUndefined:
+        _field.default = None
+_CashuMintInfo.model_rebuild(force=True)
+
 logger = get_logger(__name__)
 
 
@@ -34,6 +50,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 +75,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 +169,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 +295,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 +328,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},
@@ -352,6 +549,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_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_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_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_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_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_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
@@ -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(
@@ -394,6 +458,42 @@ async def test_refund_during_active_usage(
     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
 @pytest.mark.asyncio
 async def test_mint_unavailability_handling(

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_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_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_messages_litellm_dispatch.py

@@ -0,0 +1,749 @@
+"""Unit tests for the litellm-based /v1/messages dispatch path.
+
+Covers `BaseUpstreamProvider._forward_messages_via_litellm` and the
+shortcut wired into `forward_request`.
+"""
+
+import json
+import os
+from typing import Any, AsyncIterator
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from fastapi.responses import Response, StreamingResponse
+
+os.environ.setdefault("UPSTREAM_BASE_URL", "http://test")
+os.environ.setdefault("UPSTREAM_API_KEY", "test")
+
+from routstr.core.db import ApiKey  # noqa: E402
+from routstr.payment.models import Architecture, Model, Pricing  # noqa: E402
+from routstr.upstream.base import BaseUpstreamProvider  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+def _make_provider(supports_messages: bool = False) -> BaseUpstreamProvider:
+    provider = BaseUpstreamProvider(base_url="http://test", api_key="upstream-key")
+    if supports_messages:
+        provider.supports_anthropic_messages = True
+    return provider
+
+
+def _make_key() -> ApiKey:
+    return ApiKey(hashed_key="abcdef0123" * 4, balance=1_000_000)
+
+
+def _make_model(model_id: str = "openai/gpt-4o-mini") -> Model:
+    return Model(
+        id=model_id,
+        name=model_id,
+        forwarded_model_id=model_id,
+        created=0,
+        description="",
+        context_length=8192,
+        architecture=Architecture(
+            modality="text",
+            input_modalities=["text"],
+            output_modalities=["text"],
+            tokenizer="x",
+            instruct_type=None,
+        ),
+        pricing=Pricing(
+            prompt=0.0,
+            completion=0.0,
+            request=0.0,
+            image=0.0,
+            web_search=0.0,
+            internal_reasoning=0.0,
+            max_cost=0.0,
+        ),
+        sats_pricing=None,
+        per_request_limits=None,
+        top_provider=None,
+    )
+
+
+def _make_session() -> Any:
+    return MagicMock()
+
+
+def _anthropic_request_body(*, stream: bool = False) -> bytes:
+    return json.dumps(
+        {
+            "model": "openai/gpt-4o-mini",
+            "messages": [{"role": "user", "content": "hi"}],
+            "max_tokens": 64,
+            "stream": stream,
+        }
+    ).encode()
+
+
+def _anthropic_non_stream_response() -> dict:
+    return {
+        "id": "msg_123",
+        "type": "message",
+        "role": "assistant",
+        "model": "openai/gpt-4o-mini",
+        "content": [{"type": "text", "text": "hello!"}],
+        "stop_reason": "end_turn",
+        "stop_sequence": None,
+        "usage": {"input_tokens": 5, "output_tokens": 3},
+    }
+
+
+# ---------------------------------------------------------------------------
+# Helper / coercion
+# ---------------------------------------------------------------------------
+
+
+def test_coerce_litellm_payload_handles_dict() -> None:
+    out = BaseUpstreamProvider._coerce_litellm_payload({"a": 1})
+    assert out == {"a": 1}
+
+
+def test_coerce_litellm_payload_handles_pydantic_v2() -> None:
+    obj = MagicMock()
+    obj.model_dump.return_value = {"x": 42}
+    # ensure dict() isn't preferred over model_dump
+    out = BaseUpstreamProvider._coerce_litellm_payload(obj)
+    assert out == {"x": 42}
+
+
+def test_parse_sse_blocks_extracts_full_events() -> None:
+    buffer = (
+        b"event: message_start\n"
+        b'data: {"type":"message_start","message":{"id":"m1"}}\n\n'
+        b"event: message_stop\n"
+        b'data: {"type":"message_stop"}\n\n'
+    )
+    events, remaining = BaseUpstreamProvider._parse_sse_blocks(buffer)
+    assert remaining == b""
+    assert events == [
+        {"type": "message_start", "message": {"id": "m1"}},
+        {"type": "message_stop"},
+    ]
+
+
+def test_parse_sse_blocks_preserves_partial_trailing_block() -> None:
+    buffer = b'data: {"type":"a"}\n\nevent: b\ndata: {"type":"b"}'
+    events, remaining = BaseUpstreamProvider._parse_sse_blocks(buffer)
+    assert events == [{"type": "a"}]
+    assert remaining == b'event: b\ndata: {"type":"b"}'
+
+
+def test_parse_sse_blocks_skips_done_and_comments() -> None:
+    buffer = b": ping\n\ndata: [DONE]\n\ndata: {\"type\":\"x\"}\n\n"
+    events, remaining = BaseUpstreamProvider._parse_sse_blocks(buffer)
+    assert remaining == b""
+    assert events == [{"type": "x"}]
+
+
+def test_events_from_chunk_handles_bytes_chunks() -> None:
+    provider = _make_provider()
+    chunk = (
+        b"event: a\ndata: {\"type\":\"a\"}\n\n"
+        b"event: b\ndata: {\"type\":\"b\"}"
+    )
+    events, buf = provider._events_from_chunk(chunk, b"")
+    assert events == [{"type": "a"}]
+    # second event still partial because no trailing \n\n
+    assert buf == b'event: b\ndata: {"type":"b"}'
+
+    # Feed remainder of the second event
+    events, buf = provider._events_from_chunk(b"\n\n", buf)
+    assert events == [{"type": "b"}]
+    assert buf == b""
+
+
+def test_events_from_chunk_handles_str_chunks() -> None:
+    provider = _make_provider()
+    events, buf = provider._events_from_chunk(
+        'event: a\ndata: {"type":"a"}\n\n', b""
+    )
+    assert events == [{"type": "a"}]
+    assert buf == b""
+
+
+# ---------------------------------------------------------------------------
+# Pydantic serializer warning + usage normalization
+# ---------------------------------------------------------------------------
+
+
+def test_coerce_litellm_payload_silences_pydantic_serializer_warning() -> None:
+    """litellm response models emit a benign UserWarning when their nested
+    pydantic field (e.g. usage = ResponseAPIUsage) holds a plain dict.
+    _coerce_litellm_payload must silence it locally."""
+    import warnings as _warnings
+
+    obj = MagicMock()
+
+    def _emit_warning(*args: Any, **kwargs: Any) -> dict:
+        _warnings.warn(
+            "Pydantic serializer warnings:\n  Expected `ResponseAPIUsage`",
+            UserWarning,
+            stacklevel=2,
+        )
+        return {"id": "x", "usage": {"completion_tokens": 5}}
+
+    obj.model_dump.side_effect = _emit_warning
+
+    with _warnings.catch_warnings(record=True) as caught:
+        _warnings.simplefilter("always")
+        out = BaseUpstreamProvider._coerce_litellm_payload(obj)
+
+    assert out == {"id": "x", "usage": {"completion_tokens": 5}}
+    serializer_warnings = [
+        w for w in caught if "Pydantic serializer warnings" in str(w.message)
+    ]
+    assert serializer_warnings == [], (
+        "Pydantic serializer warning should be suppressed at source"
+    )
+
+
+def test_normalize_litellm_payload_maps_openai_keys_to_anthropic() -> None:
+    event = {
+        "type": "message_delta",
+        "usage": {
+            "prompt_tokens": 11,
+            "completion_tokens": 22,
+            "total_tokens": 33,
+        },
+        "message": {
+            "model": "x",
+            "usage": {"prompt_tokens": 7, "completion_tokens": 13},
+        },
+    }
+    out = BaseUpstreamProvider._normalize_litellm_payload(event)
+
+    # Top-level usage gets canonical Anthropic keys mirrored in
+    assert out["usage"]["input_tokens"] == 11
+    assert out["usage"]["output_tokens"] == 22
+    # Original keys preserved (non-destructive)
+    assert out["usage"]["prompt_tokens"] == 11
+    assert out["usage"]["completion_tokens"] == 22
+
+    # Nested message.usage normalized too
+    assert out["message"]["usage"]["input_tokens"] == 7
+    assert out["message"]["usage"]["output_tokens"] == 13
+
+    # Original event must not be mutated
+    assert "input_tokens" not in event["usage"]
+
+
+def test_normalize_litellm_payload_keeps_anthropic_keys_intact() -> None:
+    event = {
+        "type": "message_delta",
+        "usage": {"input_tokens": 4, "output_tokens": 9},
+    }
+    out = BaseUpstreamProvider._normalize_litellm_payload(event)
+    assert out["usage"] == {"input_tokens": 4, "output_tokens": 9}
+
+
+def test_normalize_litellm_payload_aliases_dumped_usage() -> None:
+    """A litellm result whose model_dump emits OpenAI-style usage keys
+    should be normalized to Anthropic-style keys for downstream cost
+    reconciliation, with the original keys preserved alongside."""
+    result = MagicMock()
+    result.model_dump.return_value = {
+        "id": "abc",
+        "model": "openai/gpt-4o-mini",
+        "usage": {"prompt_tokens": 12, "completion_tokens": 34},
+    }
+
+    out = BaseUpstreamProvider._normalize_litellm_payload(result)
+
+    assert out["model"] == "openai/gpt-4o-mini"
+    assert out["usage"]["input_tokens"] == 12
+    assert out["usage"]["output_tokens"] == 34
+    # OpenAI keys preserved alongside the canonical mapping
+    assert out["usage"]["prompt_tokens"] == 12
+
+
+# ---------------------------------------------------------------------------
+# Provider gating
+# ---------------------------------------------------------------------------
+
+
+def test_default_provider_does_not_support_anthropic_messages() -> None:
+    assert BaseUpstreamProvider.supports_anthropic_messages is False
+    assert BaseUpstreamProvider.litellm_provider_prefix == "openai/"
+
+
+def test_anthropic_provider_supports_native_messages() -> None:
+    from routstr.upstream.anthropic import AnthropicUpstreamProvider
+
+    assert AnthropicUpstreamProvider.supports_anthropic_messages is True
+
+
+def test_openrouter_provider_supports_native_messages() -> None:
+    from routstr.upstream.openrouter import OpenRouterUpstreamProvider
+
+    assert OpenRouterUpstreamProvider.supports_anthropic_messages is True
+
+
+def test_provider_prefix_overrides() -> None:
+    from routstr.upstream.azure import AzureUpstreamProvider
+    from routstr.upstream.fireworks import FireworksUpstreamProvider
+    from routstr.upstream.gemini import GeminiUpstreamProvider
+    from routstr.upstream.groq import GroqUpstreamProvider
+    from routstr.upstream.ollama import OllamaUpstreamProvider
+    from routstr.upstream.perplexity import PerplexityUpstreamProvider
+    from routstr.upstream.xai import XAIUpstreamProvider
+
+    assert GroqUpstreamProvider.litellm_provider_prefix == "groq/"
+    assert XAIUpstreamProvider.litellm_provider_prefix == "xai/"
+    assert FireworksUpstreamProvider.litellm_provider_prefix == "fireworks_ai/"
+    assert PerplexityUpstreamProvider.litellm_provider_prefix == "perplexity/"
+    assert GeminiUpstreamProvider.litellm_provider_prefix == "gemini/"
+    assert OllamaUpstreamProvider.litellm_provider_prefix == "ollama_chat/"
+    assert AzureUpstreamProvider.litellm_provider_prefix == "azure/"
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_non_streaming_dispatches_via_litellm_and_returns_anthropic_response() -> (
+    None
+):
+    provider = _make_provider()
+    key = _make_key()
+    model = _make_model()
+    session = _make_session()
+    body = _anthropic_request_body(stream=False)
+
+    upstream_response = _anthropic_non_stream_response()
+
+    async def fake_acreate(**kwargs: Any) -> dict:
+        # Verify model prefixing and credentials are forwarded correctly
+        assert kwargs["model"] == "openai/openai/gpt-4o-mini"
+        assert kwargs["api_base"] == "http://test"
+        assert kwargs["api_key"] == "upstream-key"
+        assert kwargs["stream"] is False
+        assert kwargs["messages"] == [{"role": "user", "content": "hi"}]
+        assert kwargs["max_tokens"] == 64
+        return upstream_response
+
+    fake_cost = {"total_msats": 1234, "total_usd": 0.0001}
+
+    with (
+        patch(
+            "litellm.anthropic.messages.acreate",
+            new=AsyncMock(side_effect=fake_acreate),
+        ),
+        patch(
+            "routstr.upstream.base.adjust_payment_for_tokens",
+            new=AsyncMock(return_value=fake_cost),
+        ),
+    ):
+        result = await provider._forward_messages_via_litellm(
+            request_body=body,
+            key=key,
+            session=session,
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+
+    assert isinstance(result, Response)
+    payload = json.loads(result.body)
+    assert payload["model"] == "openai/gpt-4o-mini"  # mapped back to requested
+    assert payload["usage"]["input_tokens"] == 5
+    assert payload["usage"]["output_tokens"] == 3
+    # Cost metadata injected
+    assert payload["usage"]["cost"] == 0.0001
+    assert payload["usage"]["cost_sats"] == 1
+
+
+# ---------------------------------------------------------------------------
+# Streaming
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_streaming_emits_sse_and_reconciles_cost_at_end() -> None:
+    provider = _make_provider()
+    key = _make_key()
+    model = _make_model()
+    session = _make_session()
+    body = _anthropic_request_body(stream=True)
+
+    async def fake_chunks() -> AsyncIterator[dict]:
+        yield {
+            "type": "message_start",
+            "message": {
+                "id": "msg_1",
+                "type": "message",
+                "role": "assistant",
+                "model": "openai/gpt-4o-mini",
+                "content": [],
+                "usage": {"input_tokens": 5, "output_tokens": 0},
+            },
+        }
+        yield {
+            "type": "content_block_start",
+            "index": 0,
+            "content_block": {"type": "text", "text": ""},
+        }
+        yield {
+            "type": "content_block_delta",
+            "index": 0,
+            "delta": {"type": "text_delta", "text": "hi"},
+        }
+        yield {"type": "content_block_stop", "index": 0}
+        yield {
+            "type": "message_delta",
+            "delta": {"stop_reason": "end_turn"},
+            "usage": {"output_tokens": 7},
+        }
+        yield {"type": "message_stop"}
+
+    fake_cost = {"total_msats": 4321, "total_usd": 0.00015}
+
+    captured_cost_call: dict[str, Any] = {}
+
+    async def fake_adjust(
+        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int
+    ) -> dict:
+        captured_cost_call["combined_data"] = combined_data
+        captured_cost_call["max_cost"] = max_cost
+        return fake_cost
+
+    fake_session = MagicMock()
+
+    class FakeSessionCtx:
+        async def __aenter__(self) -> Any:
+            return fake_session
+
+        async def __aexit__(self, *args: Any) -> None:
+            return None
+
+    fake_session.get = AsyncMock(return_value=key)
+
+    with (
+        patch(
+            "litellm.anthropic.messages.acreate",
+            new=AsyncMock(return_value=fake_chunks()),
+        ),
+        patch(
+            "routstr.upstream.base.adjust_payment_for_tokens",
+            new=AsyncMock(side_effect=fake_adjust),
+        ),
+        patch(
+            "routstr.upstream.base.create_session",
+            new=lambda: FakeSessionCtx(),
+        ),
+    ):
+        result = await provider._forward_messages_via_litellm(
+            request_body=body,
+            key=key,
+            session=session,
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+
+        assert isinstance(result, StreamingResponse)
+        emitted: list[bytes] = []
+        async for chunk in result.body_iterator:
+            if isinstance(chunk, bytes):
+                emitted.append(chunk)
+            elif isinstance(chunk, memoryview):
+                emitted.append(bytes(chunk))
+            else:
+                emitted.append(chunk.encode())
+
+    joined = b"".join(emitted).decode()
+    # SSE event header for the first chunk
+    assert "event: message_start" in joined
+    assert "event: content_block_delta" in joined
+    assert "event: message_delta" in joined
+    assert "event: cost" in joined
+
+    # Usage was extracted from message_start (input) and message_delta (output)
+    combined = captured_cost_call["combined_data"]
+    assert combined["usage"]["input_tokens"] == 5
+    assert combined["usage"]["output_tokens"] == 7
+    assert combined["model"] == "openai/gpt-4o-mini"
+
+
+@pytest.mark.asyncio
+async def test_streaming_handles_iterator_yielding_raw_sse_bytes() -> None:
+    """Regression: litellm sometimes yields already-SSE-encoded bytes.
+
+    Previously this raised TypeError("Cannot coerce bytes to dict"). The
+    stream loop must parse SSE blocks (even split across chunks) and still
+    perform cost reconciliation.
+    """
+    provider = _make_provider()
+    key = _make_key()
+    model = _make_model()
+    session = _make_session()
+    body = _anthropic_request_body(stream=True)
+
+    async def fake_byte_chunks() -> AsyncIterator[bytes]:
+        # Whole event in one chunk
+        yield (
+            b"event: message_start\n"
+            b'data: {"type":"message_start","message":{"id":"m1",'
+            b'"model":"openai/gpt-4o-mini",'
+            b'"usage":{"input_tokens":3,"output_tokens":0}}}\n\n'
+        )
+        # Event split across two chunks (boundary inside the data line)
+        yield b'event: message_delta\ndata: {"type":"message_delta",'
+        yield b'"delta":{},"usage":{"output_tokens":4}}\n\n'
+        # SSE comment + DONE sentinel must be ignored
+        yield b": keepalive\n\ndata: [DONE]\n\n"
+        yield b"event: message_stop\ndata: {\"type\":\"message_stop\"}\n\n"
+
+    fake_cost = {"total_msats": 999, "total_usd": 0.0001}
+    captured: dict[str, Any] = {}
+
+    async def fake_adjust(
+        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int
+    ) -> dict:
+        captured["combined_data"] = combined_data
+        return fake_cost
+
+    fake_session = MagicMock()
+    fake_session.get = AsyncMock(return_value=key)
+
+    class FakeSessionCtx:
+        async def __aenter__(self) -> Any:
+            return fake_session
+
+        async def __aexit__(self, *args: Any) -> None:
+            return None
+
+    with (
+        patch(
+            "litellm.anthropic.messages.acreate",
+            new=AsyncMock(return_value=fake_byte_chunks()),
+        ),
+        patch(
+            "routstr.upstream.base.adjust_payment_for_tokens",
+            new=AsyncMock(side_effect=fake_adjust),
+        ),
+        patch(
+            "routstr.upstream.base.create_session",
+            new=lambda: FakeSessionCtx(),
+        ),
+    ):
+        result = await provider._forward_messages_via_litellm(
+            request_body=body,
+            key=key,
+            session=session,
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+
+        assert isinstance(result, StreamingResponse)
+        emitted: list[bytes] = []
+        async for chunk in result.body_iterator:
+            if isinstance(chunk, bytes):
+                emitted.append(chunk)
+            elif isinstance(chunk, memoryview):
+                emitted.append(bytes(chunk))
+            else:
+                emitted.append(chunk.encode())
+
+    joined = b"".join(emitted).decode()
+    assert "event: message_start" in joined
+    assert "event: message_delta" in joined
+    assert "event: message_stop" in joined
+    assert "event: cost" in joined
+    # [DONE] sentinel and SSE comments must NOT be re-emitted as data
+    assert "[DONE]" not in joined
+
+    combined = captured["combined_data"]
+    assert combined["usage"]["input_tokens"] == 3
+    assert combined["usage"]["output_tokens"] == 4
+    assert combined["model"] == "openai/gpt-4o-mini"
+
+
+@pytest.mark.asyncio
+async def test_streaming_normalizes_openai_usage_keys_for_cost() -> None:
+    """Regression: when litellm yields chunks with OpenAI-style usage keys
+    (prompt_tokens/completion_tokens), the stream loop must map them to
+    Anthropic input_tokens/output_tokens for cost reconciliation."""
+    provider = _make_provider()
+    key = _make_key()
+    model = _make_model()
+    session = _make_session()
+    body = _anthropic_request_body(stream=True)
+
+    async def fake_chunks() -> AsyncIterator[dict]:
+        yield {
+            "type": "message_start",
+            "message": {
+                "id": "msg_1",
+                "type": "message",
+                "role": "assistant",
+                "model": "openai/gpt-4o-mini",
+                "content": [],
+                # OpenAI-style usage on the message
+                "usage": {"prompt_tokens": 9, "completion_tokens": 0},
+            },
+        }
+        yield {
+            "type": "content_block_delta",
+            "index": 0,
+            "delta": {"type": "text_delta", "text": "hi"},
+        }
+        yield {
+            "type": "message_delta",
+            "delta": {"stop_reason": "end_turn"},
+            # OpenAI-style usage on the delta
+            "usage": {"prompt_tokens": 0, "completion_tokens": 17},
+        }
+        yield {"type": "message_stop"}
+
+    fake_cost = {"total_msats": 100, "total_usd": 0.0001}
+    captured: dict[str, Any] = {}
+
+    async def fake_adjust(
+        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int
+    ) -> dict:
+        captured["combined_data"] = combined_data
+        return fake_cost
+
+    fake_session = MagicMock()
+    fake_session.get = AsyncMock(return_value=key)
+
+    class FakeSessionCtx:
+        async def __aenter__(self) -> Any:
+            return fake_session
+
+        async def __aexit__(self, *args: Any) -> None:
+            return None
+
+    with (
+        patch(
+            "litellm.anthropic.messages.acreate",
+            new=AsyncMock(return_value=fake_chunks()),
+        ),
+        patch(
+            "routstr.upstream.base.adjust_payment_for_tokens",
+            new=AsyncMock(side_effect=fake_adjust),
+        ),
+        patch(
+            "routstr.upstream.base.create_session",
+            new=lambda: FakeSessionCtx(),
+        ),
+    ):
+        result = await provider._forward_messages_via_litellm(
+            request_body=body,
+            key=key,
+            session=session,
+            max_cost_for_model=10_000,
+            model_obj=model,
+        )
+        assert isinstance(result, StreamingResponse)
+        async for _ in result.body_iterator:
+            pass
+
+    combined = captured["combined_data"]
+    # Token counts come from the OpenAI-style fields after normalization
+    assert combined["usage"]["input_tokens"] == 9
+    assert combined["usage"]["output_tokens"] == 17
+
+
+# ---------------------------------------------------------------------------
+# forward_request gating
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_forward_request_routes_messages_via_litellm() -> None:
+    provider = _make_provider()
+    key = _make_key()
+    model = _make_model()
+    session = _make_session()
+    request = MagicMock()
+
+    sentinel = Response(content=b'{"ok": true}', media_type="application/json")
+    with patch.object(
+        provider,
+        "_forward_messages_via_litellm",
+        new=AsyncMock(return_value=sentinel),
+    ) as mock_helper:
+        result = await provider.forward_request(
+            request=request,
+            path="messages",
+            headers={},
+            request_body=_anthropic_request_body(),
+            key=key,
+            max_cost_for_model=10_000,
+            session=session,
+            model_obj=model,
+        )
+
+    mock_helper.assert_awaited_once()
+    assert result is sentinel
+
+
+@pytest.mark.asyncio
+async def test_forward_request_skips_litellm_when_provider_supports_messages() -> None:
+    provider = _make_provider(supports_messages=True)
+    key = _make_key()
+    model = _make_model()
+    session = _make_session()
+    request = MagicMock()
+
+    with patch.object(
+        provider,
+        "_forward_messages_via_litellm",
+        new=AsyncMock(side_effect=AssertionError("should not be called")),
+    ):
+        # The non-litellm path will try to build a URL and call httpx, so we
+        # short-circuit by patching prepare_request_body to raise — we only
+        # care that the litellm helper was NOT invoked.
+        with patch.object(
+            provider,
+            "prepare_request_body",
+            side_effect=RuntimeError("stop here"),
+        ):
+            with pytest.raises(RuntimeError, match="stop here"):
+                await provider.forward_request(
+                    request=request,
+                    path="messages",
+                    headers={},
+                    request_body=_anthropic_request_body(),
+                    key=key,
+                    max_cost_for_model=10_000,
+                    session=session,
+                    model_obj=model,
+                )
+
+
+@pytest.mark.asyncio
+async def test_forward_request_skips_litellm_for_count_tokens() -> None:
+    provider = _make_provider()
+    key = _make_key()
+    model = _make_model()
+    session = _make_session()
+    request = MagicMock()
+
+    with patch.object(
+        provider,
+        "_forward_messages_via_litellm",
+        new=AsyncMock(side_effect=AssertionError("should not be called")),
+    ):
+        with patch.object(
+            provider,
+            "prepare_request_body",
+            side_effect=RuntimeError("stop here"),
+        ):
+            with pytest.raises(RuntimeError, match="stop here"):
+                await provider.forward_request(
+                    request=request,
+                    path="messages/count_tokens",
+                    headers={},
+                    request_body=_anthropic_request_body(),
+                    key=key,
+                    max_cost_for_model=10_000,
+                    session=session,
+                    model_obj=model,
+                )

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_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/app/model/page.tsx

@@ -0,0 +1,5 @@
+import { ModelsPage } from '@/components/models-page';
+
+export default function ModelPage() {
+  return <ModelsPage />;
+}

ui/app/page.tsx

@@ -9,6 +9,7 @@ import type { DateRange } from 'react-day-picker';
 import { UsageMetricsChart } from '@/components/usage-metrics-chart';
 import { UsageSummaryCards } from '@/components/usage-summary-cards';
 import { ErrorDetailsTable } from '@/components/error-details-table';
+import { TopModelsUsageChart } from '@/components/top-models-usage-chart';
 import { DashboardBalanceSummary } from '@/components/dashboard-balance-summary';
 import {
   AdminService,
@@ -79,6 +80,7 @@ const TIME_RANGE_PRESETS = [
   { value: '3m', label: 'Last 3 Months', hours: 90 * 24 },
   { value: '12m', label: 'Last 12 Months', hours: 365 * 24 },
 ] as const;
+const MAX_USAGE_RANGE_HOURS = 365 * 24;
 
 type TimeRangePresetValue = (typeof TIME_RANGE_PRESETS)[number]['value'];
 
@@ -159,20 +161,6 @@ function getAutoIntervalMinutes(hours: number): number {
   );
 }
 
-function getQueryErrorMessage(error: unknown): string {
-  if (
-    error &&
-    typeof error === 'object' &&
-    'message' in error &&
-    typeof error.message === 'string' &&
-    error.message.trim().length > 0
-  ) {
-    return error.message;
-  }
-
-  return 'The analytics request failed. Refresh and try again.';
-}
-
 function SectionLoading({ label }: { label: string }) {
   if (label === 'summary') {
     return (
@@ -461,7 +449,7 @@ function DashboardInsights({
                   cursor={false}
                   content={
                     <ChartTooltipContent
-                      labelFormatter={(_, payload) =>
+                      labelFormatter={(_: React.ReactNode, payload) =>
                         String(payload?.[0]?.payload?.type ?? '')
                       }
                       formatter={(value, name) => {
@@ -554,19 +542,21 @@ export default function DashboardPage() {
     isCustomRangeActive && customRangeHours
       ? customRangeHours
       : activePreset.hours;
-  const autoInterval = getAutoIntervalMinutes(queryHours);
+  const safeQueryHours = Math.min(queryHours, MAX_USAGE_RANGE_HOURS);
+  const isUsageRangeCapped = safeQueryHours < queryHours;
+  const autoInterval = getAutoIntervalMinutes(safeQueryHours);
   const usageRefetchIntervalMs = useMemo(() => {
-    if (queryHours > 90 * 24) {
+    if (safeQueryHours > 90 * 24) {
       return 4 * 60 * 60_000;
     }
-    if (queryHours > 30 * 24) {
+    if (safeQueryHours > 30 * 24) {
       return 2 * 60 * 60_000;
     }
-    if (queryHours > 7 * 24) {
+    if (safeQueryHours > 7 * 24) {
       return 30 * 60_000;
     }
     return 60_000;
-  }, [queryHours]);
+  }, [safeQueryHours]);
   const revenueDisplayUnit: DisplayUnit = useMemo(() => {
     if (displayUnit === 'usd' && usdPerSat === null) {
       // Keep revenue charts meaningful while the USD rate is unavailable.
@@ -584,43 +574,30 @@ export default function DashboardPage() {
           : revenueDisplayUnit;
 
   const {
-    data: metricsData,
-    isLoading: metricsLoading,
-    error: metricsError,
-    refetch: refetchMetrics,
+    data: usageDashboardData,
+    isLoading: usageDashboardLoading,
+    refetch: refetchUsageDashboard,
   } = useQuery({
-    queryKey: ['usage-metrics', autoInterval, queryHours],
-    queryFn: () => AdminService.getUsageMetrics(autoInterval, queryHours),
+    queryKey: ['usage-dashboard', autoInterval, safeQueryHours],
+    queryFn: () =>
+      AdminService.getUsageDashboard(safeQueryHours, autoInterval, 100, 20),
     enabled: isAuthenticated,
     refetchInterval: usageRefetchIntervalMs,
     staleTime: 30_000,
   });
 
-  const {
-    data: summaryData,
-    isLoading: summaryLoading,
-    error: summaryError,
-    refetch: refetchSummary,
-  } = useQuery({
-    queryKey: ['usage-summary', queryHours],
-    queryFn: () => AdminService.getUsageSummary(queryHours),
-    enabled: isAuthenticated,
-    refetchInterval: usageRefetchIntervalMs,
-    staleTime: 30_000,
-  });
+  const metricsData = usageDashboardData?.metrics;
+  const summaryData = usageDashboardData?.summary;
+  const errorData = usageDashboardData?.error_details;
+  const modelUsageMixData = usageDashboardData?.model_usage_mix;
+  const hasModelUsageMixMetrics =
+    Array.isArray(modelUsageMixData?.metrics) &&
+    modelUsageMixData.metrics.length > 0;
 
-  const {
-    data: errorData,
-    isLoading: errorLoading,
-    error: errorDetailsError,
-    refetch: refetchErrors,
-  } = useQuery({
-    queryKey: ['usage-errors', queryHours],
-    queryFn: () => AdminService.getErrorDetails(queryHours, 100),
-    enabled: isAuthenticated,
-    refetchInterval: usageRefetchIntervalMs,
-    staleTime: 30_000,
-  });
+  const metricsLoading = usageDashboardLoading;
+  const summaryLoading = usageDashboardLoading;
+  const errorLoading = usageDashboardLoading;
+  const metricsTotals = metricsData?.totals;
 
   const chartConfigs = useMemo<ChartConfig[]>(() => {
     if (!metricsData || metricsData.metrics.length === 0) {
@@ -647,12 +624,6 @@ export default function DashboardPage() {
       })
     ) as ChartDatum[];
 
-    const hasTokenMetrics = metricPoints.some((metric) =>
-      ['input_tokens', 'output_tokens', 'total_tokens'].some(
-        (key) => typeof metric[key] === 'number'
-      )
-    );
-
     return [
       {
         id: 'revenue',
@@ -661,6 +632,11 @@ export default function DashboardPage() {
         description: 'Track collected revenue trends over time.',
         data: revenuePoints,
         metricType: 'currency',
+        totals: metricsTotals
+          ? {
+              revenue_display: convertRevenueMsats(metricsTotals.revenue_msats),
+            }
+          : undefined,
         dataKeys: [
           {
             key: 'revenue_display',
@@ -676,6 +652,14 @@ export default function DashboardPage() {
         description: 'Understand traffic and completion reliability over time.',
         data: metricPoints,
         metricType: 'count',
+        totals: metricsTotals
+          ? {
+              total_requests: metricsTotals.total_requests,
+              successful_chat_completions:
+                metricsTotals.successful_chat_completions,
+              failed_requests: metricsTotals.failed_requests,
+            }
+          : undefined,
         dataKeys: [
           {
             key: 'total_requests',
@@ -701,6 +685,13 @@ export default function DashboardPage() {
         description: 'Monitor warnings, handled errors, and upstream failures.',
         data: metricPoints,
         metricType: 'count',
+        totals: metricsTotals
+          ? {
+              errors: metricsTotals.errors,
+              warnings: metricsTotals.warnings,
+              upstream_errors: metricsTotals.upstream_errors,
+            }
+          : undefined,
         dataKeys: [
           {
             key: 'errors',
@@ -726,6 +717,11 @@ export default function DashboardPage() {
         description: 'Follow payment processing activity by interval.',
         data: metricPoints,
         metricType: 'count',
+        totals: metricsTotals
+          ? {
+              payment_processed: metricsTotals.payment_processed,
+            }
+          : undefined,
         dataKeys: [
           {
             key: 'payment_processed',
@@ -734,38 +730,41 @@ export default function DashboardPage() {
           },
         ],
       },
-      ...(hasTokenMetrics
-        ? [
-            {
-              id: 'tokens',
-              title: 'Token Usage',
-              mobileTitle: 'Tokens',
-              description:
-                'Track input, output, and total token throughput over time.',
-              data: metricPoints,
-              metricType: 'count' as const,
-              dataKeys: [
-                {
-                  key: 'total_tokens',
-                  name: 'Total Tokens',
-                  color: 'var(--chart-1)',
-                },
-                {
-                  key: 'input_tokens',
-                  name: 'Input Tokens',
-                  color: 'var(--chart-2)',
-                },
-                {
-                  key: 'output_tokens',
-                  name: 'Output Tokens',
-                  color: 'var(--chart-3)',
-                },
-              ],
-            },
-          ]
-        : []),
+      {
+        id: 'tokens',
+        title: 'Token Usage',
+        mobileTitle: 'Tokens',
+        description:
+          'Track input, output, and total token throughput over time.',
+        data: metricPoints,
+        metricType: 'count',
+        totals: metricsTotals
+          ? {
+              input_tokens: metricsTotals.input_tokens,
+              output_tokens: metricsTotals.output_tokens,
+              total_tokens: metricsTotals.total_tokens,
+            }
+          : undefined,
+        dataKeys: [
+          {
+            key: 'total_tokens',
+            name: 'Total Tokens',
+            color: 'var(--chart-1)',
+          },
+          {
+            key: 'input_tokens',
+            name: 'Input Tokens',
+            color: 'var(--chart-2)',
+          },
+          {
+            key: 'output_tokens',
+            name: 'Output Tokens',
+            color: 'var(--chart-3)',
+          },
+        ],
+      },
     ];
-  }, [metricsData, revenueDisplayUnit, usdPerSat]);
+  }, [metricsData, metricsTotals, revenueDisplayUnit, usdPerSat]);
 
   useEffect(() => {
     if (chartConfigs.length === 0) {
@@ -803,11 +802,7 @@ export default function DashboardPage() {
 
     setIsManualRefreshing(true);
     try {
-      await Promise.allSettled([
-        refetchMetrics(),
-        refetchSummary(),
-        refetchErrors(),
-      ]);
+      await refetchUsageDashboard();
     } finally {
       setIsManualRefreshing(false);
     }
@@ -913,10 +908,16 @@ export default function DashboardPage() {
               All cards and charts in this section update from the selected
               range.
             </p>
+            {isUsageRangeCapped ? (
+              <p className='text-muted-foreground text-[11px] sm:text-xs'>
+                Usage analytics are capped to the last{' '}
+                {MAX_USAGE_RANGE_HOURS / 24} days for server safety.
+              </p>
+            ) : null}
           </div>
 
-          <div className='flex items-center gap-2'>
-            <div className='min-w-0 flex-1 sm:max-w-[22rem]'>
+          <div className='flex flex-col gap-2 sm:flex-row sm:items-center'>
+            <div className='w-full max-w-[20rem] sm:max-w-[22rem]'>
               <div className='border-input bg-card/30 dark:bg-input/30 flex h-8 w-full min-w-0 items-stretch overflow-hidden rounded-lg border sm:h-9'>
                 <Popover
                   open={isCustomRangePickerOpen}
@@ -981,39 +982,20 @@ export default function DashboardPage() {
               onClick={handleRefresh}
               variant='outline'
               disabled={isManualRefreshing}
-              aria-label='Refresh analytics'
-              className='h-8 w-8 shrink-0 rounded-lg p-0 sm:h-9 sm:w-auto sm:px-3'
+              className='h-8 w-full px-2.5 text-xs sm:ml-auto sm:w-auto'
             >
               <RefreshCw
                 className={cn(
-                  'h-3.5 w-3.5 sm:mr-1',
+                  'mr-1 h-3 w-3',
                   isManualRefreshing && 'animate-spin'
                 )}
               />
-              <span className='hidden sm:inline'>
-                {isManualRefreshing ? 'Refreshing...' : 'Refresh'}
-              </span>
+              {isManualRefreshing ? 'Refreshing...' : 'Refresh'}
             </Button>
           </div>
 
           {metricsLoading ? (
             <SectionLoading label='metrics' />
-          ) : metricsError ? (
-            <Card>
-              <CardContent>
-                <Empty className='border-none py-8'>
-                  <EmptyHeader>
-                    <EmptyMedia variant='icon'>
-                      <RefreshCw className='h-4 w-4' />
-                    </EmptyMedia>
-                    <EmptyTitle>Unable to load analytics</EmptyTitle>
-                    <EmptyDescription>
-                      {getQueryErrorMessage(metricsError)}
-                    </EmptyDescription>
-                  </EmptyHeader>
-                </Empty>
-              </CardContent>
-            </Card>
           ) : activeChartConfig ? (
             <UsageMetricsChart
               data={activeChartConfig.data}
@@ -1051,21 +1033,16 @@ export default function DashboardPage() {
             </Card>
           )}
 
+          {!metricsLoading && modelUsageMixData && hasModelUsageMixMetrics ? (
+            <TopModelsUsageChart
+              mix={modelUsageMixData}
+              displayUnit={displayUnit}
+              usdPerSat={usdPerSat}
+            />
+          ) : null}
+
           {summaryLoading ? (
             <SectionLoading label='summary' />
-          ) : summaryError ? (
-            <Card>
-              <CardContent>
-                <Empty className='border-none py-8'>
-                  <EmptyHeader>
-                    <EmptyTitle>Usage summary unavailable</EmptyTitle>
-                    <EmptyDescription>
-                      {getQueryErrorMessage(summaryError)}
-                    </EmptyDescription>
-                  </EmptyHeader>
-                </Empty>
-              </CardContent>
-            </Card>
           ) : summaryData ? (
             <UsageSummaryCards summary={summaryData} />
           ) : null}
@@ -1074,19 +1051,6 @@ export default function DashboardPage() {
 
           {errorLoading ? (
             <SectionLoading label='errors' />
-          ) : errorDetailsError ? (
-            <Card>
-              <CardContent>
-                <Empty className='border-none py-8'>
-                  <EmptyHeader>
-                    <EmptyTitle>Error details unavailable</EmptyTitle>
-                    <EmptyDescription>
-                      {getQueryErrorMessage(errorDetailsError)}
-                    </EmptyDescription>
-                  </EmptyHeader>
-                </Empty>
-              </CardContent>
-            </Card>
           ) : errorData ? (
             <ErrorDetailsTable errors={errorData.errors} />
           ) : null}

ui/app/providers/page.tsx

@@ -14,10 +14,11 @@ import {
 } from '@/lib/api/services/admin';
 import { AddProviderModelDialog } from '@/components/add-provider-model-dialog';
 import { BatchOverrideDialog } from '@/components/batch-override-dialog';
+import { ProviderFeeScheduleModal } from '@/components/provider-fee-schedule-modal';
 import { ProviderCard } from '@/components/provider-card';
 import { ProviderFormDialogContent } from '@/components/provider-form-dialog-content';
 import { Skeleton } from '@/components/ui/skeleton';
-import { AlertCircle, Plus, Server } from 'lucide-react';
+import { AlertCircle, Clock, Plus, Server } from 'lucide-react';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import { Dialog, DialogTrigger } from '@/components/ui/dialog';
 import {
@@ -70,6 +71,10 @@ export default function ProvidersPage() {
   const [batchOverrideProviderId, setBatchOverrideProviderId] = useState<
     number | null
   >(null);
+  const [feeScheduleState, setFeeScheduleState] = useState<{
+    open: boolean;
+    initialIds: number[];
+  }>({ open: false, initialIds: [] });
   const [providerDeleteTarget, setProviderDeleteTarget] =
     useState<UpstreamProvider | null>(null);
   const [modelDeleteTarget, setModelDeleteTarget] = useState<{
@@ -242,6 +247,7 @@ export default function ProvidersPage() {
       api_version: provider.api_version || null,
       enabled: provider.enabled,
       provider_fee: provider.provider_fee,
+      provider_fee_default: provider.provider_fee_default,
       provider_settings: provider.provider_settings || {},
     });
     setIsEditDialogOpen(true);
@@ -254,7 +260,7 @@ export default function ProvidersPage() {
       base_url: formData.base_url,
       api_version: formData.api_version,
       enabled: formData.enabled,
-      provider_fee: formData.provider_fee,
+      provider_fee_default: formData.provider_fee_default,
       provider_settings: formData.provider_settings,
     };
     if (formData.api_key) {
@@ -342,6 +348,13 @@ export default function ProvidersPage() {
     setBatchOverrideProviderId(providerId);
   };
 
+  const handleManageFeeSchedules = (providerId?: number) => {
+    setFeeScheduleState({
+      open: true,
+      initialIds: providerId !== undefined ? [providerId] : [],
+    });
+  };
+
   const availableMints = (globalSettings?.cashu_mints as string[]) || [];
 
   return (
@@ -352,12 +365,22 @@ export default function ProvidersPage() {
             title='Upstream Providers'
             description='Manage your AI provider connections and credentials.'
             actions={
-              <DialogTrigger asChild>
-                <Button>
-                  <Plus className='h-4 w-4' />
-                  Add Provider
+              <div className='flex gap-2'>
+                <Button
+                  variant='outline'
+                  onClick={() => handleManageFeeSchedules()}
+                  disabled={providers.length === 0}
+                >
+                  <Clock className='h-4 w-4' />
+                  Fee Schedules
                 </Button>
-              </DialogTrigger>
+                <DialogTrigger asChild>
+                  <Button>
+                    <Plus className='h-4 w-4' />
+                    Add Provider
+                  </Button>
+                </DialogTrigger>
+              </div>
             }
           />
           <ProviderFormDialogContent
@@ -437,6 +460,9 @@ export default function ProvidersPage() {
                 onEditProvider={() => handleEdit(provider)}
                 onDeleteProvider={() => setProviderDeleteTarget(provider)}
                 onBatchOverride={() => handleBatchOverride(provider.id)}
+                onManageFeeSchedules={() =>
+                  handleManageFeeSchedules(provider.id)
+                }
                 onAddModel={() => handleAddModel(provider.id)}
                 onEditModel={(model) => handleEditModel(provider.id, model)}
                 onDeleteModel={(modelId) =>
@@ -562,6 +588,16 @@ export default function ProvidersPage() {
           }}
         />
       )}
+
+      <ProviderFeeScheduleModal
+        providers={providers}
+        initialSelectedIds={feeScheduleState.initialIds}
+        isOpen={feeScheduleState.open}
+        onClose={() => setFeeScheduleState({ open: false, initialIds: [] })}
+        onSuccess={() => {
+          queryClient.invalidateQueries({ queryKey: ['upstream-providers'] });
+        }}
+      />
     </AppPageShell>
   );
 }

ui/app/settings/page.tsx

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { ServerConfigSettings } from '@/components/settings/server-config-settings';
 import { AdminSettings } from '@/components/settings/admin-settings';
+import { CliTokensSettings } from '@/components/settings/cli-tokens-settings';
 import { AppPageShell } from '@/components/app-page-shell';
 import { PageHeader } from '@/components/page-header';
 
@@ -19,6 +20,7 @@ export default function SettingsPage() {
           <TabsList variant='line' className='mb-4 w-full'>
             <TabsTrigger value='admin'>Admin Settings</TabsTrigger>
             <TabsTrigger value='server'>Server Config</TabsTrigger>
+            <TabsTrigger value='cli-tokens'>CLI Tokens</TabsTrigger>
           </TabsList>
           <TabsContent value='server'>
             <ServerConfigSettings />
@@ -26,6 +28,9 @@ export default function SettingsPage() {
           <TabsContent value='admin'>
             <AdminSettings />
           </TabsContent>
+          <TabsContent value='cli-tokens'>
+            <CliTokensSettings />
+          </TabsContent>
         </Tabs>
       </div>
     </AppPageShell>

ui/app/transactions/page.tsx

@@ -0,0 +1,560 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import { useQuery, keepPreviousData } from '@tanstack/react-query';
+import { AppPageShell } from '@/components/app-page-shell';
+import { PageHeader } from '@/components/page-header';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Badge } from '@/components/ui/badge';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { ScrollArea, ScrollBar } from '@/components/ui/scroll-area';
+import { Skeleton } from '@/components/ui/skeleton';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import {
+  RefreshCw,
+  Search,
+  ArrowDownLeft,
+  ArrowUpRight,
+  Copy,
+  Check,
+  Receipt,
+  Key,
+  Zap,
+  ChevronLeft,
+  ChevronRight,
+} from 'lucide-react';
+import { AdminService, type Transaction } from '@/lib/api/services/admin';
+import { format } from 'date-fns';
+import { toast } from 'sonner';
+
+const STORAGE_KEY = 'routstr-transaction-filters';
+
+function TransactionTable({
+  transactions,
+  copiedId,
+  onCopy,
+  getStatusBadge,
+}: {
+  transactions: Transaction[];
+  copiedId: string | null;
+  onCopy: (text: string, id: string) => void;
+  getStatusBadge: (tx: Transaction) => React.ReactNode;
+}) {
+  if (transactions.length === 0) {
+    return (
+      <Empty className='py-8'>
+        <EmptyHeader>
+          <EmptyMedia variant='icon'>
+            <Receipt className='h-4 w-4' />
+          </EmptyMedia>
+          <EmptyTitle>No transactions found</EmptyTitle>
+          <EmptyDescription>
+            Try adjusting your filters or check back later.
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+
+  return (
+    <ScrollArea className='h-[55svh] min-h-[420px] w-full sm:h-[600px]'>
+      <div className='min-w-[800px]'>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Type</TableHead>
+              <TableHead>Amount</TableHead>
+              <TableHead>Status</TableHead>
+              <TableHead>API Key</TableHead>
+              <TableHead>Request ID</TableHead>
+              <TableHead>Mint</TableHead>
+              <TableHead>Date</TableHead>
+              <TableHead className='text-right'>Actions</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {transactions.map((tx) => (
+              <TableRow key={tx.id}>
+                <TableCell>
+                  <div className='flex items-center gap-2'>
+                    {tx.type === 'in' ? (
+                      <ArrowDownLeft className='h-4 w-4 text-green-500' />
+                    ) : (
+                      <ArrowUpRight className='h-4 w-4 text-blue-500' />
+                    )}
+                    <span className='capitalize'>{tx.type}</span>
+                  </div>
+                </TableCell>
+                <TableCell className='font-mono'>
+                  {tx.amount} {tx.unit}
+                </TableCell>
+                <TableCell>{getStatusBadge(tx)}</TableCell>
+                <TableCell>
+                  {tx.api_key_hashed_key ? (
+                    <div className='flex items-center gap-1 text-xs'>
+                      <span className='max-w-[120px] truncate font-mono'>
+                        {tx.api_key_hashed_key.slice(0, 12)}...
+                      </span>
+                      <Button
+                        variant='ghost'
+                        size='icon'
+                        className='h-4 w-4'
+                        onClick={() =>
+                          onCopy(tx.api_key_hashed_key!, tx.id + '-apikey')
+                        }
+                      >
+                        {copiedId === tx.id + '-apikey' ? (
+                          <Check className='h-3 w-3' />
+                        ) : (
+                          <Copy className='h-3 w-3' />
+                        )}
+                      </Button>
+                    </div>
+                  ) : (
+                    <span className='text-muted-foreground text-xs'>—</span>
+                  )}
+                </TableCell>
+                <TableCell>
+                  {tx.request_id ? (
+                    <div className='flex items-center gap-1 text-xs'>
+                      <span className='max-w-[150px] truncate font-mono'>
+                        {tx.request_id}
+                      </span>
+                      <Button
+                        variant='ghost'
+                        size='icon'
+                        className='h-4 w-4'
+                        onClick={() => onCopy(tx.request_id!, tx.id + '-req')}
+                      >
+                        {copiedId === tx.id + '-req' ? (
+                          <Check className='h-3 w-3' />
+                        ) : (
+                          <Copy className='h-3 w-3' />
+                        )}
+                      </Button>
+                    </div>
+                  ) : (
+                    <span className='text-muted-foreground text-xs'>—</span>
+                  )}
+                </TableCell>
+                <TableCell>
+                  <div className='flex max-w-[150px] items-center gap-1 truncate text-xs'>
+                    <span className='truncate'>{tx.mint_url}</span>
+                  </div>
+                </TableCell>
+                <TableCell className='text-xs whitespace-nowrap'>
+                  {format(tx.created_at * 1000, 'yyyy-MM-dd HH:mm:ss')}
+                </TableCell>
+                <TableCell className='text-right'>
+                  <Button
+                    variant='ghost'
+                    size='icon'
+                    className='h-8 w-8'
+                    onClick={() => onCopy(tx.token, tx.id + '-token')}
+                    title='Copy Token'
+                  >
+                    {copiedId === tx.id + '-token' ? (
+                      <Check className='h-4 w-4' />
+                    ) : (
+                      <Copy className='h-4 w-4' />
+                    )}
+                  </Button>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+      <ScrollBar orientation='horizontal' />
+    </ScrollArea>
+  );
+}
+
+export default function TransactionsPage() {
+  const [search, setSearch] = useState('');
+  const [type, setType] = useState<string>('all');
+  const [status, setStatus] = useState<string>('all');
+  const [copiedId, setCopiedId] = useState<string | null>(null);
+
+  // Load filters from localStorage on mount
+  useEffect(() => {
+    const saved = localStorage.getItem(STORAGE_KEY);
+    if (saved) {
+      try {
+        const parsed = JSON.parse(saved);
+        if (parsed.search) setSearch(parsed.search);
+        if (parsed.type) setType(parsed.type);
+        if (parsed.status) setStatus(parsed.status);
+      } catch (e) {
+        console.error('Failed to load filters from localStorage', e);
+      }
+    }
+  }, []);
+
+  // Save filters to localStorage whenever they change
+  useEffect(() => {
+    const filters = { search, type, status };
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(filters));
+  }, [search, type, status]);
+
+  const PAGE_SIZE = 50;
+  const [activeTab, setActiveTab] = useState<string>('x-cashu');
+  const [xcashuPage, setXcashuPage] = useState(0);
+  const [apikeyPage, setApikeyPage] = useState(0);
+
+  const typeParam = type === 'all' ? undefined : type;
+  const statusParam = status === 'all' ? undefined : status;
+  const searchParam = search || undefined;
+
+  const xcashuQuery = useQuery({
+    queryKey: [
+      'transactions',
+      'x-cashu',
+      typeParam,
+      statusParam,
+      searchParam,
+      xcashuPage,
+    ],
+    queryFn: () =>
+      AdminService.getTransactions(
+        typeParam,
+        statusParam,
+        searchParam,
+        'x-cashu',
+        PAGE_SIZE,
+        xcashuPage * PAGE_SIZE
+      ),
+    placeholderData: keepPreviousData,
+  });
+
+  const apikeyQuery = useQuery({
+    queryKey: [
+      'transactions',
+      'apikey',
+      typeParam,
+      statusParam,
+      searchParam,
+      apikeyPage,
+    ],
+    queryFn: () =>
+      AdminService.getTransactions(
+        typeParam,
+        statusParam,
+        searchParam,
+        'apikey',
+        PAGE_SIZE,
+        apikeyPage * PAGE_SIZE
+      ),
+    placeholderData: keepPreviousData,
+  });
+
+  const handleClearFilters = () => {
+    setSearch('');
+    setType('all');
+    setStatus('all');
+    setXcashuPage(0);
+    setApikeyPage(0);
+  };
+
+  const copyToClipboard = (text: string, id: string) => {
+    navigator.clipboard.writeText(text);
+    setCopiedId(id);
+    toast.success('Copied to clipboard');
+    setTimeout(() => setCopiedId(null), 2000);
+  };
+
+  const getStatusBadge = (tx: Transaction) => {
+    if (tx.swept)
+      return (
+        <Badge
+          variant='outline'
+          className='border-orange-500/20 bg-orange-500/10 text-orange-500'
+        >
+          Swept
+        </Badge>
+      );
+    if (tx.collected)
+      return (
+        <Badge
+          variant='outline'
+          className='border-green-500/20 bg-green-500/10 text-green-500'
+        >
+          Collected
+        </Badge>
+      );
+    return (
+      <Badge
+        variant='outline'
+        className='border-blue-500/20 bg-blue-500/10 text-blue-500'
+      >
+        Pending
+      </Badge>
+    );
+  };
+
+  const hasActiveFilters =
+    type !== 'all' || status !== 'all' || Boolean(search);
+
+  const activeFilterDescription = [
+    type !== 'all' ? `type ${type === 'in' ? 'incoming' : 'outgoing'}` : null,
+    status !== 'all' ? `status ${status}` : null,
+    search ? `search "${search}"` : null,
+  ]
+    .filter(Boolean)
+    .join(' • ');
+
+  // Reset pages when filters change
+  useEffect(() => {
+    setXcashuPage(0);
+    setApikeyPage(0);
+  }, [type, status, search]);
+
+  const isRefetching = xcashuQuery.isRefetching || apikeyQuery.isRefetching;
+
+  const renderCardContent = (
+    query: typeof xcashuQuery,
+    page: number,
+    setPage: (p: number) => void
+  ) => {
+    if (query.isLoading) {
+      return (
+        <div className='space-y-2'>
+          {Array.from({ length: 8 }).map((_, index) => (
+            <Skeleton
+              key={`tx-loading-${index}`}
+              className='h-16 w-full rounded-lg'
+            />
+          ))}
+        </div>
+      );
+    }
+
+    const transactions = query.data?.transactions ?? [];
+    const total = query.data?.total ?? 0;
+    const totalPages = Math.ceil(total / PAGE_SIZE);
+
+    return (
+      <>
+        {totalPages > 1 && (
+          <div className='flex flex-col gap-2 border-b pb-3 sm:flex-row sm:items-center sm:justify-between'>
+            <span className='text-muted-foreground text-xs sm:text-sm'>
+              {page * PAGE_SIZE + 1}–{Math.min((page + 1) * PAGE_SIZE, total)}{' '}
+              of {total}
+            </span>
+            <div className='flex items-center gap-2'>
+              <Button
+                variant='outline'
+                size='sm'
+                disabled={page === 0}
+                onClick={() => setPage(page - 1)}
+              >
+                <ChevronLeft className='h-4 w-4' />
+                <span className='hidden sm:inline'>Previous</span>
+              </Button>
+              <span className='text-xs sm:text-sm'>
+                {page + 1} / {totalPages}
+              </span>
+              <Button
+                variant='outline'
+                size='sm'
+                disabled={page >= totalPages - 1}
+                onClick={() => setPage(page + 1)}
+              >
+                <span className='hidden sm:inline'>Next</span>
+                <ChevronRight className='h-4 w-4' />
+              </Button>
+            </div>
+          </div>
+        )}
+        <TransactionTable
+          transactions={transactions}
+          copiedId={copiedId}
+          onCopy={copyToClipboard}
+          getStatusBadge={getStatusBadge}
+        />
+      </>
+    );
+  };
+
+  return (
+    <AppPageShell contentClassName='mx-auto w-full max-w-5xl overflow-x-hidden'>
+      <div className='space-y-6'>
+        <PageHeader
+          title='Cashu Transactions'
+          description='View all incoming and outgoing Cashu token transactions.'
+          actions={
+            <Button
+              onClick={() => {
+                xcashuQuery.refetch();
+                apikeyQuery.refetch();
+              }}
+              variant='outline'
+              size='sm'
+              disabled={isRefetching}
+            >
+              <RefreshCw
+                className={`mr-2 h-4 w-4 ${isRefetching ? 'animate-spin' : ''}`}
+              />
+              Refresh
+            </Button>
+          }
+        />
+
+        <Card className='mb-6'>
+          <CardHeader>
+            <CardTitle>Filters</CardTitle>
+            <CardDescription>
+              Filter transactions by type, status, or search text
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <div className='grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3'>
+              <div className='space-y-2'>
+                <Label htmlFor='search'>Search</Label>
+                <div className='relative'>
+                  <Search className='text-muted-foreground absolute top-2.5 left-2.5 h-4 w-4' />
+                  <Input
+                    id='search'
+                    placeholder='Search by ID, token, request ID or key hash...'
+                    className='pl-8'
+                    value={search}
+                    onChange={(e) => setSearch(e.target.value)}
+                  />
+                </div>
+              </div>
+              <div className='space-y-2'>
+                <Label htmlFor='type'>Type</Label>
+                <Select value={type} onValueChange={setType}>
+                  <SelectTrigger>
+                    <SelectValue placeholder='Type' />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value='all'>All Types</SelectItem>
+                    <SelectItem value='in'>Incoming (Payments)</SelectItem>
+                    <SelectItem value='out'>Outgoing (Refunds)</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+              <div className='space-y-2'>
+                <Label htmlFor='status'>Status</Label>
+                <Select value={status} onValueChange={setStatus}>
+                  <SelectTrigger>
+                    <SelectValue placeholder='Status' />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value='all'>All Statuses</SelectItem>
+                    <SelectItem value='pending'>Pending</SelectItem>
+                    <SelectItem value='collected'>Collected</SelectItem>
+                    <SelectItem value='swept'>Swept</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+              <div className='flex items-end sm:col-span-2 lg:col-span-1'>
+                <Button
+                  onClick={handleClearFilters}
+                  variant='outline'
+                  className='w-full'
+                >
+                  Clear Filters
+                </Button>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+
+        <Tabs
+          defaultValue='x-cashu'
+          value={activeTab}
+          onValueChange={setActiveTab}
+        >
+          <TabsList className='mb-4'>
+            <TabsTrigger value='x-cashu' className='flex items-center gap-2'>
+              <Zap className='h-4 w-4' />
+              X-Cashu
+              {xcashuQuery.data && (
+                <Badge variant='secondary' className='ml-1'>
+                  {xcashuQuery.data.total}
+                </Badge>
+              )}
+            </TabsTrigger>
+            <TabsTrigger value='apikey' className='flex items-center gap-2'>
+              <Key className='h-4 w-4' />
+              API Key
+              {apikeyQuery.data && (
+                <Badge variant='secondary' className='ml-1'>
+                  {apikeyQuery.data.total}
+                </Badge>
+              )}
+            </TabsTrigger>
+          </TabsList>
+
+          <TabsContent value='x-cashu'>
+            <Card>
+              <CardHeader>
+                <div className='flex flex-col items-start gap-2 sm:flex-row sm:items-center sm:justify-between'>
+                  <CardTitle>X-Cashu Transaction History</CardTitle>
+                  {hasActiveFilters && (
+                    <CardDescription>
+                      Filtered by {activeFilterDescription}
+                    </CardDescription>
+                  )}
+                </div>
+              </CardHeader>
+              <CardContent className='overflow-hidden'>
+                {renderCardContent(xcashuQuery, xcashuPage, setXcashuPage)}
+              </CardContent>
+            </Card>
+          </TabsContent>
+
+          <TabsContent value='apikey'>
+            <Card>
+              <CardHeader>
+                <div className='flex flex-col items-start gap-2 sm:flex-row sm:items-center sm:justify-between'>
+                  <CardTitle>API Key Transaction History</CardTitle>
+                  {hasActiveFilters && (
+                    <CardDescription>
+                      Filtered by {activeFilterDescription}
+                    </CardDescription>
+                  )}
+                </div>
+              </CardHeader>
+              <CardContent className='overflow-hidden'>
+                {renderCardContent(apikeyQuery, apikeyPage, setApikeyPage)}
+              </CardContent>
+            </Card>
+          </TabsContent>
+        </Tabs>
+      </div>
+    </AppPageShell>
+  );
+}

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

@@ -1,6 +1,6 @@
 'use client';
 
-import React, { useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
 import { useForm } from 'react-hook-form';
 import { z } from 'zod';
 import { zodResolver } from '@hookform/resolvers/zod';
@@ -39,7 +39,7 @@ import {
   FormMessage,
 } from '@/components/ui/form';
 import { Switch } from '@/components/ui/switch';
-import { Loader2, Plus } from 'lucide-react';
+import { Check, Copy, Loader2, Plus } from 'lucide-react';
 import { toast } from 'sonner';
 import { AdminService, type AdminModel } from '@/lib/api/services/admin';
 
@@ -64,6 +64,7 @@ const FormSchema = z.object({
   instruct_type: z.string().default(''),
   canonical_slug: z.string().default(''),
   alias_ids_raw: z.string().default(''),
+  forwarded_model_id: z.string().default(''),
   upstream_provider_id: z.string().default(''),
   input_cost: z.coerce.number().min(0).default(0),
   output_cost: z.coerce.number().min(0).default(0),
@@ -104,6 +105,7 @@ export function AddProviderModelDialog({
   const [isPresetOpen, setIsPresetOpen] = useState(false);
   const [selectedPresetLabel, setSelectedPresetLabel] =
     useState('Select a preset');
+  const [forwardedModelIdCopied, setForwardedModelIdCopied] = useState(false);
 
   const form = useForm<FormData>({
     resolver: zodResolver(FormSchema) as never,
@@ -119,6 +121,7 @@ export function AddProviderModelDialog({
       instruct_type: '',
       canonical_slug: '',
       alias_ids_raw: '',
+      forwarded_model_id: '',
       upstream_provider_id: '',
       input_cost: 0,
       output_cost: 0,
@@ -180,6 +183,7 @@ export function AddProviderModelDialog({
             : '',
         canonical_slug: initialData.canonical_slug || '',
         alias_ids_raw: listToString(initialData.alias_ids),
+        forwarded_model_id: initialData.forwarded_model_id || initialData.id,
         upstream_provider_id:
           typeof initialData.upstream_provider_id === 'string'
             ? initialData.upstream_provider_id
@@ -223,6 +227,7 @@ export function AddProviderModelDialog({
         instruct_type: '',
         canonical_slug: '',
         alias_ids_raw: '',
+        forwarded_model_id: '',
         upstream_provider_id: '',
         input_cost: 0,
         output_cost: 0,
@@ -280,6 +285,7 @@ export function AddProviderModelDialog({
     );
     form.setValue('canonical_slug', model.canonical_slug || '');
     form.setValue('alias_ids_raw', listToString(model.alias_ids));
+    form.setValue('forwarded_model_id', model.forwarded_model_id || model.id);
     form.setValue(
       'upstream_provider_id',
       typeof model.upstream_provider_id === 'string'
@@ -385,6 +391,7 @@ export function AddProviderModelDialog({
         canonical_slug: data.canonical_slug?.trim() || null,
         alias_ids: listFromString(data.alias_ids_raw || ''),
         enabled: data.enabled,
+        forwarded_model_id: data.forwarded_model_id?.trim() || data.id,
       };
 
       if (isEdit) {
@@ -520,6 +527,53 @@ export function AddProviderModelDialog({
                 )}
               />
 
+              <FormField
+                control={form.control}
+                name='forwarded_model_id'
+                render={({ field }) => {
+                  const handleCopy = () => {
+                    const value = field.value || form.getValues('id');
+                    if (!value) return;
+                    navigator.clipboard.writeText(value);
+                    setForwardedModelIdCopied(true);
+                    setTimeout(() => setForwardedModelIdCopied(false), 1500);
+                  };
+                  return (
+                    <FormItem>
+                      <FormLabel>Client Alias ID</FormLabel>
+                      <FormControl>
+                        <div className='flex gap-2'>
+                          <Input
+                            placeholder={
+                              form.watch('id') || 'e.g., openai/gpt-4o'
+                            }
+                            {...field}
+                          />
+                          <Button
+                            type='button'
+                            variant='outline'
+                            size='icon'
+                            onClick={handleCopy}
+                            title='Copy model ID'
+                          >
+                            {forwardedModelIdCopied ? (
+                              <Check className='h-4 w-4 text-green-500' />
+                            ) : (
+                              <Copy className='h-4 w-4' />
+                            )}
+                          </Button>
+                        </div>
+                      </FormControl>
+                      <FormDescription>
+                        Alternate ID that clients can use to reference this
+                        model. Defaults to the model&apos;s own ID.
+                      </FormDescription>
+                      <FormMessage />
+                    </FormItem>
+                  );
+                }}
+              />
+
               <FormField
                 control={form.control}
                 name='name'

ui/components/api-endpoint-tester.tsx

@@ -471,7 +471,11 @@ export function ApiEndpointTester({ models }: ApiEndpointTesterProps) {
     testEndpointMutation.mutate(requestData);
   };
 
-  const enabledModels = models.filter((model) => model.isEnabled);
+  const enabledModels = Array.from(
+    new Map(
+      models.filter((model) => model.isEnabled).map((m) => [m.id, m])
+    ).values()
+  );
   const credentials = selectedModel ? getModelCredentials(selectedModel) : null;
   const endpointUrl = credentials
     ? buildEndpointUrl(

ui/components/api-key-input.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import * as React from 'react';
+import { Input } from '@/components/ui/input';
+
+interface ApiKeyInputProps extends React.ComponentProps<'input'> {
+  onApiKeyChange: (apiKey: string) => void;
+}
+
+export function ApiKeyInput({
+  value,
+  onApiKeyChange,
+  ...props
+}: ApiKeyInputProps) {
+  const [internalValue, setInternalValue] = useState(value || '');
+
+  useEffect(() => {
+    setInternalValue(value || '');
+  }, [value]);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      onApiKeyChange(internalValue as string);
+    }, 300);
+
+    return () => clearTimeout(handler);
+  }, [internalValue, onApiKeyChange]);
+
+  return (
+    <Input
+      value={internalValue}
+      onChange={(e) => setInternalValue(e.target.value)}
+      placeholder='sk-...'
+      className='font-mono text-sm'
+      {...props}
+    />
+  );
+}

ui/components/app-page-shell.tsx

@@ -13,6 +13,7 @@ import {
   ServerIcon,
   SettingsIcon,
   WalletIcon,
+  ArrowRightLeftIcon,
 } from 'lucide-react';
 import Image from 'next/image';
 import { toast } from 'sonner';
@@ -39,8 +40,9 @@ const NAV_ITEMS = [
   { title: 'Dashboard', url: '/', icon: LayoutDashboardIcon },
   { title: 'Balances', url: '/balances', icon: WalletIcon },
   { title: 'Logs', url: '/logs', icon: FileTextIcon },
-  { title: 'Models', url: '/models', icon: DatabaseIcon },
+  { title: 'Models', url: '/model', icon: DatabaseIcon },
   { title: 'Providers', url: '/providers', icon: ServerIcon },
+  { title: 'Transactions', url: '/transactions', icon: ArrowRightLeftIcon },
   { title: 'Settings', url: '/settings', icon: SettingsIcon },
 ] as const;
 

ui/components/app-sidebar.tsx

@@ -9,6 +9,7 @@ import {
   ServerIcon,
   SettingsIcon,
   WalletIcon,
+  ArrowRightLeftIcon,
 } from 'lucide-react';
 import Image from 'next/image';
 import Link from 'next/link';
@@ -45,6 +46,11 @@ const data = {
       url: '/balances',
       icon: WalletIcon,
     },
+    {
+      title: 'Transactions',
+      url: '/transactions',
+      icon: ArrowRightLeftIcon,
+    },
     {
       title: 'Logs',
       url: '/logs',
@@ -52,7 +58,7 @@ const data = {
     },
     {
       title: 'Models',
-      url: '/models',
+      url: '/model',
       icon: DatabaseIcon,
     },
     {

ui/components/child-key-creator.tsx

@@ -1,7 +1,9 @@
 'use client';
 
 import { useState } from 'react';
+import { useWalletInfo } from '@/hooks/use-wallet-info';
 import { WalletService } from '@/lib/api/services/wallet';
+import { ApiKeyInput } from './api-key-input';
 import { Button } from '@/components/ui/button';
 import {
   Card,
@@ -14,17 +16,8 @@ import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
 import { Input } from '@/components/ui/input';
 import { Textarea } from '@/components/ui/textarea';
 import { Label } from '@/components/ui/label';
-import {
-  Key,
-  Copy,
-  Check,
-  Loader2,
-  RotateCcw,
-  Plus,
-  Trash2,
-} from 'lucide-react';
+import { Key, Copy, Check, Loader2, Plus, Trash2 } from 'lucide-react';
 import { toast } from 'sonner';
-import { Badge } from '@/components/ui/badge';
 import { KeyOptions } from './key-options';
 
 interface KeyConfig {
@@ -42,6 +35,14 @@ interface ChildKeyCreatorProps {
   costPerKeyMsats?: number;
 }
 
+function formatSats(msats: number): string {
+  return new Intl.NumberFormat('en-US').format(Math.floor(msats / 1000));
+}
+
+function formatMsats(msats: number): string {
+  return new Intl.NumberFormat('en-US').format(msats);
+}
+
 export function ChildKeyCreator({
   baseUrl,
   apiKey: propApiKey,
@@ -50,6 +51,7 @@ export function ChildKeyCreator({
 }: ChildKeyCreatorProps) {
   const [internalApiKey, setInternalApiKey] = useState('');
   const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
   const [configs, setConfigs] = useState<KeyConfig[]>([
     {
       id: crypto.randomUUID(),
@@ -59,15 +61,15 @@ export function ChildKeyCreator({
       validityDate: '',
     },
   ]);
-  const [childKeyToCheck, setChildKeyToCheck] = useState('');
-  const [checking, setChecking] = useState(false);
-  const [keyStatus, setKeyStatus] = useState<{
-    total_spent: number;
-    balance_limit: number | null;
-    validity_date: number | null;
-    is_expired: boolean;
-    is_drained: boolean;
-  } | null>(null);
+
+  const activeApiKey = propApiKey ?? internalApiKey;
+  const { data: walletInfo } = useWalletInfo(baseUrl ?? '', activeApiKey);
+
+  const handleApiKeyChange = (val: string) => {
+    setInternalApiKey(val);
+    onApiKeyChange?.(val);
+  };
+
   const [newKeys, setNewKeys] = useState<string[]>([]);
   const [resultInfo, setResultInfo] = useState<{
     cost_msats: number;
@@ -75,13 +77,6 @@ export function ChildKeyCreator({
   } | null>(null);
   const [copiedKey, setCopiedKey] = useState<string | null>(null);
 
-  const activeApiKey = propApiKey ?? internalApiKey;
-
-  const handleApiKeyChange = (val: string) => {
-    setInternalApiKey(val);
-    onApiKeyChange?.(val);
-  };
-
   const addConfig = () => {
     setConfigs([
       ...configs,
@@ -112,6 +107,7 @@ export function ChildKeyCreator({
     }
 
     setLoading(true);
+    setError(null);
     try {
       let allNewKeys: string[] = [];
       let totalCost = 0;
@@ -152,55 +148,21 @@ export function ChildKeyCreator({
       );
     } catch (error) {
       console.error('Failed to create child key:', error);
-      toast.error(
-        error instanceof Error ? error.message : 'Failed to create child key'
-      );
+      let errorMessage =
+        error instanceof Error ? error.message : 'Failed to create child key';
+      try {
+        const parsed = JSON.parse(errorMessage);
+        errorMessage =
+          parsed.detail?.error?.message ||
+          (typeof parsed.detail === 'string' ? parsed.detail : errorMessage);
+      } catch {}
+      setError(errorMessage);
+      toast.error(errorMessage);
     } finally {
       setLoading(false);
     }
   };
 
-  const handleCheckKey = async () => {
-    if (!childKeyToCheck) {
-      toast.error('Please provide a Child API key to check');
-      return;
-    }
-
-    setChecking(true);
-    setKeyStatus(null);
-    try {
-      const baseUrlToUse = baseUrl || '';
-      const response = await fetch(`${baseUrlToUse}/v1/balance/info`, {
-        headers: {
-          Authorization: `Bearer ${childKeyToCheck}`,
-        },
-      });
-
-      if (!response.ok) {
-        throw new Error('Failed to fetch key info');
-      }
-
-      const info = await response.json();
-      const now = Math.floor(Date.now() / 1000);
-
-      setKeyStatus({
-        total_spent: info.total_spent,
-        balance_limit: info.balance_limit,
-        validity_date: info.validity_date,
-        is_expired: info.validity_date ? now > info.validity_date : false,
-        is_drained: info.balance_limit
-          ? info.total_spent >= info.balance_limit
-          : false,
-      });
-    } catch (error) {
-      toast.error(
-        error instanceof Error ? error.message : 'Failed to check child key'
-      );
-    } finally {
-      setChecking(false);
-    }
-  };
-
   const copyToClipboard = (key: string) => {
     navigator.clipboard.writeText(key);
     setCopiedKey(key);
@@ -243,12 +205,55 @@ export function ChildKeyCreator({
                 <Label className='text-muted-foreground text-[0.7rem] tracking-wider'>
                   Parent API Key
                 </Label>
-                <Input
-                  value={activeApiKey}
-                  onChange={(e) => handleApiKeyChange(e.target.value)}
-                  placeholder='sk-...'
-                  className='font-mono text-sm'
-                />
+                <div className='flex gap-2'>
+                  <div className='flex-1'>
+                    <ApiKeyInput
+                      value={activeApiKey}
+                      onApiKeyChange={handleApiKeyChange}
+                    />
+                  </div>
+                  <Button
+                    variant='outline'
+                    size='icon'
+                    onClick={() => navigator.clipboard.writeText(activeApiKey)}
+                    disabled={!activeApiKey}
+                  >
+                    <Copy className='h-4 w-4' />
+                  </Button>
+                </div>
+                {walletInfo && (
+                  <div className='bg-muted/30 mt-2 space-y-2 rounded-lg p-3'>
+                    <div className='flex items-center justify-between'>
+                      <span className='text-muted-foreground text-sm'>
+                        Spendable Balance
+                      </span>
+                      <span className='text-primary font-mono text-sm font-medium'>
+                        {formatSats(walletInfo.balanceMsats)} sats
+                      </span>
+                    </div>
+                    <div className='flex items-center justify-between'>
+                      <span className='text-muted-foreground text-sm'>
+                        Total Requests
+                      </span>
+                      <span className='font-mono text-sm font-medium'>
+                        {walletInfo.totalRequests}
+                      </span>
+                    </div>
+                    <div className='flex items-center justify-between'>
+                      <span className='text-muted-foreground text-sm'>
+                        Total Spent
+                      </span>
+                      <div className='text-right'>
+                        <p className='font-mono text-sm font-medium'>
+                          {formatSats(walletInfo.totalSpent)} sats
+                        </p>
+                        <p className='text-muted-foreground font-mono text-[0.6rem]'>
+                          {formatMsats(walletInfo.totalSpent)} msats
+                        </p>
+                      </div>
+                    </div>
+                  </div>
+                )}
               </div>
             )}
 
@@ -362,11 +367,18 @@ export function ChildKeyCreator({
                   )}
                 </Button>
               </div>
-            </div>
 
-            <p className='text-muted-foreground text-xs'>
-              Each key creation has a small one-time fee.
-            </p>
+              {error && (
+                <Alert variant='destructive'>
+                  <AlertTitle>Error</AlertTitle>
+                  <AlertDescription>{error}</AlertDescription>
+                </Alert>
+              )}
+
+              <p className='text-muted-foreground text-xs'>
+                Each key creation has a small one-time fee.
+              </p>
+            </div>
 
             {newKeys.length > 0 && (
               <div className='mt-6 space-y-4'>
@@ -458,89 +470,6 @@ export function ChildKeyCreator({
           </div>
         </CardContent>
       </Card>
-
-      <Card>
-        <CardHeader>
-          <CardTitle className='text-lg'>Check Child Key Status</CardTitle>
-          <CardDescription>
-            View the current spending, limit, and expiration status of any child
-            key.
-          </CardDescription>
-        </CardHeader>
-        <CardContent>
-          <div className='space-y-4'>
-            <div className='space-y-2'>
-              <Label className='text-muted-foreground text-[0.7rem] tracking-wider'>
-                Child API Key
-              </Label>
-              <Input
-                value={childKeyToCheck}
-                onChange={(e) => setChildKeyToCheck(e.target.value)}
-                placeholder='sk-...'
-                className='font-mono text-sm'
-              />
-            </div>
-            <Button
-              onClick={handleCheckKey}
-              disabled={checking || !childKeyToCheck}
-              variant='outline'
-              className='w-full'
-            >
-              {checking ? (
-                <>
-                  <Loader2 className='mr-2 h-4 w-4 animate-spin' />
-                  Checking...
-                </>
-              ) : (
-                <>
-                  <RotateCcw className='mr-2 h-4 w-4' />
-                  Check Status
-                </>
-              )}
-            </Button>
-
-            {keyStatus && (
-              <div className='bg-muted/30 mt-4 space-y-3 rounded-lg border p-4 text-sm'>
-                <div className='flex justify-between'>
-                  <span className='text-muted-foreground'>Total Spent:</span>
-                  <span className='font-mono font-medium'>
-                    {keyStatus.total_spent} mSats
-                  </span>
-                </div>
-                {keyStatus.balance_limit !== null && (
-                  <div className='flex justify-between'>
-                    <span className='text-muted-foreground'>Limit:</span>
-                    <span className='font-mono font-medium'>
-                      {keyStatus.balance_limit} mSats
-                    </span>
-                  </div>
-                )}
-                {keyStatus.validity_date !== null && (
-                  <div className='flex justify-between'>
-                    <span className='text-muted-foreground'>Expires:</span>
-                    <span className='font-mono font-medium'>
-                      {new Date(
-                        keyStatus.validity_date * 1000
-                      ).toLocaleDateString()}
-                    </span>
-                  </div>
-                )}
-                <div className='flex gap-2 pt-2'>
-                  {keyStatus.is_drained && (
-                    <Badge variant='destructive'>Drained</Badge>
-                  )}
-                  {keyStatus.is_expired && (
-                    <Badge variant='destructive'>Expired</Badge>
-                  )}
-                  {!keyStatus.is_drained && !keyStatus.is_expired && (
-                    <Badge>Active</Badge>
-                  )}
-                </div>
-              </div>
-            )}
-          </div>
-        </CardContent>
-      </Card>
     </div>
   );
 }

ui/components/edit-model-form.tsx

@@ -1,577 +0,0 @@
-'use client';
-
-import React, { useState, useEffect, useCallback } from 'react';
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
-import { type Model } from '@/lib/api/schemas/models';
-import { AdminService, type AdminModel } from '@/lib/api/services/admin';
-import { Button } from '@/components/ui/button';
-import { Input } from '@/components/ui/input';
-import { Textarea } from '@/components/ui/textarea';
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle,
-} from '@/components/ui/dialog';
-import {
-  Form,
-  FormControl,
-  FormDescription,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormMessage,
-} from '@/components/ui/form';
-import { Edit3, Loader2 } from 'lucide-react';
-import { toast } from 'sonner';
-import { Switch } from '@/components/ui/switch';
-
-const EditModelFormSchema = z.object({
-  name: z.string().min(1, 'Name is required'),
-  description: z.string().optional(),
-  context_length: z.number().min(0),
-  prompt: z.number().min(0),
-  completion: z.number().min(0),
-  enabled: z.boolean(),
-});
-
-type EditModelFormData = z.infer<typeof EditModelFormSchema>;
-
-const roundToFiveDecimals = (value: number | undefined | null): number => {
-  if (value === undefined || value === null || isNaN(value)) {
-    return 0;
-  }
-  return Math.round(value * 100000) / 100000;
-};
-
-const toNumber = (value: unknown, fallback = 0): number => {
-  if (typeof value === 'number' && Number.isFinite(value)) {
-    return value;
-  }
-  if (typeof value === 'string') {
-    const parsed = Number(value);
-    if (Number.isFinite(parsed)) {
-      return parsed;
-    }
-  }
-  return fallback;
-};
-
-const toStringArray = (value: unknown, fallback: string[]): string[] => {
-  if (!Array.isArray(value)) {
-    return fallback;
-  }
-  const filtered = value.filter(
-    (item): item is string => typeof item === 'string'
-  );
-  return filtered.length > 0 ? filtered : fallback;
-};
-
-interface EditModelFormProps {
-  model: Model;
-  providerId?: number;
-  onModelUpdate?: () => void;
-  onCancel?: () => void;
-  isOpen: boolean;
-}
-
-interface AdminModelData {
-  id: string;
-  name: string;
-  description?: string;
-  created: number;
-  context_length: number;
-  architecture: {
-    modality: string;
-    input_modalities: string[];
-    output_modalities: string[];
-    tokenizer: string;
-    instruct_type: string | null;
-  };
-  pricing: {
-    prompt: number;
-    completion: number;
-    request: number;
-    image: number;
-    web_search: number;
-    internal_reasoning: number;
-  };
-  per_request_limits: null | undefined;
-  top_provider: null | undefined;
-  upstream_provider_id: number;
-  enabled: boolean;
-}
-
-const normalizeAdminModelData = (
-  adminModel: AdminModel,
-  fallbackModel: Model,
-  providerId: number
-): AdminModelData => {
-  const pricingRecord =
-    adminModel.pricing && typeof adminModel.pricing === 'object'
-      ? (adminModel.pricing as Record<string, unknown>)
-      : {};
-
-  const architectureRecord =
-    adminModel.architecture && typeof adminModel.architecture === 'object'
-      ? (adminModel.architecture as Record<string, unknown>)
-      : {};
-
-  return {
-    id: adminModel.id,
-    name: adminModel.name,
-    description: adminModel.description || '',
-    created: toNumber(adminModel.created, Math.floor(Date.now() / 1000)),
-    context_length: Math.max(
-      0,
-      Math.trunc(
-        toNumber(adminModel.context_length, fallbackModel.contextLength || 4096)
-      )
-    ),
-    architecture: {
-      modality:
-        typeof architectureRecord.modality === 'string'
-          ? architectureRecord.modality
-          : fallbackModel.modelType || 'text',
-      input_modalities: toStringArray(architectureRecord.input_modalities, [
-        fallbackModel.modelType || 'text',
-      ]),
-      output_modalities: toStringArray(architectureRecord.output_modalities, [
-        fallbackModel.modelType || 'text',
-      ]),
-      tokenizer:
-        typeof architectureRecord.tokenizer === 'string'
-          ? architectureRecord.tokenizer
-          : '',
-      instruct_type:
-        typeof architectureRecord.instruct_type === 'string'
-          ? architectureRecord.instruct_type
-          : null,
-    },
-    pricing: {
-      prompt: roundToFiveDecimals(
-        toNumber(pricingRecord.prompt, fallbackModel.input_cost)
-      ),
-      completion: roundToFiveDecimals(
-        toNumber(pricingRecord.completion, fallbackModel.output_cost)
-      ),
-      request: toNumber(pricingRecord.request, 0),
-      image: toNumber(pricingRecord.image, 0),
-      web_search: toNumber(pricingRecord.web_search, 0),
-      internal_reasoning: toNumber(pricingRecord.internal_reasoning, 0),
-    },
-    per_request_limits:
-      adminModel.per_request_limits === null ||
-      adminModel.per_request_limits === undefined
-        ? adminModel.per_request_limits
-        : null,
-    top_provider:
-      adminModel.top_provider === null || adminModel.top_provider === undefined
-        ? adminModel.top_provider
-        : null,
-    upstream_provider_id:
-      typeof adminModel.upstream_provider_id === 'number'
-        ? adminModel.upstream_provider_id
-        : providerId,
-    enabled: adminModel.enabled !== false,
-  };
-};
-
-export function EditModelForm({
-  model,
-  providerId,
-  onModelUpdate,
-  onCancel,
-  isOpen,
-}: EditModelFormProps) {
-  const [isSubmitting, setIsSubmitting] = useState(false);
-  const [adminModelData, setAdminModelData] = useState<AdminModelData | null>(
-    null
-  );
-  const [isNewOverride, setIsNewOverride] = useState(false);
-
-  const form = useForm<EditModelFormData>({
-    resolver: zodResolver(EditModelFormSchema),
-    defaultValues: {
-      name: model.name,
-      description: model.description || '',
-      context_length: model.contextLength || 4096,
-      prompt: roundToFiveDecimals(model.input_cost),
-      completion: roundToFiveDecimals(model.output_cost),
-      enabled: model.isEnabled !== false,
-    },
-  });
-
-  const loadAdminModel = useCallback(async () => {
-    if (!providerId) {
-      console.error('loadAdminModel called without providerId');
-      return;
-    }
-
-    try {
-      const adminModel = await AdminService.getProviderModel(
-        providerId,
-        model.id
-      );
-
-      const normalizedAdminModel = normalizeAdminModelData(
-        adminModel,
-        model,
-        providerId
-      );
-      setAdminModelData(normalizedAdminModel);
-      setIsNewOverride(false);
-
-      form.reset({
-        name: normalizedAdminModel.name,
-        description: normalizedAdminModel.description || '',
-        context_length: normalizedAdminModel.context_length,
-        prompt: normalizedAdminModel.pricing.prompt,
-        completion: normalizedAdminModel.pricing.completion,
-        enabled: normalizedAdminModel.enabled !== false,
-      });
-    } catch {
-      setIsNewOverride(true);
-      setAdminModelData({
-        id: model.full_name,
-        name: model.name,
-        description: model.description || '',
-        created: Math.floor(Date.now() / 1000),
-        context_length: model.contextLength || 4096,
-        architecture: {
-          modality: model.modelType || 'text',
-          input_modalities: [model.modelType || 'text'],
-          output_modalities: [model.modelType || 'text'],
-          tokenizer: '',
-          instruct_type: null,
-        },
-        pricing: {
-          prompt: roundToFiveDecimals(model.input_cost),
-          completion: roundToFiveDecimals(model.output_cost),
-          request: 0,
-          image: 0,
-          web_search: 0,
-          internal_reasoning: 0,
-        },
-        per_request_limits: null,
-        top_provider: null,
-        upstream_provider_id: providerId,
-        enabled: model.isEnabled !== false,
-      });
-
-      form.reset({
-        name: model.name,
-        description: model.description || '',
-        context_length: model.contextLength || 4096,
-        prompt: roundToFiveDecimals(model.input_cost),
-        completion: roundToFiveDecimals(model.output_cost),
-        enabled: model.isEnabled !== false,
-      });
-    }
-  }, [providerId, model, form]);
-
-  useEffect(() => {
-    if (isOpen && providerId) {
-      loadAdminModel();
-    } else if (isOpen && !providerId) {
-      console.error('EditModelForm opened without providerId', {
-        model,
-        providerId,
-      });
-      toast.error('Missing provider information for this model');
-    }
-  }, [isOpen, providerId, model, loadAdminModel]);
-
-  const onSubmit = async (data: EditModelFormData) => {
-    if (!providerId) {
-      console.error('onSubmit called without providerId', {
-        model,
-        providerId,
-      });
-      toast.error('Missing provider ID - cannot update model');
-      return;
-    }
-
-    if (!adminModelData) {
-      console.error('onSubmit called without adminModelData', {
-        model,
-        providerId,
-        adminModelData,
-      });
-      toast.error('Model data not loaded - please try reopening the form');
-      return;
-    }
-
-    setIsSubmitting(true);
-    try {
-      const payload = {
-        id: adminModelData.id,
-        name: data.name,
-        description: data.description || '',
-        created: adminModelData.created || Math.floor(Date.now() / 1000),
-        context_length: data.context_length,
-        architecture: adminModelData.architecture || {
-          modality: 'text',
-          input_modalities: ['text'],
-          output_modalities: ['text'],
-          tokenizer: '',
-          instruct_type: null,
-        },
-        pricing: {
-          prompt: roundToFiveDecimals(data.prompt),
-          completion: roundToFiveDecimals(data.completion),
-          request: 0,
-          image: 0,
-          web_search: 0,
-          internal_reasoning: 0,
-        },
-        per_request_limits: adminModelData.per_request_limits,
-        top_provider: adminModelData.top_provider,
-        upstream_provider_id: providerId,
-        enabled: data.enabled,
-      };
-
-      if (isNewOverride) {
-        await AdminService.createProviderModel(providerId, payload);
-        toast.success('Model override created successfully!');
-      } else {
-        await AdminService.updateProviderModel(
-          providerId,
-          adminModelData.id,
-          payload
-        );
-        toast.success('Model updated successfully!');
-      }
-
-      onModelUpdate?.();
-      onCancel?.();
-    } catch (error) {
-      const action = isNewOverride ? 'create' : 'update';
-      toast.error(`Failed to ${action} model. Please try again.`);
-      console.error(`Error ${action}ing model:`, error);
-    } finally {
-      setIsSubmitting(false);
-    }
-  };
-
-  const handleClose = () => {
-    if (!isSubmitting) {
-      onCancel?.();
-    }
-  };
-
-  return (
-    <Dialog open={isOpen} onOpenChange={handleClose}>
-      <DialogContent className='max-h-[90vh] overflow-y-auto sm:max-w-[600px]'>
-        <DialogHeader>
-          <DialogTitle className='flex items-center gap-2'>
-            <Edit3 className='h-5 w-5' />
-            {isNewOverride ? 'Create Model Override' : 'Edit Model Override'}
-          </DialogTitle>
-          <DialogDescription>
-            {isNewOverride
-              ? `Create an override for &quot;${model.name}&quot;`
-              : `Update the model override for &quot;${model.name}&quot;`}
-          </DialogDescription>
-        </DialogHeader>
-
-        <Form {...form}>
-          <form onSubmit={form.handleSubmit(onSubmit)} className='space-y-4'>
-            <div className='grid grid-cols-1 gap-4 sm:grid-cols-2'>
-              <FormField
-                control={form.control}
-                name='name'
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel>Display Name *</FormLabel>
-                    <FormControl>
-                      <Input
-                        placeholder='e.g., GPT-4'
-                        {...field}
-                        className='w-full'
-                      />
-                    </FormControl>
-                    <FormDescription>
-                      Custom display name for the model
-                    </FormDescription>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-
-              <FormField
-                control={form.control}
-                name='context_length'
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel>Context Length *</FormLabel>
-                    <FormControl>
-                      <Input
-                        type='number'
-                        min='0'
-                        placeholder='4096'
-                        value={field.value ?? ''}
-                        onChange={(e) => {
-                          const value = e.target.value;
-                          field.onChange(
-                            value === '' ? 0 : parseInt(value, 10) || 0
-                          );
-                        }}
-                        onBlur={(e) => {
-                          const value = parseInt(e.target.value, 10);
-                          field.onChange(
-                            Number.isNaN(value) ? 0 : Math.max(0, value)
-                          );
-                        }}
-                        className='w-full'
-                      />
-                    </FormControl>
-                    <FormDescription>
-                      Maximum context window size
-                    </FormDescription>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-            </div>
-
-            <FormField
-              control={form.control}
-              name='description'
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Description</FormLabel>
-                  <FormControl>
-                    <Textarea
-                      placeholder='Brief description of the model...'
-                      {...field}
-                      rows={3}
-                      className='w-full'
-                    />
-                  </FormControl>
-                  <FormDescription>
-                    Optional description or notes about the model
-                  </FormDescription>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <div className='grid grid-cols-1 gap-4 sm:grid-cols-2'>
-              <FormField
-                control={form.control}
-                name='prompt'
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel>Input Cost (per 1M tokens) *</FormLabel>
-                    <FormControl>
-                      <Input
-                        type='number'
-                        step='0.00001'
-                        min='0'
-                        placeholder='5.00000'
-                        value={field.value ?? ''}
-                        onChange={(e) => {
-                          const value = e.target.value;
-                          field.onChange(value === '' ? 0 : parseFloat(value));
-                        }}
-                        onBlur={(e) => {
-                          const value = parseFloat(e.target.value);
-                          field.onChange(roundToFiveDecimals(value));
-                        }}
-                        className='w-full'
-                      />
-                    </FormControl>
-                    <FormDescription>
-                      Cost in USD per 1,000,000 input tokens (max 5 decimals)
-                    </FormDescription>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-
-              <FormField
-                control={form.control}
-                name='completion'
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel>Output Cost (per 1M tokens) *</FormLabel>
-                    <FormControl>
-                      <Input
-                        type='number'
-                        step='0.00001'
-                        min='0'
-                        placeholder='15.00000'
-                        value={field.value ?? ''}
-                        onChange={(e) => {
-                          const value = e.target.value;
-                          field.onChange(value === '' ? 0 : parseFloat(value));
-                        }}
-                        onBlur={(e) => {
-                          const value = parseFloat(e.target.value);
-                          field.onChange(roundToFiveDecimals(value));
-                        }}
-                        className='w-full'
-                      />
-                    </FormControl>
-                    <FormDescription>
-                      Cost in USD per 1,000,000 output tokens (max 5 decimals)
-                    </FormDescription>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-            </div>
-
-            <FormField
-              control={form.control}
-              name='enabled'
-              render={({ field }) => (
-                <FormItem className='flex flex-row items-center justify-between rounded-lg border p-4'>
-                  <div className='space-y-0.5'>
-                    <FormLabel className='text-base'>Model Enabled</FormLabel>
-                    <FormDescription>
-                      Enable or disable this model override
-                    </FormDescription>
-                  </div>
-                  <FormControl>
-                    <Switch
-                      checked={field.value}
-                      onCheckedChange={field.onChange}
-                    />
-                  </FormControl>
-                </FormItem>
-              )}
-            />
-
-            <div className='flex justify-end gap-2 pt-4'>
-              <Button
-                type='button'
-                variant='outline'
-                onClick={handleClose}
-                disabled={isSubmitting}
-              >
-                Cancel
-              </Button>
-              <Button type='submit' disabled={isSubmitting}>
-                {isSubmitting ? (
-                  <>
-                    <Loader2 className='mr-2 h-4 w-4 animate-spin' />
-                    {isNewOverride ? 'Creating...' : 'Updating...'}
-                  </>
-                ) : isNewOverride ? (
-                  'Create Override'
-                ) : (
-                  'Update Model'
-                )}
-              </Button>
-            </div>
-          </form>
-        </Form>
-      </DialogContent>
-    </Dialog>
-  );
-}

ui/components/landing/api-key-manager.tsx

@@ -239,7 +239,7 @@ export function ApiKeyManager({
                     className='gap-2'
                   >
                     <Trash2 className='h-4 w-4' />
-                    {isRefunding ? 'Processing...' : 'Refund & Delete Key'}
+                    {isRefunding ? 'Processing...' : 'Refund Key'}
                   </Button>
                   <span className='text-muted-foreground text-xs'>
                     Burns the key and returns a fresh Cashu token.

ui/components/landing/cashu-payment-workflow.tsx

@@ -1,16 +1,17 @@
 'use client';
 
 import { type JSX, useCallback, useState } from 'react';
-import { Copy, RefreshCcw, Trash2 } from 'lucide-react';
+import { Copy, RefreshCcw } from 'lucide-react';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
 import { toast } from 'sonner';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Button } from '@/components/ui/button';
 import { Textarea } from '@/components/ui/textarea';
-import { Input } from '@/components/ui/input';
 import { Separator } from '@/components/ui/separator';
 import { KeyOptions } from '@/components/key-options';
-import { WalletBalanceStats } from './wallet-balance-stats';
-import type { ChildKeyInfo, WalletSnapshot } from './key-info-details';
+import { ApiKeyInput } from '../api-key-input';
+import type { WalletSnapshot } from './key-info-details';
+import { useWalletInfo } from '@/hooks/use-wallet-info';
 
 export type RefundReceipt = {
   token?: string;
@@ -29,80 +30,41 @@ interface CashuPaymentWorkflowProps {
   onRefundComplete?: (receipt: RefundReceipt) => void;
 }
 
-async function fetchWalletInfo(
-  baseUrl: string,
-  apiKey: string
-): Promise<WalletSnapshot> {
-  const response = await fetch(`${baseUrl}/v1/balance/info`, {
-    cache: 'no-store',
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${apiKey}`,
-    },
-  });
-
-  if (!response.ok) {
-    const errorText = await response.text();
-    throw new Error(errorText || 'Unable to load wallet info');
-  }
-
-  const payload = (await response.json()) as {
-    api_key: string;
-    balance: number;
-    reserved?: number;
-    is_child: boolean;
-    parent_key: string | null;
-    total_requests: number;
-    total_spent: number;
-    balance_limit: number | null;
-    balance_limit_reset: string | null;
-    validity_date: number | null;
-    child_keys?: ChildKeyInfo[];
-  };
-
-  return {
-    apiKey: payload.api_key || apiKey,
-    balanceMsats: payload.balance ?? 0,
-    reservedMsats: payload.reserved ?? 0,
-    isChild: payload.is_child,
-    parentKey: payload.parent_key,
-    totalRequests: payload.total_requests,
-    totalSpent: payload.total_spent,
-    balanceLimit: payload.balance_limit,
-    balanceLimitReset: payload.balance_limit_reset,
-    validityDate: payload.validity_date,
-    childKeys: payload.child_keys,
-  };
-}
-
 function formatSats(msats: number): string {
   return new Intl.NumberFormat('en-US').format(Math.floor(msats / 1000));
 }
 
+function formatMsats(msats: number): string {
+  return new Intl.NumberFormat('en-US').format(msats);
+}
+
 export function CashuPaymentWorkflow({
   baseUrl,
   apiKey = '',
-  walletInfo = null,
+  walletInfo: propWalletInfo = null,
   onApiKeyCreated,
-  onApiKeyChanged,
   onWalletInfoUpdated,
-  onRefundComplete,
 }: CashuPaymentWorkflowProps): JSX.Element {
   const [initialToken, setInitialToken] = useState('');
   const [topupToken, setTopupToken] = useState('');
   const [apiKeyInput, setApiKeyInput] = useState(apiKey);
   const [isCreatingKey, setIsCreatingKey] = useState(false);
   const [isTopupLoading, setIsTopupLoading] = useState(false);
-  const [isRefunding, setIsRefunding] = useState(false);
-  const [isSyncingBalance, setIsSyncingBalance] = useState(false);
-  const [hasInteractedManage, setHasInteractedManage] = useState(false);
   const [hasInteractedTopup, setHasInteractedTopup] = useState(false);
   const [balanceLimit, setBalanceLimit] = useState<string>('');
   const [balanceLimitReset, setBalanceLimitReset] = useState<string>('');
   const [validityDate, setValidityDate] = useState<string>('');
+  const [error, setError] = useState<string | null>(null);
 
   const activeApiKey = apiKeyInput.trim();
 
+  const {
+    data: queryWalletInfo,
+    refetch,
+    isFetching,
+  } = useWalletInfo(baseUrl, activeApiKey);
+  const walletInfo = propWalletInfo ?? queryWalletInfo ?? null;
+
   const handleCopy = useCallback(async (value: string): Promise<void> => {
     if (!value) {
       return;
@@ -203,20 +165,18 @@ export function CashuPaymentWorkflow({
       return;
     }
 
-    setIsSyncingBalance(true);
+    setError(null);
     try {
-      const snapshot = await fetchWalletInfo(baseUrl, activeApiKey);
-      onWalletInfoUpdated?.(snapshot);
+      await refetch();
       toast.success('Balance synced');
     } catch (error) {
       console.error(error);
-      toast.error(
-        error instanceof Error ? error.message : 'Failed to sync balance'
-      );
-    } finally {
-      setIsSyncingBalance(false);
+      const message =
+        error instanceof Error ? error.message : 'Failed to sync balance';
+      setError(message);
+      toast.error(message);
     }
-  }, [activeApiKey, baseUrl, onWalletInfoUpdated]);
+  }, [activeApiKey, refetch]);
 
   const handleTopup = useCallback(async (): Promise<void> => {
     if (!activeApiKey) {
@@ -245,59 +205,25 @@ export function CashuPaymentWorkflow({
       const payload = (await response.json()) as { msats: number };
       toast.success(`Added ${formatSats(payload.msats)} sats`);
       setTopupToken('');
-      const snapshot = await fetchWalletInfo(baseUrl, activeApiKey);
-      onApiKeyCreated?.(snapshot.apiKey, snapshot);
+      await refetch();
     } catch (error) {
       console.error(error);
       toast.error(error instanceof Error ? error.message : 'Top-up failed');
     } finally {
       setIsTopupLoading(false);
     }
-  }, [activeApiKey, baseUrl, topupToken, onApiKeyCreated]);
-
-  const handleRefund = useCallback(async (): Promise<void> => {
-    if (!activeApiKey) {
-      toast.error('Paste an API key first');
-      return;
-    }
-
-    setIsRefunding(true);
-    try {
-      const response = await fetch(`${baseUrl}/v1/balance/refund`, {
-        method: 'POST',
-        headers: {
-          Authorization: `Bearer ${activeApiKey}`,
-        },
-      });
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(errorText || 'Refund failed');
-      }
-      const payload = (await response.json()) as RefundReceipt;
-      onRefundComplete?.(payload);
-      onWalletInfoUpdated?.(null);
-      setApiKeyInput('');
-      toast.success('Refund requested');
-    } catch (error) {
-      console.error(error);
-      toast.error(error instanceof Error ? error.message : 'Refund failed');
-    } finally {
-      setIsRefunding(false);
-    }
-  }, [activeApiKey, baseUrl, onRefundComplete, onWalletInfoUpdated]);
+  }, [activeApiKey, baseUrl, topupToken, refetch]);
 
   const handleApiKeyChange = useCallback(
     (newKey: string) => {
       setApiKeyInput(newKey);
-      onApiKeyChanged?.(newKey);
       if (newKey !== apiKey) {
         onWalletInfoUpdated?.(null);
       }
     },
-    [apiKey, onApiKeyChanged, onWalletInfoUpdated]
+    [apiKey, onWalletInfoUpdated]
   );
 
-  const showManageDetails = hasInteractedManage || Boolean(walletInfo);
   const showTopupDetails = hasInteractedTopup || topupToken.trim().length > 0;
   const canTopup = Boolean(activeApiKey);
   const showCreateDetails = initialToken.trim().length > 0;
@@ -365,40 +291,72 @@ export function CashuPaymentWorkflow({
             )}
           </header>
           <div className='flex flex-col gap-2 sm:flex-row'>
-            <Input
+            <ApiKeyInput
               value={apiKeyInput}
-              onChange={(event) => handleApiKeyChange(event.target.value)}
-              placeholder='sk-...'
-              className='font-mono text-sm'
-              onFocus={() => setHasInteractedManage(true)}
+              onApiKeyChange={handleApiKeyChange}
             />
             <div className='flex gap-2'>
               <Button
                 variant='outline'
                 size='icon'
-                className='h-10 w-10'
                 onClick={() => handleCopy(activeApiKey)}
                 disabled={!activeApiKey}
               >
                 <Copy className='h-4 w-4' />
               </Button>
+
               <Button
                 variant='secondary'
                 size='sm'
                 className='gap-1'
                 onClick={handleSyncBalance}
-                disabled={isSyncingBalance || !activeApiKey}
+                disabled={isFetching || !activeApiKey}
               >
-                <RefreshCcw className='h-4 w-4' />
+                <RefreshCcw
+                  className={`h-4 w-4 ${isFetching ? 'animate-spin' : ''}`}
+                />
                 Sync
               </Button>
             </div>
           </div>
-          {showManageDetails && (
-            <WalletBalanceStats
-              balanceMsats={walletInfo?.balanceMsats}
-              reservedMsats={walletInfo?.reservedMsats}
-            />
+          {walletInfo && (
+            <div className='bg-muted/30 mt-2 space-y-2 rounded-lg p-3'>
+              <div className='flex items-center justify-between'>
+                <span className='text-muted-foreground text-sm'>
+                  Spendable Balance
+                </span>
+                <span className='text-primary font-mono text-sm font-medium'>
+                  {formatSats(walletInfo.balanceMsats)} sats
+                </span>
+              </div>
+              <div className='flex items-center justify-between'>
+                <span className='text-muted-foreground text-sm'>
+                  Total Requests
+                </span>
+                <span className='font-mono text-sm font-medium'>
+                  {walletInfo.totalRequests}
+                </span>
+              </div>
+              <div className='flex items-center justify-between'>
+                <span className='text-muted-foreground text-sm'>
+                  Total Spent
+                </span>
+                <div className='text-right'>
+                  <p className='font-mono text-sm font-medium'>
+                    {formatSats(walletInfo.totalSpent)} sats
+                  </p>
+                  <p className='text-muted-foreground font-mono text-[0.6rem]'>
+                    {formatMsats(walletInfo.totalSpent)} msats
+                  </p>
+                </div>
+              </div>
+            </div>
+          )}
+          {error && (
+            <Alert variant='destructive' className='mt-2'>
+              <AlertTitle>Error</AlertTitle>
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
           )}
         </section>
 
@@ -444,28 +402,6 @@ export function CashuPaymentWorkflow({
             </div>
           )}
         </section>
-
-        <Separator />
-
-        <section className='space-y-2'>
-          <header className='text-muted-foreground flex items-center justify-between text-[0.7rem] tracking-wider'>
-            <span>4 · Refund</span>
-          </header>
-          <div className='flex flex-wrap gap-2'>
-            <Button
-              onClick={handleRefund}
-              disabled={isRefunding || !activeApiKey}
-              variant='destructive'
-              className='gap-2'
-            >
-              <Trash2 className='h-4 w-4' />
-              {isRefunding ? 'Processing…' : 'Refund remaining balance'}
-            </Button>
-            <span className='text-muted-foreground text-xs'>
-              Burns the key and returns a fresh Cashu token.
-            </span>
-          </div>
-        </section>
       </CardContent>
     </Card>
   );

ui/components/landing/cheat-sheet.tsx

@@ -18,7 +18,6 @@ import {
   type RefundReceipt,
 } from './cashu-payment-workflow';
 import { LightningPaymentWorkflow } from './lightning-payment-workflow';
-import { ApiKeyManager } from './api-key-manager';
 import { KeyInfoDetails, type WalletSnapshot } from './key-info-details';
 import { ChildKeyCreator } from '@/components/child-key-creator';
 
@@ -135,8 +134,8 @@ export function CheatSheet(): JSX.Element {
 
   const handleRefundComplete = useCallback((receipt: RefundReceipt) => {
     setRefundReceipt(receipt);
-    setWalletInfo(null);
-    setApiKeyInput('');
+    // setWalletInfo(null); // Keep info
+    // setApiKeyInput(''); // Keep input
   }, []);
 
   const handleRefreshInfo = useCallback(async (): Promise<void> => {
@@ -391,12 +390,11 @@ export function CheatSheet(): JSX.Element {
         </section>
 
         <Tabs defaultValue='cashu' className='w-full'>
-          <TabsList className='grid w-full grid-cols-5'>
+          <TabsList className='grid w-full grid-cols-4'>
             <TabsTrigger value='cashu'>Cashu</TabsTrigger>
             <TabsTrigger value='lightning'>Lightning</TabsTrigger>
-            <TabsTrigger value='manage'>Manage Keys</TabsTrigger>
-            <TabsTrigger value='details'>Key Details</TabsTrigger>
             <TabsTrigger value='child-keys'>Child Keys</TabsTrigger>
+            <TabsTrigger value='management'>Key Management</TabsTrigger>
           </TabsList>
 
           <TabsContent value='cashu' className='space-y-4'>
@@ -413,8 +411,8 @@ export function CheatSheet(): JSX.Element {
             />
           </TabsContent>
 
-          <TabsContent value='manage' className='space-y-4'>
-            <ApiKeyManager
+          <TabsContent value='management' className='space-y-4'>
+            <KeyInfoDetails
               baseUrl={normalizedBaseUrl}
               apiKey={apiKeyInput}
               walletInfo={walletInfo}
@@ -445,7 +443,7 @@ export function CheatSheet(): JSX.Element {
                     <Textarea
                       value={refundToken}
                       readOnly
-                      rows={4}
+                      rows={15}
                       className='font-mono text-xs'
                     />
                   </div>
@@ -454,16 +452,6 @@ export function CheatSheet(): JSX.Element {
             )}
           </TabsContent>
 
-          <TabsContent value='details' className='space-y-4'>
-            <KeyInfoDetails
-              baseUrl={normalizedBaseUrl}
-              apiKey={apiKeyInput}
-              walletInfo={walletInfo}
-              onApiKeyChanged={handleApiKeyChanged}
-              onWalletInfoUpdated={handleWalletInfoUpdated}
-            />
-          </TabsContent>
-
           <TabsContent value='child-keys' className='space-y-4'>
             <ChildKeyCreator
               baseUrl={normalizedBaseUrl}

ui/components/landing/key-info-details.tsx

@@ -1,8 +1,10 @@
 'use client';
 
-import { type JSX, useState, useCallback, useEffect } from 'react';
-import { Copy, RefreshCcw, RotateCcw } from 'lucide-react';
+import { useWalletInfo } from '@/hooks/use-wallet-info';
+import type { RefundReceipt } from './cashu-payment-workflow';
 import { toast } from 'sonner';
+import { ApiKeyInput } from '../api-key-input';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
 import {
   Card,
   CardContent,
@@ -12,8 +14,9 @@ import {
 } from '@/components/ui/card';
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
-import { Input } from '@/components/ui/input';
 import { WalletService } from '@/lib/api/services/wallet';
+import React, { useState, useCallback, useEffect } from 'react';
+import { Copy, RefreshCcw, RotateCcw, Trash2 } from 'lucide-react';
 
 export type ChildKeyInfo = {
   api_key: string;
@@ -44,68 +47,44 @@ interface KeyInfoDetailsProps {
   walletInfo?: WalletSnapshot | null;
   onApiKeyChanged?: (apiKey: string) => void;
   onWalletInfoUpdated?: (walletInfo: WalletSnapshot | null) => void;
+  onRefundComplete?: (receipt: RefundReceipt) => void;
 }
 
 export function KeyInfoDetails({
   baseUrl,
   apiKey = '',
-  walletInfo = null,
+  walletInfo: propWalletInfo = null,
   onApiKeyChanged,
   onWalletInfoUpdated,
-}: KeyInfoDetailsProps): JSX.Element {
+  onRefundComplete,
+}: KeyInfoDetailsProps): React.ReactNode {
   const [apiKeyInput, setApiKeyInput] = useState(apiKey);
-  const [isRefreshing, setIsRefreshing] = useState(false);
   const [isResetting, setIsResetting] = useState<string | null>(null);
+  const [isRefunding, setIsRefunding] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const {
+    data: queryWalletInfo,
+    refetch,
+    isFetching,
+  } = useWalletInfo(baseUrl, apiKeyInput);
+  const walletInfo = propWalletInfo ?? queryWalletInfo ?? null;
 
   // Sync internal state with props if they change
   useEffect(() => {
     setApiKeyInput(apiKey);
   }, [apiKey]);
 
-  const fetchDetails = useCallback(
-    async (keyToFetch: string) => {
-      setIsRefreshing(true);
-      try {
-        const response = await fetch(`${baseUrl}/v1/balance/info`, {
-          headers: { Authorization: `Bearer ${keyToFetch}` },
-        });
-        if (!response.ok) {
-          throw new Error('Failed to fetch key info');
-        }
-        const payload = await response.json();
-        const snapshot: WalletSnapshot = {
-          apiKey: payload.api_key || keyToFetch,
-          balanceMsats: payload.balance ?? 0,
-          reservedMsats: payload.reserved ?? 0,
-          isChild: payload.is_child,
-          parentKey: payload.parent_key,
-          totalRequests: payload.total_requests,
-          totalSpent: payload.total_spent,
-          balanceLimit: payload.balance_limit,
-          balanceLimitReset: payload.balance_limit_reset,
-          validityDate: payload.validity_date,
-          childKeys: payload.child_keys,
-        };
-        onWalletInfoUpdated?.(snapshot);
-        toast.success('Key details synced');
-      } catch (error) {
-        toast.error(
-          error instanceof Error ? error.message : 'Failed to fetch details'
-        );
-      } finally {
-        setIsRefreshing(false);
-      }
-    },
-    [baseUrl, onWalletInfoUpdated]
-  );
-
-  const handleRefresh = async () => {
+  const handleRefresh = async (e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
     if (!apiKeyInput) return;
-    await fetchDetails(apiKeyInput);
+    await refetch();
   };
 
   const handleKeyChange = (newKey: string) => {
     setApiKeyInput(newKey);
+    setError(null);
     onApiKeyChanged?.(newKey);
     // Optionally clear info when key changes
     if (newKey !== apiKey) {
@@ -125,7 +104,7 @@ export function KeyInfoDetails({
     try {
       await WalletService.resetChildKeySpent(baseUrl, apiKeyInput, childKey);
       toast.success('Child key spent reset');
-      await fetchDetails(apiKeyInput);
+      await refetch();
     } catch (error) {
       toast.error(
         error instanceof Error ? error.message : 'Failed to reset child key'
@@ -135,6 +114,36 @@ export function KeyInfoDetails({
     }
   };
 
+  const handleRefund = useCallback(async (): Promise<void> => {
+    if (!apiKeyInput) {
+      toast.error('Paste an API key first');
+      return;
+    }
+
+    setIsRefunding(true);
+    try {
+      const response = await fetch(`${baseUrl}/v1/balance/refund`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${apiKeyInput}`,
+        },
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(errorText || 'Refund failed');
+      }
+      const receipt = (await response.json()) as RefundReceipt;
+      onRefundComplete?.(receipt);
+      toast.success('Refund completed');
+      await refetch();
+    } catch (error) {
+      console.error(error);
+      toast.error(error instanceof Error ? error.message : 'Refund failed');
+    } finally {
+      setIsRefunding(false);
+    }
+  }, [apiKeyInput, baseUrl, onRefundComplete, refetch]);
+
   const formatSats = (msats: number) =>
     new Intl.NumberFormat('en-US').format(Math.floor(msats / 1000));
   const formatMsats = (msats: number) =>
@@ -153,17 +162,11 @@ export function KeyInfoDetails({
         </CardHeader>
         <CardContent>
           <div className='flex flex-col gap-2 sm:flex-row'>
-            <Input
-              value={apiKeyInput}
-              onChange={(e) => handleKeyChange(e.target.value)}
-              placeholder='sk-...'
-              className='font-mono text-sm'
-            />
+            <ApiKeyInput value={apiKeyInput} onApiKeyChange={handleKeyChange} />
             <div className='flex gap-2'>
               <Button
                 variant='outline'
                 size='icon'
-                className='h-10 w-10 shrink-0'
                 onClick={() => handleCopy(apiKeyInput)}
                 disabled={!apiKeyInput}
               >
@@ -174,15 +177,22 @@ export function KeyInfoDetails({
                 size='sm'
                 className='min-w-[80px] gap-1'
                 onClick={handleRefresh}
-                disabled={isRefreshing || !apiKeyInput}
+                disabled={isFetching || !apiKeyInput}
+                type='button'
               >
                 <RefreshCcw
-                  className={`h-4 w-4 ${isRefreshing ? 'animate-spin' : ''}`}
+                  className={`h-8 w-4 ${isFetching ? 'animate-spin' : ''}`}
                 />
-                {isRefreshing ? 'Syncing...' : 'Sync'}
+                {isFetching ? 'Syncing...' : 'Sync'}
               </Button>
             </div>
           </div>
+          {error && (
+            <Alert variant='destructive' className='mt-2'>
+              <AlertTitle>Error</AlertTitle>
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
+          )}
         </CardContent>
       </Card>
 
@@ -228,6 +238,14 @@ export function KeyInfoDetails({
                     {formatDate(walletInfo.validityDate)}
                   </span>
                 </div>
+              </CardContent>
+            </Card>
+
+            <Card>
+              <CardHeader className='pb-2'>
+                <CardTitle className='text-lg'>Infos</CardTitle>
+              </CardHeader>
+              <CardContent className='space-y-4'>
                 <div className='flex items-center justify-between'>
                   <span className='text-muted-foreground text-sm'>
                     Spendable Balance
@@ -236,14 +254,6 @@ export function KeyInfoDetails({
                     {formatSats(walletInfo.balanceMsats)} sats
                   </span>
                 </div>
-              </CardContent>
-            </Card>
-
-            <Card>
-              <CardHeader className='pb-2'>
-                <CardTitle className='text-lg'>Consumption</CardTitle>
-              </CardHeader>
-              <CardContent className='space-y-4'>
                 <div className='flex items-center justify-between'>
                   <span className='text-muted-foreground text-sm'>
                     Total Requests
@@ -390,18 +400,16 @@ export function KeyInfoDetails({
               </Card>
             )}
 
-          <div className='flex justify-center'>
+          <div className='flex justify-center gap-4'>
             <Button
-              variant='ghost'
+              onClick={handleRefund}
+              disabled={isRefunding || !apiKeyInput}
+              variant='destructive'
               size='sm'
-              onClick={handleRefresh}
-              disabled={isRefreshing}
-              className='text-muted-foreground'
+              className='gap-2'
             >
-              <RefreshCcw
-                className={`mr-2 h-3 w-3 ${isRefreshing ? 'animate-spin' : ''}`}
-              />
-              Last synced: {new Date().toLocaleTimeString()}
+              <Trash2 className='h-4 w-4' />
+              {isRefunding ? 'Processing...' : 'Refund Key'}
             </Button>
           </div>
         </>

ui/components/landing/key-info-display.tsx

@@ -0,0 +1,198 @@
+'use client';
+
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+} from '@/components/ui/card';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Copy, RotateCcw } from 'lucide-react';
+import type { WalletSnapshot } from './key-info-details';
+import { toast } from 'sonner';
+
+interface KeyInfoDisplayProps {
+  walletInfo: WalletSnapshot;
+  onResetSpent?: (childKey: string) => Promise<void>;
+  isResetting?: string | null;
+}
+
+const formatSats = (msats: number) =>
+  new Intl.NumberFormat('en-US').format(Math.floor(msats / 1000));
+const formatMsats = (msats: number) =>
+  new Intl.NumberFormat('en-US').format(msats);
+const formatDate = (timestamp: number | null) =>
+  timestamp ? new Date(timestamp * 1000).toLocaleDateString() : 'Never';
+
+export function KeyInfoDisplay({
+  walletInfo,
+  onResetSpent,
+  isResetting,
+}: KeyInfoDisplayProps) {
+  const handleCopy = (value: string) => {
+    navigator.clipboard.writeText(value);
+    toast.success('Copied to clipboard');
+  };
+
+  return (
+    <div className='space-y-4'>
+      <div className='grid gap-4 md:grid-cols-2'>
+        <Card>
+          <CardHeader className='pb-2'>
+            <CardTitle className='text-lg'>Status & Identity</CardTitle>
+          </CardHeader>
+          <CardContent className='space-y-4'>
+            <div className='flex items-center justify-between'>
+              <span className='text-muted-foreground text-sm'>Type</span>
+              <Badge variant={walletInfo.isChild ? 'secondary' : 'default'}>
+                {walletInfo.isChild ? 'Child Key' : 'Parent Key'}
+              </Badge>
+            </div>
+            {walletInfo.parentKey && (
+              <div className='space-y-1'>
+                <span className='text-muted-foreground text-xs tracking-wider'>
+                  Parent Key
+                </span>
+                <div className='flex items-center gap-2'>
+                  <code className='bg-muted flex-1 rounded px-2 py-1 font-mono text-xs break-all'>
+                    {walletInfo.parentKey}
+                  </code>
+                  <Button
+                    variant='ghost'
+                    size='icon'
+                    className='h-8 w-8'
+                    onClick={() => handleCopy(walletInfo.parentKey!)}
+                  >
+                    <Copy className='h-4 w-4' />
+                  </Button>
+                </div>
+              </div>
+            )}
+            <div className='flex items-center justify-between'>
+              <span className='text-muted-foreground text-sm'>Validity</span>
+              <span className='text-sm font-medium'>
+                {formatDate(walletInfo.validityDate)}
+              </span>
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className='pb-2'>
+            <CardTitle className='text-lg'>Infos</CardTitle>
+          </CardHeader>
+          <CardContent className='space-y-4'>
+            <div className='flex items-center justify-between'>
+              <span className='text-muted-foreground text-sm'>
+                Spendable Balance
+              </span>
+              <span className='text-primary font-mono text-sm font-medium'>
+                {formatSats(walletInfo.balanceMsats)} sats
+              </span>
+            </div>
+            <div className='flex items-center justify-between'>
+              <span className='text-muted-foreground text-sm'>
+                Total Requests
+              </span>
+              <span className='font-mono text-sm font-medium'>
+                {walletInfo.totalRequests}
+              </span>
+            </div>
+            <div className='flex items-center justify-between'>
+              <span className='text-muted-foreground text-sm'>Total Spent</span>
+              <div className='text-right'>
+                <p className='font-mono text-sm font-medium'>
+                  {formatSats(walletInfo.totalSpent)} sats
+                </p>
+                <p className='text-muted-foreground font-mono text-[0.6rem]'>
+                  {formatMsats(walletInfo.totalSpent)} msats
+                </p>
+              </div>
+            </div>
+            {walletInfo.balanceLimit !== null && (
+              <div className='space-y-2'>
+                <div className='flex items-center justify-between'>
+                  <span className='text-muted-foreground text-sm'>
+                    Spend Limit
+                  </span>
+                  <span className='font-mono text-sm font-medium'>
+                    {formatSats(walletInfo.balanceLimit)} sats
+                  </span>
+                </div>
+                {walletInfo.balanceLimitReset && (
+                  <div className='flex items-center justify-between'>
+                    <span className='text-muted-foreground text-sm'>
+                      Reset Policy
+                    </span>
+                    <Badge variant='outline' className='capitalize'>
+                      {walletInfo.balanceLimitReset}
+                    </Badge>
+                  </div>
+                )}
+              </div>
+            )}
+          </CardContent>
+        </Card>
+      </div>
+
+      {!walletInfo.isChild &&
+        walletInfo.childKeys &&
+        walletInfo.childKeys.length > 0 && (
+          <Card>
+            <CardHeader>
+              <CardTitle className='text-lg'>
+                Child Keys ({walletInfo.childKeys.length})
+              </CardTitle>
+              <CardDescription>
+                Secondary keys using this account&apos;s balance
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className='space-y-4'>
+                {walletInfo.childKeys.map((ck) => (
+                  <div
+                    key={ck.api_key}
+                    className='space-y-3 rounded-lg border p-4'
+                  >
+                    <div className='flex items-center justify-between gap-4'>
+                      <code className='bg-muted flex-1 rounded px-2 py-1 font-mono text-xs break-all'>
+                        {ck.api_key}
+                      </code>
+                      <div className='flex gap-1'>
+                        <Button
+                          variant='ghost'
+                          size='icon'
+                          className='h-8 w-8'
+                          onClick={() => handleCopy(ck.api_key)}
+                        >
+                          <Copy className='h-4 w-4' />
+                        </Button>
+                        {onResetSpent && (
+                          <Button
+                            variant='ghost'
+                            size='icon'
+                            className='text-destructive h-8 w-8'
+                            title='Reset consumption'
+                            disabled={isResetting === ck.api_key}
+                            onClick={() => onResetSpent(ck.api_key)}
+                          >
+                            {isResetting === ck.api_key ? (
+                              <RotateCcw className='h-4 w-4 animate-spin' />
+                            ) : (
+                              <RotateCcw className='h-4 w-4' />
+                            )}
+                          </Button>
+                        )}
+                      </div>
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </CardContent>
+          </Card>
+        )}
+    </div>
+  );
+}

ui/components/model-tester.tsx

@@ -197,7 +197,11 @@ export function ModelTester({ models }: ModelTesterProps) {
     testModelMutation.mutate(request);
   };
 
-  const enabledModels = models.filter((model) => model.isEnabled);
+  const enabledModels = Array.from(
+    new Map(
+      models.filter((model) => model.isEnabled).map((m) => [m.id, m])
+    ).values()
+  );
   const credentials = selectedModel ? getModelCredentials(selectedModel) : null;
 
   return (

ui/components/models-page.tsx

@@ -23,7 +23,7 @@ import {
 import { Skeleton } from '@/components/ui/skeleton';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 
-export default function ModelsPage() {
+export function ModelsPage() {
   const [filteredModels, setFilteredModels] = useState<Model[] | undefined>(
     undefined
   );
@@ -124,12 +124,14 @@ export default function ModelsPage() {
             >
               Basic Testing
             </TabsTrigger>
+            {/*
             <TabsTrigger
               value='test-api'
               className='h-9 snap-start px-2 text-[13px] sm:h-10 sm:px-2.5 sm:text-sm'
             >
               API Endpoints
             </TabsTrigger>
+            */}
           </TabsList>
 
           <TabsContent value='manage' className='mt-0'>

ui/components/provider-card.tsx

@@ -20,6 +20,7 @@ import {
   Trash2,
   Key,
   RotateCcw,
+  Clock,
 } from 'lucide-react';
 import { ProviderBalance } from '@/components/provider-balance';
 import { ProviderModelsPanel } from '@/components/provider-models-panel';
@@ -54,6 +55,7 @@ interface ProviderCardProps {
   onDeleteModel: (modelId: string) => void;
   onOverrideModel: (model: AdminModel) => void;
   onUpdateApiKey: (newKey: string) => void;
+  onManageFeeSchedules: () => void;
   availableMints: string[];
 }
 
@@ -74,6 +76,7 @@ export function ProviderCard({
   onDeleteModel,
   onOverrideModel,
   onUpdateApiKey,
+  onManageFeeSchedules,
 }: ProviderCardProps) {
   const queryClient = useQueryClient();
   const [isKeyModalOpen, setIsKeyModalOpen] = useState(false);
@@ -113,6 +116,14 @@ export function ProviderCard({
               >
                 {provider.enabled ? 'Enabled' : 'Disabled'}
               </Badge>
+              <Badge variant='outline' className='w-fit'>
+                Fee: {provider.provider_fee}x
+                {provider.provider_fee !== provider.provider_fee_default && (
+                  <span className='text-muted-foreground ml-1 font-normal'>
+                    (default: {provider.provider_fee_default}x)
+                  </span>
+                )}
+              </Badge>
             </div>
             <CardDescription className='break-all'>
               {provider.base_url}
@@ -189,6 +200,22 @@ export function ProviderCard({
               )}
             </Button>
 
+            <Button
+              variant='outline'
+              size='sm'
+              onClick={onManageFeeSchedules}
+              className='justify-center gap-1.5'
+              title='Manage fee schedules'
+            >
+              <Clock className='h-4 w-4' />
+              <span>Fees</span>
+              {(provider.provider_fee_schedules?.length ?? 0) > 0 && (
+                <Badge variant='secondary' className='ml-0.5 h-4 px-1 text-xs'>
+                  {provider.provider_fee_schedules!.length}
+                </Badge>
+              )}
+            </Button>
+
             <Button
               variant='outline'
               size='sm'

ui/components/provider-fee-schedule-modal.tsx

@@ -0,0 +1,500 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { Plus, Trash2 } from 'lucide-react';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Badge } from '@/components/ui/badge';
+import { Checkbox } from '@/components/ui/checkbox';
+import {
+  AdminService,
+  FeeTimeRange,
+  UpstreamProvider,
+} from '@/lib/api/services/admin';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ProviderFeeScheduleModalProps {
+  providers: UpstreamProvider[];
+  /** Pre-selected provider IDs (e.g. clicked from a card). Empty = all selected. */
+  initialSelectedIds?: number[];
+  isOpen: boolean;
+  onClose: () => void;
+  onSuccess: () => void;
+}
+
+interface RangeRow extends FeeTimeRange {
+  _id: number;
+}
+
+// ---------------------------------------------------------------------------
+// Overlap helpers (mirrored from backend logic)
+// ---------------------------------------------------------------------------
+
+function _toMinutes(t: string): number {
+  const [h, m] = t.split(':').map(Number);
+  return h * 60 + m;
+}
+
+function _rangeIntervals(start: string, end: string): Array<[number, number]> {
+  const s = _toMinutes(start);
+  const e = _toMinutes(end);
+  if (s < e) return [[s, e]];
+  if (s > e)
+    return [
+      [s, 1440],
+      [0, e],
+    ];
+  return [[0, 1440]];
+}
+
+function _intervalsOverlap(a: [number, number], b: [number, number]): boolean {
+  return a[0] < b[1] && b[0] < a[1];
+}
+
+function findOverlappingIds(rows: RangeRow[]): Set<number> {
+  const overlapping = new Set<number>();
+  for (let i = 0; i < rows.length; i++) {
+    for (let j = i + 1; j < rows.length; j++) {
+      const a = rows[i];
+      const b = rows[j];
+      if (!a.start_time || !a.end_time || !b.start_time || !b.end_time)
+        continue;
+      for (const ia of _rangeIntervals(a.start_time, a.end_time)) {
+        for (const ib of _rangeIntervals(b.start_time, b.end_time)) {
+          if (_intervalsOverlap(ia, ib)) {
+            overlapping.add(a._id);
+            overlapping.add(b._id);
+          }
+        }
+      }
+    }
+  }
+  return overlapping;
+}
+
+function isValidTime(t: string): boolean {
+  return /^([01]\d|2[0-3]):([0-5]\d)$/.test(t);
+}
+
+function utcTimeNow(): string {
+  const now = new Date();
+  return now.toUTCString().slice(17, 22);
+}
+
+// Browsers may return "HH:MM:SS" from time inputs — strip seconds.
+function normalizeTime(v: string): string {
+  return v.slice(0, 5);
+}
+
+let _nextId = 1;
+
+function makeRow(partial: Partial<FeeTimeRange> = {}): RangeRow {
+  return {
+    _id: _nextId++,
+    start_time: partial.start_time ?? '',
+    end_time: partial.end_time ?? '',
+    provider_fee: partial.provider_fee ?? 1.05,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Sub-component: read-only range list under a provider
+// ---------------------------------------------------------------------------
+
+function ProviderRangePreview({ schedules }: { schedules: FeeTimeRange[] }) {
+  if (schedules.length === 0) {
+    return (
+      <p className='text-muted-foreground pl-7 text-xs'>
+        No scheduled ranges — default fee always applies.
+      </p>
+    );
+  }
+  return (
+    <ul className='space-y-0.5 pl-7'>
+      {schedules.map((s, i) => (
+        <li key={i} className='flex items-center gap-2 text-xs'>
+          <span className='text-muted-foreground font-mono'>
+            {s.start_time} → {s.end_time} UTC
+          </span>
+          <Badge variant='outline' className='py-0 font-mono text-xs'>
+            ×{s.provider_fee.toFixed(3)}
+          </Badge>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Modal
+// ---------------------------------------------------------------------------
+
+export function ProviderFeeScheduleModal({
+  providers,
+  initialSelectedIds,
+  isOpen,
+  onClose,
+  onSuccess,
+}: ProviderFeeScheduleModalProps) {
+  const queryClient = useQueryClient();
+
+  const [selectedIds, setSelectedIds] = useState<Set<number>>(new Set());
+  const [rows, setRows] = useState<RangeRow[]>([]);
+  const [enforceOverride, setEnforceOverride] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [clearing, setClearing] = useState(false);
+
+  // Reset state when modal opens. If a single provider is pre-selected,
+  // pre-populate the editor with its existing schedule so the user can edit it.
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const ids =
+      initialSelectedIds && initialSelectedIds.length > 0
+        ? new Set(initialSelectedIds)
+        : new Set(providers.map((p) => p.id));
+
+    setSelectedIds(ids);
+    setEnforceOverride(false);
+
+    if (initialSelectedIds && initialSelectedIds.length === 1) {
+      const provider = providers.find((p) => p.id === initialSelectedIds[0]);
+      const existing = provider?.provider_fee_schedules ?? [];
+      setRows(existing.length > 0 ? existing.map((s) => makeRow(s)) : []);
+      setEnforceOverride(true);
+    } else {
+      setRows([]);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen]);
+
+  const overlapping = findOverlappingIds(rows);
+  const allSelected =
+    providers.length > 0 && selectedIds.size === providers.length;
+  const noneSelected = selectedIds.size === 0;
+
+  const toggleProvider = (id: number) => {
+    setSelectedIds((prev) => {
+      const next = new Set(prev);
+      next.has(id) ? next.delete(id) : next.add(id);
+      return next;
+    });
+  };
+
+  const toggleAll = () => {
+    setSelectedIds(
+      allSelected ? new Set() : new Set(providers.map((p) => p.id))
+    );
+  };
+
+  const addRow = () => setRows((prev) => [...prev, makeRow()]);
+
+  const removeRow = (id: number) =>
+    setRows((prev) => prev.filter((r) => r._id !== id));
+
+  const updateRow = (
+    id: number,
+    field: keyof FeeTimeRange,
+    value: string | number
+  ) =>
+    setRows((prev) =>
+      prev.map((r) => (r._id === id ? { ...r, [field]: value } : r))
+    );
+
+  const hasValidationErrors =
+    noneSelected ||
+    rows.some(
+      (r) =>
+        !isValidTime(r.start_time) ||
+        !isValidTime(r.end_time) ||
+        r.provider_fee <= 0
+    ) ||
+    overlapping.size > 0;
+
+  const handleSave = async () => {
+    if (hasValidationErrors) return;
+    const newSchedules: FeeTimeRange[] = rows.map(
+      ({ start_time, end_time, provider_fee }) => ({
+        start_time,
+        end_time,
+        provider_fee,
+      })
+    );
+    setSaving(true);
+    try {
+      await Promise.all(
+        [...selectedIds].map((id) => {
+          const provider = providers.find((p) => p.id === id);
+          const existing = provider?.provider_fee_schedules ?? [];
+
+          let finalSchedules: FeeTimeRange[];
+          if (enforceOverride) {
+            finalSchedules = newSchedules;
+          } else {
+            // Only override ranges that overlap with ANY of the new ranges.
+            // Keep existing non-overlapping ranges.
+            const keptExisting = existing.filter((ex) => {
+              return !newSchedules.some((nw) =>
+                _rangeIntervals(ex.start_time, ex.end_time).some((ia) =>
+                  _rangeIntervals(nw.start_time, nw.end_time).some((ib) =>
+                    _intervalsOverlap(ia, ib)
+                  )
+                )
+              );
+            });
+            finalSchedules = [...keptExisting, ...newSchedules];
+          }
+
+          return AdminService.updateFeeSchedules(id, finalSchedules);
+        })
+      );
+      queryClient.invalidateQueries({ queryKey: ['upstream-providers'] });
+      toast.success(
+        `Fee schedules saved for ${selectedIds.size} provider${selectedIds.size > 1 ? 's' : ''}`
+      );
+      onSuccess();
+      onClose();
+    } catch (err) {
+      toast.error(
+        `Failed to save: ${err instanceof Error ? err.message : 'Unknown error'}`
+      );
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleClearAll = async () => {
+    if (noneSelected) return;
+    setClearing(true);
+    try {
+      await Promise.all(
+        [...selectedIds].map((id) => AdminService.deleteFeeSchedules(id))
+      );
+      queryClient.invalidateQueries({ queryKey: ['upstream-providers'] });
+      setRows([]);
+      toast.success(
+        `Fee schedules cleared for ${selectedIds.size} provider${selectedIds.size > 1 ? 's' : ''}`
+      );
+      onSuccess();
+    } catch (err) {
+      toast.error(
+        `Failed to clear: ${err instanceof Error ? err.message : 'Unknown error'}`
+      );
+    } finally {
+      setClearing(false);
+    }
+  };
+
+  return (
+    <Dialog open={isOpen} onOpenChange={(open) => !open && onClose()}>
+      <DialogContent className='max-h-[90vh] overflow-y-auto sm:max-w-[660px]'>
+        <DialogHeader>
+          <DialogTitle>Fee Schedules</DialogTitle>
+          <DialogDescription>
+            Select providers and configure time-based fee ranges (UTC). Outside
+            scheduled ranges each provider&apos;s default fee applies. Current
+            UTC time:{' '}
+            <Badge variant='outline' className='font-mono'>
+              {utcTimeNow()}
+            </Badge>
+          </DialogDescription>
+        </DialogHeader>
+
+        {/* Provider selection with existing-range read view */}
+        <div className='space-y-2'>
+          <div className='flex items-center justify-between'>
+            <Label className='text-sm font-medium'>Apply to providers</Label>
+            <button
+              onClick={toggleAll}
+              className='text-muted-foreground hover:text-foreground text-xs underline-offset-2 hover:underline'
+            >
+              {allSelected ? 'Deselect all' : 'Select all'}
+            </button>
+          </div>
+          <div className='divide-y rounded-md border'>
+            {providers.map((p) => (
+              <div key={p.id} className='space-y-1.5 px-3 py-2'>
+                <label className='hover:bg-muted/50 flex cursor-pointer items-center gap-3 rounded'>
+                  <Checkbox
+                    checked={selectedIds.has(p.id)}
+                    onCheckedChange={() => toggleProvider(p.id)}
+                  />
+                  <span className='flex-1 text-sm font-medium'>
+                    {p.provider_type}
+                  </span>
+                  <span className='text-muted-foreground truncate text-xs'>
+                    {p.base_url}
+                  </span>
+                </label>
+                <ProviderRangePreview
+                  schedules={p.provider_fee_schedules ?? []}
+                />
+              </div>
+            ))}
+          </div>
+          {noneSelected && (
+            <p className='text-destructive text-xs'>
+              Select at least one provider.
+            </p>
+          )}
+        </div>
+
+        {/* Fee range editor */}
+        <div className='space-y-4'>
+          <div className='flex items-center justify-between'>
+            <Label className='text-sm font-medium'>
+              New schedule{' '}
+              {!enforceOverride && (
+                <span className='text-muted-foreground font-normal'>
+                  (merges with existing ranges, overriding only overlaps)
+                </span>
+              )}
+            </Label>
+            <div className='flex items-center space-x-2'>
+              <Checkbox
+                id='enforce-override'
+                checked={enforceOverride}
+                onCheckedChange={(checked) => setEnforceOverride(!!checked)}
+              />
+              <label
+                htmlFor='enforce-override'
+                className='text-xs leading-none font-medium peer-disabled:cursor-not-allowed peer-disabled:opacity-70'
+              >
+                Enforce overriding everything
+              </label>
+            </div>
+          </div>
+
+          <div className='space-y-2'>
+            {rows.length === 0 && (
+              <p className='text-muted-foreground rounded-md border border-dashed p-4 text-center text-sm'>
+                No ranges configured — saving with no ranges will clear
+                schedules.
+              </p>
+            )}
+
+            {rows.map((row) => {
+              const isOverlap = overlapping.has(row._id);
+              const badTime =
+                (row.start_time && !isValidTime(row.start_time)) ||
+                (row.end_time && !isValidTime(row.end_time));
+              const badFee = row.provider_fee <= 1.0;
+              const hasError = isOverlap || badTime || badFee;
+
+              return (
+                <div
+                  key={row._id}
+                  className={`flex flex-col gap-2 rounded-md border p-3 sm:flex-row sm:items-end ${
+                    hasError ? 'border-destructive bg-destructive/5' : ''
+                  }`}
+                >
+                  <div className='flex flex-1 flex-col gap-1'>
+                    <Label className='text-xs'>Start (UTC)</Label>
+                    <input
+                      type='time'
+                      value={row.start_time}
+                      onChange={(e) =>
+                        updateRow(
+                          row._id,
+                          'start_time',
+                          normalizeTime(e.target.value)
+                        )
+                      }
+                      className='border-input bg-background ring-offset-background focus-visible:ring-ring flex h-10 w-full rounded-md border px-3 py-2 font-mono text-sm focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50'
+                    />
+                  </div>
+                  <div className='flex flex-1 flex-col gap-1'>
+                    <Label className='text-xs'>End (UTC)</Label>
+                    <input
+                      type='time'
+                      value={row.end_time}
+                      onChange={(e) =>
+                        updateRow(
+                          row._id,
+                          'end_time',
+                          normalizeTime(e.target.value)
+                        )
+                      }
+                      className='border-input bg-background ring-offset-background focus-visible:ring-ring flex h-10 w-full rounded-md border px-3 py-2 font-mono text-sm focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50'
+                    />
+                  </div>
+                  <div className='flex flex-1 flex-col gap-1'>
+                    <Label className='text-xs'>Fee multiplier</Label>
+                    <Input
+                      type='number'
+                      step='0.001'
+                      min='0.001'
+                      placeholder='1.05'
+                      value={row.provider_fee}
+                      onChange={(e) =>
+                        updateRow(
+                          row._id,
+                          'provider_fee',
+                          parseFloat(e.target.value) || 0
+                        )
+                      }
+                    />
+                  </div>
+                  <Button
+                    variant='ghost'
+                    size='icon'
+                    className='text-destructive hover:text-destructive shrink-0'
+                    onClick={() => removeRow(row._id)}
+                  >
+                    <Trash2 className='h-4 w-4' />
+                  </Button>
+                </div>
+              );
+            })}
+          </div>
+
+          {overlapping.size > 0 && (
+            <p className='text-destructive text-xs'>
+              Some ranges overlap — fix them before saving.
+            </p>
+          )}
+        </div>
+
+        <div>
+          <Button variant='outline' size='sm' onClick={addRow}>
+            <Plus className='mr-1.5 h-4 w-4' />
+            Add Range
+          </Button>
+        </div>
+
+        <DialogFooter className='gap-2'>
+          <Button
+            variant='ghost'
+            onClick={handleClearAll}
+            disabled={clearing || noneSelected}
+            className='text-destructive hover:text-destructive mr-auto'
+          >
+            {clearing ? 'Clearing…' : 'Clear Selected'}
+          </Button>
+          <Button variant='outline' onClick={onClose}>
+            Cancel
+          </Button>
+          <Button onClick={handleSave} disabled={saving || hasValidationErrors}>
+            {saving
+              ? 'Saving…'
+              : `Save to ${selectedIds.size} provider${selectedIds.size !== 1 ? 's' : ''}`}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

ui/components/provider-form-fields.tsx

@@ -202,26 +202,34 @@ export function ProviderFormFields({
 
       <div className='grid gap-2'>
         <Label htmlFor={`${idPrefix}provider_fee`}>
-          Provider Fee (Multiplier)
+          {mode === 'edit'
+            ? 'Default Provider Fee (Multiplier)'
+            : 'Provider Fee (Multiplier)'}
         </Label>
         <Input
           id={`${idPrefix}provider_fee`}
           type='number'
           step='0.001'
           min='1.0'
-          value={formData.provider_fee || ''}
-          onChange={(e) =>
-            setFormData((prev) => ({
-              ...prev,
-              provider_fee: e.target.value
-                ? parseFloat(e.target.value)
-                : undefined,
-            }))
+          value={
+            (mode === 'edit'
+              ? formData.provider_fee_default
+              : formData.provider_fee) || ''
           }
+          onChange={(e) => {
+            const val = e.target.value ? parseFloat(e.target.value) : undefined;
+            setFormData((prev) =>
+              mode === 'edit'
+                ? { ...prev, provider_fee_default: val }
+                : { ...prev, provider_fee: val }
+            );
+          }}
           placeholder={providerFeePlaceholder}
         />
         <p className='text-muted-foreground text-xs'>
-          1.01 means +1% e.g. currency exchange, card fees, etc.
+          {mode === 'edit'
+            ? 'This is the default fee when no schedule is active. Updates will not affect currently active scheduled fees.'
+            : '1.01 means +1% e.g. currency exchange, card fees, etc.'}
         </p>
       </div>
 

ui/components/providers/RoutstrCreateKeySection.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useState } from 'react';
+import { useState } from 'react';
 import Image from 'next/image';
 import { Copy, Loader2, Zap, KeyRound } from 'lucide-react';
 import { toast } from 'sonner';
@@ -10,7 +10,6 @@ import { Input } from '@/components/ui/input';
 import { Textarea } from '@/components/ui/textarea';
 import { Label } from '@/components/ui/label';
 import { Badge } from '@/components/ui/badge';
-import { Separator } from '@/components/ui/separator';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 
 interface RoutstrCreateKeySectionProps {

ui/components/settings/admin-settings.tsx

@@ -26,6 +26,7 @@ interface SettingsData {
   description?: string;
   npub?: string;
   nsec?: string;
+  enable_analytics_sharing?: boolean;
   upstream_api_key?: string;
   http_url?: string;
   onion_url?: string;
@@ -43,6 +44,7 @@ const HANDLED_KEYS = [
   'nsec',
   'cashu_mints',
   'relays',
+  'enable_analytics_sharing',
   'admin_password',
   'id',
   'updated_at',
@@ -366,6 +368,7 @@ export function AdminSettings() {
   const nostrChanged = ['npub', 'nsec'].some(hasFieldChanged);
   const cashuMintsChanged = hasFieldChanged('cashu_mints');
   const relaysChanged = hasFieldChanged('relays');
+  const analyticsSharingChanged = hasFieldChanged('enable_analytics_sharing');
   const advancedKeys = Object.keys(settings).filter(
     (key) => !HANDLED_KEYS.includes(key) && !IGNORED_KEYS.includes(key)
   );
@@ -397,6 +400,7 @@ export function AdminSettings() {
     resetFields(['relays']);
     setNewRelay('');
   };
+  const resetAnalyticsSharing = () => resetFields(['enable_analytics_sharing']);
   const resetAdvanced = () => resetFields(advancedKeys);
 
   if (loading) {
@@ -686,6 +690,52 @@ export function AdminSettings() {
           ) : null}
         </Card>
 
+        {/* Analytics Sharing */}
+        <Card>
+          <CardHeader>
+            <CardTitle>Analytics Sharing</CardTitle>
+            <CardDescription>
+              Publish aggregate usage stats to Nostr for external dashboards
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <div className='flex items-center justify-between space-y-0 py-1'>
+              <div className='space-y-1'>
+                <Label htmlFor='enable_analytics_sharing'>
+                  Share analytics to Nostr
+                </Label>
+                <p className='text-muted-foreground text-sm'>
+                  When enabled, Routstr periodically publishes aggregate model
+                  usage and revenue stats.
+                </p>
+              </div>
+              <Switch
+                id='enable_analytics_sharing'
+                checked={Boolean(settings.enable_analytics_sharing ?? true)}
+                onCheckedChange={(checked) =>
+                  handleInputChange('enable_analytics_sharing', checked)
+                }
+              />
+            </div>
+          </CardContent>
+          {analyticsSharingChanged ? (
+            <CardFooter className='justify-start'>
+              <div className='flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center'>
+                <Button
+                  variant='outline'
+                  onClick={resetAnalyticsSharing}
+                  disabled={loading || saving}
+                >
+                  Cancel
+                </Button>
+                <Button onClick={handleSave} disabled={loading || saving}>
+                  {saving ? 'Saving...' : 'Save'}
+                </Button>
+              </div>
+            </CardFooter>
+          ) : null}
+        </Card>
+
         {/* Other Settings */}
         <Card>
           <CardHeader>

ui/components/settings/cli-tokens-settings.tsx

@@ -0,0 +1,265 @@
+'use client';
+
+import * as React from 'react';
+import { useState, useEffect, useCallback } from 'react';
+import {
+  AdminService,
+  type CliTokenListItem,
+  type CliTokenCreated,
+} from '@/lib/api/services/admin';
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+} from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Skeleton } from '@/components/ui/skeleton';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { AlertCircle, Copy, Trash2, Check } from 'lucide-react';
+import { toast } from 'sonner';
+
+function formatTs(ts: number | null): string {
+  if (!ts) return '—';
+  return new Date(ts * 1000).toLocaleString();
+}
+
+export function CliTokensSettings(): React.ReactElement {
+  const [tokens, setTokens] = useState<CliTokenListItem[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [name, setName] = useState('');
+  const [expiresInDays, setExpiresInDays] = useState<string>('');
+  const [creating, setCreating] = useState(false);
+  const [newToken, setNewToken] = useState<CliTokenCreated | null>(null);
+  const [copied, setCopied] = useState(false);
+
+  const loadTokens = useCallback(async (): Promise<void> => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await AdminService.listCliTokens();
+      setTokens(data);
+    } catch (err: unknown) {
+      const message =
+        err instanceof Error ? err.message : 'Failed to load tokens';
+      setError(message);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadTokens();
+  }, [loadTokens]);
+
+  async function handleCreate(): Promise<void> {
+    const trimmed = name.trim();
+    if (!trimmed) {
+      toast.error('Name is required');
+      return;
+    }
+    const days = expiresInDays.trim()
+      ? Number.parseInt(expiresInDays.trim(), 10)
+      : undefined;
+    if (days !== undefined && (Number.isNaN(days) || days <= 0)) {
+      toast.error('Expiry must be a positive number of days');
+      return;
+    }
+
+    setCreating(true);
+    try {
+      const created = await AdminService.createCliToken(trimmed, days);
+      setNewToken(created);
+      setName('');
+      setExpiresInDays('');
+      await loadTokens();
+      toast.success('Token created. Copy it now — it will not be shown again.');
+    } catch (err: unknown) {
+      const message =
+        err instanceof Error ? err.message : 'Failed to create token';
+      toast.error(message);
+    } finally {
+      setCreating(false);
+    }
+  }
+
+  async function handleRevoke(id: string): Promise<void> {
+    if (
+      !confirm('Revoke this token? Any CLI/agent using it will lose access.')
+    ) {
+      return;
+    }
+    try {
+      await AdminService.revokeCliToken(id);
+      await loadTokens();
+      toast.success('Token revoked');
+    } catch (err: unknown) {
+      const message =
+        err instanceof Error ? err.message : 'Failed to revoke token';
+      toast.error(message);
+    }
+  }
+
+  async function handleCopy(): Promise<void> {
+    if (!newToken) return;
+    await navigator.clipboard.writeText(newToken.token);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  }
+
+  return (
+    <div className='space-y-6'>
+      <Card>
+        <CardHeader>
+          <CardTitle>Create CLI Token</CardTitle>
+          <CardDescription>
+            Generate a long-lived bearer token for the Routstr CLI or AI agents.
+            Use this token in <code>~/.routstr/config.json</code> or with{' '}
+            <code>routstr init --token &lt;token&gt;</code>.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className='space-y-4'>
+          {newToken && (
+            <Alert className='border-green-500/50 bg-green-500/10'>
+              <AlertDescription className='space-y-3'>
+                <div className='font-medium text-green-700 dark:text-green-400'>
+                  Token created. Copy it now — it will not be shown again.
+                </div>
+                <div className='flex items-center gap-2'>
+                  <code className='bg-muted flex-1 rounded px-3 py-2 text-xs break-all'>
+                    {newToken.token}
+                  </code>
+                  <Button
+                    type='button'
+                    variant='outline'
+                    size='sm'
+                    onClick={handleCopy}
+                  >
+                    {copied ? (
+                      <Check className='h-4 w-4' />
+                    ) : (
+                      <Copy className='h-4 w-4' />
+                    )}
+                  </Button>
+                </div>
+                <Button
+                  type='button'
+                  variant='ghost'
+                  size='sm'
+                  onClick={() => setNewToken(null)}
+                >
+                  Dismiss
+                </Button>
+              </AlertDescription>
+            </Alert>
+          )}
+          <div className='grid grid-cols-1 gap-4 md:grid-cols-2'>
+            <div className='space-y-2'>
+              <Label htmlFor='cli-token-name'>Name</Label>
+              <Input
+                id='cli-token-name'
+                placeholder='e.g. dev-laptop, ci-runner'
+                value={name}
+                onChange={(e) => setName(e.target.value)}
+                disabled={creating}
+              />
+            </div>
+            <div className='space-y-2'>
+              <Label htmlFor='cli-token-expiry'>
+                Expires in days (optional)
+              </Label>
+              <Input
+                id='cli-token-expiry'
+                type='number'
+                min='1'
+                placeholder='Never expires if blank'
+                value={expiresInDays}
+                onChange={(e) => setExpiresInDays(e.target.value)}
+                disabled={creating}
+              />
+            </div>
+          </div>
+          <Button onClick={handleCreate} disabled={creating || !name.trim()}>
+            {creating ? 'Creating…' : 'Create Token'}
+          </Button>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Active Tokens</CardTitle>
+          <CardDescription>
+            Tokens authorize CLI/agent calls to admin endpoints. Revoke any
+            token that may have been exposed.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          {error && (
+            <Alert variant='destructive' className='mb-4'>
+              <AlertCircle className='h-4 w-4' />
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
+          )}
+          {loading ? (
+            <div className='space-y-2'>
+              <Skeleton className='h-12 w-full' />
+              <Skeleton className='h-12 w-full' />
+            </div>
+          ) : tokens.length === 0 ? (
+            <p className='text-muted-foreground text-sm'>
+              No tokens yet. Create one above.
+            </p>
+          ) : (
+            <div className='overflow-x-auto'>
+              <table className='w-full text-sm'>
+                <thead>
+                  <tr className='text-muted-foreground border-b text-left'>
+                    <th className='py-2 pr-4 font-medium'>Name</th>
+                    <th className='py-2 pr-4 font-medium'>Token</th>
+                    <th className='py-2 pr-4 font-medium'>Created</th>
+                    <th className='py-2 pr-4 font-medium'>Last used</th>
+                    <th className='py-2 pr-4 font-medium'>Expires</th>
+                    <th className='py-2 font-medium'></th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {tokens.map((t) => (
+                    <tr key={t.id} className='border-b last:border-0'>
+                      <td className='py-2 pr-4'>{t.name}</td>
+                      <td className='py-2 pr-4 font-mono text-xs'>
+                        {t.token_preview}
+                      </td>
+                      <td className='text-muted-foreground py-2 pr-4'>
+                        {formatTs(t.created_at)}
+                      </td>
+                      <td className='text-muted-foreground py-2 pr-4'>
+                        {formatTs(t.last_used_at)}
+                      </td>
+                      <td className='text-muted-foreground py-2 pr-4'>
+                        {t.expires_at ? formatTs(t.expires_at) : 'Never'}
+                      </td>
+                      <td className='py-2'>
+                        <Button
+                          type='button'
+                          variant='ghost'
+                          size='sm'
+                          onClick={() => void handleRevoke(t.id)}
+                        >
+                          <Trash2 className='h-4 w-4' />
+                        </Button>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

ui/components/site-header.tsx

@@ -23,7 +23,7 @@ const PAGE_META: Record<string, { title: string; description: string }> = {
     title: 'System Logs',
     description: 'Inspect request and application logs.',
   },
-  '/models': {
+  '/model': {
     title: 'Models',
     description: 'Manage model catalog and provider mappings.',
   },

ui/components/top-models-usage-chart.tsx

@@ -0,0 +1,872 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { ExpandIcon, Minimize2Icon } from 'lucide-react';
+import { Bar, BarChart, CartesianGrid, XAxis, YAxis } from 'recharts';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import {
+  ChartConfig,
+  ChartContainer,
+  ChartTooltip,
+} from '@/components/ui/chart';
+import { useIsMobile } from '@/hooks/use-mobile';
+import { type ModelUsageMix } from '@/lib/api/services/admin';
+import type { DisplayUnit } from '@/lib/types/units';
+import { cn } from '@/lib/utils';
+
+interface TopModelsUsageChartProps {
+  mix: ModelUsageMix;
+  displayUnit: DisplayUnit;
+  usdPerSat: number | null;
+}
+
+type ChartMode = 'requests' | 'revenue' | 'tokens';
+
+interface TooltipRow {
+  color: string;
+  dataKey: string;
+  label: string;
+  value: number;
+}
+
+type LeaderboardTrend = 'up' | 'down' | 'flat' | 'new';
+
+interface LeaderboardRow {
+  chartDataKey: string | null;
+  displayName: string;
+  model: string;
+  provider: string;
+  rank: number;
+  totalRaw: number;
+  trend: LeaderboardTrend;
+  trendPercent: number | null;
+}
+
+function parseBucketDate(value: string): Date | null {
+  const normalized = value.includes('T')
+    ? value
+    : `${value.replace(' ', 'T')}Z`;
+  const parsed = new Date(normalized);
+  if (!Number.isNaN(parsed.getTime())) {
+    return parsed;
+  }
+  const fallback = new Date(value);
+  return Number.isNaN(fallback.getTime()) ? null : fallback;
+}
+
+function hueFromString(input: string): number {
+  let hash = 0;
+  for (let i = 0; i < input.length; i += 1) {
+    hash = (hash << 5) - hash + input.charCodeAt(i);
+    hash |= 0;
+  }
+  return Math.abs(hash) % 360;
+}
+
+function getSeriesColor(model: string, index: number): string {
+  const palette = [
+    'var(--chart-1)',
+    'var(--chart-2)',
+    'var(--chart-3)',
+    'var(--chart-4)',
+    'var(--chart-5)',
+    '#f59e0b',
+    '#06b6d4',
+    '#8b5cf6',
+    '#f97316',
+    '#34d399',
+  ];
+
+  if (index < palette.length) {
+    return palette[index];
+  }
+
+  const hue = (hueFromString(model) + index * 23) % 360;
+  return `hsl(${hue} 70% 56%)`;
+}
+
+function formatTooltipTimestamp(
+  label: string,
+  intervalMinutes: number,
+  hoursBack: number
+): string {
+  const date = parseBucketDate(label);
+  if (!date) {
+    return label;
+  }
+  const shouldShowTime = intervalMinutes <= 6 * 60 || hoursBack <= 48;
+  if (shouldShowTime) {
+    return date.toLocaleString([], {
+      month: 'long',
+      day: 'numeric',
+      year: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+  }
+  return date.toLocaleString([], {
+    month: 'long',
+    day: 'numeric',
+    year: 'numeric',
+  });
+}
+
+function formatAxisTimestamp(
+  timestamp: string,
+  hasMultipleDays: boolean,
+  intervalMinutes: number,
+  hoursBack: number
+): string {
+  const date = parseBucketDate(timestamp);
+  if (!date) {
+    return '';
+  }
+
+  const shouldShowTime = intervalMinutes <= 6 * 60 || hoursBack <= 48;
+  if (shouldShowTime && hasMultipleDays) {
+    return date.toLocaleString([], {
+      month: 'short',
+      day: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+  }
+
+  if (shouldShowTime) {
+    return date.toLocaleTimeString([], {
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+  }
+
+  if (intervalMinutes >= 24 * 60 && hoursBack >= 24 * 180) {
+    return date.toLocaleDateString([], {
+      month: 'short',
+      year: '2-digit',
+    });
+  }
+
+  if (hasMultipleDays) {
+    return date.toLocaleDateString([], {
+      month: 'short',
+      day: 'numeric',
+    });
+  }
+
+  return date.toLocaleTimeString([], {
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+function convertRevenueMsats(
+  amountMsats: number,
+  displayUnit: DisplayUnit,
+  usdPerSat: number | null
+): number {
+  if (displayUnit === 'msat') {
+    return amountMsats;
+  }
+
+  const sats = amountMsats / 1000;
+  if (displayUnit === 'usd') {
+    return sats * (usdPerSat ?? 0);
+  }
+
+  return sats;
+}
+
+function prettifyProvider(provider: string): string {
+  const normalized = provider.trim().toLowerCase();
+  const aliasMap: Record<string, string> = {
+    'x ai': 'x-ai',
+    xai: 'x-ai',
+    'z ai': 'z-ai',
+    zai: 'z-ai',
+    open_ai: 'openai',
+    openai: 'openai',
+  };
+  if (aliasMap[normalized]) {
+    return aliasMap[normalized];
+  }
+  return normalized.replace(/[_-]+/g, ' ');
+}
+
+function detectProviderFromModel(model: string): string {
+  const value = model.toLowerCase();
+  if (value.includes('claude')) return 'anthropic';
+  if (value.includes('gpt') || value.includes('openai')) return 'openai';
+  if (value.includes('gemini')) return 'google';
+  if (
+    value.includes('grok') ||
+    value.includes('x-ai') ||
+    value.includes('xai')
+  ) {
+    return 'x-ai';
+  }
+  if (value.includes('deepseek')) return 'deepseek';
+  if (value.includes('minimax')) return 'minimax';
+  if (value.includes('kimi') || value.includes('moonshot')) return 'moonshot';
+  if (value.includes('mistral')) return 'mistral';
+  if (value.includes('qwen') || value.includes('alibaba')) return 'alibaba';
+  if (
+    value.includes('glm') ||
+    value.includes('z-ai') ||
+    value.includes('z ai')
+  ) {
+    return 'z-ai';
+  }
+  return 'unknown';
+}
+
+function getModelPresentation(model: string): {
+  displayName: string;
+  provider: string;
+} {
+  const trimmed = model.trim();
+  const slashIndex = trimmed.indexOf('/');
+  if (slashIndex > 0 && slashIndex < trimmed.length - 1) {
+    const provider = prettifyProvider(trimmed.slice(0, slashIndex));
+    const displayName = trimmed.slice(slashIndex + 1);
+    return { displayName, provider };
+  }
+
+  return {
+    displayName: trimmed,
+    provider: detectProviderFromModel(trimmed),
+  };
+}
+
+export function TopModelsUsageChart({
+  mix,
+  displayUnit,
+  usdPerSat,
+}: TopModelsUsageChartProps) {
+  const [mode, setMode] = useState<ChartMode>('requests');
+  const [hoveredSeriesKey, setHoveredSeriesKey] = useState<string | null>(null);
+  const [isChartPointerInside, setIsChartPointerInside] = useState(false);
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const isMobile = useIsMobile();
+  const containerRef = useRef<HTMLDivElement>(null);
+  const compactNumber = useMemo(
+    () =>
+      new Intl.NumberFormat('en-US', {
+        notation: 'compact',
+        maximumFractionDigits: 2,
+      }),
+    []
+  );
+  const mixTopModels = useMemo(
+    () => (Array.isArray(mix.top_models) ? mix.top_models : []),
+    [mix.top_models]
+  );
+  const mixMetrics = useMemo(
+    () => (Array.isArray(mix.metrics) ? mix.metrics : []),
+    [mix.metrics]
+  );
+
+  const chartModels = useMemo(() => mixTopModels.slice(0, 20), [mixTopModels]);
+  const leaderboardModels = useMemo(
+    () => mixTopModels.slice(0, 20),
+    [mixTopModels]
+  );
+  const revenueDisplayUnit: DisplayUnit = useMemo(() => {
+    if (displayUnit === 'usd' && usdPerSat === null) {
+      return 'sat';
+    }
+    return displayUnit;
+  }, [displayUnit, usdPerSat]);
+  const revenueUnitLabel =
+    revenueDisplayUnit === 'usd'
+      ? 'USD'
+      : revenueDisplayUnit === 'sat'
+        ? 'sats'
+        : revenueDisplayUnit === 'msat'
+          ? 'msats'
+          : revenueDisplayUnit;
+
+  const series = useMemo(
+    () =>
+      chartModels.map((model, index) => ({
+        requestsKey: `model_req_${index}`,
+        revenueKey: `model_rev_${index}`,
+        tokensKey: `model_tok_${index}`,
+        label: model,
+        color: getSeriesColor(model, index),
+      })),
+    [chartModels]
+  );
+
+  const chartData = useMemo(
+    () =>
+      mixMetrics.map((metric) => {
+        const modelCounts = metric.model_counts ?? {};
+        const modelRevenue = metric.model_revenue_msats ?? {};
+        const modelTokens = metric.model_tokens ?? {};
+        const point: Record<string, number | string> = {
+          timestamp: metric.timestamp,
+          total_successful: metric.total_successful,
+          total_revenue_msats: metric.total_revenue_msats,
+          total_tokens: metric.total_tokens,
+          others_requests: metric.others,
+          others_revenue_msats: metric.others_revenue_msats,
+          others_tokens: metric.others_tokens,
+        };
+
+        for (const item of series) {
+          point[item.requestsKey] = modelCounts[item.label] ?? 0;
+          point[item.revenueKey] = modelRevenue[item.label] ?? 0;
+          point[item.tokensKey] = modelTokens[item.label] ?? 0;
+        }
+
+        return point;
+      }),
+    [mixMetrics, series]
+  );
+
+  const hasMultipleDays = useMemo(() => {
+    const daySet = new Set(
+      chartData.map((item) =>
+        parseBucketDate(String(item.timestamp))?.toDateString()
+      )
+    );
+    return daySet.size > 1;
+  }, [chartData]);
+
+  const chartConfig = useMemo(() => {
+    const config: ChartConfig = {};
+    for (const item of series) {
+      config[item.requestsKey] = {
+        label: item.label,
+        color: item.color,
+      };
+      config[item.revenueKey] = {
+        label: item.label,
+        color: item.color,
+      };
+      config[item.tokensKey] = {
+        label: item.label,
+        color: item.color,
+      };
+    }
+    config.others_requests = {
+      label: 'Others',
+      color: '#6b7280',
+    };
+    config.others_revenue_msats = {
+      label: 'Others',
+      color: '#6b7280',
+    };
+    config.others_tokens = {
+      label: 'Others',
+      color: '#6b7280',
+    };
+    return config;
+  }, [series]);
+
+  useEffect(() => {
+    setHoveredSeriesKey(null);
+    setIsChartPointerInside(false);
+  }, [mode]);
+
+  useEffect(() => {
+    const handleFullscreenChange = () => {
+      setIsFullscreen(document.fullscreenElement === containerRef.current);
+    };
+
+    document.addEventListener('fullscreenchange', handleFullscreenChange);
+
+    return () => {
+      document.removeEventListener('fullscreenchange', handleFullscreenChange);
+    };
+  }, []);
+
+  const toggleFullscreen = async () => {
+    if (!containerRef.current) {
+      return;
+    }
+
+    try {
+      if (document.fullscreenElement === containerRef.current) {
+        await document.exitFullscreen();
+      } else {
+        await containerRef.current.requestFullscreen();
+      }
+    } catch (error) {
+      console.error('Failed to toggle top models chart fullscreen', error);
+    }
+  };
+
+  const formatValue = (rawValue: number): string => {
+    if (mode === 'requests') {
+      return compactNumber.format(rawValue);
+    }
+
+    if (mode === 'tokens') {
+      return compactNumber.format(rawValue);
+    }
+
+    const converted = convertRevenueMsats(
+      rawValue,
+      revenueDisplayUnit,
+      usdPerSat
+    );
+    const compact = compactNumber.format(converted);
+    if (revenueDisplayUnit === 'usd') {
+      return `$${compact}`;
+    }
+    return `${compact} ${revenueUnitLabel}`;
+  };
+
+  const activeSeries = series.map((item) => ({
+    dataKey:
+      mode === 'requests'
+        ? item.requestsKey
+        : mode === 'revenue'
+          ? item.revenueKey
+          : item.tokensKey,
+    name: item.label,
+    color: item.color,
+  }));
+  const othersKey = (
+    mode === 'requests'
+      ? 'others_requests'
+      : mode === 'revenue'
+        ? 'others_revenue_msats'
+        : 'others_tokens'
+  ) as 'others_requests' | 'others_revenue_msats' | 'others_tokens';
+  const activeSeriesKeys = [
+    ...activeSeries.map((item) => item.dataKey),
+    othersKey,
+  ];
+  const activeHoverSeriesKey =
+    hoveredSeriesKey && activeSeriesKeys.includes(hoveredSeriesKey)
+      ? hoveredSeriesKey
+      : null;
+  const getSeriesOpacity = (dataKey: string): number =>
+    activeHoverSeriesKey && activeHoverSeriesKey !== dataKey ? 0.18 : 1;
+  const formatLeaderboardTotal = (rawValue: number): string => {
+    if (mode === 'requests') {
+      return `${compactNumber.format(rawValue)} requests`;
+    }
+
+    if (mode === 'tokens') {
+      return `${compactNumber.format(rawValue)} tokens`;
+    }
+
+    const converted = convertRevenueMsats(
+      rawValue,
+      revenueDisplayUnit,
+      usdPerSat
+    );
+    const compact = compactNumber.format(converted);
+    if (revenueDisplayUnit === 'usd') {
+      return `$${compact}`;
+    }
+    return `${compact} ${revenueUnitLabel}`;
+  };
+  const formatTrendPercent = (value: number): string => {
+    const abs = Math.abs(value);
+    const rounded = abs >= 10 ? abs.toFixed(0) : abs.toFixed(1);
+    return rounded.replace(/\.0$/, '');
+  };
+  const leaderboardRows = useMemo<LeaderboardRow[]>(() => {
+    if (leaderboardModels.length === 0 || mixMetrics.length === 0) {
+      return [];
+    }
+
+    const windowSize = Math.floor(mixMetrics.length / 2);
+    const previousMetrics =
+      windowSize > 0 ? mixMetrics.slice(-windowSize * 2, -windowSize) : [];
+    const currentMetrics =
+      windowSize > 0 ? mixMetrics.slice(-windowSize) : mixMetrics;
+
+    const rows = leaderboardModels
+      .map((model) => {
+        const readMetric = (metric: (typeof mixMetrics)[number]): number =>
+          mode === 'requests'
+            ? ((metric.model_counts ?? {})[model] ?? 0)
+            : mode === 'revenue'
+              ? ((metric.model_revenue_msats ?? {})[model] ?? 0)
+              : ((metric.model_tokens ?? {})[model] ?? 0);
+
+        const totalRaw = mixMetrics.reduce(
+          (sum, metric) => sum + readMetric(metric),
+          0
+        );
+        const previousRaw = previousMetrics.reduce(
+          (sum, metric) => sum + readMetric(metric),
+          0
+        );
+        const currentRaw = currentMetrics.reduce(
+          (sum, metric) => sum + readMetric(metric),
+          0
+        );
+        const trendPercent =
+          previousRaw > 0
+            ? ((currentRaw - previousRaw) / previousRaw) * 100
+            : null;
+
+        let trend: LeaderboardTrend = 'flat';
+        if (previousRaw <= 0 && currentRaw > 0) {
+          trend = 'new';
+        } else if (trendPercent !== null && trendPercent > 0.5) {
+          trend = 'up';
+        } else if (trendPercent !== null && trendPercent < -0.5) {
+          trend = 'down';
+        }
+
+        const presentation = getModelPresentation(model);
+        const matchingSeries = series.find((item) => item.label === model);
+        const chartDataKey = matchingSeries
+          ? mode === 'requests'
+            ? matchingSeries.requestsKey
+            : mode === 'revenue'
+              ? matchingSeries.revenueKey
+              : matchingSeries.tokensKey
+          : null;
+
+        return {
+          chartDataKey,
+          displayName: presentation.displayName,
+          model,
+          provider: presentation.provider,
+          rank: 0,
+          totalRaw,
+          trend,
+          trendPercent,
+        } satisfies LeaderboardRow;
+      })
+      .filter((row) => row.totalRaw > 0)
+      .sort((a, b) => b.totalRaw - a.totalRaw)
+      .slice(0, 20)
+      .map((row, index) => ({
+        ...row,
+        rank: index + 1,
+      }));
+
+    return rows;
+  }, [leaderboardModels, mixMetrics, mode, series]);
+
+  if (chartData.length === 0) {
+    return null;
+  }
+
+  return (
+    <div ref={containerRef}>
+      <Card
+        className={cn(isFullscreen && 'h-full rounded-none border-0 ring-0')}
+      >
+        <CardHeader className='space-y-3 sm:space-y-4'>
+          <div className='flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between'>
+            <div className='min-w-0'>
+              <CardTitle className='text-base sm:text-lg'>
+                Model Usage
+              </CardTitle>
+              <p className='text-muted-foreground mt-1 text-xs sm:text-sm'>
+                Stacked requests, revenue, or tokens by model (
+                {mix.interval_minutes}m buckets).
+              </p>
+            </div>
+            <div className='flex items-center gap-2 sm:shrink-0'>
+              <div className='bg-muted/25 border-border/60 flex items-center gap-1 rounded-full border p-1'>
+                <Button
+                  type='button'
+                  size='sm'
+                  variant={mode === 'requests' ? 'secondary' : 'ghost'}
+                  onClick={() => setMode('requests')}
+                  className='h-7 rounded-full px-2.5 text-xs'
+                >
+                  Requests
+                </Button>
+                <Button
+                  type='button'
+                  size='sm'
+                  variant={mode === 'revenue' ? 'secondary' : 'ghost'}
+                  onClick={() => setMode('revenue')}
+                  className='h-7 rounded-full px-2.5 text-xs'
+                >
+                  Revenue
+                </Button>
+                <Button
+                  type='button'
+                  size='sm'
+                  variant={mode === 'tokens' ? 'secondary' : 'ghost'}
+                  onClick={() => setMode('tokens')}
+                  className='h-7 rounded-full px-2.5 text-xs'
+                >
+                  Tokens
+                </Button>
+              </div>
+              <Button
+                type='button'
+                variant='outline'
+                size='icon'
+                className='hidden h-8 w-8 shrink-0 sm:inline-flex'
+                onClick={toggleFullscreen}
+              >
+                {isFullscreen ? (
+                  <Minimize2Icon className='h-4 w-4' />
+                ) : (
+                  <ExpandIcon className='h-4 w-4' />
+                )}
+                <span className='sr-only'>
+                  {isFullscreen
+                    ? 'Exit fullscreen chart'
+                    : 'Enter fullscreen chart'}
+                </span>
+              </Button>
+            </div>
+          </div>
+        </CardHeader>
+        <CardContent className='space-y-3 sm:space-y-4'>
+          <ChartContainer
+            config={chartConfig}
+            className={cn(
+              'aspect-auto w-full',
+              isFullscreen
+                ? 'h-[calc(100vh-220px)] min-h-[340px] sm:h-[calc(100vh-260px)] sm:min-h-[420px]'
+                : 'h-[260px] sm:h-[340px]'
+            )}
+            onMouseLeave={() => {
+              setHoveredSeriesKey(null);
+              setIsChartPointerInside(false);
+            }}
+          >
+            <BarChart
+              data={chartData}
+              onMouseEnter={() => setIsChartPointerInside(true)}
+              onMouseMove={() => setIsChartPointerInside(true)}
+              onMouseLeave={() => {
+                setHoveredSeriesKey(null);
+                setIsChartPointerInside(false);
+              }}
+              margin={{
+                top: 12,
+                right: isMobile ? 8 : 18,
+                left: isMobile ? 0 : 8,
+                bottom: 0,
+              }}
+            >
+              <CartesianGrid vertical={false} className='stroke-muted/30' />
+              <XAxis
+                dataKey='timestamp'
+                tickLine={false}
+                axisLine={false}
+                minTickGap={isMobile ? 14 : 24}
+                tickFormatter={(value) =>
+                  formatAxisTimestamp(
+                    String(value),
+                    hasMultipleDays,
+                    mix.interval_minutes,
+                    mix.hours_back
+                  )
+                }
+              />
+              <YAxis
+                tickLine={false}
+                axisLine={false}
+                width={isMobile ? 40 : 56}
+                tickFormatter={(value) =>
+                  formatValue(
+                    typeof value === 'number' ? value : Number(value || 0)
+                  )
+                }
+              />
+              <ChartTooltip
+                cursor={false}
+                content={({ active, payload, label }) => {
+                  if (!isChartPointerInside || !active || !payload?.length) {
+                    return null;
+                  }
+
+                  const rows = payload
+                    .map((entry) => {
+                      const value =
+                        typeof entry.value === 'number'
+                          ? entry.value
+                          : Number(entry.value || 0);
+
+                      return {
+                        color: String(entry.color || '#6b7280'),
+                        dataKey: String(entry.dataKey || ''),
+                        label: String(entry.name || ''),
+                        value,
+                      } satisfies TooltipRow;
+                    })
+                    .filter(
+                      (row) => Number.isFinite(row.value) && row.value > 0
+                    )
+                    .sort((a, b) => b.value - a.value);
+
+                  const total = rows.reduce((sum, row) => sum + row.value, 0);
+                  if (rows.length === 0) {
+                    return null;
+                  }
+
+                  return (
+                    <div className='border-border/50 bg-background min-w-[220px] rounded-lg border px-2.5 py-2 text-xs shadow-xl'>
+                      <p className='text-foreground mb-2 text-sm font-medium'>
+                        {formatTooltipTimestamp(
+                          String(label || ''),
+                          mix.interval_minutes,
+                          mix.hours_back
+                        )}
+                      </p>
+                      <div className='space-y-1.5'>
+                        {rows.map((row) => (
+                          <div
+                            key={row.label}
+                            className={cn(
+                              'grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-3',
+                              activeHoverSeriesKey &&
+                                row.dataKey !== activeHoverSeriesKey &&
+                                'opacity-45'
+                            )}
+                          >
+                            <span className='text-muted-foreground flex min-w-0 items-center gap-2'>
+                              <span
+                                className='h-2.5 w-1.5 shrink-0 rounded-sm'
+                                style={{ backgroundColor: row.color }}
+                              />
+                              <span className='truncate'>{row.label}</span>
+                            </span>
+                            <span className='text-foreground font-mono tabular-nums'>
+                              {formatValue(row.value)}
+                            </span>
+                          </div>
+                        ))}
+                      </div>
+                      <div className='border-border/60 mt-2 border-t pt-2'>
+                        <div className='grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-3'>
+                          <span className='text-muted-foreground'>Total</span>
+                          <span className='text-foreground font-mono font-semibold tabular-nums'>
+                            {formatValue(total)}
+                          </span>
+                        </div>
+                      </div>
+                    </div>
+                  );
+                }}
+              />
+              {activeSeries.map((item) => (
+                <Bar
+                  key={item.dataKey}
+                  dataKey={item.dataKey}
+                  name={item.name}
+                  stackId='models'
+                  fill={item.color}
+                  fillOpacity={getSeriesOpacity(item.dataKey)}
+                  maxBarSize={44}
+                  onMouseEnter={() => setHoveredSeriesKey(item.dataKey)}
+                  onMouseLeave={() => setHoveredSeriesKey(null)}
+                />
+              ))}
+              <Bar
+                dataKey={othersKey}
+                name='Others'
+                stackId='models'
+                fill='#6b7280'
+                fillOpacity={getSeriesOpacity(othersKey)}
+                maxBarSize={44}
+                onMouseEnter={() => setHoveredSeriesKey(othersKey)}
+                onMouseLeave={() => setHoveredSeriesKey(null)}
+              />
+            </BarChart>
+          </ChartContainer>
+
+          <div className='border-border/60 space-y-2 border-t pt-3 sm:pt-4'>
+            <div className='flex items-center justify-between gap-3'>
+              <p className='text-muted-foreground text-xs font-medium'>
+                Top models
+              </p>
+              <p className='text-muted-foreground text-xs'>
+                Change vs prior period
+              </p>
+            </div>
+
+            {leaderboardRows.length > 0 ? (
+              <div className='divide-border/40 divide-y'>
+                {leaderboardRows.map((row) => {
+                  const rowIsLinked = Boolean(row.chartDataKey);
+                  const rowIsActive =
+                    row.chartDataKey !== null &&
+                    activeHoverSeriesKey === row.chartDataKey;
+                  const rowIsDimmed =
+                    Boolean(activeHoverSeriesKey) &&
+                    row.chartDataKey !== null &&
+                    row.chartDataKey !== activeHoverSeriesKey;
+
+                  let trendLabel = '0%';
+                  let trendClass = 'text-muted-foreground';
+                  if (row.trend === 'new') {
+                    trendLabel = 'new';
+                    trendClass = 'text-blue-500';
+                  } else if (row.trend === 'up' && row.trendPercent !== null) {
+                    trendLabel = `↑${formatTrendPercent(row.trendPercent)}%`;
+                    trendClass = 'text-emerald-500';
+                  } else if (
+                    row.trend === 'down' &&
+                    row.trendPercent !== null
+                  ) {
+                    trendLabel = `↓${formatTrendPercent(row.trendPercent)}%`;
+                    trendClass = 'text-red-500';
+                  } else if (row.trendPercent !== null) {
+                    trendLabel = `${formatTrendPercent(row.trendPercent)}%`;
+                  }
+
+                  return (
+                    <div
+                      key={row.model}
+                      className={cn(
+                        'grid grid-cols-[auto_minmax(0,1fr)_auto_auto] items-center gap-3 rounded-md px-2 py-2 text-xs',
+                        rowIsLinked &&
+                          'hover:bg-muted/25 cursor-pointer transition',
+                        rowIsActive && 'bg-muted/30',
+                        rowIsDimmed && 'opacity-45'
+                      )}
+                      title={row.model}
+                      onMouseEnter={() => {
+                        if (row.chartDataKey) {
+                          setHoveredSeriesKey(row.chartDataKey);
+                        }
+                      }}
+                      onMouseLeave={() => {
+                        if (row.chartDataKey) {
+                          setHoveredSeriesKey(null);
+                        }
+                      }}
+                    >
+                      <span className='text-muted-foreground w-5 text-right font-mono tabular-nums'>
+                        {row.rank}.
+                      </span>
+                      <div className='min-w-0'>
+                        <span className='truncate font-medium'>
+                          {row.displayName}
+                        </span>{' '}
+                        <span className='text-muted-foreground truncate'>
+                          by {row.provider}
+                        </span>
+                      </div>
+                      <span className='text-foreground font-mono tabular-nums'>
+                        {formatLeaderboardTotal(row.totalRaw)}
+                      </span>
+                      <span className={cn('font-medium', trendClass)}>
+                        {trendLabel}
+                      </span>
+                    </div>
+                  );
+                })}
+              </div>
+            ) : (
+              <p className='text-muted-foreground text-xs'>
+                No model totals available for this range.
+              </p>
+            )}
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

ui/components/usage-summary-cards.tsx

@@ -35,9 +35,10 @@ export function UsageSummaryCards({ summary }: UsageSummaryCardsProps) {
 
   const formatAmount = (msat: number) =>
     formatFromMsat(msat, displayUnit, usdPerSat);
-  const hasTokenStats =
-    typeof summary.total_tokens === 'number' ||
-    typeof summary.avg_total_tokens_per_completion === 'number';
+  const totalTokens = Number(summary.total_tokens ?? 0);
+  const avgTotalTokensPerCompletion = Number(
+    summary.avg_total_tokens_per_completion ?? 0
+  );
 
   const cards = [
     {
@@ -52,26 +53,20 @@ export function UsageSummaryCards({ summary }: UsageSummaryCardsProps) {
       icon: CheckCircle2,
       iconClassName: 'text-emerald-600 dark:text-emerald-300',
     },
-    ...(hasTokenStats
-      ? [
-          {
-            title: 'Total Tokens',
-            value: Number(summary.total_tokens ?? 0).toLocaleString(),
-            icon: Database,
-            iconClassName: 'text-cyan-600 dark:text-cyan-300',
-          },
-          {
-            title: 'Avg Tokens/Completion',
-            value: Number(
-              summary.avg_total_tokens_per_completion ?? 0
-            ).toLocaleString(undefined, {
-              maximumFractionDigits: 1,
-            }),
-            icon: Activity,
-            iconClassName: 'text-indigo-600 dark:text-indigo-300',
-          },
-        ]
-      : []),
+    {
+      title: 'Total Tokens',
+      value: totalTokens.toLocaleString(),
+      icon: Database,
+      iconClassName: 'text-cyan-600 dark:text-cyan-300',
+    },
+    {
+      title: 'Avg Tokens/Completion',
+      value: avgTotalTokensPerCompletion.toLocaleString(undefined, {
+        maximumFractionDigits: 1,
+      }),
+      icon: Activity,
+      iconClassName: 'text-indigo-600 dark:text-indigo-300',
+    },
     {
       title: 'Revenue',
       value: formatAmount(summary.revenue_msats),

ui/hooks/use-wallet-info.ts

@@ -0,0 +1,38 @@
+import { useQuery } from '@tanstack/react-query';
+import type { WalletSnapshot } from '@/components/landing/key-info-details';
+
+export function useWalletInfo(baseUrl: string, apiKey: string) {
+  return useQuery({
+    queryKey: ['walletInfo', baseUrl, apiKey],
+    queryFn: async (): Promise<WalletSnapshot> => {
+      const response = await fetch(`${baseUrl}/v1/balance/info`, {
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(errorText || 'Unable to load wallet info');
+      }
+
+      const payload = await response.json();
+      return {
+        apiKey: payload.api_key || apiKey,
+        balanceMsats: payload.balance ?? 0,
+        reservedMsats: payload.reserved ?? 0,
+        isChild: payload.is_child,
+        parentKey: payload.parent_key,
+        totalRequests: payload.total_requests,
+        totalSpent: payload.total_spent,
+        balanceLimit: payload.balance_limit,
+        balanceLimitReset: payload.balance_limit_reset,
+        validityDate: payload.validity_date,
+        childKeys: payload.child_keys,
+      };
+    },
+    enabled: !!baseUrl && !!apiKey,
+    staleTime: 5000, // Consider data stale after 5 seconds
+  });
+}

ui/lib/api/services/admin.ts

@@ -12,6 +12,12 @@ export const ProviderTypeSchema = z.object({
   can_show_balance: z.boolean(),
 });
 
+export const FeeTimeRangeSchema = z.object({
+  start_time: z.string(),
+  end_time: z.string(),
+  provider_fee: z.number(),
+});
+
 export const UpstreamProviderSchema = z.object({
   id: z.number(),
   provider_type: z.string(),
@@ -20,7 +26,9 @@ export const UpstreamProviderSchema = z.object({
   api_version: z.string().nullable().optional(),
   enabled: z.boolean(),
   provider_fee: z.number().optional(),
+  provider_fee_default: z.number().optional(),
   provider_settings: z.record(z.string(), z.any()).nullable().optional(),
+  provider_fee_schedules: z.array(FeeTimeRangeSchema).optional().default([]),
 });
 
 export const CreateUpstreamProviderSchema = z.object({
@@ -30,6 +38,7 @@ export const CreateUpstreamProviderSchema = z.object({
   api_version: z.string().nullable().optional(),
   enabled: z.boolean().default(true),
   provider_fee: z.number().optional(),
+  provider_fee_default: z.number().optional(),
   provider_settings: z.record(z.string(), z.any()).nullable().optional(),
 });
 
@@ -40,6 +49,7 @@ export const UpdateUpstreamProviderSchema = z.object({
   api_version: z.string().nullable().optional(),
   enabled: z.boolean().optional(),
   provider_fee: z.number().optional(),
+  provider_fee_default: z.number().optional(),
   provider_settings: z.record(z.string(), z.any()).nullable().optional(),
 });
 
@@ -76,6 +86,7 @@ export const AdminModelSchema = z.object({
   canonical_slug: z.string().nullable().optional(),
   alias_ids: z.array(z.string()).nullable().optional(),
   enabled: z.boolean().default(true),
+  forwarded_model_id: z.string().nullable().optional(),
 });
 
 export const ProviderModelsSchema = z.object({
@@ -96,6 +107,7 @@ export type CreateUpstreamProvider = z.infer<
 export type UpdateUpstreamProvider = z.infer<
   typeof UpdateUpstreamProviderSchema
 >;
+export type FeeTimeRange = z.infer<typeof FeeTimeRangeSchema>;
 export type AdminModel = z.infer<typeof AdminModelSchema>;
 export type AdminModelPricing = z.infer<typeof AdminModelPricingSchema>;
 export type AdminModelArchitecture = z.infer<
@@ -307,6 +319,30 @@ export class AdminService {
     );
   }
 
+  static async getFeeSchedules(providerId: number): Promise<FeeTimeRange[]> {
+    return await apiClient.get<FeeTimeRange[]>(
+      `/admin/api/upstream-providers/${providerId}/fee-schedules`
+    );
+  }
+
+  static async updateFeeSchedules(
+    providerId: number,
+    schedules: FeeTimeRange[]
+  ): Promise<FeeTimeRange[]> {
+    return await apiClient.put<FeeTimeRange[]>(
+      `/admin/api/upstream-providers/${providerId}/fee-schedules`,
+      { schedules }
+    );
+  }
+
+  static async deleteFeeSchedules(
+    providerId: number
+  ): Promise<{ ok: boolean }> {
+    return await apiClient.delete<{ ok: boolean }>(
+      `/admin/api/upstream-providers/${providerId}/fee-schedules`
+    );
+  }
+
   static async getProviderModels(providerId: number): Promise<ProviderModels> {
     const data = await apiClient.get<ProviderModels>(
       `/admin/api/upstream-providers/${providerId}/models`
@@ -845,6 +881,23 @@ export class AdminService {
     );
   }
 
+  static async getUsageDashboard(
+    hours: number = 24,
+    interval: number = 15,
+    errorLimit: number = 100,
+    modelLimit: number = 20
+  ): Promise<UsageDashboardResponse> {
+    const params = new URLSearchParams();
+    params.set('interval', String(interval));
+    params.set('hours', String(hours));
+    params.set('error_limit', String(errorLimit));
+    params.set('model_limit', String(modelLimit));
+
+    return await apiClient.get<UsageDashboardResponse>(
+      `/admin/api/usage/dashboard?${params.toString()}`
+    );
+  }
+
   static async getUsageSummary(hours: number = 24): Promise<UsageSummary> {
     return await apiClient.get<UsageSummary>(
       `/admin/api/usage/summary?hours=${hours}`
@@ -869,6 +922,27 @@ export class AdminService {
     );
   }
 
+  static async getTransactions(
+    type?: string,
+    status?: string,
+    search?: string,
+    source?: string,
+    limit: number = 50,
+    offset: number = 0
+  ): Promise<TransactionsResponse> {
+    const params = new URLSearchParams();
+    if (type) params.append('type', type);
+    if (status) params.append('status', status);
+    if (search) params.append('search', search);
+    if (source) params.append('source', source);
+    params.append('limit', limit.toString());
+    params.append('offset', offset.toString());
+
+    return await apiClient.get<TransactionsResponse>(
+      `/admin/api/transactions?${params.toString()}`
+    );
+  }
+
   static async createProviderAccountByType(providerType: string): Promise<{
     ok: boolean;
     account_data: Record<string, unknown>;
@@ -927,6 +1001,45 @@ export class AdminService {
       balance_data: number | null | Record<string, unknown>;
     }>(`/admin/api/upstream-providers/${providerId}/balance`);
   }
+
+  // ── CLI Tokens ──
+
+  static async listCliTokens(): Promise<CliTokenListItem[]> {
+    return await apiClient.get<CliTokenListItem[]>('/admin/api/cli-tokens');
+  }
+
+  static async createCliToken(
+    name: string,
+    expiresInDays?: number
+  ): Promise<CliTokenCreated> {
+    return await apiClient.post<CliTokenCreated>('/admin/api/cli-tokens', {
+      name,
+      expires_in_days: expiresInDays ?? null,
+    });
+  }
+
+  static async revokeCliToken(tokenId: string): Promise<{ ok: boolean }> {
+    return await apiClient.delete<{ ok: boolean }>(
+      `/admin/api/cli-tokens/${encodeURIComponent(tokenId)}`
+    );
+  }
+}
+
+export interface CliTokenListItem {
+  id: string;
+  name: string;
+  token_preview: string;
+  created_at: number;
+  last_used_at: number | null;
+  expires_at: number | null;
+}
+
+export interface CliTokenCreated {
+  id: string;
+  name: string;
+  token: string;
+  created_at: number;
+  expires_at: number | null;
 }
 
 export const TemporaryBalanceSchema = z.object({
@@ -952,9 +1065,9 @@ export interface UsageMetricData {
   upstream_errors: number;
   revenue_msats: number;
   refunds_msats: number;
-  input_tokens?: number;
-  output_tokens?: number;
-  total_tokens?: number;
+  input_tokens: number;
+  output_tokens: number;
+  total_tokens: number;
   [key: string]: unknown;
 }
 
@@ -963,7 +1076,20 @@ export interface UsageMetrics {
   interval_minutes: number;
   hours_back: number;
   total_buckets: number;
-  totals?: Partial<Record<string, number>>;
+  totals?: {
+    total_requests: number;
+    successful_chat_completions: number;
+    failed_requests: number;
+    errors: number;
+    warnings: number;
+    payment_processed: number;
+    upstream_errors: number;
+    revenue_msats: number;
+    refunds_msats: number;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+  };
 }
 
 export interface UsageSummary {
@@ -978,6 +1104,12 @@ export interface UsageSummary {
   unique_models_count: number;
   unique_models: string[];
   error_types: Record<string, number>;
+  input_tokens: number;
+  output_tokens: number;
+  total_tokens: number;
+  avg_input_tokens_per_completion: number;
+  avg_output_tokens_per_completion: number;
+  avg_total_tokens_per_completion: number;
   success_rate: number;
   revenue_msats: number;
   refunds_msats: number;
@@ -987,8 +1119,6 @@ export interface UsageSummary {
   net_revenue_sats: number;
   avg_revenue_per_request_msats: number;
   refund_rate: number;
-  total_tokens?: number;
-  avg_total_tokens_per_completion?: number;
 }
 
 export interface ErrorDetail {
@@ -1022,6 +1152,35 @@ export interface RevenueByModel {
   total_models: number;
 }
 
+export interface ModelUsageMixMetric {
+  timestamp: string;
+  total_successful: number;
+  total_revenue_msats: number;
+  total_tokens: number;
+  others: number;
+  others_revenue_msats: number;
+  others_tokens: number;
+  model_counts: Record<string, number>;
+  model_revenue_msats: Record<string, number>;
+  model_tokens: Record<string, number>;
+}
+
+export interface ModelUsageMix {
+  top_models: string[];
+  metrics: ModelUsageMixMetric[];
+  interval_minutes: number;
+  hours_back: number;
+  total_buckets: number;
+}
+
+export interface UsageDashboardResponse {
+  metrics: UsageMetrics;
+  summary: UsageSummary;
+  error_details: ErrorDetails;
+  revenue_by_model: RevenueByModel;
+  model_usage_mix?: ModelUsageMix;
+}
+
 export interface LogEntry {
   asctime: string;
   name: string;
@@ -1042,3 +1201,23 @@ export interface LogResponse {
   search: string | null;
   limit: number;
 }
+
+export interface Transaction {
+  id: string;
+  token: string;
+  amount: number;
+  unit: string;
+  mint_url: string;
+  type: 'in' | 'out';
+  request_id?: string;
+  created_at: number;
+  collected: boolean;
+  swept: boolean;
+  source: 'x-cashu' | 'apikey';
+  api_key_hashed_key?: string;
+}
+
+export interface TransactionsResponse {
+  transactions: Transaction[];
+  total: number;
+}