fix test

Allow multiple providers per base URL

docs/api/endpoints.md

@@ -434,6 +434,42 @@ Authorization: Bearer sk-...
 }
 ```
 
+### Create Child Key
+
+Creates one or more child API keys that share the parent's balance. Each child key creation costs a fixed amount (configurable).
+
+```http
+POST /v1/balance/child-key
+Authorization: Bearer sk-...
+```
+
+**Request Body:**
+
+```json
+{
+  "count": 1
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `count` | integer | Yes | - | Number of child keys to create (1-50) |
+
+**Response:**
+
+```json
+{
+  "api_keys": ["sk-abc...", "sk-def..."],
+  "count": 2,
+  "cost_msats": 2000,
+  "cost_sats": 2,
+  "parent_balance": 98000,
+  "parent_balance_sats": 98
+}
+```
+
 ## Provider Discovery
 
 ## Admin Settings

examples/create_child_keys.py

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

migrations/versions/06f81c0fc88d_add_key_management_and_reset_fields_to_.py

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

migrations/versions/a86e5348850b_.py

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

migrations/versions/c2d3e4f5a6b7_upstream_provider_base_url_api_key_unique.py

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

pyproject.toml

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

routstr/algorithm.py

@@ -84,93 +84,26 @@ def get_provider_penalty(provider: "BaseUpstreamProvider") -> float:
     return penalty
 
 
-def should_prefer_model(
-    candidate_model: "Model",
-    candidate_provider: "BaseUpstreamProvider",
-    current_model: "Model",
-    current_provider: "BaseUpstreamProvider",
-    alias: str,
-) -> bool:
-    """Determine if candidate model should replace current model for an alias.
-
-    This is the core decision function for model prioritization. It considers:
-    1. Alias matching quality (exact match vs. canonical slug match)
-    2. Model cost (lower is better)
-    3. Provider penalties (e.g., slight preference against OpenRouter)
-
-    Args:
-        candidate_model: The new model being considered
-        candidate_provider: Provider offering the candidate model
-        current_model: The currently selected model for this alias
-        current_provider: Provider offering the current model
-        alias: The model alias being mapped
-
-    Returns:
-        True if candidate should replace current, False otherwise
-    """
-
-    def get_base_model_id(model_id: str) -> str:
-        """Get base model ID by removing provider prefix."""
-        return model_id.split("/", 1)[1] if "/" in model_id else model_id
-
-    def alias_priority(model: "Model") -> int:
-        """Rank how strong the mapping of alias->model is.
-
-        Highest priority when alias exactly equals the model ID without provider prefix.
-        Next when alias equals canonical slug without prefix. Otherwise lowest.
-        """
-        model_base = get_base_model_id(model.id)
-        if model_base == alias:
-            return 3
-        if model.canonical_slug:
-            canonical_base = get_base_model_id(model.canonical_slug)
-            if canonical_base == alias:
-                return 2
-        return 1
-
-    candidate_alias_priority = alias_priority(candidate_model)
-    current_alias_priority = alias_priority(current_model)
-
-    # If candidate has better alias match, prefer it regardless of cost
-    if candidate_alias_priority > current_alias_priority:
-        return True
-
-    # If current has better alias match, keep it regardless of cost
-    if current_alias_priority > candidate_alias_priority:
-        return False
-
-    # Same alias priority - compare costs
-    candidate_cost = calculate_model_cost_score(candidate_model)
-    current_cost = calculate_model_cost_score(current_model)
-
-    # Apply provider penalties
-    candidate_adjusted = candidate_cost * get_provider_penalty(candidate_provider)
-    current_adjusted = current_cost * get_provider_penalty(current_provider)
-
-    # Prefer lower adjusted cost
-    should_replace = candidate_adjusted < current_adjusted
-
-    return should_replace
-
-
 def create_model_mappings(
     upstreams: list["BaseUpstreamProvider"],
     overrides_by_id: dict[str, tuple],
     disabled_model_ids: set[str],
-) -> tuple[dict[str, "Model"], dict[str, "BaseUpstreamProvider"], dict[str, "Model"]]:
+) -> tuple[
+    dict[str, "Model"], dict[str, list["BaseUpstreamProvider"]], dict[str, "Model"]
+]:
     """Create optimal model mappings based on cost and provider preferences.
 
     This is the main entry point for the algorithm. It processes all upstream providers
     and creates three mappings based on cost optimization:
 
     1. model_instances: alias -> Model (all model aliases mapped to their Model objects)
-    2. provider_map: alias -> UpstreamProvider (which provider to use for each alias)
+    2. provider_map: alias -> List[UpstreamProvider] (sorted list of providers for each alias)
     3. unique_models: base_id -> Model (unique models without provider prefixes)
 
     The algorithm:
     - Processes non-OpenRouter providers first (they're typically cheaper)
     - Then processes OpenRouter models (they can still win if cheaper)
-    - For each model alias, uses should_prefer_model() to select the best provider
+    - For each model alias, collects all candidates and sorts them by priority and cost.
 
     Args:
         upstreams: List of all upstream provider instances
@@ -183,8 +116,7 @@ def create_model_mappings(
     from .payment.models import _row_to_model
     from .upstream.helpers import resolve_model_alias
 
-    model_instances: dict[str, "Model"] = {}
-    provider_map: dict[str, "BaseUpstreamProvider"] = {}
+    candidates: dict[str, list[tuple["Model", "BaseUpstreamProvider"]]] = {}
     unique_models: dict[str, "Model"] = {}
 
     # Separate OpenRouter from other providers
@@ -202,24 +134,14 @@ def create_model_mappings(
         """Get base model ID by removing provider prefix."""
         return model_id.split("/", 1)[1] if "/" in model_id else model_id
 
-    def _maybe_set_alias(
+    def _add_candidate(
         alias: str, model: "Model", provider: "BaseUpstreamProvider"
     ) -> None:
-        """Set alias to model/provider if not set or if new model is preferred."""
+        """Add candidate model/provider for an alias."""
         alias_lower = alias.lower()
-        existing_model = model_instances.get(alias_lower)
-        if not existing_model:
-            # No existing mapping, set it
-            model_instances[alias_lower] = model
-            provider_map[alias_lower] = provider
-        else:
-            # Check if candidate should replace existing
-            existing_provider = provider_map[alias_lower]
-            if should_prefer_model(
-                model, provider, existing_model, existing_provider, alias
-            ):
-                model_instances[alias_lower] = model
-                provider_map[alias_lower] = provider
+        if alias_lower not in candidates:
+            candidates[alias_lower] = []
+        candidates[alias_lower].append((model, provider))
 
     def process_provider_models(
         upstream: "BaseUpstreamProvider", is_openrouter: bool = False
@@ -266,21 +188,55 @@ def create_model_mappings(
 
             # Try to set each alias
             for alias in aliases:
-                _maybe_set_alias(alias, model_to_use, upstream)
+                _add_candidate(alias, model_to_use, upstream)
 
-    # Process non-OpenRouter providers first (they're typically cheaper)
+    # Process non-OpenRouter providers first
     for upstream in other_upstreams:
         process_provider_models(upstream, is_openrouter=False)
 
-    # Process OpenRouter last - models only win if they're cheaper or better matched
+    # Process OpenRouter last
     if openrouter:
         process_provider_models(openrouter, is_openrouter=True)
 
-    # Log provider distribution
+    # Sort candidates and build final maps
+    model_instances: dict[str, "Model"] = {}
+    provider_map: dict[str, list["BaseUpstreamProvider"]] = {}
+
+    def alias_priority(model: "Model", alias: str) -> int:
+        """Rank how strong the mapping of alias->model is."""
+        model_base = get_base_model_id(model.id)
+        if model_base == alias:
+            return 3
+        if model.canonical_slug:
+            canonical_base = get_base_model_id(model.canonical_slug)
+            if canonical_base == alias:
+                return 2
+        return 1
+
+    for alias, items in candidates.items():
+        # Sort key: (priority DESC, cost ASC)
+        # Using negative cost for DESC sort overall to keep high priority first
+        def sort_key(item: tuple["Model", "BaseUpstreamProvider"]) -> tuple[int, float]:
+            model, provider = item
+            priority = alias_priority(model, alias)
+            cost = calculate_model_cost_score(model)
+            penalty = get_provider_penalty(provider)
+            adjusted_cost = cost * penalty
+            return (priority, -adjusted_cost)
+
+        items.sort(key=sort_key, reverse=True)
+
+        best_model, best_provider = items[0]
+        model_instances[alias] = best_model
+        provider_map[alias] = [p for _, p in items]
+
+    # Log provider distribution (using top provider for stats)
     provider_counts: dict[str, int] = {}
-    for provider in provider_map.values():
-        provider_name = getattr(provider, "upstream_name", "unknown")
-        provider_counts[provider_name] = provider_counts.get(provider_name, 0) + 1
+    for providers in provider_map.values():
+        if providers:
+            provider = providers[0]
+            provider_name = getattr(provider, "upstream_name", "unknown")
+            provider_counts[provider_name] = provider_counts.get(provider_name, 0) + 1
 
     logger.debug(
         f"Updated model mappings with ({len(unique_models)} unique models and {len(model_instances)} aliases)",

routstr/auth.py

@@ -1,10 +1,14 @@
+import asyncio
 import hashlib
 import math
+import random
+import time
+from datetime import datetime
 from typing import Optional
 
 from fastapi import HTTPException
 from sqlalchemy.exc import IntegrityError
-from sqlmodel import col, update
+from sqlmodel import col, select, update
 
 from .core import get_logger
 from .core.db import ApiKey, AsyncSession
@@ -24,16 +28,60 @@ logger = get_logger(__name__)
 # PREPAID_BALANCE = int(os.environ.get("PREPAID_BALANCE", "0")) * 1000  # Convert to msats
 
 
+async def check_and_reset_limit(key: ApiKey, session: AsyncSession) -> bool:
+    """Checks if a key's balance limit should be reset based on its policy."""
+    if key.balance_limit is not None and key.balance_limit_reset:
+        now = int(time.time())
+        reset_date = key.balance_limit_reset_date or 0
+        should_reset = False
+
+        if key.balance_limit_reset == "daily":
+            if (
+                datetime.fromtimestamp(now).date()
+                > datetime.fromtimestamp(reset_date).date()
+            ):
+                should_reset = True
+        elif key.balance_limit_reset == "weekly":
+            if (
+                datetime.fromtimestamp(now).isocalendar()[:2]
+                > datetime.fromtimestamp(reset_date).isocalendar()[:2]
+            ):
+                should_reset = True
+        elif key.balance_limit_reset == "monthly":
+            dt_now = datetime.fromtimestamp(now)
+            dt_reset = datetime.fromtimestamp(reset_date)
+            if dt_now.year > dt_reset.year or dt_now.month > dt_reset.month:
+                should_reset = True
+
+        if should_reset:
+            logger.info(
+                "Resetting balance limit for key",
+                extra={
+                    "key_hash": key.hashed_key[:8] + "...",
+                    "policy": key.balance_limit_reset,
+                    "old_spent": key.total_spent,
+                },
+            )
+            key.total_spent = 0
+            key.balance_limit_reset_date = now
+            session.add(key)
+            await session.flush()
+            return True
+    return False
+
+
 async def validate_bearer_key(
     bearer_key: str,
     session: AsyncSession,
     refund_address: Optional[str] = None,
     key_expiry_time: Optional[int] = None,
+    min_cost: int = 0,
 ) -> ApiKey:
     """
     Validates the provided API key using SQLModel.
     If it's a cashu key, it redeems it and stores its hash and balance.
     Otherwise checks if the hash of the key exists.
+    Includes a balance check against min_cost for limited keys.
     """
     logger.debug(
         "Starting bearer key validation",
@@ -43,6 +91,7 @@ async def validate_bearer_key(
             else bearer_key,
             "has_refund_address": bool(refund_address),
             "has_expiry_time": bool(key_expiry_time),
+            "min_cost": min_cost,
         },
     )
 
@@ -97,6 +146,50 @@ async def validate_bearer_key(
                     },
                 )
 
+            # Check and reset limit if needed
+            await check_and_reset_limit(existing_key, session)
+
+            # Early check: Billing balance check (Parent balance)
+            billing_key = await get_billing_key(existing_key, session)
+            if min_cost > 0 and billing_key.total_balance < min_cost:
+                logger.warning(
+                    "Insufficient billing balance during validation",
+                    extra={
+                        "key_hash": existing_key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                        "balance": billing_key.total_balance,
+                        "required": min_cost,
+                    },
+                )
+                raise HTTPException(
+                    status_code=402,
+                    detail={
+                        "error": {
+                            "message": f"Insufficient balance: {min_cost} mSats required for this model. {billing_key.total_balance} available.",
+                            "type": "insufficient_quota",
+                            "code": "insufficient_balance",
+                        }
+                    },
+                )
+
+            # Early check: Spending limit check (Child key limit)
+            if (
+                min_cost > 0
+                and existing_key.balance_limit is not None
+                and existing_key.total_spent + existing_key.reserved_balance + min_cost
+                > existing_key.balance_limit
+            ):
+                raise HTTPException(
+                    status_code=402,
+                    detail={
+                        "error": {
+                            "message": f"Balance limit exceeded: {existing_key.balance_limit} mSats limit. {existing_key.total_spent} already spent ({existing_key.reserved_balance} reserved), {min_cost} minimum required for this model.",
+                            "type": "insufficient_quota",
+                            "code": "balance_limit_exceeded",
+                        }
+                    },
+                )
+
             return existing_key
         else:
             logger.warning(
@@ -152,6 +245,19 @@ async def validate_bearer_key(
                         },
                     )
 
