fix refund token multiple times

fix negative reserve balance

docs/api/endpoints.md

@@ -360,6 +360,42 @@ POST /v1/wallet/create
 }
 ```
 
+### Get Key Information
+
+Get current balance, consumption data, and child keys for an API key.
+
+```http
+GET /v1/balance/info
+Authorization: Bearer sk-...
+```
+
+**Response:**
+
+```json
+{
+  "api_key": "sk-abc...",
+  "balance": 8500000,
+  "reserved": 0,
+  "is_child": false,
+  "parent_key": null,
+  "total_requests": 42,
+  "total_spent": 1500000,
+  "balance_limit": null,
+  "balance_limit_reset": null,
+  "validity_date": null,
+  "child_keys": [
+    {
+      "api_key": "sk-child1...",
+      "total_requests": 10,
+      "total_spent": 500000,
+      "balance_limit": 1000000,
+      "balance_limit_reset": "daily",
+      "validity_date": 1738000000
+    }
+  ]
+}
+```
+
 ### Check Balance
 
 Get current wallet balance.

docs/provider/configuration.md

@@ -6,6 +6,32 @@ For automated deployments, you can optionally pre-configure settings via environ
 
 ---
 
+## Initial Setup (.env file)
+
+Before running your node, you should create a `.env` file in the project root. This file is used to bootstrap the initial configuration and store sensitive secrets.
+
+### Example .env
+
+```bash
+ADMIN_PASSWORD=your-secure-password
+
+# Node Identity
+NAME="My AI Node"
+DESCRIPTION="Fast access to models"
+
+# Lightning Payouts
+RECEIVE_LN_ADDRESS=yourname@wallet.com
+```
+
+### Setting the UI Password
+
+There are two ways to set or change your Admin Dashboard password:
+
+1.  **Via Environment Variable**: Set `ADMIN_PASSWORD` in your `.env` file before starting the container. This will be the password used for the first login.
+2.  **Via Dashboard**: Once logged in, go to **Settings** → **Security** to update your password. Dashboard settings override the `.env` file once saved.
+
+---
+
 ## Admin Dashboard (Primary)
 
 Access the dashboard at `/admin/` on your node.
@@ -14,29 +40,29 @@ Access the dashboard at `/admin/` on your node.
 
 Connect to your AI provider(s):
 
-| Setting | Description |
-|---------|-------------|
+| Setting          | Description                                      |
+| ---------------- | ------------------------------------------------ |
 | **Upstream URL** | API endpoint (e.g., `https://api.openai.com/v1`) |
-| **API Key** | Your provider's API key |
+| **API Key**      | Your provider's API key                          |
 
 ### Node Identity
 
 How your node appears to clients:
 
-| Setting | Description |
-|---------|-------------|
-| **Name** | Display name (e.g., "Fast GPT-4 Node") |
-| **Description** | Brief description of your service |
+| Setting         | Description                            |
+| --------------- | -------------------------------------- |
+| **Name**        | Display name (e.g., "Fast GPT-4 Node") |
+| **Description** | Brief description of your service      |
 
 ### Pricing
 
 Control your profit margins:
 
-| Setting | Description | Default |
-|---------|-------------|---------|
-| **Fixed Pricing** | Charge flat rate per request vs. per-token | Off |
-| **Exchange Fee** | Buffer for BTC volatility | 1.005 (0.5%) |
-| **Upstream Fee** | Your profit markup | 1.10 (10%) |
+| Setting           | Description                                | Default      |
+| ----------------- | ------------------------------------------ | ------------ |
+| **Fixed Pricing** | Charge flat rate per request vs. per-token | Off          |
+| **Exchange Fee**  | Buffer for BTC volatility                  | 1.005 (0.5%) |
+| **Upstream Fee**  | Your profit markup                         | 1.10 (10%)   |
 
 See [Pricing](pricing.md) for detailed strategies.
 
@@ -44,33 +70,33 @@ See [Pricing](pricing.md) for detailed strategies.
 
 Which mints to accept payments from:
 
-| Setting | Description |
-|---------|-------------|
+| Setting   | Description                     |
+| --------- | ------------------------------- |
 | **Mints** | List of trusted Cashu mint URLs |
 
 ### Lightning Withdrawals
 
 Automatic profit withdrawal:
 
-| Setting | Description |
-|---------|-------------|
+| Setting               | Description                     |
+| --------------------- | ------------------------------- |
 | **Lightning Address** | Your LN address for withdrawals |
 
 ### Security
 
-| Setting | Description |
-|---------|-------------|
+| Setting            | Description                   |
+| ------------------ | ----------------------------- |
 | **Admin Password** | Password for dashboard access |
 
 ### Nostr Discovery
 
 Announce your node on the network:
 
-| Setting | Description |
-|---------|-------------|
-| **Npub** | Your Nostr public key |
-| **Nsec** | Your Nostr private key (for signing) |
-| **Relays** | Relays to publish announcements |
+| Setting    | Description                          |
+| ---------- | ------------------------------------ |
+| **Npub**   | Your Nostr public key                |
+| **Nsec**   | Your Nostr private key (for signing) |
+| **Relays** | Relays to publish announcements      |
 
 See [Discovery](discovery.md) for details.
 
@@ -86,21 +112,21 @@ Use environment variables for:
 
 ### All Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `UPSTREAM_BASE_URL` | Upstream API endpoint | — |
-| `UPSTREAM_API_KEY` | Upstream API key | — |
-| `ADMIN_PASSWORD` | Dashboard password | (none) |
-| `DATABASE_URL` | Database connection string | `sqlite+aiosqlite:///keys.db` |
-| `NAME` | Node display name | `ARoutstrNode` |
-| `DESCRIPTION` | Node description | `A Routstr Node` |
-| `NPUB` | Nostr public key (bech32) | — |
-| `NSEC` | Nostr private key | — |
-| `CASHU_MINTS` | Comma-separated mint URLs | `https://mint.minibits.cash/Bitcoin` |
-| `RECEIVE_LN_ADDRESS` | Lightning address for withdrawals | — |
-| `TOR_PROXY_URL` | SOCKS5 proxy for Tor | `socks5://127.0.0.1:9050` |
-| `CORS_ORIGINS` | Allowed CORS origins | `*` |
-| `RELAYS` | Nostr relays (comma-separated) | (default set) |
+| Variable             | Description                       | Default                              |
+| -------------------- | --------------------------------- | ------------------------------------ |
+| `UPSTREAM_BASE_URL`  | Upstream API endpoint             | —                                    |
+| `UPSTREAM_API_KEY`   | Upstream API key                  | —                                    |
+| `ADMIN_PASSWORD`     | Dashboard password                | (none)                               |
+| `DATABASE_URL`       | Database connection string        | `sqlite+aiosqlite:///keys.db`        |
+| `NAME`               | Node display name                 | `ARoutstrNode`                       |
+| `DESCRIPTION`        | Node description                  | `A Routstr Node`                     |
+| `NPUB`               | Nostr public key (bech32)         | —                                    |
+| `NSEC`               | Nostr private key                 | —                                    |
+| `CASHU_MINTS`        | Comma-separated mint URLs         | `https://mint.minibits.cash/Bitcoin` |
+| `RECEIVE_LN_ADDRESS` | Lightning address for withdrawals | —                                    |
+| `TOR_PROXY_URL`      | SOCKS5 proxy for Tor              | `socks5://127.0.0.1:9050`            |
+| `CORS_ORIGINS`       | Allowed CORS origins              | `*`                                  |
+| `RELAYS`             | Nostr relays (comma-separated)    | (default set)                        |
 
 ### Priority
 

docs/provider/quickstart.md

@@ -13,7 +13,7 @@ A **Routstr Provider Node** acts as a gateway that:
 You bring the API keys, Routstr handles the billing, payments, and client management.
 
 !!! tip "Future: Node-to-Node Routing"
-    In future versions, you'll be able to run a node that connects to other Routstr nodes—eliminating the need to configure upstream providers yourself. For now, you'll need your own API credentials.
+In future versions, you'll be able to run a node that connects to other Routstr nodes—eliminating the need to configure upstream providers yourself. For now, you'll need your own API credentials.
 
 ---
 
@@ -24,7 +24,24 @@ You bring the API keys, Routstr handles the billing, payments, and client manage
 
 ---
 
-## 1. Start the Node
+## 1. Prepare Configuration
+
+Create a `.env` file in the root of the project to store your secrets:
+
+```bash
+# Initial Admin Password
+ADMIN_PASSWORD=mysecretpassword
+
+# Node Identity
+NAME="My AI Node"
+DESCRIPTION="Fast access to models"
+
+# Lightning Payouts
+RECEIVE_LN_ADDRESS=yourname@wallet.com
+
+```
+
+## 2. Start the Node
 
 You can run the pre-built image directly:
 
@@ -32,18 +49,26 @@ You can run the pre-built image directly:
 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 --name routstr routstr-local
+docker run -d -p 8000:8000 --env-file .env --name routstr routstr-local
 ```
 
 Verify it's running:
@@ -54,12 +79,12 @@ curl http://localhost:8000/v1/info
 
 ---
 
-## 2. Configure via Dashboard
+## 3. Configure via Dashboard
 
 Open the **Admin Dashboard** at [http://localhost:8000/admin/](http://localhost:8000/admin/).
 
-!!! note "Default Access"
-    The dashboard has no password by default. Set one immediately in Settings for production use.
+!!! note "Login"
+Use the `ADMIN_PASSWORD` you defined in your `.env` file to log in. If you didn't set one, the dashboard will prompt you to set one on first visit.
 
 ### Connect Your AI Providers
 

routstr/algorithm.py

@@ -118,6 +118,13 @@ def create_model_mappings(
 
     candidates: dict[str, list[tuple["Model", "BaseUpstreamProvider"]]] = {}
     unique_models: dict[str, "Model"] = {}
+    seen_model_provider: set[tuple[str, str]] = set()
+
+    providers_by_db_id: dict[int, "BaseUpstreamProvider"] = {}
+    for upstream in upstreams:
+        db_id = getattr(upstream, "db_id", None)
+        if isinstance(db_id, int):
+            providers_by_db_id[db_id] = upstream
 
     # Separate OpenRouter from other providers
     openrouter: "BaseUpstreamProvider" | None = None
@@ -134,6 +141,16 @@ def create_model_mappings(
         """Get base model ID by removing provider prefix."""
         return model_id.split("/", 1)[1] if "/" in model_id else model_id
 
+    def get_provider_identity(upstream: "BaseUpstreamProvider") -> str:
+        """Get a stable provider identity used for deduplication."""
+        db_id = getattr(upstream, "db_id", None)
+        if isinstance(db_id, int):
+            return f"db:{db_id}"
+
+        provider_type = str(getattr(upstream, "provider_type", "") or "").lower()
+        base_url = str(getattr(upstream, "base_url", "") or "").lower()
+        return f"{provider_type}|{base_url}"
+
     def _add_candidate(
         alias: str, model: "Model", provider: "BaseUpstreamProvider"
     ) -> None:
@@ -148,6 +165,7 @@ def create_model_mappings(
     ) -> None:
         """Process all models from a given provider."""
         upstream_prefix = getattr(upstream, "upstream_name", None)
+        provider_key = get_provider_identity(upstream)
 
         for model in upstream.get_cached_models():
             if not model.enabled or model.id in disabled_model_ids:
@@ -189,6 +207,7 @@ def create_model_mappings(
             # Try to set each alias
             for alias in aliases:
                 _add_candidate(alias, model_to_use, upstream)
+            seen_model_provider.add((model_to_use.id.lower(), provider_key))
 
     # Process non-OpenRouter providers first
     for upstream in other_upstreams:
@@ -198,6 +217,85 @@ def create_model_mappings(
     if openrouter:
         process_provider_models(openrouter, is_openrouter=True)
 
+    # Include enabled DB overrides even when provider discovery misses models.
+    # This is important for deployment-based providers like Azure.
+    for model_id, override_data in overrides_by_id.items():
+        if model_id in disabled_model_ids:
+            continue
+        override_row, provider_fee = override_data
+        upstream_provider_id = getattr(override_row, "upstream_provider_id", None)
+        if not isinstance(upstream_provider_id, int):
+            continue
+
+        upstream_for_override = providers_by_db_id.get(upstream_provider_id)
+        if upstream_for_override is None:
+            continue
+
+        provider_key = get_provider_identity(upstream_for_override)
+        dedupe_key = (model_id.lower(), provider_key)
+        if dedupe_key in seen_model_provider:
+            continue
+
+        try:
+            model_to_use = _row_to_model(
+                override_row, apply_provider_fee=True, provider_fee=provider_fee
+            )
+        except Exception as exc:
+            logger.warning(
+                "Skipping invalid model override while building model mappings",
+                extra={
+                    "model_id": model_id,
+                    "upstream_provider_id": upstream_provider_id,
+                    "error": str(exc),
+                    "error_type": type(exc).__name__,
+                },
+            )
+            continue
+        if not model_to_use.enabled:
+            continue
+
+        base_id = get_base_model_id(model_to_use.id)
+        is_openrouter = (
+            getattr(upstream_for_override, "base_url", "")
+            == "https://openrouter.ai/api/v1"
+        )
+        if not is_openrouter or base_id not in unique_models:
+            unique_model = model_to_use.copy(
+                update={
+                    "id": base_id,
+                    "upstream_provider_id": upstream_for_override.provider_type,
+                }
+            )
+            unique_models[base_id] = unique_model
+
+        try:
+            aliases = resolve_model_alias(
+                model_to_use.id,
+                model_to_use.canonical_slug,
+                alias_ids=model_to_use.alias_ids,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Skipping model aliases for invalid override model",
+                extra={
+                    "model_id": model_id,
+                    "upstream_provider_id": upstream_provider_id,
+                    "error": str(exc),
+                    "error_type": type(exc).__name__,
+                },
+            )
+            continue
+
+        upstream_prefix = getattr(upstream_for_override, "upstream_name", None)
+        if upstream_prefix and "/" not in model_to_use.id:
+            prefixed_id = f"{upstream_prefix}/{model_to_use.id}"
+            if prefixed_id not in aliases:
+                aliases.append(prefixed_id)
+
+        for alias in aliases:
+            _add_candidate(alias, model_to_use, upstream_for_override)
+        seen_model_provider.add(dedupe_key)
+
     # Sort candidates and build final maps
     model_instances: dict[str, "Model"] = {}
     provider_map: dict[str, list["BaseUpstreamProvider"]] = {}

routstr/auth.py

@@ -348,6 +348,8 @@ async def validate_bearer_key(
             )
 
             return new_key
+        except HTTPException:
+            raise
         except Exception as e:
             logger.error(
                 "Cashu token redemption failed",
@@ -588,12 +590,15 @@ async def pay_for_request(
 
 async def revert_pay_for_request(
     key: ApiKey, session: AsyncSession, cost_per_request: int
-) -> None:
+) -> bool:
+    """Revert a previously reserved payment. Returns True if revert succeeded,
+    False if the reservation was already released (prevents negative reserved_balance)."""
     billing_key = await get_billing_key(key, session)
 
     stmt = (
         update(ApiKey)
         .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
+        .where(col(ApiKey.reserved_balance) >= cost_per_request)
         .values(
             reserved_balance=col(ApiKey.reserved_balance) - cost_per_request,
             total_requests=col(ApiKey.total_requests) - 1,
@@ -607,6 +612,7 @@ async def revert_pay_for_request(
         child_stmt = (
             update(ApiKey)
             .where(col(ApiKey.hashed_key) == key.hashed_key)
+            .where(col(ApiKey.reserved_balance) >= cost_per_request)
             .values(
                 total_requests=col(ApiKey.total_requests) - 1,
                 reserved_balance=col(ApiKey.reserved_balance) - cost_per_request,
@@ -616,8 +622,8 @@ async def revert_pay_for_request(
 
     await session.commit()
     if result.rowcount == 0:
-        logger.error(
-            "Failed to revert payment - insufficient reserved balance",
+        logger.warning(
+            "Revert skipped - reservation already released (no-op to prevent negative reserved_balance)",
             extra={
                 "key_hash": key.hashed_key[:8] + "...",
                 "billing_key_hash": billing_key.hashed_key[:8] + "...",
@@ -625,19 +631,11 @@ async def revert_pay_for_request(
                 "current_reserved_balance": billing_key.reserved_balance,
             },
         )
-        raise HTTPException(
-            status_code=402,
-            detail={
-                "error": {
-                    "message": f"failed to revert request payment: {cost_per_request} mSats required. {billing_key.balance} available.",
-                    "type": "payment_error",
-                    "code": "payment_error",
-                }
-            },
-        )
+        return False
     await session.refresh(billing_key)
     if billing_key.hashed_key != key.hashed_key:
         await session.refresh(key)
+    return True
 
 
 async def adjust_payment_for_tokens(
@@ -669,17 +667,19 @@ async def adjust_payment_for_tokens(
             release_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
                 )
             )
-            await session.exec(release_stmt)  # type: ignore[call-overload]
+            result = await session.exec(release_stmt)  # type: ignore[call-overload]
 
             # Also release on child key if it's different
             if billing_key.hashed_key != key.hashed_key:
                 child_release_stmt = (
                     update(ApiKey)
                     .where(col(ApiKey.hashed_key) == key.hashed_key)
+                    .where(col(ApiKey.reserved_balance) >= deducted_max_cost)
                     .values(
                         reserved_balance=col(ApiKey.reserved_balance)
                         - deducted_max_cost
@@ -688,14 +688,24 @@ async def adjust_payment_for_tokens(
                 await session.exec(child_release_stmt)  # type: ignore[call-overload]
 
             await session.commit()
-            logger.warning(
-                "Released reservation without charging (fallback)",
-                extra={
-                    "key_hash": key.hashed_key[:8] + "...",
-                    "billing_key_hash": billing_key.hashed_key[:8] + "...",
-                    "deducted_max_cost": deducted_max_cost,
-                },
-            )
+            if result.rowcount == 0:  # type: ignore[union-attr]
+                logger.warning(
+                    "Release reservation skipped - already released (no-op to prevent negative reserved_balance)",
+                    extra={
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                        "deducted_max_cost": deducted_max_cost,
+                    },
+                )
+            else:
+                logger.warning(
+                    "Released reservation without charging (fallback)",
+                    extra={
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                        "deducted_max_cost": deducted_max_cost,
+                    },
+                )
         except Exception as e:
             logger.error(
                 "Failed to release reservation in fallback",
@@ -997,18 +1007,8 @@ async def adjust_payment_for_tokens(
                     }
                 },
             )
-    # Fallback: should not reach here, but release reservation just in case
-    logger.error(
-        "Unexpected fallback in adjust_payment_for_tokens - releasing reservation",
-        extra={"key_hash": key.hashed_key[:8] + "...", "model": model},
-    )
-    await release_reservation_only()
-    return {
-        "base_msats": deducted_max_cost,
-        "input_msats": 0,
-        "output_msats": 0,
-        "total_msats": deducted_max_cost,
-    }
+    # All calculate_cost variants are handled above.
+    raise AssertionError("Unreachable: unhandled calculate_cost result")
 
 
 async def periodic_key_reset() -> None:

routstr/balance.py

@@ -6,8 +6,9 @@ from typing import Annotated, NoReturn
 
 from fastapi import APIRouter, Depends, Header, HTTPException
 from pydantic import BaseModel
+from sqlmodel import select
 
-from .auth import validate_bearer_key
+from .auth import get_billing_key, validate_bearer_key
 from .core.db import ApiKey, AsyncSession, get_session
 from .core.logging import get_logger
 from .core.settings import settings
@@ -34,10 +35,8 @@ async def get_key_from_header(
 
 
 async def get_balance_info(key: ApiKey, session: AsyncSession) -> dict:
-    from .auth import get_billing_key
-
     billing_key = await get_billing_key(key, session)
-    return {
+    info = {
         "api_key": "sk-" + key.hashed_key,
         "balance": billing_key.balance,
         "reserved": billing_key.reserved_balance,
@@ -50,6 +49,26 @@ async def get_balance_info(key: ApiKey, session: AsyncSession) -> dict:
         "validity_date": key.validity_date,
     }
 
+    if not key.parent_key_hash:
+        # Fetch child keys if this is a parent key
+        statement = select(ApiKey).where(ApiKey.parent_key_hash == key.hashed_key)
+        results = await session.exec(statement)
+        child_keys = results.all()
+        if child_keys:
+            info["child_keys"] = [
+                {
+                    "api_key": "sk-" + ck.hashed_key,
+                    "total_requests": ck.total_requests,
+                    "total_spent": ck.total_spent,
+                    "balance_limit": ck.balance_limit,
+                    "balance_limit_reset": ck.balance_limit_reset,
+                    "validity_date": ck.validity_date,
+                }
+                for ck in child_keys
+            ]
+
+    return info
+
 
 # TODO: remove this endpoint when frontend is updated
 @router.get("/", include_in_schema=False)
@@ -117,8 +136,6 @@ async def topup_wallet_endpoint(
     key: ApiKey = Depends(get_key_from_header),
     session: AsyncSession = Depends(get_session),
 ) -> dict[str, int]:
-    from .auth import get_billing_key
-
     billing_key = await get_billing_key(key, session)
 
     if topup_request is not None:
@@ -188,8 +205,9 @@ async def refund_wallet_endpoint(
 
     key: ApiKey = await validate_bearer_key(bearer_value, session)
 
-    if cached := await _refund_cache_get(bearer_value):
-        return cached
+    if key.total_balance <= 0:
+        if cached := await _refund_cache_get(bearer_value):
+            return cached
 
     if key.parent_key_hash:
         raise HTTPException(

routstr/core/admin.py

@@ -456,18 +456,18 @@ async def batch_override_provider_models(
     logger.info(
         f"BATCH_OVERRIDE called: provider_id={provider_id}, count={len(payload.models)}"
     )
-    
+
     async with create_session() as session:
         provider = await session.get(UpstreamProviderRow, provider_id)
         if not provider:
             raise HTTPException(status_code=404, detail="Provider not found")
-            
+
         overridden_count = 0
-        
+
         for model_data in payload.models:
             # Try to get existing model regardless of whether it's enabled or not
             existing_row = await session.get(ModelRow, (model_data.id, provider_id))
-            
+
             if existing_row:
                 # Update existing
                 existing_row.name = model_data.name
@@ -483,7 +483,9 @@ async def batch_override_provider_models(
                     else None
                 )
                 existing_row.top_provider = (
-                    json.dumps(model_data.top_provider) if model_data.top_provider else None
+                    json.dumps(model_data.top_provider)
+                    if model_data.top_provider
+                    else None
                 )
                 existing_row.canonical_slug = model_data.canonical_slug
                 existing_row.alias_ids = (
@@ -508,23 +510,32 @@ async def batch_override_provider_models(
                         else None
                     ),
                     top_provider=(
-                        json.dumps(model_data.top_provider) if model_data.top_provider else None
+                        json.dumps(model_data.top_provider)
+                        if model_data.top_provider
+                        else None
                     ),
                     canonical_slug=model_data.canonical_slug,
                     alias_ids=(
-                        json.dumps(model_data.alias_ids) if model_data.alias_ids else None
+                        json.dumps(model_data.alias_ids)
+                        if model_data.alias_ids
+                        else None
                     ),
                     upstream_provider_id=provider_id,
                     enabled=model_data.enabled,
                 )
                 session.add(row)
-            
+
             overridden_count += 1
-            
+
         await session.commit()
 
     await refresh_model_maps()
-    return {"ok": True, "count": overridden_count, "message": f"Successfully batch overridden {overridden_count} models"}
+    return {
+        "ok": True,
+        "count": overridden_count,
+        "message": f"Successfully batch overridden {overridden_count} models",
+    }
+
 
 class UpstreamProviderCreate(BaseModel):
     provider_type: str
@@ -570,12 +581,14 @@ async def create_upstream_provider(
     async with create_session() as session:
         result = await session.exec(
             select(UpstreamProviderRow).where(
-                UpstreamProviderRow.base_url == payload.base_url
+                UpstreamProviderRow.base_url == payload.base_url,
+                UpstreamProviderRow.api_key == payload.api_key,
             )
         )
         if result.first():
             raise HTTPException(
-                status_code=409, detail="Provider with this base URL already exists"
+                status_code=409,
+                detail="Provider with this base URL and API key already exists",
             )
 
         provider = UpstreamProviderRow(
@@ -717,9 +730,7 @@ 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.name not in db_model_ids
-        ]
+        filtered_remote_models = [m for m in upstream_models if m.id not in db_model_ids]
 
         return {
             "provider": {

routstr/core/db.py

@@ -1,4 +1,6 @@
 import os
+import pathlib
+import sqlite3
 import time
 from contextlib import asynccontextmanager
 from typing import AsyncGenerator
@@ -181,11 +183,53 @@ async def create_session() -> AsyncGenerator[AsyncSession, None]:
         yield session
 
 
+def fix_cashu_migrations() -> None:
+    """
+    Fixes Cashu wallet migrations that are not idempotent.
+    This specifically addresses the 'duplicate column name: public_keys' error
+    in the keysets table of Cashu's internal SQLite databases.
+    """
+    project_root = pathlib.Path(__file__).resolve().parents[2]
+    wallet_dir = project_root / ".wallet"
+
+    if not wallet_dir.exists() or not wallet_dir.is_dir():
+        return
+
+    logger.info("Checking Cashu wallet databases for migration idempotency")
+
+    for db_file in wallet_dir.glob("*.sqlite3"):
+        try:
+            conn = sqlite3.connect(db_file)
+            cursor = conn.cursor()
+
+            # Check if keysets table exists
+            cursor.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='keysets'"
+            )
+            if not cursor.fetchone():
+                conn.close()
+                continue
+
+            # Check if public_keys column exists
+            cursor.execute("PRAGMA table_info(keysets)")
+            columns = [info[1] for info in cursor.fetchall()]
+
+            if "public_keys" not in columns:
+                logger.info(f"Adding missing public_keys column to {db_file.name}")
+                cursor.execute("ALTER TABLE keysets ADD COLUMN public_keys TEXT")
+                conn.commit()
+
+            conn.close()
+        except Exception as e:
+            logger.warning(f"Could not check/fix Cashu database {db_file}: {e}")
+
+
 def run_migrations() -> None:
     """Run Alembic migrations programmatically."""
-    import pathlib
-
     try:
+        # Run Cashu migration fix first
+        fix_cashu_migrations()
+
         # Get the path to the alembic.ini file
         project_root = pathlib.Path(__file__).resolve().parents[2]
         alembic_ini_path = project_root / "alembic.ini"

routstr/payment/helpers.py

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

routstr/proxy.py

@@ -300,9 +300,13 @@ async def proxy(
                         session,
                         model_obj,
                     )
+            except UpstreamError:
+                # Let the outer UpstreamError handler manage retry/revert
+                raise
             except Exception as e:
+                # Unexpected error (not an upstream failure) — revert and propagate
                 logger.error(
-                    "Upstream request failed, ensuring payment is reverted",
+                    "Unexpected error in upstream request, reverting payment",
                     extra={
                         "error": str(e),
                         "error_type": type(e).__name__,
@@ -390,7 +394,8 @@ async def get_bearer_token_key(
     headers: dict, path: str, session: AsyncSession, auth: str, min_cost: int = 0
 ) -> ApiKey:
     """Handle bearer token authentication proxy requests."""
-    bearer_key = auth.replace("Bearer ", "") if auth.startswith("Bearer ") else ""
+    parts = auth.split()
+    bearer_key = parts[1] if len(parts) > 1 and parts[0].lower() == "bearer" else ""
     refund_address = headers.get("Refund-LNURL", None)
     key_expiry_time = headers.get("Key-Expiry-Time", None)
 

routstr/upstream/azure.py

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

routstr/upstream/base.py

@@ -5,21 +5,18 @@ import json
 import re
 import traceback
 from collections.abc import AsyncGenerator
-from typing import TYPE_CHECKING, Mapping
+from typing import Mapping
 
 import httpx
 from fastapi import BackgroundTasks, HTTPException, Request
 from fastapi.responses import Response, StreamingResponse
 from pydantic import BaseModel
+from sqlmodel import select
 
-from ..auth import adjust_payment_for_tokens, revert_pay_for_request
+from ..auth import adjust_payment_for_tokens
 from ..core import get_logger
-from ..core.db import ApiKey, AsyncSession, create_session
+from ..core.db import ApiKey, AsyncSession, UpstreamProviderRow, create_session
 from ..core.exceptions import UpstreamError
-
-if TYPE_CHECKING:
-    from ..core.db import UpstreamProviderRow
-
 from ..payment.cost_calculation import (
     CostData,
     CostDataError,
@@ -32,6 +29,7 @@ from ..payment.models import (
     Pricing,
     _calculate_usd_max_costs,
     _update_model_sats_pricing,
+    list_models,
 )
 from ..payment.price import sats_usd_price
 from ..wallet import recieve_token, send_token
@@ -199,6 +197,23 @@ class BaseUpstreamProvider:
         """
         return model_id
 
+    def normalize_request_path(self, path: str, model_obj: Model | None = None) -> str:
+        """Normalize request path before forwarding to upstream."""
+        if path.startswith("v1/"):
+            return path.replace("v1/", "", 1)
+        return path
+
+    def get_request_base_url(
+        self, path: str, model_obj: Model | None = None
+    ) -> str:
+        """Get upstream base URL used when building forwarding URL."""
+        return self.base_url.rstrip("/")
+
+    def build_request_url(self, path: str, model_obj: Model | None = None) -> str:
+        """Build full upstream URL from normalized path."""
+        clean_path = path.lstrip("/")
+        return f"{self.get_request_base_url(path, model_obj)}/{clean_path}"
+
     def prepare_responses_request_body(
         self, body: bytes | None, model_obj: Model
     ) -> bytes | None:
@@ -525,10 +540,17 @@ class BaseUpstreamProvider:
                                     session,
                                     max_cost_for_model,
                                 )
+                                remaining_balance_msats = fresh_key.balance
                                 # Merge cost into usage
                                 usage_chunk_data["usage"]["cost"] = cost_data.get(
                                     "total_usd", 0.0
                                 )
+                                usage_chunk_data["usage"]["cost_sats"] = (
+                                    cost_data.get("total_msats", 0) // 1000
+                                )
+                                usage_chunk_data["usage"]["remaining_balance_msats"] = (
+                                    remaining_balance_msats
+                                )
                                 # Keep detailed cost in metadata
                                 usage_chunk_data["metadata"] = usage_chunk_data.get(
                                     "metadata", {}
@@ -536,6 +558,12 @@ class BaseUpstreamProvider:
                                 usage_chunk_data["metadata"]["routstr"] = {
                                     "cost": cost_data
                                 }
+                                usage_chunk_data["metadata"]["routstr"]["cost"][
+                                    "sats_cost"
+                                ] = cost_data.get("total_msats", 0) // 1000
+                                usage_chunk_data["metadata"]["routstr"]["cost"][
+                                    "remaining_balance_msats"
+                                ] = remaining_balance_msats
                                 yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
                                 usage_finalized = True
                             except Exception as e:
@@ -626,14 +654,31 @@ class BaseUpstreamProvider:
                 key, response_json, session, deducted_max_cost
             )
 
+            await session.refresh(key)
+            remaining_balance_msats = key.balance
+
             # Merge cost into usage for OpenCode
             if "usage" in response_json:
                 response_json["usage"]["cost"] = cost_data.get("total_usd", 0.0)
+                response_json["usage"]["cost_sats"] = (
+                    cost_data.get("total_msats", 0) // 1000
+                )
+                response_json["usage"]["remaining_balance_msats"] = (
+                    remaining_balance_msats
+                )
 
             # Keep detailed cost
             response_json["metadata"] = response_json.get("metadata", {})
             response_json["metadata"]["routstr"] = {"cost": cost_data}
+            response_json["metadata"]["routstr"]["cost"]["sats_cost"] = (
+                cost_data.get("total_msats", 0) // 1000
+            )
+            response_json["metadata"]["routstr"]["cost"]["remaining_balance_msats"] = (
+                remaining_balance_msats
+            )
             response_json["cost"] = cost_data
+            response_json["cost"]["sats_cost"] = cost_data.get("total_msats", 0) // 1000
+            response_json["cost"]["remaining_balance_msats"] = remaining_balance_msats
 
             logger.info(
                 "Payment adjustment completed for non-streaming",
@@ -803,6 +848,7 @@ class BaseUpstreamProvider:
                                     session,
                                     max_cost_for_model,
                                 )
+                                remaining_balance_msats = fresh_key.balance
                                 # Merge cost into usage chunk
                                 if (
                                     "response" in usage_chunk_data
@@ -811,10 +857,22 @@ class BaseUpstreamProvider:
                                     usage_chunk_data["response"]["usage"]["cost"] = (
                                         cost_data.get("total_usd", 0.0)
                                     )
+                                    usage_chunk_data["response"]["usage"][
+                                        "cost_sats"
+                                    ] = cost_data.get("total_msats", 0) // 1000
+                                    usage_chunk_data["response"]["usage"][
+                                        "remaining_balance_msats"
+                                    ] = remaining_balance_msats
                                 elif "usage" in usage_chunk_data:
                                     usage_chunk_data["usage"]["cost"] = cost_data.get(
                                         "total_usd", 0.0
                                     )
+                                    usage_chunk_data["usage"]["cost_sats"] = (
+                                        cost_data.get("total_msats", 0) // 1000
+                                    )
+                                    usage_chunk_data["usage"][
+                                        "remaining_balance_msats"
+                                    ] = remaining_balance_msats
 
                                 # Keep detailed cost in metadata
                                 usage_chunk_data["metadata"] = usage_chunk_data.get(
@@ -823,6 +881,12 @@ class BaseUpstreamProvider:
                                 usage_chunk_data["metadata"]["routstr"] = {
                                     "cost": cost_data
                                 }
+                                usage_chunk_data["metadata"]["routstr"]["cost"][
+                                    "sats_cost"
+                                ] = cost_data.get("total_msats", 0) // 1000
+                                usage_chunk_data["metadata"]["routstr"]["cost"][
+                                    "remaining_balance_msats"
+                                ] = remaining_balance_msats
                                 yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
                                 usage_finalized = True
                             except Exception:
@@ -907,14 +971,31 @@ class BaseUpstreamProvider:
                 key, response_json, session, deducted_max_cost
             )
 
+            await session.refresh(key)
+            remaining_balance_msats = key.balance
+
             # Merge cost into usage for OpenCode
             if "usage" in response_json:
                 response_json["usage"]["cost"] = cost_data.get("total_usd", 0.0)
+                response_json["usage"]["cost_sats"] = (
+                    cost_data.get("total_msats", 0) // 1000
+                )
+                response_json["usage"]["remaining_balance_msats"] = (
+                    remaining_balance_msats
+                )
 
             # Keep detailed cost
             response_json["metadata"] = response_json.get("metadata", {})
             response_json["metadata"]["routstr"] = {"cost": cost_data}
+            response_json["metadata"]["routstr"]["cost"]["sats_cost"] = (
+                cost_data.get("total_msats", 0) // 1000
+            )
+            response_json["metadata"]["routstr"]["cost"]["remaining_balance_msats"] = (
+                remaining_balance_msats
+            )
             response_json["cost"] = cost_data
+            response_json["cost"]["sats_cost"] = cost_data.get("total_msats", 0) // 1000
+            response_json["cost"]["remaining_balance_msats"] = remaining_balance_msats
 
             logger.info(
                 "Payment adjustment completed for non-streaming Responses API",
@@ -1037,10 +1118,8 @@ class BaseUpstreamProvider:
         Returns:
             Response or StreamingResponse from upstream with cost tracking
         """
-        if path.startswith("v1/"):
-            path = path.replace("v1/", "")
-
-        url = f"{self.base_url}/{path}"
+        path = self.normalize_request_path(path, model_obj)
+        url = self.build_request_url(path, model_obj)
 
         transformed_body = self.prepare_request_body(request_body, model_obj)
 
@@ -1215,8 +1294,7 @@ class BaseUpstreamProvider:
                 },
             )
 
-            await revert_pay_for_request(key, session, max_cost_for_model)
-
+            # Don't revert here — proxy.py owns payment revert to avoid double-revert
             if isinstance(exc, httpx.ConnectError):
                 error_message = "Unable to connect to upstream service"
             elif isinstance(exc, httpx.TimeoutException):
@@ -1246,13 +1324,9 @@ class BaseUpstreamProvider:
                 },
             )
 
-            await revert_pay_for_request(key, session, max_cost_for_model)
-
-            return create_error_response(
-                "internal_error",
-                "An unexpected server error occurred",
-                500,
-                request=request,
+            # Don't revert here — proxy.py owns payment revert to avoid double-revert
+            raise UpstreamError(
+                "An unexpected server error occurred", status_code=500
             )
 
     async def forward_responses_request(
@@ -1281,11 +1355,8 @@ class BaseUpstreamProvider:
         Returns:
             Response or StreamingResponse from upstream with cost tracking
         """
-        # Remove v1/ prefix if present for Responses API
-        if path.startswith("v1/"):
-            path = path.replace("v1/", "")
-
-        url = f"{self.base_url}/{path}"
+        path = self.normalize_request_path(path, model_obj)
+        url = self.build_request_url(path, model_obj)
 
         transformed_body = self.prepare_responses_request_body(request_body, model_obj)
 
@@ -1437,8 +1508,7 @@ class BaseUpstreamProvider:
                 },
             )
 
-            await revert_pay_for_request(key, session, max_cost_for_model)
-
+            # Don't revert here — proxy.py owns payment revert to avoid double-revert
             if isinstance(exc, httpx.ConnectError):
                 error_message = "Unable to connect to upstream service"
             elif isinstance(exc, httpx.TimeoutException):
@@ -1468,13 +1538,9 @@ class BaseUpstreamProvider:
                 },
             )
 
-            await revert_pay_for_request(key, session, max_cost_for_model)
-
-            return create_error_response(
-                "internal_error",
-                "An unexpected server error occurred",
-                500,
-                request=request,
+            # Don't revert here — proxy.py owns payment revert to avoid double-revert
+            raise UpstreamError(
+                "An unexpected server error occurred", status_code=500
             )
 
     async def forward_get_request(
@@ -1493,10 +1559,8 @@ class BaseUpstreamProvider:
         Returns:
             StreamingResponse from upstream
         """
-        if path.startswith("v1/"):
-            path = path.replace("v1/", "")
-
-        url = f"{self.base_url}/{path}"
+        path = self.normalize_request_path(path)
+        url = self.build_request_url(path)
 
         logger.info(
             "Forwarding GET request to upstream",
@@ -3023,18 +3087,44 @@ class BaseUpstreamProvider:
     async def refresh_models_cache(self) -> None:
         """Refresh the in-memory models cache from upstream API."""
         try:
-            models = await self.fetch_models()
-            models_with_fees = [self._apply_provider_fee_to_model(m) for m in models]
+            async with create_session() as session:
+                stmt = select(UpstreamProviderRow).where(
+                    UpstreamProviderRow.base_url == self.base_url,
+                    UpstreamProviderRow.api_key == self.api_key
+                )
+                result = await session.exec(stmt)
 
-            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
+                # .first() returns the object or None if not found
+                provider = result.first()
+                if not provider or not provider.id:
+                    raise HTTPException(status_code=404, detail="Provider not found")
 
-            self._models_by_id = {m.id: m for m in self._models_cache}
+                db_models = await list_models(
+                    session=session,
+                    upstream_id=provider.id,
+                    include_disabled=False,
+                    apply_fees=False,
+                )
+                db_model_ids: set[str] = {model.id for model in db_models}
+                models = await self.fetch_models()
+                model_ids = [model.id for model in models]
+                diff = set(db_model_ids) - set(model_ids)
+
+                for db_model_id in diff:
+                    found_db_model = next((model_obj for model_obj in db_models if model_obj.id == db_model_id))
+                    models.append(found_db_model)
+
+                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}
 
         except Exception as e:
             logger.error(

routstr/upstream/gemini.py

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

routstr/upstream/helpers.py

@@ -205,6 +205,9 @@ async def init_upstreams() -> list[BaseUpstreamProvider]:
 
             provider = _instantiate_provider(provider_row)
             if provider:
+                # Keep provider DB id on runtime instance so model mapping can
+                # bind DB overrides to the correct upstream.
+                setattr(provider, "db_id", provider_row.id)
                 await provider.refresh_models_cache()
                 logger.debug(
                     f"Initialized {provider_row.provider_type} provider",

routstr/upstream/ollama.py

@@ -3,13 +3,11 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 import httpx
-from fastapi import Request
-from fastapi.responses import Response, StreamingResponse
 
 from .base import BaseUpstreamProvider
 
 if TYPE_CHECKING:
-    from ..core.db import ApiKey, AsyncSession, UpstreamProviderRow
+    from ..core.db import UpstreamProviderRow
     from ..payment.models import Model
 
 from ..core.logging import get_logger
@@ -67,38 +65,11 @@ class OllamaUpstreamProvider(BaseUpstreamProvider):
         """Strip 'ollama/' prefix for Ollama API compatibility."""
         return model_id.removeprefix("ollama/")
 
-    async def forward_request(
-        self,
-        request: Request,
-        path: str,
-        headers: dict,
-        request_body: bytes | None,
-        key: ApiKey,
-        max_cost_for_model: int,
-        session: AsyncSession,
-        model_obj: Model,
-    ) -> Response | StreamingResponse:
-        """Override to use OpenAI-compatible endpoint for proxy requests."""
-        if path.startswith("v1/"):
-            path = path.replace("v1/", "")
-
-        original_base_url = self.base_url
-        self.base_url = f"{self.base_url}/v1"
-
-        try:
-            result = await super().forward_request(
-                request,
-                path,
-                headers,
-                request_body,
-                key,
-                max_cost_for_model,
-                session,
-                model_obj,
-            )
-            return result
-        finally:
-            self.base_url = original_base_url
+    def get_request_base_url(
+        self, path: str, model_obj: Model | None = None
+    ) -> str:
+        """Route proxy traffic through Ollama's OpenAI-compatible /v1 endpoint."""
+        return f"{self.base_url.rstrip('/')}/v1"
 
     async def fetch_models(self) -> list[Model]:
         """Fetch models from Ollama API using /api/tags endpoint."""

tests/integration/test_child_keys_api.py

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

tests/integration/test_reserved_balance_negative.py

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

tests/unit/test_algorithm.py

@@ -1,14 +1,18 @@
 """Tests for the model prioritization algorithm."""
 
 import os
+from types import SimpleNamespace
 from unittest.mock import Mock
 
+import pytest
+
 # Set required env vars before importing
 os.environ["UPSTREAM_BASE_URL"] = "http://test"
 os.environ["UPSTREAM_API_KEY"] = "test"
 
 from routstr.algorithm import (  # noqa: E402
     calculate_model_cost_score,
+    create_model_mappings,
     get_provider_penalty,
 )
 from routstr.payment.models import Architecture, Model, Pricing  # noqa: E402
@@ -45,11 +49,21 @@ def create_test_model(
     )
 
 
-def create_test_provider(name: str, base_url: str = "http://test.com") -> Mock:
+def create_test_provider(
+    name: str,
+    base_url: str = "http://test.com",
+    *,
+    db_id: int | None = None,
+    models: list[Model] | None = None,
+    upstream_name: str | None = None,
+) -> Mock:
     """Helper to create a test provider mock."""
     provider = Mock()
     provider.provider_type = name
     provider.base_url = base_url
+    provider.db_id = db_id
+    provider.upstream_name = upstream_name or name
+    provider.get_cached_models.return_value = models or []
     return provider
 
 
@@ -99,3 +113,80 @@ def test_get_provider_penalty_openrouter() -> None:
     provider = create_test_provider("openrouter", "https://openrouter.ai/api/v1")
     penalty = get_provider_penalty(provider)
     assert penalty == 1.001
+
+
+def test_create_model_mappings_includes_db_override_for_missing_cached_model(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Model overrides should still map when provider discovery misses the model."""
+    provider = create_test_provider(
+        "azure",
+        "https://example.openai.azure.com/openai/v1",
+        db_id=7,
+        models=[],
+    )
+    override_model = create_test_model("azure/gpt-4o")
+    override_model.canonical_slug = "azure-deployment"
+
+    def fake_row_to_model(*args, **kwargs) -> Model:  # type: ignore[no-untyped-def]
+        return override_model
+
+    monkeypatch.setattr("routstr.payment.models._row_to_model", fake_row_to_model)
+
+    override_row = SimpleNamespace(id="azure/gpt-4o", upstream_provider_id=7, enabled=True)
+
+    model_instances, provider_map, unique_models = create_model_mappings(
+        upstreams=[provider],
+        overrides_by_id={"azure/gpt-4o": (override_row, 1.01)},
+        disabled_model_ids=set(),
+    )
+
+    assert "azure/gpt-4o" in model_instances
+    assert provider_map["azure/gpt-4o"] == [provider]
+    assert "gpt-4o" in unique_models
+
+
+def test_create_model_mappings_dedupes_with_provider_identity_not_provider_type(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Different provider instances of same type should both survive dedupe."""
+    provider_a_model = create_test_model(
+        "azure/gpt-4o", prompt_price=0.01, completion_price=0.01
+    )
+    provider_a = create_test_provider(
+        "azure",
+        "https://a.openai.azure.com/openai/v1",
+        db_id=1,
+        models=[provider_a_model],
+        upstream_name="azure-a",
+    )
+    provider_b = create_test_provider(
+        "azure",
+        "https://b.openai.azure.com/openai/v1",
+        db_id=2,
+        models=[],
+        upstream_name="azure-b",
+    )
+
+    override_model = create_test_model(
+        "azure/gpt-4o", prompt_price=0.001, completion_price=0.001
+    )
+    override_model.canonical_slug = "azure-b-deployment"
+
+    def fake_row_to_model(*args, **kwargs) -> Model:  # type: ignore[no-untyped-def]
+        return override_model
+
+    monkeypatch.setattr("routstr.payment.models._row_to_model", fake_row_to_model)
+
+    override_row = SimpleNamespace(id="azure/gpt-4o", upstream_provider_id=2, enabled=True)
+
+    _, provider_map, _ = create_model_mappings(
+        upstreams=[provider_a, provider_b],
+        overrides_by_id={"azure/gpt-4o": (override_row, 1.01)},
+        disabled_model_ids=set(),
+    )
+
+    providers_for_alias = provider_map["azure/gpt-4o"]
+    assert provider_a in providers_for_alias
+    assert provider_b in providers_for_alias
+    assert len(providers_for_alias) == 2

tests/unit/test_upstream_azure.py

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

ui/components/child-key-creator.tsx

@@ -251,7 +251,7 @@ export function ChildKeyCreator({
             )}
 
             <div className='flex flex-col gap-6'>
-              {configs.map((config, index) => (
+              {configs.map((config) => (
                 <div
                   key={config.id}
                   className='bg-muted/30 relative space-y-4 rounded-lg border p-4 pt-6'

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

@@ -7,19 +7,8 @@ import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Separator } from '@/components/ui/separator';
-
-type WalletSnapshot = {
-  apiKey: string;
-  balanceMsats: number;
-  reservedMsats: number;
-};
-
-type RefundReceipt = {
-  token?: string;
-  recipient?: string;
-  sats?: string;
-  msats?: string;
-};
+import type { WalletSnapshot, ChildKeyInfo } from './key-info-details';
+import type { RefundReceipt } from './cashu-payment-workflow';
 
 interface ApiKeyManagerProps {
   baseUrl: string;
@@ -51,12 +40,28 @@ async function fetchWalletInfo(
     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,
   };
 }
 

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

@@ -9,14 +9,9 @@ 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 type { ChildKeyInfo, WalletSnapshot } from './key-info-details';
 
-type WalletSnapshot = {
-  apiKey: string;
-  balanceMsats: number;
-  reservedMsats: number;
-};
-
-type RefundReceipt = {
+export type RefundReceipt = {
   token?: string;
   recipient?: string;
   sats?: string;
@@ -54,12 +49,28 @@ async function fetchWalletInfo(
     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,
   };
 }
 
@@ -147,11 +158,25 @@ export function CashuPaymentWorkflow({
       const payload = (await response.json()) as {
         api_key: string;
         balance: 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;
       };
       const snapshot: WalletSnapshot = {
         apiKey: payload.api_key,
         balanceMsats: payload.balance ?? 0,
         reservedMsats: 0,
+        isChild: payload.is_child ?? false,
+        parentKey: payload.parent_key ?? null,
+        totalRequests: payload.total_requests ?? 0,
+        totalSpent: payload.total_spent ?? 0,
+        balanceLimit: payload.balance_limit ?? null,
+        balanceLimitReset: payload.balance_limit_reset ?? null,
+        validityDate: payload.validity_date ?? null,
       };
 
       setApiKeyInput(snapshot.apiKey);

ui/components/landing/cheat-sheet.tsx

@@ -11,29 +11,24 @@ import { Input } from '@/components/ui/input';
 import { Badge } from '@/components/ui/badge';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { ConfigurationService } from '@/lib/api/services/configuration';
-import { CashuPaymentWorkflow } from './cashu-payment-workflow';
+import {
+  CashuPaymentWorkflow,
+  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';
 
 type NodeInfo = {
-  name: string;
-  description: string;
-  version: string;
-  npub?: string | null;
-  mints: string[];
-  http_url?: string | null;
-  onion_url?: string | null;
+  name?: string;
+  description?: string;
+  version?: string;
+  http_url?: string;
+  onion_url?: string;
+  npub?: string;
+  mints?: string[];
   child_key_cost_msats?: number;
-};
-
-type WalletSnapshot = {
-  apiKey: string;
-  balanceMsats: number;
-  reservedMsats: number;
-};
-
-type RefundReceipt = {
   token?: string;
   recipient?: string;
   sats?: string;
@@ -285,7 +280,7 @@ export function CheatSheet(): JSX.Element {
                       Cashu mints
                     </p>
                     <div className='flex flex-wrap gap-2'>
-                      {nodeInfo.mints.length ? (
+                      {nodeInfo.mints?.length ? (
                         nodeInfo.mints.map((mint) => (
                           <Badge
                             key={mint}
@@ -364,10 +359,11 @@ export function CheatSheet(): JSX.Element {
         </section>
 
         <Tabs defaultValue='cashu' className='w-full'>
-          <TabsList className='grid w-full grid-cols-4'>
-            <TabsTrigger value='cashu'>Cashu Payments</TabsTrigger>
-            <TabsTrigger value='lightning'>Lightning Payments</TabsTrigger>
+          <TabsList className='grid w-full grid-cols-5'>
+            <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>
           </TabsList>
 
@@ -426,6 +422,16 @@ 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

@@ -0,0 +1,429 @@
+'use client';
+
+import { type JSX, useState, useCallback, useEffect } from 'react';
+import {
+  Copy,
+  RefreshCcw,
+  ShieldCheck,
+  History,
+  Users,
+  RotateCcw,
+  KeyRound,
+} from 'lucide-react';
+import { toast } from 'sonner';
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+} 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';
+
+export type ChildKeyInfo = {
+  api_key: string;
+  total_requests: number;
+  total_spent: number;
+  balance_limit: number | null;
+  balance_limit_reset: string | null;
+  validity_date: number | null;
+};
+
+export type WalletSnapshot = {
+  apiKey: string;
+  balanceMsats: number;
+  reservedMsats: number;
+  isChild: boolean;
+  parentKey: string | null;
+  totalRequests: number;
+  totalSpent: number;
+  balanceLimit: number | null;
+  balanceLimitReset: string | null;
+  validityDate: number | null;
+  childKeys?: ChildKeyInfo[];
+};
+
+interface KeyInfoDetailsProps {
+  baseUrl: string;
+  apiKey?: string;
+  walletInfo?: WalletSnapshot | null;
+  onApiKeyChanged?: (apiKey: string) => void;
+  onWalletInfoUpdated?: (walletInfo: WalletSnapshot | null) => void;
+}
+
+export function KeyInfoDetails({
+  baseUrl,
+  apiKey = '',
+  walletInfo = null,
+  onApiKeyChanged,
+  onWalletInfoUpdated,
+}: KeyInfoDetailsProps): JSX.Element {
+  const [apiKeyInput, setApiKeyInput] = useState(apiKey);
+  const [isRefreshing, setIsRefreshing] = useState(false);
+  const [isResetting, setIsResetting] = useState<string | null>(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 () => {
+    if (!apiKeyInput) return;
+    await fetchDetails(apiKeyInput);
+  };
+
+  const handleKeyChange = (newKey: string) => {
+    setApiKeyInput(newKey);
+    onApiKeyChanged?.(newKey);
+    // Optionally clear info when key changes
+    if (newKey !== apiKey) {
+      onWalletInfoUpdated?.(null);
+    }
+  };
+
+  const handleCopy = (value: string) => {
+    navigator.clipboard.writeText(value);
+    toast.success('Copied to clipboard');
+  };
+
+  const handleResetSpent = async (childKey: string) => {
+    if (!walletInfo || walletInfo.isChild) return;
+
+    setIsResetting(childKey);
+    try {
+      await WalletService.resetChildKeySpent(baseUrl, apiKeyInput, childKey);
+      toast.success('Child key spent reset');
+      await fetchDetails(apiKeyInput);
+    } catch (error) {
+      toast.error(
+        error instanceof Error ? error.message : 'Failed to reset child key'
+      );
+    } finally {
+      setIsResetting(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';
+
+  return (
+    <div className='space-y-6'>
+      <Card>
+        <CardHeader className='space-y-1'>
+          <CardTitle className='flex items-center gap-2 text-xl'>
+            <KeyRound className='text-primary h-5 w-5' />
+            Key Information
+          </CardTitle>
+          <CardDescription>
+            Enter an API key to view its balance, consumption, and child keys.
+          </CardDescription>
+        </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'
+            />
+            <div className='flex gap-2'>
+              <Button
+                variant='outline'
+                size='icon'
+                className='h-10 w-10 shrink-0'
+                onClick={() => handleCopy(apiKeyInput)}
+                disabled={!apiKeyInput}
+              >
+                <Copy className='h-4 w-4' />
+              </Button>
+              <Button
+                variant='secondary'
+                size='sm'
+                className='min-w-[80px] gap-1'
+                onClick={handleRefresh}
+                disabled={isRefreshing || !apiKeyInput}
+              >
+                <RefreshCcw
+                  className={`h-4 w-4 ${isRefreshing ? 'animate-spin' : ''}`}
+                />
+                {isRefreshing ? 'Syncing...' : 'Sync'}
+              </Button>
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      {walletInfo && (
+        <>
+          <div className='grid gap-4 md:grid-cols-2'>
+            <Card>
+              <CardHeader className='pb-2'>
+                <CardTitle className='flex items-center gap-2 text-lg'>
+                  <ShieldCheck className='text-primary h-5 w-5' />
+                  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 uppercase'>
+                      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>
+                <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>
+              </CardContent>
+            </Card>
+
+            <Card>
+              <CardHeader className='pb-2'>
+                <CardTitle className='flex items-center gap-2 text-lg'>
+                  <History className='text-primary h-5 w-5' />
+                  Consumption
+                </CardTitle>
+              </CardHeader>
+              <CardContent className='space-y-4'>
+                <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='flex items-center gap-2 text-lg'>
+                    <Users className='text-primary h-5 w-5' />
+                    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>
+                            <Button
+                              variant='ghost'
+                              size='icon'
+                              className='text-destructive h-8 w-8'
+                              title='Reset consumption'
+                              disabled={isResetting === ck.api_key}
+                              onClick={() => handleResetSpent(ck.api_key)}
+                            >
+                              {isResetting === ck.api_key ? (
+                                <RefreshCcw className='h-4 w-4 animate-spin' />
+                              ) : (
+                                <RotateCcw className='h-4 w-4' />
+                              )}
+                            </Button>
+                          </div>
+                        </div>
+                        <div className='grid grid-cols-2 gap-4 text-xs sm:grid-cols-5'>
+                          <div>
+                            <p className='text-muted-foreground text-[0.6rem] tracking-wider uppercase'>
+                              Requests
+                            </p>
+                            <p className='font-mono font-medium'>
+                              {ck.total_requests}
+                            </p>
+                          </div>
+                          <div>
+                            <p className='text-muted-foreground text-[0.6rem] tracking-wider uppercase'>
+                              Spent
+                            </p>
+                            <p className='font-mono font-medium'>
+                              {formatSats(ck.total_spent)} sats
+                            </p>
+                          </div>
+                          <div>
+                            <p className='text-muted-foreground text-[0.6rem] tracking-wider uppercase'>
+                              Limit
+                            </p>
+                            <p className='font-mono font-medium'>
+                              {ck.balance_limit
+                                ? `${formatSats(ck.balance_limit)} sats`
+                                : 'None'}
+                            </p>
+                          </div>
+                          <div>
+                            <p className='text-muted-foreground text-[0.6rem] tracking-wider uppercase'>
+                              Policy
+                            </p>
+                            <p className='font-medium capitalize'>
+                              {ck.balance_limit_reset || 'None'}
+                            </p>
+                          </div>
+                          <div>
+                            <p className='text-muted-foreground text-[0.6rem] tracking-wider uppercase'>
+                              Expires
+                            </p>
+                            <p className='font-medium'>
+                              {formatDate(ck.validity_date)}
+                            </p>
+                          </div>
+                        </div>
+                      </div>
+                    ))}
+                  </div>
+                </CardContent>
+              </Card>
+            )}
+
+          <div className='flex justify-center'>
+            <Button
+              variant='ghost'
+              size='sm'
+              onClick={handleRefresh}
+              disabled={isRefreshing}
+              className='text-muted-foreground'
+            >
+              <RefreshCcw
+                className={`mr-2 h-3 w-3 ${isRefreshing ? 'animate-spin' : ''}`}
+              />
+              Last synced: {new Date().toLocaleTimeString()}
+            </Button>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

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

@@ -11,12 +11,7 @@ import { Input } from '@/components/ui/input';
 import { Textarea } from '@/components/ui/textarea';
 import { Separator } from '@/components/ui/separator';
 import { KeyOptions } from '@/components/key-options';
-
-type WalletSnapshot = {
-  apiKey: string;
-  balanceMsats: number;
-  reservedMsats: number;
-};
+import type { WalletSnapshot } from './key-info-details';
 
 type LightningInvoice = {
   invoice_id: string;
@@ -215,6 +210,13 @@ export function LightningPaymentWorkflow({
             apiKey: status.api_key,
             balanceMsats: status.amount_sats * 1000,
             reservedMsats: 0,
+            isChild: false,
+            parentKey: null,
+            totalRequests: 0,
+            totalSpent: 0,
+            balanceLimit: null,
+            balanceLimitReset: null,
+            validityDate: null,
           };
           onApiKeyCreated?.(status.api_key, walletInfo);
           setCreatedApiKey(status.api_key);
@@ -289,6 +291,13 @@ export function LightningPaymentWorkflow({
             apiKey: status.api_key,
             balanceMsats: status.amount_sats * 1000,
             reservedMsats: 0,
+            isChild: false,
+            parentKey: null,
+            totalRequests: 0,
+            totalSpent: 0,
+            balanceLimit: null,
+            balanceLimitReset: null,
+            validityDate: null,
           };
           onApiKeyCreated?.(status.api_key, walletInfo);
           setTopupApiKeyResult(status.api_key);
@@ -343,6 +352,13 @@ export function LightningPaymentWorkflow({
           apiKey: status.api_key,
           balanceMsats: status.amount_sats * 1000,
           reservedMsats: 0,
+          isChild: false,
+          parentKey: null,
+          totalRequests: 0,
+          totalSpent: 0,
+          balanceLimit: null,
+          balanceLimitReset: null,
+          validityDate: null,
         };
         onApiKeyCreated?.(status.api_key, walletInfo);
         setRecoveredApiKey(status.api_key);

ui/lib/api/services/auth.ts

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import { apiClient } from '../client';
 import { ConfigurationService } from './configuration';
 import axios from 'axios';