+                # Early check: Billing balance check
+                if min_cost > 0 and existing_key.total_balance < min_cost:
+                    raise HTTPException(
+                        status_code=402,
+                        detail={
+                            "error": {
+                                "message": f"Insufficient balance: {min_cost} mSats required for this model. {existing_key.total_balance} available.",
+                                "type": "insufficient_quota",
+                                "code": "insufficient_balance",
+                            }
+                        },
+                    )
+
                 return existing_key
 
             logger.info(
@@ -286,30 +392,57 @@ async def validate_bearer_key(
     )
 
 
+async def get_billing_key(key: ApiKey, session: AsyncSession) -> ApiKey:
+    """Returns the key that should be charged for the request."""
+    if key.parent_key_hash:
+        parent = await session.get(ApiKey, key.parent_key_hash)
+        if parent:
+            # We want to keep the total_requests and total_spent on the child key
+            # but use the balance and reserved_balance of the parent.
+            # However, pay_for_request updates reserved_balance and total_requests.
+            # To stay simple, we charge the parent's balance and update parent's total_requests.
+            return parent
+        else:
+            logger.error(
+                "Parent key not found for child key",
+                extra={
+                    "child_key_hash": key.hashed_key[:8] + "...",
+                    "parent_key_hash": key.parent_key_hash[:8] + "...",
+                },
+            )
+    return key
+
+
 async def pay_for_request(
     key: ApiKey, cost_per_request: int, session: AsyncSession
 ) -> int:
     """Process payment for a request."""
+    # Ensure cost_per_request is at least the minimum allowed request cost
+    cost_per_request = max(cost_per_request, settings.min_request_msat)
+
+    billing_key = await get_billing_key(key, session)
 
     logger.info(
         "Processing payment for request",
         extra={
             "key_hash": key.hashed_key[:8] + "...",
-            "current_balance": key.balance,
+            "billing_key_hash": billing_key.hashed_key[:8] + "...",
+            "current_balance": billing_key.balance,
             "required_cost": cost_per_request,
-            "sufficient_balance": key.balance >= cost_per_request,
+            "sufficient_balance": billing_key.balance >= cost_per_request,
         },
     )
 
-    if key.total_balance < cost_per_request:
+    if billing_key.total_balance < cost_per_request:
         logger.warning(
             "Insufficient balance for request",
             extra={
                 "key_hash": key.hashed_key[:8] + "...",
-                "balance": key.balance,
-                "reserved_balance": key.reserved_balance,
+                "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                "balance": billing_key.balance,
+                "reserved_balance": billing_key.reserved_balance,
                 "required": cost_per_request,
-                "shortfall": cost_per_request - key.total_balance,
+                "shortfall": cost_per_request - billing_key.total_balance,
             },
         )
 
@@ -317,26 +450,78 @@ async def pay_for_request(
             status_code=402,
             detail={
                 "error": {
-                    "message": f"Insufficient balance: {cost_per_request} mSats required. {key.total_balance} available. (reserved: {key.reserved_balance})",
+                    "message": f"Insufficient balance: {cost_per_request} mSats required. {billing_key.total_balance} available. (reserved: {billing_key.reserved_balance})",
                     "type": "insufficient_quota",
                     "code": "insufficient_balance",
                 }
             },
         )
 
+    # Check validity date
+    if key.validity_date is not None:
+        if time.time() > key.validity_date:
+            logger.warning(
+                "Key validity date expired",
+                extra={
+                    "key_hash": key.hashed_key[:8] + "...",
+                    "validity_date": key.validity_date,
+                    "current_time": time.time(),
+                },
+            )
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": {
+                        "message": "API key has expired (validity date reached).",
+                        "type": "invalid_request_error",
+                        "code": "key_expired",
+                    }
+                },
+            )
+
+    # Check balance limit for child keys (or any key with a limit)
+    if key.balance_limit is not None:
+        await check_and_reset_limit(key, session)
+
+        if (
+            key.total_spent + key.reserved_balance + cost_per_request
+            > key.balance_limit
+        ):
+            logger.warning(
+                "Balance limit exceeded",
+                extra={
+                    "key_hash": key.hashed_key[:8] + "...",
+                    "total_spent": key.total_spent,
+                    "reserved": key.reserved_balance,
+                    "balance_limit": key.balance_limit,
+                    "required": cost_per_request,
+                },
+            )
+            raise HTTPException(
+                status_code=402,
+                detail={
+                    "error": {
+                        "message": f"Balance limit exceeded: {key.balance_limit} mSats limit. {key.total_spent} already spent ({key.reserved_balance} reserved), {cost_per_request} required for this request.",
+                        "type": "insufficient_quota",
+                        "code": "balance_limit_exceeded",
+                    }
+                },
+            )
+
     logger.debug(
         "Charging base cost for request",
         extra={
             "key_hash": key.hashed_key[:8] + "...",
+            "billing_key_hash": billing_key.hashed_key[:8] + "...",
             "cost": cost_per_request,
-            "balance_before": key.balance,
+            "balance_before": billing_key.balance,
         },
     )
 
     # Charge the base cost for the request atomically to avoid race conditions
     stmt = (
         update(ApiKey)
-        .where(col(ApiKey.hashed_key) == key.hashed_key)
+        .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
         .where(col(ApiKey.balance) - col(ApiKey.reserved_balance) >= cost_per_request)
         .values(
             reserved_balance=col(ApiKey.reserved_balance) + cost_per_request,
@@ -344,6 +529,19 @@ async def pay_for_request(
         )
     )
     result = await session.exec(stmt)  # type: ignore[call-overload]
+
+    # Also increment total_requests and reserved_balance on the child key if it's different
+    if billing_key.hashed_key != key.hashed_key:
+        child_stmt = (
+            update(ApiKey)
+            .where(col(ApiKey.hashed_key) == key.hashed_key)
+            .values(
+                total_requests=col(ApiKey.total_requests) + 1,
+                reserved_balance=col(ApiKey.reserved_balance) + cost_per_request,
+            )
+        )
+        await session.exec(child_stmt)  # type: ignore[call-overload]
+
     await session.commit()
 
     if result.rowcount == 0:
@@ -351,8 +549,9 @@ async def pay_for_request(
             "Concurrent request depleted balance",
             extra={
                 "key_hash": key.hashed_key[:8] + "...",
+                "billing_key_hash": billing_key.hashed_key[:8] + "...",
                 "required_cost": cost_per_request,
-                "current_balance": key.balance,
+                "current_balance": billing_key.balance,
             },
         )
 
@@ -361,23 +560,26 @@ async def pay_for_request(
             status_code=402,
             detail={
                 "error": {
-                    "message": f"Insufficient balance: {cost_per_request} mSats required. {key.balance} available.",
+                    "message": f"Insufficient balance: {cost_per_request} mSats required. {billing_key.balance} available.",
                     "type": "insufficient_quota",
                     "code": "insufficient_balance",
                 }
             },
         )
 
-    await session.refresh(key)
+    await session.refresh(billing_key)
+    if billing_key.hashed_key != key.hashed_key:
+        await session.refresh(key)
 
     logger.info(
         "Payment processed successfully",
         extra={
             "key_hash": key.hashed_key[:8] + "...",
+            "billing_key_hash": billing_key.hashed_key[:8] + "...",
             "charged_amount": cost_per_request,
-            "new_balance": key.balance,
-            "total_spent": key.total_spent,
-            "total_requests": key.total_requests,
+            "new_balance": billing_key.balance,
+            "total_spent": billing_key.total_spent,
+            "total_requests": billing_key.total_requests,
         },
     )
 
@@ -387,9 +589,11 @@ async def pay_for_request(
 async def revert_pay_for_request(
     key: ApiKey, session: AsyncSession, cost_per_request: int
 ) -> None:
+    billing_key = await get_billing_key(key, session)
+
     stmt = (
         update(ApiKey)
-        .where(col(ApiKey.hashed_key) == key.hashed_key)
+        .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
         .values(
             reserved_balance=col(ApiKey.reserved_balance) - cost_per_request,
             total_requests=col(ApiKey.total_requests) - 1,
@@ -397,27 +601,43 @@ async def revert_pay_for_request(
     )
 
     result = await session.exec(stmt)  # type: ignore[call-overload]
+
+    # Also decrement total_requests and reserved_balance on the child key if it's different
+    if billing_key.hashed_key != key.hashed_key:
+        child_stmt = (
+            update(ApiKey)
+            .where(col(ApiKey.hashed_key) == key.hashed_key)
+            .values(
+                total_requests=col(ApiKey.total_requests) - 1,
+                reserved_balance=col(ApiKey.reserved_balance) - cost_per_request,
+            )
+        )
+        await session.exec(child_stmt)  # type: ignore[call-overload]
+
     await session.commit()
     if result.rowcount == 0:
         logger.error(
             "Failed to revert payment - insufficient reserved balance",
             extra={
                 "key_hash": key.hashed_key[:8] + "...",
+                "billing_key_hash": billing_key.hashed_key[:8] + "...",
                 "cost_to_revert": cost_per_request,
-                "current_reserved_balance": key.reserved_balance,
+                "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. {key.balance} available.",
+                    "message": f"failed to revert request payment: {cost_per_request} mSats required. {billing_key.balance} available.",
                     "type": "payment_error",
                     "code": "payment_error",
                 }
             },
         )
-    await session.refresh(key)
+    await session.refresh(billing_key)
+    if billing_key.hashed_key != key.hashed_key:
+        await session.refresh(key)
 
 
 async def adjust_payment_for_tokens(
@@ -428,15 +648,17 @@ async def adjust_payment_for_tokens(
     This is called after the initial payment and the upstream request is complete.
     Returns cost data to be included in the response.
     """
+    billing_key = await get_billing_key(key, session)
     model = response_data.get("model", "unknown")
 
     logger.debug(
         "Starting payment adjustment for tokens",
         extra={
             "key_hash": key.hashed_key[:8] + "...",
+            "billing_key_hash": billing_key.hashed_key[:8] + "...",
             "model": model,
             "deducted_max_cost": deducted_max_cost,
-            "current_balance": key.balance,
+            "current_balance": billing_key.balance,
             "has_usage": "usage" in response_data,
         },
     )
@@ -446,22 +668,42 @@ async def adjust_payment_for_tokens(
         try:
             release_stmt = (
                 update(ApiKey)
-                .where(col(ApiKey.hashed_key) == key.hashed_key)
-                .values(reserved_balance=col(ApiKey.reserved_balance) - deducted_max_cost)
+                .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
+                .values(
+                    reserved_balance=col(ApiKey.reserved_balance) - deducted_max_cost
+                )
             )
             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)
+                    .values(
+                        reserved_balance=col(ApiKey.reserved_balance)
+                        - deducted_max_cost
+                    )
+                )
+                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,
                 },
             )
         except Exception as e:
             logger.error(
                 "Failed to release reservation in fallback",
-                extra={"error": str(e), "key_hash": key.hashed_key[:8] + "..."},
+                extra={
+                    "error": str(e),
+                    "key_hash": key.hashed_key[:8] + "...",
+                    "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                },
             )
 
     match await calculate_cost(response_data, deducted_max_cost, session):
@@ -470,6 +712,7 @@ async def adjust_payment_for_tokens(
                 "Using max cost data (no token adjustment)",
                 extra={
                     "key_hash": key.hashed_key[:8] + "...",
+                    "billing_key_hash": billing_key.hashed_key[:8] + "...",
                     "model": model,
                     "max_cost": cost.total_msats,
                 },
@@ -477,7 +720,7 @@ async def adjust_payment_for_tokens(
             # Finalize by releasing reservation and charging max cost
             finalize_stmt = (
                 update(ApiKey)
-                .where(col(ApiKey.hashed_key) == key.hashed_key)
+                .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
                 .values(
                     reserved_balance=col(ApiKey.reserved_balance) - deducted_max_cost,
                     balance=col(ApiKey.balance) - cost.total_msats,
@@ -485,27 +728,45 @@ async def adjust_payment_for_tokens(
                 )
             )
             result = await session.exec(finalize_stmt)  # type: ignore[call-overload]
+
+            # Also update total_spent and reserved_balance on the child key if it's different
+            if billing_key.hashed_key != key.hashed_key:
+                child_stmt = (
+                    update(ApiKey)
+                    .where(col(ApiKey.hashed_key) == key.hashed_key)
+                    .values(
+                        total_spent=col(ApiKey.total_spent) + cost.total_msats,
+                        reserved_balance=col(ApiKey.reserved_balance)
+                        - deducted_max_cost,
+                    )
+                )
+                await session.exec(child_stmt)  # type: ignore[call-overload]
+
             await session.commit()
             if result.rowcount == 0:
                 logger.error(
                     "Failed to finalize max-cost payment - retrying reservation release",
                     extra={
                         "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
                         "deducted_max_cost": deducted_max_cost,
-                        "current_reserved_balance": key.reserved_balance,
+                        "current_reserved_balance": billing_key.reserved_balance,
                         "total_cost": cost.total_msats,
                         "model": model,
                     },
                 )
                 await release_reservation_only()
             else:
-                await session.refresh(key)
+                await session.refresh(billing_key)
+                if billing_key.hashed_key != key.hashed_key:
+                    await session.refresh(key)
                 logger.info(
                     "Max cost payment finalized",
                     extra={
                         "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
                         "charged_amount": cost.total_msats,
-                        "new_balance": key.balance,
+                        "new_balance": billing_key.balance,
                         "model": model,
                     },
                 )
@@ -521,6 +782,7 @@ async def adjust_payment_for_tokens(
                 "Calculated token-based cost",
                 extra={
                     "key_hash": key.hashed_key[:8] + "...",
+                    "billing_key_hash": billing_key.hashed_key[:8] + "...",
                     "model": model,
                     "token_cost": cost.total_msats,
                     "deducted_max_cost": deducted_max_cost,
@@ -533,11 +795,15 @@ async def adjust_payment_for_tokens(
             if cost_difference == 0:
                 logger.debug(
                     "Finalizing with exact reserved cost",
-                    extra={"key_hash": key.hashed_key[:8] + "...", "model": model},
+                    extra={
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
+                        "model": model,
+                    },
                 )
                 finalize_stmt = (
                     update(ApiKey)
-                    .where(col(ApiKey.hashed_key) == key.hashed_key)
+                    .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
                     .values(
                         reserved_balance=col(ApiKey.reserved_balance)
                         - deducted_max_cost,
@@ -546,8 +812,24 @@ async def adjust_payment_for_tokens(
                     )
                 )
                 await session.exec(finalize_stmt)  # type: ignore[call-overload]
+
+                # Also update total_spent and reserved_balance on the child key if it's different
+                if billing_key.hashed_key != key.hashed_key:
+                    child_stmt = (
+                        update(ApiKey)
+                        .where(col(ApiKey.hashed_key) == key.hashed_key)
+                        .values(
+                            total_spent=col(ApiKey.total_spent) + total_cost_msats,
+                            reserved_balance=col(ApiKey.reserved_balance)
+                            - deducted_max_cost,
+                        )
+                    )
+                    await session.exec(child_stmt)  # type: ignore[call-overload]
+
                 await session.commit()
-                await session.refresh(key)
+                await session.refresh(billing_key)
+                if billing_key.hashed_key != key.hashed_key:
+                    await session.refresh(key)
                 return cost.dict()
 
             # this should never happen why do we handle this???
@@ -557,16 +839,17 @@ async def adjust_payment_for_tokens(
                     "Additional charge required for token usage",
                     extra={
                         "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
                         "additional_charge": cost_difference,
-                        "current_balance": key.balance,
-                        "sufficient_balance": key.balance >= cost_difference,
+                        "current_balance": billing_key.balance,
+                        "sufficient_balance": billing_key.balance >= cost_difference,
                         "model": model,
                     },
                 )
 
                 finalize_stmt = (
                     update(ApiKey)
-                    .where(col(ApiKey.hashed_key) == key.hashed_key)
+                    .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
                     .values(
                         reserved_balance=col(ApiKey.reserved_balance)
                         - deducted_max_cost,
@@ -575,18 +858,35 @@ async def adjust_payment_for_tokens(
                     )
                 )
                 result = await session.exec(finalize_stmt)  # type: ignore[call-overload]
+
+                # Also update total_spent and reserved_balance on the child key if it's different
+                if billing_key.hashed_key != key.hashed_key:
+                    child_stmt = (
+                        update(ApiKey)
+                        .where(col(ApiKey.hashed_key) == key.hashed_key)
+                        .values(
+                            total_spent=col(ApiKey.total_spent) + total_cost_msats,
+                            reserved_balance=col(ApiKey.reserved_balance)
+                            - deducted_max_cost,
+                        )
+                    )
+                    await session.exec(child_stmt)  # type: ignore[call-overload]
+
                 await session.commit()
 
                 if result.rowcount:
                     cost.total_msats = total_cost_msats
-                    await session.refresh(key)
+                    await session.refresh(billing_key)
+                    if billing_key.hashed_key != key.hashed_key:
+                        await session.refresh(key)
 
                     logger.info(
                         "Finalized payment with additional charge",
                         extra={
                             "key_hash": key.hashed_key[:8] + "...",
+                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
                             "charged_amount": total_cost_msats,
-                            "new_balance": key.balance,
+                            "new_balance": billing_key.balance,
                             "model": model,
                         },
                     )
@@ -595,6 +895,7 @@ async def adjust_payment_for_tokens(
                         "Failed to finalize additional charge - releasing reservation",
                         extra={
                             "key_hash": key.hashed_key[:8] + "...",
+                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
                             "attempted_charge": total_cost_msats,
                             "model": model,
                         },
@@ -607,15 +908,16 @@ async def adjust_payment_for_tokens(
                     "Refunding excess payment",
                     extra={
                         "key_hash": key.hashed_key[:8] + "...",
+                        "billing_key_hash": billing_key.hashed_key[:8] + "...",
                         "refund_amount": refund,
-                        "current_balance": key.balance,
+                        "current_balance": billing_key.balance,
                         "model": model,
                     },
                 )
 
                 refund_stmt = (
                     update(ApiKey)
-                    .where(col(ApiKey.hashed_key) == key.hashed_key)
+                    .where(col(ApiKey.hashed_key) == billing_key.hashed_key)
                     .values(
                         reserved_balance=col(ApiKey.reserved_balance)
                         - deducted_max_cost,
@@ -624,6 +926,20 @@ async def adjust_payment_for_tokens(
                     )
                 )
                 result = await session.exec(refund_stmt)  # type: ignore[call-overload]
+
+                # Also update total_spent and reserved_balance on the child key if it's different
+                if billing_key.hashed_key != key.hashed_key:
+                    child_stmt = (
+                        update(ApiKey)
+                        .where(col(ApiKey.hashed_key) == key.hashed_key)
+                        .values(
+                            total_spent=col(ApiKey.total_spent) + total_cost_msats,
+                            reserved_balance=col(ApiKey.reserved_balance)
+                            - deducted_max_cost,
+                        )
+                    )
+                    await session.exec(child_stmt)  # type: ignore[call-overload]
+
                 await session.commit()
 
                 if result.rowcount == 0:
@@ -631,8 +947,9 @@ async def adjust_payment_for_tokens(
                         "Failed to finalize payment - releasing reservation",
                         extra={
                             "key_hash": key.hashed_key[:8] + "...",
+                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
                             "deducted_max_cost": deducted_max_cost,
-                            "current_reserved_balance": key.reserved_balance,
+                            "current_reserved_balance": billing_key.reserved_balance,
                             "total_cost": total_cost_msats,
                             "model": model,
                         },
@@ -640,14 +957,17 @@ async def adjust_payment_for_tokens(
                     await release_reservation_only()
                 else:
                     cost.total_msats = total_cost_msats
-                    await session.refresh(key)
+                    await session.refresh(billing_key)
+                    if billing_key.hashed_key != key.hashed_key:
+                        await session.refresh(key)
 
                     logger.info(
                         "Refund processed successfully",
                         extra={
                             "key_hash": key.hashed_key[:8] + "...",
+                            "billing_key_hash": billing_key.hashed_key[:8] + "...",
                             "refunded_amount": refund,
-                            "new_balance": key.balance,
+                            "new_balance": billing_key.balance,
                             "final_cost": cost.total_msats,
                             "model": model,
                         },
@@ -689,3 +1009,65 @@ async def adjust_payment_for_tokens(
         "output_msats": 0,
         "total_msats": deducted_max_cost,
     }
+
+
+async def periodic_key_reset() -> None:
+    """Background task to reset key limits based on their policy."""
+    from .core.db import create_session
+
+    while True:
+        try:
+            interval = 3600  # Run every hour
+            jitter = 300
+            await asyncio.sleep(interval + random.uniform(0, jitter))
+        except asyncio.CancelledError:
+            break
+
+        try:
+            async with create_session() as session:
+                # Find all keys that have a reset policy
+                stmt = select(ApiKey).where(ApiKey.balance_limit_reset.is_not(None))  # type: ignore
+                keys = (await session.exec(stmt)).all()
+
+                now = int(time.time())
+                updated_count = 0
+
+                for key in keys:
+                    reset_date = key.balance_limit_reset_date or 0
+                    should_reset = False
+
+                    if key.balance_limit_reset == "daily":
+                        if (
+                            datetime.fromtimestamp(now).date()
+                            > datetime.fromtimestamp(reset_date).date()
+                        ):
+                            should_reset = True
+                    elif key.balance_limit_reset == "weekly":
+                        if (
+                            datetime.fromtimestamp(now).isocalendar()[:2]
+                            > datetime.fromtimestamp(reset_date).isocalendar()[:2]
+                        ):
+                            should_reset = True
+                    elif key.balance_limit_reset == "monthly":
+                        dt_now = datetime.fromtimestamp(now)
+                        dt_reset = datetime.fromtimestamp(reset_date)
+                        if dt_now.year > dt_reset.year or dt_now.month > dt_reset.month:
+                            should_reset = True
+
+                    if should_reset:
+                        key.total_spent = 0
+                        key.balance_limit_reset_date = now
+                        session.add(key)
+                        updated_count += 1
+
+                if updated_count > 0:
+                    await session.commit()
+                    logger.info(
+                        "Periodic key reset complete",
+                        extra={"keys_reset": updated_count},
+                    )
+
+        except asyncio.CancelledError:
+            break
+        except Exception as e:
+            logger.error(f"Error in periodic_key_reset: {e}")

routstr/balance.py

@@ -1,5 +1,6 @@
 import asyncio
 import hashlib
+import time
 from time import monotonic
 from typing import Annotated, NoReturn
 
@@ -32,16 +33,33 @@ async def get_key_from_header(
     )
 
 
-# TODO: remove this endpoint when frontend is updated
-@router.get("/", include_in_schema=False)
-async def account_info(key: ApiKey = Depends(get_key_from_header)) -> dict:
+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 {
         "api_key": "sk-" + key.hashed_key,
-        "balance": key.balance,
-        "reserved": key.reserved_balance,
+        "balance": billing_key.balance,
+        "reserved": billing_key.reserved_balance,
+        "is_child": key.parent_key_hash is not None,
+        "parent_key": "sk-" + key.parent_key_hash if key.parent_key_hash else None,
+        "total_requests": key.total_requests,
+        "total_spent": key.total_spent,
+        "balance_limit": key.balance_limit,
+        "balance_limit_reset": key.balance_limit_reset,
+        "validity_date": key.validity_date,
     }
 
 
+# TODO: remove this endpoint when frontend is updated
+@router.get("/", include_in_schema=False)
+async def account_info(
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    return await get_balance_info(key, session)
+
+
 # TODO: Implement POST /v1/wallet/create endpoint
 # This endpoint should accept:
 # - cashu_token (required): The eCash token to deposit
@@ -56,9 +74,24 @@ async def account_info(key: ApiKey = Depends(get_key_from_header)) -> dict:
 
 @router.get("/create")
 async def create_balance(
-    initial_balance_token: str, session: AsyncSession = Depends(get_session)
+    initial_balance_token: str,
+    balance_limit: int | None = None,
+    balance_limit_reset: str | None = None,
+    validity_date: int | None = None,
+    session: AsyncSession = Depends(get_session),
 ) -> dict:
     key = await validate_bearer_key(initial_balance_token, session)
+
+    if balance_limit is not None or balance_limit_reset or validity_date:
+        key.balance_limit = balance_limit
+        key.balance_limit_reset = balance_limit_reset
+        key.validity_date = validity_date
+        if balance_limit_reset:
+            key.balance_limit_reset_date = int(time.time())
+        session.add(key)
+        await session.commit()
+        await session.refresh(key)
+
     return {
         "api_key": "sk-" + key.hashed_key,
         "balance": key.balance,
@@ -66,12 +99,11 @@ async def create_balance(
 
 
 @router.get("/info")
-async def wallet_info(key: ApiKey = Depends(get_key_from_header)) -> dict:
-    return {
-        "api_key": "sk-" + key.hashed_key,
-        "balance": key.balance,
-        "reserved": key.reserved_balance,
-    }
+async def wallet_info(
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    return await get_balance_info(key, session)
 
 
 class TopupRequest(BaseModel):
@@ -85,6 +117,10 @@ 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:
         cashu_token = topup_request.cashu_token
     if cashu_token is None:
@@ -94,7 +130,7 @@ async def topup_wallet_endpoint(
     if len(cashu_token) < 10 or "cashu" not in cashu_token:
         raise HTTPException(status_code=400, detail="Invalid token format")
     try:
-        amount_msats = await credit_balance(cashu_token, key, session)
+        amount_msats = await credit_balance(cashu_token, billing_key, session)
     except ValueError as e:
         error_msg = str(e)
         if "already spent" in error_msg.lower():
@@ -150,10 +186,16 @@ async def refund_wallet_endpoint(
 
     bearer_value: str = authorization[7:]
 
+    key: ApiKey = await validate_bearer_key(bearer_value, session)
+
     if cached := await _refund_cache_get(bearer_value):
         return cached
 
-    key: ApiKey = await validate_bearer_key(bearer_value, session)
+    if key.parent_key_hash:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot refund child key. Please refund the parent key instead.",
+        )
 
     remaining_balance_msats: int = key.total_balance
 
@@ -209,7 +251,9 @@ async def refund_wallet_endpoint(
 
     await _refund_cache_set(bearer_value, result)
 
-    await session.delete(key)
+    key.balance = 0
+    key.reserved_balance = 0
+    session.add(key)
     await session.commit()
 
     return result
@@ -228,6 +272,117 @@ async def donate(token: str, ref: str | None = None) -> str:
         return "Invalid token."
 
 
+class ChildKeyRequest(BaseModel):
+    count: int
+    balance_limit: int | None = None
+    balance_limit_reset: str | None = None
+    validity_date: int | None = None
+
+
+@router.post("/child-key")
+async def create_child_key(
+    payload: ChildKeyRequest,
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    """Creates one or more child API keys that use the parent's balance."""
+    # Log incoming request for debugging
+    logger.debug(f"Child key creation request: count={payload.count}")
+
+    count = payload.count
+    if count < 1 or count > 50:
+        raise HTTPException(status_code=400, detail="Count must be between 1 and 50.")
+
+    # Check if this is already a child key
+    if key.parent_key_hash:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot create a child key for another child key.",
+        )
+
+    cost_per_key = settings.child_key_cost
+    total_cost = cost_per_key * count
+
+    if key.total_balance < total_cost:
+        raise HTTPException(
+            status_code=402,
+            detail=f"Insufficient balance to create {count} child keys. {total_cost} mSats required.",
+        )
+
+    # Deduct cost from parent
+    key.balance -= total_cost
+    key.total_spent += total_cost
+    session.add(key)
+
+    # Generate new keys
+    import secrets
+
+    new_keys = []
+    for _ in range(count):
+        new_key_raw = secrets.token_hex(32)
+        new_key_hash = new_key_raw  # We use the raw key as the hash for sk- keys
+
+        child_key = ApiKey(
+            hashed_key=new_key_hash,
+            balance=0,
+            parent_key_hash=key.hashed_key,
+            balance_limit=payload.balance_limit,
+            balance_limit_reset=payload.balance_limit_reset,
+            balance_limit_reset_date=int(time.time())
+            if payload.balance_limit_reset
+            else None,
+            validity_date=payload.validity_date,
+        )
+        session.add(child_key)
+        new_keys.append("sk-" + new_key_hash)
+
+    await session.commit()
+
+    response_data = {
+        "api_keys": new_keys,
+        "count": count,
+        "cost_msats": total_cost,
+        "cost_sats": total_cost // 1000,
+        "parent_balance": key.balance,
+        "parent_balance_sats": key.balance // 1000,
+    }
+    logger.debug(f"Child key creation response: {response_data}")
+    return response_data
+
+
+class ChildKeyResetRequest(BaseModel):
+    child_key: str
+
+
+@router.post("/child-key/reset")
+async def reset_child_key_spent(
+    payload: ChildKeyResetRequest,
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict:
+    """Resets the total_spent of a child key. Must be called by the parent."""
+    child_key_raw = payload.child_key
+    if child_key_raw.startswith("sk-"):
+        child_key_raw = child_key_raw[3:]
+
+    child_key = await session.get(ApiKey, child_key_raw)
+    if not child_key:
+        raise HTTPException(status_code=404, detail="Child key not found.")
+
+    if child_key.parent_key_hash != key.hashed_key:
+        raise HTTPException(
+            status_code=403, detail="Unauthorized. You are not the parent of this key."
+        )
+
+    child_key.total_spent = 0
+    if child_key.balance_limit_reset:
+        child_key.balance_limit_reset_date = int(time.time())
+    session.add(child_key)
+    await session.commit()
+
+    return {"success": True, "message": "Child key balance reset successfully."}
+
+
 @router.api_route(
     "/{path:path}",
     methods=["GET", "POST", "PUT", "DELETE"],

routstr/core/admin.py

@@ -124,7 +124,7 @@ async def partial_apikeys(request: Request) -> str:
 
     rows = "".join(
         [
-            f"<tr><td>{key.hashed_key}</td><td>{key.balance}</td><td>{key.total_spent}</td><td>{key.total_requests}</td><td>{key.refund_address}</td><td>{fmt_time(key.key_expiry_time)}</td></tr>"
+            f"<tr><td>{key.hashed_key}{' <br><small>(Child of ' + key.parent_key_hash[:8] + '...)</small>' if key.parent_key_hash else ''}</td><td>{key.balance}</td><td>{key.total_spent}</td><td>{key.total_requests}</td><td>{key.refund_address}</td><td>{fmt_time(key.key_expiry_time)}</td></tr>"
             for key in api_keys
         ]
     )
@@ -158,11 +158,51 @@ async def get_temporary_balances_api(request: Request) -> list[dict[str, object]
             "total_requests": key.total_requests,
             "refund_address": key.refund_address,
             "key_expiry_time": key.key_expiry_time,
+            "parent_key_hash": key.parent_key_hash,
+            "balance_limit": key.balance_limit,
+            "balance_limit_reset": key.balance_limit_reset,
+            "validity_date": key.validity_date,
         }
         for key in api_keys
     ]
 
 
+class ApiKeyUpdate(BaseModel):
+    balance_limit: int | None = None
+    balance_limit_reset: str | None = None
+    validity_date: int | None = None
+
+
+@admin_router.patch(
+    "/api/apikeys/{hashed_key}", dependencies=[Depends(require_admin_api)]
+)
+async def update_apikey(
+    request: Request, hashed_key: str, update: ApiKeyUpdate
+) -> dict:
+    async with create_session() as session:
+        key = await session.get(ApiKey, hashed_key)
+        if not key:
+            raise HTTPException(status_code=404, detail="API key not found")
+
+        if update.balance_limit is not None:
+            key.balance_limit = update.balance_limit
+        if update.balance_limit_reset is not None:
+            key.balance_limit_reset = update.balance_limit_reset
+        if update.validity_date is not None:
+            key.validity_date = update.validity_date
+
+        session.add(key)
+        await session.commit()
+        await session.refresh(key)
+
+    return {
+        "hashed_key": key.hashed_key,
+        "balance_limit": key.balance_limit,
+        "balance_limit_reset": key.balance_limit_reset,
+        "validity_date": key.validity_date,
+    }
+
+
 @admin_router.get("/api/balances", dependencies=[Depends(require_admin_api)])
 async def get_balances_api(request: Request) -> list[dict[str, object]]:
     balance_details, _tw, _tu, _ow = await fetch_all_balances()
@@ -2597,12 +2637,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(

routstr/core/db.py

@@ -5,6 +5,7 @@ from typing import AsyncGenerator
 
 from alembic import command
 from alembic.config import Config
+from sqlalchemy import UniqueConstraint
 from sqlalchemy.ext.asyncio.engine import create_async_engine
 from sqlmodel import Field, Relationship, SQLModel, func, select, update
 from sqlmodel.ext.asyncio.session import AsyncSession
@@ -47,6 +48,25 @@ class ApiKey(SQLModel, table=True):  # type: ignore
         default=None,
         description="Currency of the cashu-token",
     )
+    parent_key_hash: str | None = Field(
+        default=None, foreign_key="api_keys.hashed_key", index=True
+    )
+    balance_limit: int | None = Field(
+        default=None,
+        description="Max spendable balance in msats for this key (mostly for child keys)",
+    )
+    balance_limit_reset: str | None = Field(
+        default=None,
+        description="Reset policy for balance limit (manual, daily, monthly, etc.)",
+    )
+    balance_limit_reset_date: int | None = Field(
+        default=None,
+        description="Unix timestamp of the last time the balance limit was reset",
+    )
+    validity_date: int | None = Field(
+        default=None,
+        description="Unix timestamp after which the key is no longer valid",
+    )
 
     @property
     def total_balance(self) -> int:
@@ -108,11 +128,16 @@ class LightningInvoice(SQLModel, table=True):  # type: ignore
 
 class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
     __tablename__ = "upstream_providers"
+    __table_args__ = (
+        UniqueConstraint(
+            "base_url", "api_key", name="uq_upstream_providers_base_url_api_key"
+        ),
+    )
     id: int | None = Field(default=None, primary_key=True)
     provider_type: str = Field(
         description="Provider type: custom, openai, anthropic, azure, openrouter, etc."
     )
-    base_url: str = Field(unique=True, description="Base URL of the upstream API")
+    base_url: str = Field(description="Base URL of the upstream API")
     api_key: str = Field(description="API key for the upstream provider")
     api_version: str | None = Field(
         default=None, description="API version for Azure OpenAI"

routstr/core/exceptions.py

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

routstr/core/main.py

@@ -10,13 +10,11 @@ from fastapi.responses import FileResponse, RedirectResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.exceptions import HTTPException
 
+from ..auth import periodic_key_reset
 from ..balance import balance_router, deprecated_wallet_router
 from ..discovery import providers_cache_refresher, providers_router
 from ..nip91 import announce_provider
-from ..payment.models import (
-    models_router,
-    update_sats_pricing,
-)
+from ..payment.models import models_router, update_sats_pricing
 from ..payment.price import update_prices_periodically
 from ..proxy import initialize_upstreams, proxy_router, refresh_model_maps_periodically
 from ..wallet import periodic_payout
@@ -33,9 +31,9 @@ setup_logging()
 logger = get_logger(__name__)
 
 if os.getenv("VERSION_SUFFIX") is not None:
-    __version__ = f"0.2.2-{os.getenv('VERSION_SUFFIX')}"
+    __version__ = f"0.3.0-{os.getenv('VERSION_SUFFIX')}"
 else:
-    __version__ = "0.2.2"
+    __version__ = "0.3.0"
 
 
 @asynccontextmanager
@@ -49,6 +47,7 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
     providers_task = None
     models_refresh_task = None
     model_maps_refresh_task = None
+    key_reset_task = None
 
     try:
         # Run database migrations on startup
@@ -104,6 +103,7 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
             nip91_task = asyncio.create_task(announce_provider())
         if global_settings.providers_refresh_interval_seconds > 0:
             providers_task = asyncio.create_task(providers_cache_refresher())
+        key_reset_task = asyncio.create_task(periodic_key_reset())
 
         yield
 
@@ -133,6 +133,8 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
             models_refresh_task.cancel()
         if model_maps_refresh_task is not None:
             model_maps_refresh_task.cancel()
+        if key_reset_task is not None:
+            key_reset_task.cancel()
 
         try:
             tasks_to_wait = []
@@ -150,6 +152,8 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
                 tasks_to_wait.append(models_refresh_task)
             if model_maps_refresh_task is not None:
                 tasks_to_wait.append(model_maps_refresh_task)
+            if key_reset_task is not None:
+                tasks_to_wait.append(key_reset_task)
 
             if tasks_to_wait:
                 await asyncio.gather(*tasks_to_wait, return_exceptions=True)
@@ -191,6 +195,7 @@ async def info() -> dict:
         "mints": global_settings.cashu_mints,
         "http_url": global_settings.http_url,
         "onion_url": global_settings.onion_url,
+        "child_key_cost_msats": global_settings.child_key_cost,
     }
 
 

routstr/core/settings.py

@@ -52,6 +52,7 @@ class Settings(BaseSettings):
     exchange_fee: float = Field(default=1.005, env="EXCHANGE_FEE")
     upstream_provider_fee: float = Field(default=1.05, env="UPSTREAM_PROVIDER_FEE")
     tolerance_percentage: float = Field(default=1.0, env="TOLERANCE_PERCENTAGE")
+    child_key_cost: int = Field(default=1000, env="CHILD_KEY_COST")
     # Minimum per-request charge in millisatoshis when model pricing is free/zero
     min_request_msat: int = Field(default=1, env="MIN_REQUEST_MSAT")
     reset_reserved_balance_on_startup: bool = Field(

routstr/lightning.py

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

routstr/payment/cost_calculation.py

@@ -15,6 +15,7 @@ class CostData(BaseModel):
     input_msats: int
     output_msats: int
     total_msats: int
+    total_usd: float = 0.0
 
 
 class MaxCostData(CostData):
@@ -61,6 +62,7 @@ async def calculate_cost(  # todo: can be sync
             input_msats=0,
             output_msats=0,
             total_msats=0,
+            total_usd=0.0,
         )
 
     usage_data = response_data["usage"]
@@ -101,6 +103,7 @@ async def calculate_cost(  # todo: can be sync
                 input_msats=-1,  # Cost field doesn't break down by token type
                 output_msats=-1,
                 total_msats=cost_in_msats,
+                total_usd=usd_cost,
             )
         except Exception as e:
             logger.warning(
@@ -210,6 +213,7 @@ async def calculate_cost(  # todo: can be sync
 
     output_msats = round(output_tokens / 1000 * MSATS_PER_1K_OUTPUT_TOKENS, 3)
     token_based_cost = math.ceil(input_msats + output_msats)
+    total_usd = (token_based_cost / 1000.0) * sats_usd_price()
 
     logger.info(
         "Calculated token-based cost",
@@ -219,6 +223,7 @@ async def calculate_cost(  # todo: can be sync
             "input_cost_msats": input_msats,
             "output_cost_msats": output_msats,
             "total_cost_msats": token_based_cost,
+            "total_usd": total_usd,
             "model": response_data.get("model", "unknown"),
         },
     )
@@ -228,4 +233,5 @@ async def calculate_cost(  # todo: can be sync
         input_msats=int(input_msats),
         output_msats=int(output_msats),
         total_msats=token_based_cost,
+        total_usd=total_usd,
     )

routstr/proxy.py

@@ -16,6 +16,8 @@ from .core.db import (
     create_session,
     get_session,
 )
+from .core.exceptions import UpstreamError
+from .core.settings import settings
 from .payment.helpers import (
     calculate_discounted_max_cost,
     check_token_balance,
@@ -31,7 +33,9 @@ proxy_router = APIRouter()
 
 _upstreams: list[BaseUpstreamProvider] = []
 _model_instances: dict[str, Model] = {}  # All aliases -> Model
-_provider_map: dict[str, BaseUpstreamProvider] = {}  # All aliases -> Provider
+_provider_map: dict[
+    str, list[BaseUpstreamProvider]
+] = {}  # All aliases -> List[Provider]
 _unique_models: dict[str, Model] = {}  # Unique model.id -> Model (no duplicates)
 
 
@@ -68,8 +72,8 @@ def get_model_instance(model_id: str) -> Model | None:
     return _model_instances.get(model_id.lower())
 
 
-def get_provider_for_model(model_id: str) -> BaseUpstreamProvider | None:
-    """Get UpstreamProvider for model ID from global cache."""
+def get_provider_for_model(model_id: str) -> list[BaseUpstreamProvider] | None:
+    """Get UpstreamProvider list for model ID from global cache."""
     return _provider_map.get(model_id.lower())
 
 
@@ -154,8 +158,8 @@ async def proxy(
             "invalid_model", f"Model '{model_id}' not found", 400, request=request
         )
 
-    upstream = get_provider_for_model(model_id)
-    if not upstream:
+    upstreams = get_provider_for_model(model_id)
+    if not upstreams:
         return create_error_response(
             "invalid_model",
             f"No provider found for model '{model_id}'",
@@ -163,26 +167,52 @@ async def proxy(
             request=request,
         )
 
+    # todo figure out cost calculation since fallback provider is usually not the same price
+    # Use first provider for initial checks/cost calculation
+    # primary_upstream = upstreams[0]
+
     _max_cost_for_model = await get_max_cost_for_model(
         model=model_id, session=session, model_obj=model_obj
     )
     max_cost_for_model = await calculate_discounted_max_cost(
         _max_cost_for_model, request_body_dict, model_obj=model_obj
     )
+    # Ensure max_cost_for_model is at least the minimum allowed request cost
+    max_cost_for_model = max(max_cost_for_model, settings.min_request_msat)
+
     check_token_balance(headers, request_body_dict, max_cost_for_model)
 
     if x_cashu := headers.get("x-cashu", None):
-        if is_responses_api:
-            return await upstream.handle_x_cashu_responses(
-                request, x_cashu, path, max_cost_for_model, model_obj
-            )
-        else:
-            return await upstream.handle_x_cashu(
-                request, x_cashu, path, max_cost_for_model, model_obj
-            )
+        last_error = None
+        for i, upstream in enumerate(upstreams):
+            try:
+                if is_responses_api:
+                    return await upstream.handle_x_cashu_responses(
+                        request, x_cashu, path, max_cost_for_model, model_obj
+                    )
+                else:
+                    return await upstream.handle_x_cashu(
+                        request, x_cashu, path, max_cost_for_model, model_obj
+                    )
+            except UpstreamError as e:
+                logger.warning(
+                    f"Upstream {upstream.provider_type} failed (x-cashu): {e}"
+                )
+                if i == len(upstreams) - 1:
+                    last_error = e
+                continue
+
+        return create_error_response(
+            "upstream_error",
+            str(last_error) if last_error else "All upstreams failed",
+            502,
+            request=request,
+        )
 
     elif auth := headers.get("authorization", None):
-        key = await get_bearer_token_key(headers, path, session, auth)
+        key = await get_bearer_token_key(
+            headers, path, session, auth, max_cost_for_model
+        )
 
     else:
         if request.method not in ["GET"]:
@@ -194,60 +224,156 @@ async def proxy(
             )
 
         logger.debug("Processing unauthenticated GET request", extra={"path": path})
-        headers = upstream.prepare_headers(dict(request.headers))
-        return await upstream.forward_get_request(request, path, headers)
+
+        last_error_response = None
+        for i, upstream in enumerate(upstreams):
+            try:
+                headers = upstream.prepare_headers(dict(request.headers))
+                response = await upstream.forward_get_request(request, path, headers)
+
+                if response.status_code in [502, 429] and i < len(upstreams) - 1:
+                    error_message = ""
+                    try:
+                        if hasattr(response, "body"):
+                            body_bytes = response.body
+                            data = json.loads(body_bytes)
+                            if "error" in data:
+                                error_data = data["error"]
+                                if isinstance(error_data, dict):
+                                    error_message = error_data.get("message", "")
+                                elif isinstance(error_data, str):
+                                    error_message = error_data
+                    except Exception:
+                        pass
+
+                    await upstream.on_upstream_error_redirect(
+                        response.status_code, error_message
+                    )
+
+                    logger.warning(
+                        f"Upstream {upstream.provider_type} returned {response.status_code} (GET), trying next provider",
+                        extra={
+                            "status_code": response.status_code,
+                            "upstream": upstream.provider_type,
+                        },
+                    )
+                    continue
+                return response
+            except UpstreamError as e:
+                logger.warning(f"Upstream {upstream.provider_type} failed (GET): {e}")
+                if i == len(upstreams) - 1:
+                    last_error_response = create_error_response(
+                        "upstream_error", str(e), 502, request=request
+                    )
+                continue
+        return last_error_response or create_error_response(
+            "upstream_error", "All upstreams failed", 502, request=request
+        )
 
     if request_body_dict:
         await pay_for_request(key, max_cost_for_model, session)
 
-    headers = upstream.prepare_headers(dict(request.headers))
+    for i, upstream in enumerate(upstreams):
+        headers = upstream.prepare_headers(dict(request.headers))
 
-    if is_responses_api:
-        response = await upstream.forward_responses_request(
-            request,
-            path,
-            headers,
-            request_body,
-            key,
-            max_cost_for_model,
-            session,
-            model_obj,
-        )
-    else:
-        response = await upstream.forward_request(
-            request,
-            path,
-            headers,
-            request_body,
-            key,
-            max_cost_for_model,
-            session,
-            model_obj,
-        )
+        try:
+            if is_responses_api:
+                response = await upstream.forward_responses_request(
+                    request,
+                    path,
+                    headers,
+                    request_body,
+                    key,
+                    max_cost_for_model,
+                    session,
+                    model_obj,
+                )
+            else:
+                response = await upstream.forward_request(
+                    request,
+                    path,
+                    headers,
+                    request_body,
+                    key,
+                    max_cost_for_model,
+                    session,
+                    model_obj,
+                )
 
-    if response.status_code != 200:
-        await revert_pay_for_request(key, session, max_cost_for_model)
-        logger.warning(
-            "Upstream request failed, revert payment",
-            extra={
-                "status_code": response.status_code,
-                "path": path,
-                "key_hash": key.hashed_key[:8] + "...",
-                "key_balance": key.balance,
-                "max_cost_for_model": max_cost_for_model,
-                "upstream_headers": response.headers
-                if hasattr(response, "headers")
-                else None,
-            },
-        )
-        # Return the mapped error response generated earlier rather than masking with 502
-        return response
+            if response.status_code != 200:
+                # Check if we should retry (502 Upstream Error or 429 Rate Limit)
+                should_retry = response.status_code in [502, 429, 400, 401, 403, 404]
+                if should_retry and i < len(upstreams) - 1:
+                    error_message = ""
+                    try:
+                        if hasattr(response, "body"):
+                            body_bytes = response.body
+                            data = json.loads(body_bytes)
+                            if "error" in data:
+                                error_data = data["error"]
+                                if isinstance(error_data, dict):
+                                    error_message = error_data.get("message", "")
+                                elif isinstance(error_data, str):
+                                    error_message = error_data
+                    except Exception:
+                        pass
 
-    return response
+                    await upstream.on_upstream_error_redirect(
+                        response.status_code, error_message
+                    )
+
+                    logger.warning(
+                        f"Upstream {upstream.provider_type} returned {response.status_code}, trying next provider",
+                        extra={
+                            "status_code": response.status_code,
+                            "upstream": upstream.provider_type,
+                        },
+                    )
+                    continue
+
+                # 4xx error (user error), or other non-retryable error, or last provider failed
+                await revert_pay_for_request(key, session, max_cost_for_model)
+                logger.warning(
+                    "Upstream request failed, revert payment",
+                    extra={
+                        "status_code": response.status_code,
+                        "path": path,
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "key_balance": key.balance,
+                        "max_cost_for_model": max_cost_for_model,
+                        "upstream_headers": response.headers
+                        if hasattr(response, "headers")
+                        else None,
+                    },
+                )
+                return response
+
+            return response
+
+        except UpstreamError as e:
+            logger.warning(
+                f"Upstream {upstream.provider_type} failed: {e}",
+                extra={"retry": i < len(upstreams) - 1},
+            )
+
+            # If this was the last provider
+            if i == len(upstreams) - 1:
+                await revert_pay_for_request(key, session, max_cost_for_model)
+                return create_error_response(
+                    "upstream_error", str(e), 502, request=request
+                )
+
+            # Otherwise loop continues to next provider
+            continue
+
+    # Should not be reached given logic above
+    return create_error_response(
+        "upstream_error", "All upstreams failed", 502, request=request
+    )
 
 
 async def get_bearer_token_key(
-    headers: dict, path: str, session: AsyncSession, auth: str
+    headers: dict, path: str, session: AsyncSession, auth: str, min_cost: int = 0
 ) -> ApiKey:
     """Handle bearer token authentication proxy requests."""
     bearer_key = auth.replace("Bearer ", "") if auth.startswith("Bearer ") else ""
@@ -263,6 +389,7 @@ async def get_bearer_token_key(
             "bearer_key_preview": bearer_key[:20] + "..."
             if len(bearer_key) > 20
             else bearer_key,
+            "min_cost": min_cost,
         },
     )
 
@@ -301,6 +428,7 @@ async def get_bearer_token_key(
             session,
             refund_address,
             key_expiry_time,  # type: ignore
+            min_cost=min_cost,
         )
         logger.info(
             "Bearer token validated successfully",

routstr/upstream/base.py

@@ -15,6 +15,7 @@ from pydantic import BaseModel
 from ..auth import adjust_payment_for_tokens
 from ..core import get_logger
 from ..core.db import ApiKey, AsyncSession, create_session
+from ..core.exceptions import UpstreamError
 
 if TYPE_CHECKING:
     from ..core.db import UpstreamProviderRow
@@ -340,6 +341,20 @@ class BaseUpstreamProvider:
                 message = preview[:500]
         return message, upstream_code
 
+    async def on_upstream_error_redirect(
+        self, status_code: int, error_message: str
+    ) -> None:
+        """Hook called when the proxy redirects to another provider due to an error.
+
+        Subclasses can implement this to perform actions like disabling the provider
+        if it's out of balance.
+
+        Args:
+            status_code: The HTTP status code returned by the upstream
+            error_message: The error message extracted from the upstream response
+        """
+        pass
+
     async def map_upstream_error_response(
         self, request: Request, path: str, upstream_response: httpx.Response
     ) -> Response:
@@ -436,164 +451,111 @@ class BaseUpstreamProvider:
         async def stream_with_cost(
             max_cost_for_model: int,
         ) -> AsyncGenerator[bytes, None]:
-            stored_chunks: list[bytes] = []
             usage_finalized: bool = False
             last_model_seen: str | None = None
+            usage_chunk_data: dict | None = None
+            done_seen: bool = False
 
-            async def finalize_without_usage() -> bytes | None:
+            async def finalize_db_only() -> None:
                 nonlocal usage_finalized
                 if usage_finalized:
-                    return None
+                    return
                 async with create_session() as new_session:
                     fresh_key = await new_session.get(key.__class__, key.hashed_key)
                     if not fresh_key:
-                        logger.warning(
-                            "Key not found when finalizing streaming payment",
-                            extra={"key_hash": key.hashed_key[:8] + "..."},
-                        )
-                        usage_finalized = True
-                        return None
+                        return
                     try:
-                        fallback: dict = {
-                            "model": last_model_seen or "unknown",
-                            "usage": None,
-                        }
-                        cost_data = await adjust_payment_for_tokens(
-                            fresh_key, fallback, new_session, max_cost_for_model
+                        await adjust_payment_for_tokens(
+                            fresh_key,
+                            {"model": last_model_seen or "unknown", "usage": None},
+                            new_session,
+                            max_cost_for_model,
                         )
                         usage_finalized = True
-                        logger.info(
-                            "Finalized streaming payment without explicit usage",
-                            extra={
-                                "key_hash": key.hashed_key[:8] + "...",
-                                "cost_data": cost_data,
-                                "balance_after_adjustment": fresh_key.balance,
-                            },
-                        )
-                        return f"data: {json.dumps({'cost': cost_data})}\n\n".encode()
-                    except Exception as cost_error:
-                        logger.error(
-                            "Error finalizing payment without usage",
-                            extra={
-                                "error": str(cost_error),
-                                "error_type": type(cost_error).__name__,
-                                "key_hash": key.hashed_key[:8] + "...",
-                            },
-                        )
-                        usage_finalized = True
-                        return None
-
-            try:
-                async for chunk in response.aiter_bytes():
-                    stored_chunks.append(chunk)
-                    try:
-                        for part in re.split(b"data: ", chunk):
-                            if not part or part.strip() in (b"[DONE]", b""):
-                                continue
-                            try:
-                                obj = json.loads(part)
-                                if isinstance(obj, dict) and obj.get("model"):
-                                    last_model_seen = str(obj.get("model"))
-                            except json.JSONDecodeError:
-                                pass
                     except Exception:
                         pass
 
-                    yield chunk
+            try:
+                async for chunk in response.aiter_bytes():
+                    # Split chunk into SSE events
+                    parts = re.split(b"data: ", chunk)
+                    for i, part in enumerate(parts):
+                        if not part:
+                            continue
 
-                logger.debug(
-                    "Streaming completed, analyzing usage data",
-                    extra={
-                        "key_hash": key.hashed_key[:8] + "...",
-                        "chunks_count": len(stored_chunks),
-                    },
-                )
+                        stripped_part = part.strip()
+                        if not stripped_part:
+                            continue
 
-                for i in range(len(stored_chunks) - 1, -1, -1):
-                    chunk = stored_chunks[i]
-                    if not chunk:
-                        continue
-                    try:
-                        events = re.split(b"data: ", chunk)
-                        for event_data in events:
-                            if not event_data or event_data.strip() in (b"[DONE]", b""):
-                                continue
-                            try:
-                                data = json.loads(event_data)
-                                if isinstance(data, dict) and data.get("model"):
-                                    last_model_seen = str(data.get("model"))
-                                if isinstance(data, dict) and isinstance(
-                                    data.get("usage"), dict
-                                ):
-                                    async with create_session() as new_session:
-                                        fresh_key = await new_session.get(
-                                            key.__class__, key.hashed_key
-                                        )
-                                        if fresh_key:
-                                            try:
-                                                cost_data = (
-                                                    await adjust_payment_for_tokens(
-                                                        fresh_key,
-                                                        data,
-                                                        new_session,
-                                                        max_cost_for_model,
-                                                    )
-                                                )
-                                                usage_finalized = True
-                                                logger.info(
-                                                    "Payment adjustment completed for streaming",
-                                                    extra={
-                                                        "key_hash": key.hashed_key[:8]
-                                                        + "...",
-                                                        "cost_data": cost_data,
-                                                        "model": last_model_seen,
-                                                        "balance_after_adjustment": fresh_key.balance,
-                                                    },
-                                                )
-                                                yield f"data: {json.dumps({'cost': cost_data})}\n\n".encode()
-                                            except Exception as cost_error:
-                                                logger.error(
-                                                    "Error adjusting payment for streaming tokens",
-                                                    extra={
-                                                        "error": str(cost_error),
-                                                        "error_type": type(
-                                                            cost_error
-                                                        ).__name__,
-                                                        "key_hash": key.hashed_key[:8]
-                                                        + "...",
-                                                    },
-                                                )
-                                    break
-                            except json.JSONDecodeError:
-                                continue
-                    except Exception as e:
-                        logger.error(
-                            "Error processing streaming response chunk",
-                            extra={
-                                "error": str(e),
-                                "error_type": type(e).__name__,
-                                "key_hash": key.hashed_key[:8] + "...",
-                            },
+                        if stripped_part == b"[DONE]":
+                            done_seen = True
+                            continue
+
+                        try:
+                            obj = json.loads(part)
+                            if isinstance(obj, dict):
+                                if obj.get("model"):
+                                    last_model_seen = str(obj.get("model"))
+
+                                if isinstance(obj.get("usage"), dict):
+                                    # Hold this chunk back to merge cost later
+                                    usage_chunk_data = obj
+                                    continue
+                        except json.JSONDecodeError:
+                            pass
+
+                        prefix = (
+                            b"data: " if (i > 0 or chunk.startswith(b"data: ")) else b""
                         )
+                        yield prefix + part
+
+                # Stream finished, process usage if found
+                if usage_chunk_data:
+                    async with create_session() as session:
+                        fresh_key = await session.get(key.__class__, key.hashed_key)
+                        if fresh_key:
+                            try:
+                                cost_data = await adjust_payment_for_tokens(
+                                    fresh_key,
+                                    usage_chunk_data,
+                                    session,
+                                    max_cost_for_model,
+                                )
+                                # Merge cost into usage
+                                usage_chunk_data["usage"]["cost"] = cost_data.get(
+                                    "total_usd", 0.0
+                                )
+                                # Keep detailed cost in metadata
+                                usage_chunk_data["metadata"] = usage_chunk_data.get(
+                                    "metadata", {}
+                                )
+                                usage_chunk_data["metadata"]["routstr"] = {
+                                    "cost": cost_data
+                                }
+                                yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
+                                usage_finalized = True
+                            except Exception:
+                                # Fallback: yield original usage chunk if adjustment fails
+                                yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
 
                 if not usage_finalized:
-                    maybe_cost_event = await finalize_without_usage()
-                    if maybe_cost_event is not None:
-                        yield maybe_cost_event
+                    await finalize_db_only()
+
+                if done_seen:
+                    yield b"data: [DONE]\n\n"
 
             except Exception as stream_error:
                 logger.warning(
-                    "Streaming interrupted; finalizing without usage",
+                    "Streaming interrupted; finalizing in background",
                     extra={
                         "error": str(stream_error),
-                        "error_type": type(stream_error).__name__,
                         "key_hash": key.hashed_key[:8] + "...",
                     },
                 )
                 raise
             finally:
                 if not usage_finalized:
-                    await finalize_without_usage()
+                    await finalize_db_only()
 
         # Remove inaccurate encoding headers from upstream response
         response_headers = dict(response.headers)
@@ -633,6 +595,7 @@ class BaseUpstreamProvider:
             },
         )
 
+        content: bytes | None = None
         try:
             content = await response.aread()
             response_json = json.loads(content)
@@ -649,6 +612,14 @@ class BaseUpstreamProvider:
             cost_data = await adjust_payment_for_tokens(
                 key, response_json, session, deducted_max_cost
             )
+
+            # Merge cost into usage for OpenCode
+            if "usage" in response_json:
+                response_json["usage"]["cost"] = cost_data.get("total_usd", 0.0)
+
+            # Keep detailed cost
+            response_json["metadata"] = response_json.get("metadata", {})
+            response_json["metadata"]["routstr"] = {"cost": cost_data}
             response_json["cost"] = cost_data
 
             logger.info(
@@ -734,180 +705,135 @@ class BaseUpstreamProvider:
         async def stream_with_responses_cost(
             max_cost_for_model: int,
         ) -> AsyncGenerator[bytes, None]:
-            stored_chunks: list[bytes] = []
             usage_finalized: bool = False
             last_model_seen: str | None = None
             reasoning_tokens: int = 0
+            usage_chunk_data: dict | None = None
+            done_seen: bool = False
 
-            async def finalize_without_usage() -> bytes | None:
+            async def finalize_db_only() -> None:
                 nonlocal usage_finalized
                 if usage_finalized:
-                    return None
+                    return
                 async with create_session() as new_session:
                     fresh_key = await new_session.get(key.__class__, key.hashed_key)
                     if not fresh_key:
-                        logger.warning(
-                            "Key not found when finalizing Responses API streaming payment",
-                            extra={"key_hash": key.hashed_key[:8] + "..."},
-                        )
-                        usage_finalized = True
-                        return None
+                        return
                     try:
-                        fallback: dict = {
-                            "model": last_model_seen or "unknown",
-                            "usage": None,
-                        }
-                        cost_data = await adjust_payment_for_tokens(
-                            fresh_key, fallback, new_session, max_cost_for_model
+                        await adjust_payment_for_tokens(
+                            fresh_key,
+                            {"model": last_model_seen or "unknown", "usage": None},
+                            new_session,
+                            max_cost_for_model,
                         )
                         usage_finalized = True
-                        logger.info(
-                            "Finalized Responses API streaming payment without explicit usage",
-                            extra={
-                                "key_hash": key.hashed_key[:8] + "...",
-                                "cost_data": cost_data,
-                                "balance_after_adjustment": fresh_key.balance,
-                            },
-                        )
-                        return f"data: {json.dumps({'cost': cost_data})}\\n\\n".encode()
-                    except Exception as cost_error:
-                        logger.error(
-                            "Error finalizing Responses API payment without usage",
-                            extra={
-                                "error": str(cost_error),
-                                "error_type": type(cost_error).__name__,
-                                "key_hash": key.hashed_key[:8] + "...",
-                            },
-                        )
-                        usage_finalized = True
-                        return None
-
-            try:
-                async for chunk in response.aiter_bytes():
-                    stored_chunks.append(chunk)
-                    try:
-                        for part in re.split(b"data: ", chunk):
-                            if not part or part.strip() in (b"[DONE]", b""):
-                                continue
-                            try:
-                                obj = json.loads(part)
-                                if isinstance(obj, dict):
-                                    if obj.get("model"):
-                                        last_model_seen = str(obj.get("model"))
-
-                                    # Track reasoning tokens for Responses API
-                                    if usage := obj.get("usage", {}):
-                                        if (
-                                            isinstance(usage, dict)
-                                            and "reasoning_tokens" in usage
-                                        ):
-                                            reasoning_tokens += usage.get(
-                                                "reasoning_tokens", 0
-                                            )
-                            except json.JSONDecodeError:
-                                pass
                     except Exception:
                         pass
 
-                    yield chunk
+            try:
+                async for chunk in response.aiter_bytes():
+                    # Split chunk into SSE events
+                    parts = re.split(b"data: ", chunk)
+                    for i, part in enumerate(parts):
+                        if not part:
+                            continue
 
-                logger.debug(
-                    "Responses API streaming completed, analyzing usage data",
-                    extra={
-                        "key_hash": key.hashed_key[:8] + "...",
-                        "chunks_count": len(stored_chunks),
-                        "reasoning_tokens": reasoning_tokens,
-                    },
-                )
+                        stripped_part = part.strip()
+                        if not stripped_part:
+                            continue
 
-                # Process final usage data
-                for i in range(len(stored_chunks) - 1, -1, -1):
-                    chunk = stored_chunks[i]
-                    if not chunk:
-                        continue
-                    try:
-                        events = re.split(b"data: ", chunk)
-                        for event_data in events:
-                            if not event_data or event_data.strip() in (b"[DONE]", b""):
-                                continue
-                            try:
-                                data = json.loads(event_data)
-                                if isinstance(data, dict) and data.get("model"):
-                                    last_model_seen = str(data.get("model"))
-                                if isinstance(data, dict) and isinstance(
-                                    data.get("usage"), dict
-                                ):
-                                    # Include reasoning tokens in usage calculation
-                                    async with create_session() as new_session:
-                                        fresh_key = await new_session.get(
-                                            key.__class__, key.hashed_key
+                        if stripped_part == b"[DONE]":
+                            done_seen = True
+                            continue
+
+                        try:
+                            obj = json.loads(part)
+                            if isinstance(obj, dict):
+                                if obj.get("model"):
+                                    last_model_seen = str(obj.get("model"))
+
+                                # Track reasoning tokens for Responses API
+                                if usage := obj.get("usage", {}):
+                                    if (
+                                        isinstance(usage, dict)
+                                        and "reasoning_tokens" in usage
+                                    ):
+                                        reasoning_tokens += usage.get(
+                                            "reasoning_tokens", 0
                                         )
-                                        if fresh_key:
-                                            try:
-                                                cost_data = (
-                                                    await adjust_payment_for_tokens(
-                                                        fresh_key,
-                                                        data,
-                                                        new_session,
-                                                        max_cost_for_model,
-                                                    )
-                                                )
-                                                usage_finalized = True
-                                                logger.info(
-                                                    "Payment adjustment completed for Responses API streaming",
-                                                    extra={
-                                                        "key_hash": key.hashed_key[:8]
-                                                        + "...",
-                                                        "cost_data": cost_data,
-                                                        "model": last_model_seen,
-                                                        "reasoning_tokens": reasoning_tokens,
-                                                        "balance_after_adjustment": fresh_key.balance,
-                                                    },
-                                                )
-                                                yield f"data: {json.dumps({'cost': cost_data})}\\n\\n".encode()
-                                            except Exception as cost_error:
-                                                logger.error(
-                                                    "Error adjusting payment for Responses API streaming tokens",
-                                                    extra={
-                                                        "error": str(cost_error),
-                                                        "error_type": type(
-                                                            cost_error
-                                                        ).__name__,
-                                                        "key_hash": key.hashed_key[:8]
-                                                        + "...",
-                                                    },
-                                                )
-                                    break
-                            except json.JSONDecodeError:
-                                continue
-                    except Exception as e:
-                        logger.error(
-                            "Error processing Responses API streaming response chunk",
-                            extra={
-                                "error": str(e),
-                                "error_type": type(e).__name__,
-                                "key_hash": key.hashed_key[:8] + "...",
-                            },
+
+                                # Responses API usage is in response.completed/incomplete events
+                                chunk_type = obj.get("type", "")
+                                if chunk_type in (
+                                    "response.completed",
+                                    "response.incomplete",
+                                ):
+                                    usage_chunk_data = obj
+                                    continue
+                        except json.JSONDecodeError:
+                            pass
+
+                        prefix = (
+                            b"data: " if (i > 0 or chunk.startswith(b"data: ")) else b""
                         )
+                        yield prefix + part
+
+                # Stream finished, process usage if found
+                if usage_chunk_data:
+                    async with create_session() as session:
+                        fresh_key = await session.get(key.__class__, key.hashed_key)
+                        if fresh_key:
+                            try:
+                                cost_data = await adjust_payment_for_tokens(
+                                    fresh_key,
+                                    usage_chunk_data,
+                                    session,
+                                    max_cost_for_model,
+                                )
+                                # Merge cost into usage chunk
+                                if (
+                                    "response" in usage_chunk_data
+                                    and "usage" in usage_chunk_data["response"]
+                                ):
+                                    usage_chunk_data["response"]["usage"]["cost"] = (
+                                        cost_data.get("total_usd", 0.0)
+                                    )
+                                elif "usage" in usage_chunk_data:
+                                    usage_chunk_data["usage"]["cost"] = cost_data.get(
+                                        "total_usd", 0.0
+                                    )
+
+                                # Keep detailed cost in metadata
+                                usage_chunk_data["metadata"] = usage_chunk_data.get(
+                                    "metadata", {}
+                                )
+                                usage_chunk_data["metadata"]["routstr"] = {
+                                    "cost": cost_data
+                                }
+                                yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
+                                usage_finalized = True
+                            except Exception:
+                                # Fallback: yield original usage chunk if adjustment fails
+                                yield f"data: {json.dumps(usage_chunk_data)}\n\n".encode()
 
                 if not usage_finalized:
-                    maybe_cost_event = await finalize_without_usage()
-                    if maybe_cost_event is not None:
-                        yield maybe_cost_event
+                    await finalize_db_only()
+
+                if done_seen:
+                    yield b"data: [DONE]\n\n"
 
             except Exception as stream_error:
                 logger.warning(
-                    "Responses API streaming interrupted; finalizing without usage",
+                    "Responses API streaming interrupted; finalizing in background",
                     extra={
                         "error": str(stream_error),
-                        "error_type": type(stream_error).__name__,
                         "key_hash": key.hashed_key[:8] + "...",
                     },
                 )
                 raise
             finally:
                 if not usage_finalized:
-                    await finalize_without_usage()
+                    await finalize_db_only()
 
         # Remove inaccurate encoding headers from upstream response
         response_headers = dict(response.headers)
@@ -947,6 +873,7 @@ class BaseUpstreamProvider:
             },
         )
 
+        content: bytes | None = None
         try:
             content = await response.aread()
             response_json = json.loads(content)
@@ -966,6 +893,14 @@ class BaseUpstreamProvider:
             cost_data = await adjust_payment_for_tokens(
                 key, response_json, session, deducted_max_cost
             )
+
+            # Merge cost into usage for OpenCode
+            if "usage" in response_json:
+                response_json["usage"]["cost"] = cost_data.get("total_usd", 0.0)
+
+            # Keep detailed cost
+            response_json["metadata"] = response_json.get("metadata", {})
+            response_json["metadata"]["routstr"] = {"cost": cost_data}
             response_json["cost"] = cost_data
 
             logger.info(
@@ -1148,6 +1083,14 @@ class BaseUpstreamProvider:
             )
 
             if response.status_code != 200:
+                if response.status_code >= 500:
+                    await response.aclose()
+                    await client.aclose()
+                    raise UpstreamError(
+                        f"Upstream returned status {response.status_code}",
+                        status_code=response.status_code,
+                    )
+
                 try:
                     mapped_error = await self.map_upstream_error_response(
                         request, path, response
@@ -1238,6 +1181,9 @@ class BaseUpstreamProvider:
                 background=background_tasks,
             )
 
+        except UpstreamError:
+            raise
+
         except httpx.RequestError as exc:
             await client.aclose()
             error_type = type(exc).__name__
@@ -1265,9 +1211,7 @@ class BaseUpstreamProvider:
             else:
                 error_message = f"Error connecting to upstream service: {error_type}"
 
-            return create_error_response(
-                "upstream_error", error_message, 502, request=request
-            )
+            raise UpstreamError(error_message, status_code=502)
 
         except Exception as exc:
             await client.aclose()
@@ -1380,6 +1324,14 @@ class BaseUpstreamProvider:
             )
 
             if response.status_code != 200:
+                if response.status_code >= 500:
+                    await response.aclose()
+                    await client.aclose()
+                    raise UpstreamError(
+                        f"Upstream returned status {response.status_code}",
+                        status_code=response.status_code,
+                    )
+
                 try:
                     mapped_error = await self.map_upstream_error_response(
                         request, path, response
@@ -1447,6 +1399,9 @@ class BaseUpstreamProvider:
                 background=background_tasks,
             )
 
+        except UpstreamError:
+            raise
+
         except httpx.RequestError as exc:
             await client.aclose()
             error_type = type(exc).__name__
@@ -1474,9 +1429,7 @@ class BaseUpstreamProvider:
             else:
                 error_message = f"Error connecting to upstream service: {error_type}"
 
-            return create_error_response(
-                "upstream_error", error_message, 502, request=request
-            )
+            raise UpstreamError(error_message, status_code=502)
 
         except Exception as exc:
             await client.aclose()

routstr/upstream/helpers.py

@@ -236,7 +236,7 @@ async def _seed_providers_from_settings(
     from . import upstream_provider_classes
 
     providers_to_add: list[UpstreamProviderRow] = []
-    seeded_base_urls: set[str] = set()
+    seeded_provider_keys: set[tuple[str, str]] = set()
 
     provider_classes_by_type = {
         cls.provider_type: cls
@@ -261,7 +261,8 @@ async def _seed_providers_from_settings(
                 base_url = provider_class.default_base_url  # type: ignore[attr-defined]
                 result = await session.exec(
                     select(UpstreamProviderRow).where(
-                        UpstreamProviderRow.base_url == base_url
+                        UpstreamProviderRow.base_url == base_url,
+                        UpstreamProviderRow.api_key == api_key,
                     )
                 )
                 if not result.first():
@@ -273,13 +274,15 @@ async def _seed_providers_from_settings(
                             enabled=True,
                         )
                     )
-                    seeded_base_urls.add(base_url)
+                    seeded_provider_keys.add((base_url, api_key))
 
     ollama_base_url = os.environ.get("OLLAMA_BASE_URL")
     if ollama_base_url:
+        ollama_api_key = os.environ.get("OLLAMA_API_KEY", "")
         result = await session.exec(
             select(UpstreamProviderRow).where(
-                UpstreamProviderRow.base_url == ollama_base_url
+                UpstreamProviderRow.base_url == ollama_base_url,
+                UpstreamProviderRow.api_key == ollama_api_key,
             )
         )
         if not result.first():
@@ -287,18 +290,20 @@ async def _seed_providers_from_settings(
                 UpstreamProviderRow(
                     provider_type="ollama",
                     base_url=ollama_base_url,
-                    api_key=os.environ.get("OLLAMA_API_KEY", ""),
+                    api_key=ollama_api_key,
                     enabled=True,
                 )
             )
-            seeded_base_urls.add(ollama_base_url)
+            seeded_provider_keys.add((ollama_base_url, ollama_api_key))
 
     if settings.chat_completions_api_version and settings.upstream_base_url:
         base_url = settings.upstream_base_url
-        if base_url not in seeded_base_urls:
+        api_key = settings.upstream_api_key
+        if (base_url, api_key) not in seeded_provider_keys:
             result = await session.exec(
                 select(UpstreamProviderRow).where(
-                    UpstreamProviderRow.base_url == base_url
+                    UpstreamProviderRow.base_url == base_url,
+                    UpstreamProviderRow.api_key == api_key,
                 )
             )
             if not result.first():
@@ -306,19 +311,21 @@ async def _seed_providers_from_settings(
                     UpstreamProviderRow(
                         provider_type="azure",
                         base_url=base_url,
-                        api_key=settings.upstream_api_key,
+                        api_key=api_key,
                         api_version=settings.chat_completions_api_version,
                         enabled=True,
                     )
                 )
-                seeded_base_urls.add(base_url)
+                seeded_provider_keys.add((base_url, api_key))
 
     if settings.upstream_base_url and settings.upstream_api_key:
         base_url = settings.upstream_base_url
-        if base_url not in seeded_base_urls:
+        api_key = settings.upstream_api_key
+        if (base_url, api_key) not in seeded_provider_keys:
             result = await session.exec(
                 select(UpstreamProviderRow).where(
-                    UpstreamProviderRow.base_url == base_url
+                    UpstreamProviderRow.base_url == base_url,
+                    UpstreamProviderRow.api_key == api_key,
                 )
             )
             if not result.first():
@@ -326,11 +333,11 @@ async def _seed_providers_from_settings(
                     UpstreamProviderRow(
                         provider_type="custom",
                         base_url=base_url,
-                        api_key=settings.upstream_api_key,
+                        api_key=api_key,
                         enabled=True,
                     )
                 )
-                seeded_base_urls.add(base_url)
+                seeded_provider_keys.add((base_url, api_key))
 
     for provider in providers_to_add:
         session.add(provider)

routstr/upstream/ppqai.py

@@ -196,6 +196,37 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
             )
             return []
 
+    async def on_upstream_error_redirect(
+        self, status_code: int, error_message: str
+    ) -> None:
+        if "insufficient balance" in error_message.lower():
+            logger.warning(
+                f"Disabling PPQ.AI provider ({self.base_url}) due to insufficient balance",
+                extra={"error": error_message},
+            )
+            from sqlmodel import select
+
+            from ..core.db import UpstreamProviderRow, create_session
+
+            async with create_session() as session:
+                statement = select(UpstreamProviderRow).where(
+                    UpstreamProviderRow.base_url == self.base_url,
+                    UpstreamProviderRow.api_key == self.api_key,
+                )
+                result = await session.exec(statement)
+                provider = result.first()
+
+                if provider:
+                    provider.enabled = False
+                    session.add(provider)
+                    await session.commit()
+
+                    # Trigger re-initialization of providers
+                    # Import here to avoid circular dependency
+                    from ..proxy import reinitialize_upstreams
+
+                    await reinitialize_upstreams()
+
     async def create_account(self) -> dict[str, object]:
         """Create a new PPQ.AI account.
 

tests/integration/test_child_keys.py

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

tests/integration/test_key_logic.py

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

tests/integration/test_wallet_refund.py

@@ -65,9 +65,10 @@ async def test_full_balance_refund_returns_cashu_token(
     except Exception as e:
         pytest.fail(f"Invalid Cashu token format: {e}")
 
-    # Try to use the API key - should fail since it's been deleted
+    # Try to use the API key - should still work but have 0 balance
     response = await authenticated_client.get("/v1/wallet/")
-    assert response.status_code == 401
+    assert response.status_code == 200
+    assert response.json()["balance"] == 0
 
     # The refund token has been validated above by decoding it
     # The API key deletion has been verified by the 401 response
@@ -261,17 +262,16 @@ async def test_database_state_after_refund(
     response = await authenticated_client.post("/v1/wallet/refund")
     assert response.status_code == 200
 
-    # Verify key is deleted after refund
-    result = await integration_session.execute(
-        select(ApiKey).where(ApiKey.hashed_key == hashed_key)  # type: ignore[arg-type]
-    )
-    assert result.scalar_one_or_none() is None
+    # Refresh the key to get the updated balance from the database
+    await integration_session.refresh(key_before)
 
-    # Count total keys to ensure only the specific one was deleted
+    # Verify key balance is 0 after refund
+    assert key_before.balance == 0
+
+    # Count total keys to ensure it wasn't deleted
     result = await integration_session.execute(select(ApiKey))
     remaining_keys = result.scalars().all()
-    # Should have no keys left (assuming clean test environment)
-    assert len(remaining_keys) == 0
+    assert len(remaining_keys) == 1
 
 
 @pytest.mark.integration
@@ -388,9 +388,10 @@ async def test_refund_during_active_usage(
     # Refund should succeed
     assert refund_response.status_code == 200
 
-    # Further usage should fail
+    # Further usage should return 200 but with 0 balance
     response = await authenticated_client.get("/v1/wallet/")
-    assert response.status_code == 401
+    assert response.status_code == 200
+    assert response.json()["balance"] == 0
 
 
 @pytest.mark.integration
@@ -535,6 +536,3 @@ async def test_refund_with_expired_key(
         # Should still allow manual refund
         assert response.status_code == 200
         assert response.json()["recipient"] == "expired@ln.address"
-
-
-

tests/unit/test_algorithm.py

@@ -10,7 +10,6 @@ os.environ["UPSTREAM_API_KEY"] = "test"
 from routstr.algorithm import (  # noqa: E402
     calculate_model_cost_score,
     get_provider_penalty,
-    should_prefer_model,
 )
 from routstr.payment.models import Architecture, Model, Pricing  # noqa: E402
 
@@ -100,100 +99,3 @@ 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_should_prefer_model_cheaper_wins() -> None:
-    """Test that cheaper model is preferred."""
-    cheap_model = create_test_model("cheap", prompt_price=0.001, completion_price=0.002)
-    expensive_model = create_test_model(
-        "expensive", prompt_price=0.03, completion_price=0.06
-    )
-
-    provider1 = create_test_provider("provider1")
-    provider2 = create_test_provider("provider2")
-
-    # Cheaper model should win
-    assert should_prefer_model(
-        cheap_model, provider1, expensive_model, provider2, "test-alias"
-    )
-
-    # More expensive model should not win
-    assert not should_prefer_model(
-        expensive_model, provider2, cheap_model, provider1, "test-alias"
-    )
-
-
-def test_should_prefer_model_exact_match_wins() -> None:
-    """Test that exact alias match beats cheaper price."""
-    # Make model IDs match the alias differently
-    exact_match = create_test_model(
-        "test-model", prompt_price=0.03, completion_price=0.06
-    )
-    no_match = create_test_model(
-        "other-model", prompt_price=0.001, completion_price=0.002
-    )
-
-    provider1 = create_test_provider("provider1")
-    provider2 = create_test_provider("provider2")
-
-    # Exact match should win even though it's more expensive
-    assert should_prefer_model(
-        exact_match, provider1, no_match, provider2, "test-model"
-    )
-
-
-def test_should_prefer_model_openrouter_slight_penalty() -> None:
-    """Test that OpenRouter has slight penalty compared to other providers."""
-    model1 = create_test_model("model1", prompt_price=0.001, completion_price=0.002)
-    model2 = create_test_model("model2", prompt_price=0.001, completion_price=0.002)
-
-    regular_provider = create_test_provider("regular", "http://provider.com")
-    openrouter_provider = create_test_provider(
-        "openrouter", "https://openrouter.ai/api/v1"
-    )
-
-    # Regular provider should be preferred over OpenRouter at same cost
-    assert should_prefer_model(
-        model1, regular_provider, model2, openrouter_provider, "test-alias"
-    )
-
-    # OpenRouter should not replace regular provider at same cost
-    assert not should_prefer_model(
-        model2, openrouter_provider, model1, regular_provider, "test-alias"
-    )
-
-
-def test_should_prefer_model_openrouter_can_win_if_cheaper() -> None:
-    """Test that OpenRouter can still win if significantly cheaper."""
-    cheap_model = create_test_model(
-        "cheap", prompt_price=0.0001, completion_price=0.0002
-    )
-    expensive_model = create_test_model(
-        "expensive", prompt_price=0.03, completion_price=0.06
-    )
-
-    regular_provider = create_test_provider("regular", "http://provider.com")
-    openrouter_provider = create_test_provider(
-        "openrouter", "https://openrouter.ai/api/v1"
-    )
-
-    # OpenRouter should win if it's much cheaper (even with penalty)
-    assert should_prefer_model(
-        cheap_model,
-        openrouter_provider,
-        expensive_model,
-        regular_provider,
-        "test-alias",
-    )
-
-
-def test_should_prefer_model_same_cost_first_wins() -> None:
-    """Test that when costs are identical, current model is kept."""
-    model1 = create_test_model("model1", prompt_price=0.001, completion_price=0.002)
-    model2 = create_test_model("model2", prompt_price=0.001, completion_price=0.002)
-
-    provider1 = create_test_provider("provider1")
-    provider2 = create_test_provider("provider2")
-
-    # When costs are equal, should not replace
-    assert not should_prefer_model(model2, provider2, model1, provider1, "test-alias")

ui/components/AddProviderModelDialog.tsx

@@ -248,7 +248,9 @@ export function AddProviderModelDialog({
     const pricing = model.pricing as Record<string, number>;
     const topProvider = model.top_provider as Record<string, unknown> | null;
 
-    form.setValue('id', model.id);
+    if (!isOverride) {
+      form.setValue('id', model.id);
+    }
     form.setValue('name', model.name);
     form.setValue('description', model.description || '');
     form.setValue('context_length', model.context_length);
@@ -425,7 +427,7 @@ export function AddProviderModelDialog({
           </DialogTitle>
           <DialogDescription>{description}</DialogDescription>
         </DialogHeader>
-        {!isEdit && !isOverride && (
+        {!isEdit && (
           <div className='bg-muted/30 rounded-md border p-3'>
             <div className='mb-2 text-sm font-medium'>Presets</div>
             <div className='grid gap-2 sm:grid-cols-3 sm:items-start'>
@@ -488,8 +490,9 @@ export function AddProviderModelDialog({
               </Popover>
             </div>
             <div className='text-muted-foreground mt-1 text-xs'>
-              Prefill fields from a preset model definition, then adjust as
-              needed.
+              {isOverride
+                ? 'Apply pricing and settings from a preset model (keeping the model ID unchanged).'
+                : 'Prefill fields from a preset model definition, then adjust as needed.'}
             </div>
           </div>
         )}

ui/components/child-key-creator.tsx

@@ -0,0 +1,546 @@
+'use client';
+
+import { useState } from 'react';
+import { WalletService } from '@/lib/api/services/wallet';
+import { Button } from '@/components/ui/button';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import { Input } from '@/components/ui/input';
+import {
+  Key,
+  Copy,
+  Check,
+  Loader2,
+  RotateCcw,
+  Plus,
+  Trash2,
+} from 'lucide-react';
+import { toast } from 'sonner';
+import { Badge } from '@/components/ui/badge';
+import { KeyOptions } from './key-options';
+
+interface KeyConfig {
+  id: string;
+  count: number;
+  balanceLimit: string;
+  balanceLimitReset: string;
+  validityDate: string;
+}
+
+interface ChildKeyCreatorProps {
+  baseUrl?: string;
+  apiKey?: string;
+  onApiKeyChange?: (apiKey: string) => void;
+  costPerKeyMsats?: number;
+}
+
+export function ChildKeyCreator({
+  baseUrl,
+  apiKey: propApiKey,
+  onApiKeyChange,
+  costPerKeyMsats,
+}: ChildKeyCreatorProps) {
+  const [internalApiKey, setInternalApiKey] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [configs, setConfigs] = useState<KeyConfig[]>([
+    {
+      id: crypto.randomUUID(),
+      count: 1,
+      balanceLimit: '',
+      balanceLimitReset: '',
+      validityDate: '',
+    },
+  ]);
+  const [childKeyToCheck, setChildKeyToCheck] = useState('');
+  const [checking, setChecking] = useState(false);
+  const [keyStatus, setKeyStatus] = useState<{
+    total_spent: number;
+    balance_limit: number | null;
+    validity_date: number | null;
+    is_expired: boolean;
+    is_drained: boolean;
+  } | null>(null);
+  const [newKeys, setNewKeys] = useState<string[]>([]);
+  const [resultInfo, setResultInfo] = useState<{
+    cost_msats: number;
+    parent_balance: number;
+  } | null>(null);
+  const [copiedKey, setCopiedKey] = useState<string | null>(null);
+
+  const activeApiKey = propApiKey ?? internalApiKey;
+
+  const handleApiKeyChange = (val: string) => {
+    setInternalApiKey(val);
+    onApiKeyChange?.(val);
+  };
+
+  const addConfig = () => {
+    setConfigs([
+      ...configs,
+      {
+        id: crypto.randomUUID(),
+        count: 1,
+        balanceLimit: '',
+        balanceLimitReset: '',
+        validityDate: '',
+      },
+    ]);
+  };
+
+  const removeConfig = (id: string) => {
+    if (configs.length > 1) {
+      setConfigs(configs.filter((c) => c.id !== id));
+    }
+  };
+
+  const updateConfig = (id: string, updates: Partial<KeyConfig>) => {
+    setConfigs(configs.map((c) => (c.id === id ? { ...c, ...updates } : c)));
+  };
+
+  const handleCreateKey = async () => {
+    if (!activeApiKey && baseUrl) {
+      toast.error('Please provide a Parent API key first');
+      return;
+    }
+
+    setLoading(true);
+    try {
+      let allNewKeys: string[] = [];
+      let totalCost = 0;
+      let lastParentBalance = 0;
+
+      for (const config of configs) {
+        const requestedCount = Math.max(1, Math.min(50, Number(config.count)));
+        const result = await WalletService.createChildKey(
+          baseUrl,
+          activeApiKey,
+          requestedCount,
+          config.balanceLimit ? parseInt(config.balanceLimit) : undefined,
+          config.balanceLimitReset || undefined,
+          config.validityDate
+            ? Math.floor(
+                new Date(config.validityDate + 'T23:59:59').getTime() / 1000
+              )
+            : undefined
+        );
+
+        if (result.api_keys) {
+          allNewKeys = [...allNewKeys, ...result.api_keys];
+        }
+        totalCost += result.cost_msats;
+        lastParentBalance = result.parent_balance;
+      }
+
+      setNewKeys(allNewKeys);
+      setResultInfo({
+        cost_msats: totalCost,
+        parent_balance: lastParentBalance,
+      });
+
+      toast.success(
+        `${allNewKeys.length} child API key${
+          allNewKeys.length > 1 ? 's' : ''
+        } created successfully`
+      );
+    } catch (error) {
+      console.error('Failed to create child key:', error);
+      toast.error(
+        error instanceof Error ? error.message : 'Failed to create child key'
+      );
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleCheckKey = async () => {
+    if (!childKeyToCheck) {
+      toast.error('Please provide a Child API key to check');
+      return;
+    }
+
+    setChecking(true);
+    setKeyStatus(null);
+    try {
+      const baseUrlToUse = baseUrl || '';
+      const response = await fetch(`${baseUrlToUse}/v1/balance/info`, {
+        headers: {
+          Authorization: `Bearer ${childKeyToCheck}`,
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error('Failed to fetch key info');
+      }
+
+      const info = await response.json();
+      const now = Math.floor(Date.now() / 1000);
+
+      setKeyStatus({
+        total_spent: info.total_spent,
+        balance_limit: info.balance_limit,
+        validity_date: info.validity_date,
+        is_expired: info.validity_date ? now > info.validity_date : false,
+        is_drained: info.balance_limit
+          ? info.total_spent >= info.balance_limit
+          : false,
+      });
+    } catch (error) {
+      toast.error(
+        error instanceof Error ? error.message : 'Failed to check child key'
+      );
+    } finally {
+      setChecking(false);
+    }
+  };
+
+  const copyToClipboard = (key: string) => {
+    navigator.clipboard.writeText(key);
+    setCopiedKey(key);
+    toast.success('API key copied to clipboard');
+    setTimeout(() => setCopiedKey(null), 2000);
+  };
+
+  const copyAllToClipboard = () => {
+    navigator.clipboard.writeText(newKeys.join('\n'));
+    toast.success('All API keys copied to clipboard');
+  };
+
+  return (
+    <div className='space-y-6'>
+      <Card>
+        <CardHeader>
+          <div className='flex items-center justify-between'>
+            <div className='space-y-1'>
+              <CardTitle>Create Child API Key</CardTitle>
+              <CardDescription>
+                Generate secondary API keys that share your account balance.
+              </CardDescription>
+            </div>
+            {costPerKeyMsats !== undefined && (
+              <div className='text-right'>
+                <p className='text-muted-foreground text-[0.65rem] tracking-wide uppercase'>
+                  Unit Cost
+                </p>
+                <p className='text-primary text-sm font-bold'>
+                  {costPerKeyMsats / 1000} sats
+                </p>
+              </div>
+            )}
+          </div>
+        </CardHeader>
+        <CardContent>
+          <div className='space-y-4'>
+            {baseUrl && (
+              <div className='space-y-2'>
+                <label className='text-muted-foreground text-[0.7rem] tracking-wider uppercase'>
+                  Parent API Key
+                </label>
+                <Input
+                  value={activeApiKey}
+                  onChange={(e) => handleApiKeyChange(e.target.value)}
+                  placeholder='sk-...'
+                  className='font-mono text-sm'
+                />
+              </div>
+            )}
+
+            <div className='flex flex-col gap-6'>
+              {configs.map((config, index) => (
+                <div
+                  key={config.id}
+                  className='bg-muted/30 relative space-y-4 rounded-lg border p-4 pt-6'
+                >
+                  {configs.length > 1 && (
+                    <Button
+                      variant='ghost'
+                      size='icon'
+                      className='text-destructive hover:bg-destructive/10 hover:text-destructive absolute top-2 right-2 h-7 w-7'
+                      onClick={() => removeConfig(config.id)}
+                    >
+                      <Trash2 className='h-4 w-4' />
+                    </Button>
+                  )}
+                  <div className='flex flex-col gap-4 sm:flex-row sm:items-end'>
+                    <div className='w-full space-y-2 sm:w-32'>
+                      <label className='text-muted-foreground text-[0.7rem] tracking-wider uppercase'>
+                        Number of keys
+                      </label>
+                      <Input
+                        type='number'
+                        min={1}
+                        max={50}
+                        value={config.count}
+                        onChange={(e) => {
+                          const val = parseInt(e.target.value);
+                          updateConfig(config.id, {
+                            count: isNaN(val)
+                              ? 1
+                              : Math.max(1, Math.min(50, val)),
+                          });
+                        }}
+                        className='h-9'
+                      />
+                    </div>
+
+                    <div className='flex-1'>
+                      <KeyOptions
+                        balanceLimit={config.balanceLimit}
+                        setBalanceLimit={(val) =>
+                          updateConfig(config.id, { balanceLimit: val })
+                        }
+                        validityDate={config.validityDate}
+                        setValidityDate={(val) =>
+                          updateConfig(config.id, { validityDate: val })
+                        }
+                        balanceLimitReset={config.balanceLimitReset}
+                        setBalanceLimitReset={(val) =>
+                          updateConfig(config.id, { balanceLimitReset: val })
+                        }
+                      />
+                    </div>
+                  </div>
+                </div>
+              ))}
+
+              <div className='flex justify-center'>
+                <Button
+                  variant='outline'
+                  size='sm'
+                  onClick={addConfig}
+                  className='gap-2 border-dashed'
+                >
+                  <Plus className='h-4 w-4' />
+                  Add Another Configuration
+                </Button>
+              </div>
+
+              <div className='flex flex-wrap items-center justify-between gap-4'>
+                <div className='text-muted-foreground text-xs'>
+                  {costPerKeyMsats && (
+                    <p>
+                      Total Cost:{' '}
+                      <span className='text-foreground font-medium'>
+                        {costPerKeyMsats *
+                          configs.reduce(
+                            (acc, c) => acc + Number(c.count),
+                            0
+                          )}{' '}
+                        mSats
+                      </span>
+                    </p>
+                  )}
+                </div>
+
+                <Button
+                  onClick={handleCreateKey}
+                  disabled={loading || (!!baseUrl && !activeApiKey)}
+                  className='w-full min-w-[140px] sm:w-auto'
+                >
+                  {loading ? (
+                    <>
+                      <Loader2 className='mr-2 h-4 w-4 animate-spin' />
+                      Creating...
+                    </>
+                  ) : (
+                    <>
+                      <Key className='mr-2 h-4 w-4' />
+                      Generate{' '}
+                      {configs.reduce(
+                        (acc, c) => acc + Number(c.count),
+                        0
+                      )}{' '}
+                      Keys
+                    </>
+                  )}
+                </Button>
+              </div>
+            </div>
+
+            <p className='text-muted-foreground text-xs'>
+              Each key creation has a small one-time fee.
+            </p>
+
+            {newKeys.length > 0 && (
+              <div className='mt-6 space-y-4'>
+                <Alert className='border-green-200 bg-green-50 dark:border-green-900/20 dark:bg-green-900/10'>
+                  <AlertTitle className='text-green-800 dark:text-green-400'>
+                    {newKeys.length} New API Key{newKeys.length > 1 ? 's' : ''}{' '}
+                    Generated
+                  </AlertTitle>
+                  <AlertDescription className='text-green-700 dark:text-green-500'>
+                    Copy {newKeys.length > 1 ? 'these keys' : 'this key'} now.
+                    You won&apos;t be able to see them again.
+                    {resultInfo && (
+                      <div className='mt-2 font-medium opacity-80'>
+                        Total Cost: {resultInfo.cost_msats / 1000} sats | New
+                        Balance: {resultInfo.parent_balance / 1000} sats
+                      </div>
+                    )}
+                  </AlertDescription>
+                </Alert>
+
+                <div className='space-y-2'>
+                  <div className='flex items-center justify-between'>
+                    <span className='text-muted-foreground text-xs font-medium uppercase'>
+                      Generated Keys ({newKeys.length})
+                    </span>
+                    {newKeys.length > 1 && (
+                      <Button
+                        variant='ghost'
+                        size='sm'
+                        className='h-7 text-[10px] uppercase'
+                        onClick={copyAllToClipboard}
+                      >
+                        <Copy className='mr-1 h-3 w-3' />
+                        Copy All
+                      </Button>
+                    )}
+                  </div>
+                  <div className='grid gap-2'>
+                    {newKeys.map((key, index) => (
+                      <div
+                        key={index}
+                        className='group relative flex items-center gap-2'
+                      >
+                        <code className='bg-muted/50 flex-1 rounded border p-2.5 font-mono text-[10px] break-all sm:text-xs'>
+                          {key}
+                        </code>
+                        <Button
+                          size='icon'
+                          variant='ghost'
+                          className='h-8 w-8 shrink-0'
+                          onClick={() => copyToClipboard(key)}
+                        >
+                          {copiedKey === key ? (
+                            <Check className='h-3.5 w-3.5 text-green-500' />
+                          ) : (
+                            <Copy className='h-3.5 w-3.5 opacity-50 group-hover:opacity-100' />
+                          )}
+                        </Button>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+
+                {newKeys.length > 3 && (
+                  <div className='space-y-2'>
+                    <label className='text-muted-foreground text-[0.7rem] tracking-wider uppercase'>
+                      Bulk Export (All Keys)
+                    </label>
+                    <div className='relative'>
+                      <textarea
+                        readOnly
+                        value={newKeys.join('\n')}
+                        rows={Math.min(newKeys.length, 6)}
+                        className='bg-muted/30 w-full rounded-md border p-3 font-mono text-[10px] focus:outline-none'
+                      />
+                      <Button
+                        size='sm'
+                        variant='secondary'
+                        className='absolute right-2 bottom-2 h-7 text-[10px]'
+                        onClick={copyAllToClipboard}
+                      >
+                        Copy Bulk
+                      </Button>
+                    </div>
+                  </div>
+                )}
+              </div>
+            )}
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle className='text-lg'>Check Child Key Status</CardTitle>
+          <CardDescription>
+            View the current spending, limit, and expiration status of any child
+            key.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className='space-y-4'>
+            <div className='space-y-2'>
+              <label className='text-muted-foreground text-[0.7rem] tracking-wider uppercase'>
+                Child API Key
+              </label>
+              <Input
+                value={childKeyToCheck}
+                onChange={(e) => setChildKeyToCheck(e.target.value)}
+                placeholder='sk-...'
+                className='font-mono text-sm'
+              />
+            </div>
+            <Button
+              onClick={handleCheckKey}
+              disabled={checking || !childKeyToCheck}
+              variant='outline'
+              className='w-full'
+            >
+              {checking ? (
+                <>
+                  <Loader2 className='mr-2 h-4 w-4 animate-spin' />
+                  Checking...
+                </>
+              ) : (
+                <>
+                  <RotateCcw className='mr-2 h-4 w-4' />
+                  Check Status
+                </>
+              )}
+            </Button>
+
+            {keyStatus && (
+              <div className='bg-muted/30 mt-4 space-y-3 rounded-lg border p-4 text-sm'>
+                <div className='flex justify-between'>
+                  <span className='text-muted-foreground'>Total Spent:</span>
+                  <span className='font-mono font-medium'>
+                    {keyStatus.total_spent} mSats
+                  </span>
+                </div>
+                {keyStatus.balance_limit !== null && (
+                  <div className='flex justify-between'>
+                    <span className='text-muted-foreground'>Limit:</span>
+                    <span className='font-mono font-medium'>
+                      {keyStatus.balance_limit} mSats
+                    </span>
+                  </div>
+                )}
+                {keyStatus.validity_date !== null && (
+                  <div className='flex justify-between'>
+                    <span className='text-muted-foreground'>Expires:</span>
+                    <span className='font-mono font-medium'>
+                      {new Date(
+                        keyStatus.validity_date * 1000
+                      ).toLocaleDateString()}
+                    </span>
+                  </div>
+                )}
+                <div className='flex gap-2 pt-2'>
+                  {keyStatus.is_drained && (
+                    <Badge variant='destructive'>Drained</Badge>
+                  )}
+                  {keyStatus.is_expired && (
+                    <Badge variant='destructive'>Expired</Badge>
+                  )}
+                  {!keyStatus.is_drained && !keyStatus.is_expired && (
+                    <Badge className='bg-green-600 hover:bg-green-700'>
+                      Active
+                    </Badge>
+                  )}
+                </div>
+              </div>
+            )}
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

ui/components/key-options.tsx

@@ -0,0 +1,72 @@
+import { Zap, Calendar, Shield } from 'lucide-react';
+import { Input } from '@/components/ui/input';
+
+interface KeyOptionsProps {
+  balanceLimit: string;
+  setBalanceLimit: (val: string) => void;
+  validityDate: string;
+  setValidityDate: (val: string) => void;
+  balanceLimitReset: string;
+  setBalanceLimitReset: (val: string) => void;
+  showBalanceLimit?: boolean;
+}
+
+export function KeyOptions({
+  balanceLimit,
+  setBalanceLimit,
+  validityDate,
+  setValidityDate,
+  balanceLimitReset,
+  setBalanceLimitReset,
+  showBalanceLimit = true,
+}: KeyOptionsProps) {
+  return (
+    <div className='grid gap-4 sm:grid-cols-3'>
+      {showBalanceLimit && (
+        <div className='space-y-2'>
+          <label className='text-muted-foreground flex items-center gap-1.5 text-[0.7rem] tracking-wider uppercase'>
+            <Zap className='h-3 w-3' />
+            Balance Limit (mSats)
+          </label>
+          <Input
+            type='number'
+            placeholder='No limit'
+            value={balanceLimit}
+            onChange={(e) => setBalanceLimit(e.target.value)}
+            className='h-9 text-xs'
+          />
+        </div>
+      )}
+
+      <div className='space-y-2'>
+        <label className='text-muted-foreground flex items-center gap-1.5 text-[0.7rem] tracking-wider uppercase'>
+          <Calendar className='h-3 w-3' />
+          Validity Date
+        </label>
+        <Input
+          type='date'
+          value={validityDate}
+          onChange={(e) => setValidityDate(e.target.value)}
+          className='h-9 text-xs'
+        />
+      </div>
+
+      <div className='space-y-2'>
+        <label className='text-muted-foreground flex items-center gap-1.5 text-[0.7rem] tracking-wider uppercase'>
+          <Shield className='h-3 w-3' />
+          Reset Policy
+        </label>
+        <select
+          value={balanceLimitReset}
+          onChange={(e) => setBalanceLimitReset(e.target.value)}
+          className='bg-background border-input flex h-9 w-full rounded-md border px-3 py-1 text-xs shadow-sm transition-colors'
+        >
+          <option value=''>None</option>
+          <option value='daily'>Daily</option>
+          <option value='weekly'>Weekly</option>
+          <option value='monthly'>Monthly</option>
+        </select>
+      </div>
+    </div>
+  );
+}

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

@@ -8,6 +8,7 @@ import { Button } from '@/components/ui/button';
 import { Textarea } from '@/components/ui/textarea';
 import { Input } from '@/components/ui/input';
 import { Separator } from '@/components/ui/separator';
+import { KeyOptions } from '@/components/key-options';
 
 type WalletSnapshot = {
   apiKey: string;
@@ -86,9 +87,11 @@ export function CashuPaymentWorkflow({
   const [isTopupLoading, setIsTopupLoading] = useState(false);
   const [isRefunding, setIsRefunding] = useState(false);
   const [isSyncingBalance, setIsSyncingBalance] = useState(false);
-  const [hasInteractedCreate, setHasInteractedCreate] = useState(false);
   const [hasInteractedManage, setHasInteractedManage] = useState(false);
   const [hasInteractedTopup, setHasInteractedTopup] = useState(false);
+  const [balanceLimit, setBalanceLimit] = useState<string>('');
+  const [balanceLimitReset, setBalanceLimitReset] = useState<string>('');
+  const [validityDate, setValidityDate] = useState<string>('');
 
   const activeApiKey = apiKeyInput.trim();
 
@@ -121,6 +124,15 @@ export function CashuPaymentWorkflow({
       const params = new URLSearchParams({
         initial_balance_token: initialToken.trim(),
       });
+      if (balanceLimit) params.append('balance_limit', balanceLimit);
+      if (balanceLimitReset)
+        params.append('balance_limit_reset', balanceLimitReset);
+      if (validityDate) {
+        const timestamp = Math.floor(
+          new Date(validityDate + 'T23:59:59').getTime() / 1000
+        );
+        params.append('validity_date', timestamp.toString());
+      }
       const response = await fetch(
         `${baseUrl}/v1/balance/create?${params.toString()}`,
         {
@@ -154,7 +166,14 @@ export function CashuPaymentWorkflow({
     } finally {
       setIsCreatingKey(false);
     }
-  }, [initialToken, baseUrl, onApiKeyCreated]);
+  }, [
+    initialToken,
+    baseUrl,
+    onApiKeyCreated,
+    balanceLimit,
+    balanceLimitReset,
+    validityDate,
+  ]);
 
   const handleSyncBalance = useCallback(async (): Promise<void> => {
     if (!activeApiKey) {
@@ -256,11 +275,10 @@ export function CashuPaymentWorkflow({
     [apiKey, onApiKeyChanged, onWalletInfoUpdated]
   );
 
-  const showCreateDetails =
-    hasInteractedCreate || initialToken.trim().length > 0;
   const showManageDetails = hasInteractedManage || Boolean(walletInfo);
   const showTopupDetails = hasInteractedTopup || topupToken.trim().length > 0;
   const canTopup = Boolean(activeApiKey);
+  const showCreateDetails = initialToken.trim().length > 0;
 
   return (
     <Card>
@@ -285,12 +303,21 @@ export function CashuPaymentWorkflow({
             value={initialToken}
             onChange={(event) => setInitialToken(event.target.value)}
             placeholder='cashuA1...'
-            rows={showCreateDetails ? 4 : 2}
+            rows={4}
             className='font-mono text-sm transition-all duration-200'
-            onFocus={() => setHasInteractedCreate(true)}
           />
-          {showCreateDetails && (
-            <div className='flex flex-wrap gap-2'>
+          <div className='space-y-4'>
+            <KeyOptions
+              balanceLimit={balanceLimit}
+              setBalanceLimit={setBalanceLimit}
+              validityDate={validityDate}
+              setValidityDate={setValidityDate}
+              balanceLimitReset={balanceLimitReset}
+              setBalanceLimitReset={setBalanceLimitReset}
+              showBalanceLimit={false}
+            />
+
+            <div className='flex flex-wrap items-center gap-3'>
               <Button
                 onClick={handleCreateKey}
                 disabled={isCreatingKey}
@@ -298,11 +325,13 @@ export function CashuPaymentWorkflow({
               >
                 {isCreatingKey ? 'Creating…' : 'Create API key'}
               </Button>
-              <span className='text-muted-foreground text-xs'>
+              <span className='text-muted-foreground text-[0.7rem] leading-relaxed'>
                 Redeems instantly and returns <code>sk-</code> key.
+                <br />
+                Optional limits can be set above for enhanced security.
               </span>
             </div>
-          )}
+          </div>
         </section>
 
         <Separator />

ui/components/landing/cheat-sheet.tsx

@@ -14,6 +14,7 @@ import { ConfigurationService } from '@/lib/api/services/configuration';
 import { CashuPaymentWorkflow } from './cashu-payment-workflow';
 import { LightningPaymentWorkflow } from './lightning-payment-workflow';
 import { ApiKeyManager } from './api-key-manager';
+import { ChildKeyCreator } from '@/components/child-key-creator';
 
 type NodeInfo = {
   name: string;
@@ -23,6 +24,7 @@ type NodeInfo = {
   mints: string[];
   http_url?: string | null;
   onion_url?: string | null;
+  child_key_cost_msats?: number;
 };
 
 type WalletSnapshot = {
@@ -362,10 +364,11 @@ export function CheatSheet(): JSX.Element {
         </section>
 
         <Tabs defaultValue='cashu' className='w-full'>
-          <TabsList className='grid w-full grid-cols-3'>
+          <TabsList className='grid w-full grid-cols-4'>
             <TabsTrigger value='cashu'>Cashu Payments</TabsTrigger>
             <TabsTrigger value='lightning'>Lightning Payments</TabsTrigger>
             <TabsTrigger value='manage'>Manage Keys</TabsTrigger>
+            <TabsTrigger value='child-keys'>Child Keys</TabsTrigger>
           </TabsList>
 
           <TabsContent value='cashu' className='space-y-4'>
@@ -422,6 +425,15 @@ export function CheatSheet(): JSX.Element {
               </Card>
             )}
           </TabsContent>
+
+          <TabsContent value='child-keys' className='space-y-4'>
+            <ChildKeyCreator
+              baseUrl={normalizedBaseUrl}
+              apiKey={apiKeyInput}
+              onApiKeyChange={handleApiKeyChanged}
+              costPerKeyMsats={nodeInfo?.child_key_cost_msats}
+            />
+          </TabsContent>
         </Tabs>
       </main>
     </div>

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

@@ -10,6 +10,7 @@ import { Button } from '@/components/ui/button';
 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;
@@ -89,7 +90,10 @@ export function LightningPaymentWorkflow({
   const [isTopupping, setIsTopupping] = useState(false);
   const [isRecovering, setIsRecovering] = useState(false);
 
-  const [hasInteractedCreate, setHasInteractedCreate] = useState(false);
+  const [balanceLimit, setBalanceLimit] = useState<string>('');
+  const [balanceLimitReset, setBalanceLimitReset] = useState<string>('');
+  const [validityDate, setValidityDate] = useState<string>('');
+
   const [hasInteractedTopup, setHasInteractedTopup] = useState(false);
   const [hasInteractedRecover, setHasInteractedRecover] = useState(false);
 
@@ -166,13 +170,29 @@ export function LightningPaymentWorkflow({
     setIsCreating(true);
 
     try {
+      const payload: {
+        amount_sats: number;
+        purpose: string;
+        balance_limit?: number;
+        balance_limit_reset?: string;
+        validity_date?: number;
+      } = {
+        amount_sats: amount,
+        purpose: 'create',
+      };
+
+      if (balanceLimit) payload.balance_limit = parseInt(balanceLimit);
+      if (balanceLimitReset) payload.balance_limit_reset = balanceLimitReset;
+      if (validityDate) {
+        payload.validity_date = Math.floor(
+          new Date(validityDate + 'T23:59:59').getTime() / 1000
+        );
+      }
+
       const response = await fetch(`${baseUrl}/v1/balance/lightning/invoice`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          amount_sats: amount,
-          purpose: 'create',
-        }),
+        body: JSON.stringify(payload),
       });
 
       if (!response.ok) {
@@ -214,7 +234,15 @@ export function LightningPaymentWorkflow({
     } finally {
       setIsCreating(false);
     }
-  }, [createAmount, baseUrl, pollInvoiceStatus, onApiKeyCreated]);
+  }, [
+    createAmount,
+    baseUrl,
+    pollInvoiceStatus,
+    onApiKeyCreated,
+    balanceLimit,
+    balanceLimitReset,
+    validityDate,
+  ]);
 
   const handleTopupInvoice = useCallback(async (): Promise<void> => {
     const amount = parseInt(topupAmount);
@@ -333,14 +361,13 @@ export function LightningPaymentWorkflow({
     }
   }, [recoverInvoice, baseUrl, onApiKeyCreated]);
 
-  const showCreateDetails =
-    hasInteractedCreate || createAmount.trim().length > 0;
   const showTopupDetails =
     hasInteractedTopup ||
     topupAmount.trim().length > 0 ||
     topupApiKey.trim().length > 0;
   const showRecoverDetails =
     hasInteractedRecover || recoverInvoice.trim().length > 0;
+  const showCreateDetails = createAmount.trim().length > 0;
 
   return (
     <Card>
@@ -367,9 +394,18 @@ export function LightningPaymentWorkflow({
             onChange={(event) => setCreateAmount(event.target.value)}
             placeholder='Amount in sats (e.g., 1000)'
             className='text-sm'
-            onFocus={() => setHasInteractedCreate(true)}
           />
-          {showCreateDetails && (
+          <div className='space-y-4'>
+            <KeyOptions
+              balanceLimit={balanceLimit}
+              setBalanceLimit={setBalanceLimit}
+              validityDate={validityDate}
+              setValidityDate={setValidityDate}
+              balanceLimitReset={balanceLimitReset}
+              setBalanceLimitReset={setBalanceLimitReset}
+              showBalanceLimit={false}
+            />
+
             <div className='space-y-3'>
               <Button
                 onClick={handleCreateInvoice}
@@ -473,7 +509,7 @@ export function LightningPaymentWorkflow({
                 </div>
               )}
             </div>
-          )}
+          </div>
         </section>
 
         <Separator />

ui/components/temporary-balances.tsx

@@ -60,7 +60,11 @@ export function TemporaryBalances({
     let totalRequests = 0;
 
     balances.forEach((balance) => {
-      totalBalance += balance.balance || 0;
+      // Only count parents for total balance to avoid double counting
+      // since child keys use parent balance
+      if (!balance.parent_key_hash) {
+        totalBalance += balance.balance || 0;
+      }
       totalSpent += balance.total_spent || 0;
       totalRequests += balance.total_requests || 0;
     });
@@ -72,6 +76,34 @@ export function TemporaryBalances({
     ? calculateTotals(data)
     : { totalBalance: 0, totalSpent: 0, totalRequests: 0 };
 
+  // Group parents and children
+  const hierarchicalData = (() => {
+    if (!data) return [];
+
+    const parents = filteredData.filter((item) => !item.parent_key_hash);
+    const result: (TemporaryBalance & { isChild?: boolean })[] = [];
+
+    parents.forEach((parent) => {
+      result.push(parent);
+      const children = data.filter(
+        (item) => item.parent_key_hash === parent.hashed_key
+      );
+      children.forEach((child) => {
+        result.push({ ...child, isChild: true });
+      });
+    });
+
+    // Add children whose parents didn't match the search or aren't in the list
+    const orphans = filteredData.filter(
+      (item) =>
+        item.parent_key_hash &&
+        !result.some((r) => r.hashed_key === item.hashed_key)
+    );
+    result.push(...orphans.map((o) => ({ ...o, isChild: true })));
+
+    return result;
+  })();
+
   return (
     <>
       <Card className='h-full w-full shadow-sm'>
@@ -182,22 +214,37 @@ export function TemporaryBalances({
                   <div className='text-right'>Expiry Time</div>
                 </div>
 
-                {filteredData.length > 0 ? (
-                  filteredData.map((balance, index) => (
+                {hierarchicalData.length > 0 ? (
+                  hierarchicalData.map((balance, index) => (
                     <div
                       key={index}
                       className={cn(
                         'hover:bg-muted/50 border-t p-3 text-sm transition-colors',
-                        balance.balance === 0 && 'opacity-60'
+                        balance.balance === 0 &&
+                          !balance.isChild &&
+                          'opacity-60',
+                        balance.isChild &&
+                          'ml-4 border-l-2 border-l-blue-200 bg-blue-50/30'
                       )}
                     >
                       {/* Desktop Layout */}
                       <div className='hidden grid-cols-6 gap-2 md:grid'>
-                        <div className='max-w-32 truncate font-mono text-xs break-all'>
+                        <div className='flex max-w-48 items-center gap-2 truncate font-mono text-xs break-all'>
+                          {balance.isChild && (
+                            <span className='rounded bg-blue-100 px-1 py-0.5 text-[10px] font-bold text-blue-700 uppercase'>
+                              Child
+                            </span>
+                          )}
                           {balance.hashed_key}
                         </div>
                         <div className='text-right font-mono'>
-                          {formatBalance(balance.balance)}
+                          {balance.isChild ? (
+                            <span className='text-muted-foreground italic'>
+                              (Parent)
+                            </span>
+                          ) : (
+                            formatBalance(balance.balance)
+                          )}
                         </div>
                         <div className='text-right font-mono'>
                           {formatBalance(balance.total_spent)}
@@ -226,13 +273,20 @@ export function TemporaryBalances({
 
                       {/* Mobile Layout */}
                       <div className='space-y-3 md:hidden'>
-                        <div className='space-y-1'>
-                          <span className='text-muted-foreground text-xs font-medium'>
-                            Key
-                          </span>
-                          <div className='font-mono text-xs break-all'>
-                            {balance.hashed_key}
+                        <div className='flex items-center justify-between'>
+                          <div className='space-y-1'>
+                            <span className='text-muted-foreground text-xs font-medium'>
+                              {balance.isChild ? 'Child Key' : 'Key'}
+                            </span>
+                            <div className='font-mono text-xs break-all'>
+                              {balance.hashed_key}
+                            </div>
                           </div>
+                          {balance.isChild && (
+                            <span className='rounded bg-blue-100 px-1.5 py-0.5 text-[10px] font-bold text-blue-700 uppercase'>
+                              Child
+                            </span>
+                          )}
                         </div>
 
                         <div className='grid grid-cols-2 gap-3'>
@@ -241,7 +295,13 @@ export function TemporaryBalances({
                               Balance
                             </div>
                             <div className='truncate font-mono text-sm'>
-                              {formatBalance(balance.balance)}
+                              {balance.isChild ? (
+                                <span className='text-muted-foreground text-xs italic'>
+                                  (Uses Parent)
+                                </span>
+                              ) : (
+                                formatBalance(balance.balance)
+                              )}
                             </div>
                           </div>
                           <div className='space-y-1'>

ui/lib/api/services/admin.ts

@@ -926,6 +926,7 @@ export const TemporaryBalanceSchema = z.object({
   total_requests: z.number(),
   refund_address: z.string().nullable(),
   key_expiry_time: z.number().nullable(),
+  parent_key_hash: z.string().nullable().optional(),
 });
 
 export type TemporaryBalance = z.infer<typeof TemporaryBalanceSchema>;

ui/lib/api/services/wallet.ts

@@ -29,6 +29,28 @@ export type RedeemTokenResponse = z.infer<typeof RedeemTokenResponseSchema>;
 export type SendTokenRequest = z.infer<typeof SendTokenRequestSchema>;
 export type SendTokenResponse = z.infer<typeof SendTokenResponseSchema>;
 
+export interface BalanceDetail {
+  mint_url: string;
+  unit: string;
+  wallet_balance: number;
+  user_balance: number;
+  owner_balance: number;
+  error?: string;
+}
+
+export interface WithdrawResponse {
+  token: string;
+}
+
+export interface CreateChildKeyResponse {
+  api_keys: string[];
+  count: number;
+  cost_msats: number;
+  cost_sats: number;
+  parent_balance: number;
+  parent_balance_sats: number;
+}
+
 export class WalletService {
   static async redeemToken(token: string): Promise<RedeemTokenResponse> {
     try {
@@ -108,17 +130,84 @@ export class WalletService {
       throw error;
     }
   }
-}
 
-export interface BalanceDetail {
-  mint_url: string;
-  unit: string;
-  wallet_balance: number;
-  user_balance: number;
-  owner_balance: number;
-  error?: string;
-}
+  static async createChildKey(
+    baseUrl?: string,
+    apiKey?: string,
+    count: number = 1,
+    balanceLimit?: number,
+    balanceLimitReset?: string,
+    validityDate?: number
+  ): Promise<CreateChildKeyResponse> {
+    try {
+      if (baseUrl && apiKey) {
+        const response = await fetch(`${baseUrl}/v1/balance/child-key`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            count,
+            balance_limit: balanceLimit,
+            balance_limit_reset: balanceLimitReset,
+            validity_date: validityDate,
+          }),
+        });
 
-export interface WithdrawResponse {
-  token: string;
+        if (!response.ok) {
+          const errorText = await response.text();
+          throw new Error(errorText || 'Failed to create child key');
+        }
+
+        return (await response.json()) as CreateChildKeyResponse;
+      }
+
+      return await apiClient.post<CreateChildKeyResponse>(
+        '/v1/balance/child-key',
+        {
+          count,
+          balance_limit: balanceLimit,
+          balance_limit_reset: balanceLimitReset,
+          validity_date: validityDate,
+        }
+      );
+    } catch (error) {
+      console.error('Error creating child key:', error);
+      throw error;
+    }
+  }
+
+  static async resetChildKeySpent(
+    baseUrl: string | undefined,
+    parentKey: string,
+    childKey: string
+  ): Promise<{ success: boolean; message: string }> {
+    try {
+      const url = baseUrl
+        ? `${baseUrl}/v1/balance/child-key/reset`
+        : '/v1/balance/child-key/reset';
+
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${parentKey}`,
+      };
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ child_key: childKey }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(errorText || 'Failed to reset child key');
+      }
+
+      return await response.json();
+    } catch (error) {
+      console.error('Error resetting child key:', error);
+      throw error;
+    }
+  }
 }

uv.lock

@@ -1878,7 +1878,7 @@ wheels = [
 
 [[package]]
 name = "routstr"
-version = "0.2.2"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },