use correct field label

release v0.4.3

migrations/versions/02650cd6f028_add_routstr_fees_table.py

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

migrations/versions/d4e5f6a7b8c9_add_api_key_to_cashu_transactions.py

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

migrations/versions/e8f9a0b1c2d3_merge_heads.py

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

pyproject.toml

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

routstr/auth.py

@@ -12,7 +12,7 @@ from sqlalchemy.exc import IntegrityError
 from sqlmodel import col, select, update
 
 from .core import get_logger
-from .core.db import ApiKey, AsyncSession
+from .core.db import ApiKey, AsyncSession, accumulate_routstr_fee
 from .core.settings import settings
 from .payment.cost_calculation import (
     CostData,
@@ -25,6 +25,12 @@ from .wallet import credit_balance, deserialize_token_from_string
 logger = get_logger(__name__)
 payments_logger = get_logger("routstr.payments")
 
+# Routstr platform fee constants
+ROUTSTR_FEE_PERCENT: float = 2.1
+ROUTSTR_LN_ADDRESS: str = "npub130mznv74rxs032peqym6g3wqavh472623mt3z5w73xq9r6qqdufs7ql29s@npub.cash"
+ROUTSTR_FEE_PAYOUT_INTERVAL_SECONDS: int = 900
+ROUTSTR_FEE_DEFAULT_PAYOUT: int = 200
+
 # TODO: implement prepaid api key (not like it was before)
 # PREPAID_API_KEY = os.environ.get("PREPAID_API_KEY", None)
 # PREPAID_BALANCE = int(os.environ.get("PREPAID_BALANCE", "0")) * 1000  # Convert to msats
@@ -741,6 +747,17 @@ async def adjust_payment_for_tokens(
                 },
             )
 
+    async def _accumulate_fee(total_cost_msats: int) -> None:
+        if total_cost_msats > 0 and ROUTSTR_FEE_PERCENT > 0:
+            fee_msats = math.ceil(total_cost_msats * ROUTSTR_FEE_PERCENT / 100)
+            try:
+                await accumulate_routstr_fee(session, fee_msats)
+            except Exception as e:
+                logger.warning(
+                    "Failed to accumulate Routstr fee",
+                    extra={"error": str(e), "fee_msats": fee_msats},
+                )
+
     match await calculate_cost(response_data, deducted_max_cost, session):
         case MaxCostData() as cost:
             logger.debug(
@@ -832,6 +849,7 @@ async def adjust_payment_for_tokens(
                         "model": model,
                     },
                 )
+                await _accumulate_fee(cost.total_msats)
                 payments_logger.info(
                     "FINALIZE",
                     extra={
@@ -935,6 +953,7 @@ async def adjust_payment_for_tokens(
                 await session.refresh(billing_key)
                 if billing_key.hashed_key != key.hashed_key:
                     await session.refresh(key)
+                await _accumulate_fee(total_cost_msats)
                 payments_logger.info(
                     "FINALIZE",
                     extra={
@@ -1005,6 +1024,7 @@ async def adjust_payment_for_tokens(
                             "model": model,
                         },
                     )
+                    await _accumulate_fee(total_cost_msats)
                     payments_logger.info(
                         "FINALIZE",
                         extra={
@@ -1130,6 +1150,7 @@ async def adjust_payment_for_tokens(
                             "model": model,
                         },
                     )
+                    await _accumulate_fee(total_cost_msats)
                     payments_logger.info(
                         "FINALIZE",
                         extra={

routstr/balance.py

@@ -7,7 +7,7 @@ from typing import Annotated, NoReturn
 from fastapi import APIRouter, Depends, Header, HTTPException
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
-from sqlmodel import select
+from sqlmodel import col, select, update
 
 from .auth import get_billing_key, validate_bearer_key
 from .core.db import (
@@ -211,6 +211,26 @@ async def _refund_cache_set(authorization: str, value: dict[str, str]) -> None:
         _refund_cache[key] = (expiry, value)
 
 
+async def _restore_balance(
+    session: AsyncSession, hashed_key: str, balance: int, reserved_balance: int
+) -> None:
+    """Restore balance after a failed refund mint attempt."""
+    restore_stmt = (
+        update(ApiKey)
+        .where(col(ApiKey.hashed_key) == hashed_key)
+        .values(
+            balance=col(ApiKey.balance) + balance,
+            reserved_balance=col(ApiKey.reserved_balance) + reserved_balance,
+        )
+    )
+    await session.exec(restore_stmt)  # type: ignore[call-overload]
+    await session.commit()
+    logger.info(
+        "refund_wallet_endpoint: balance restored after mint failure",
+        extra={"hashed_key": hashed_key, "restored_balance": balance},
+    )
+
+
 @router.post("/refund", response_model=None)
 async def refund_wallet_endpoint(
     authorization: Annotated[str | None, Header()] = None,
@@ -292,7 +312,31 @@ async def refund_wallet_endpoint(
     elif remaining_balance <= 0:
         raise HTTPException(status_code=400, detail="No balance to refund")
 
-    # Perform refund operation first, before modifying balance
+    # Capture values before debit — the session may refresh key after commit
+    pre_debit_balance = key.balance
+    pre_debit_reserved = key.reserved_balance
+
+    # --- DEBIT FIRST: atomically zero the balance before minting tokens ---
+    # This prevents the race where a concurrent topup/spend happens between
+    # reading the balance and minting the refund token (double-spend).
+    debit_stmt = (
+        update(ApiKey)
+        .where(col(ApiKey.hashed_key) == key.hashed_key)
+        .where(col(ApiKey.balance) == pre_debit_balance)
+        .where(col(ApiKey.reserved_balance) == pre_debit_reserved)
+        .values(balance=0, reserved_balance=0)
+    )
+    debit_result = await session.exec(debit_stmt)  # type: ignore[call-overload]
+    await session.commit()
+
+    if debit_result.rowcount == 0:
+        # Balance changed between read and debit — another request is active
+        raise HTTPException(
+            status_code=409,
+            detail="Balance changed concurrently. Please retry the refund.",
+        )
+
+    # --- MINT: balance is locked at zero, safe to create the refund token ---
     try:
         if key.refund_address:
             from .core.settings import settings as global_settings
@@ -328,10 +372,12 @@ async def refund_wallet_endpoint(
             )
 
     except HTTPException:
-        # Re-raise HTTP exceptions (like 400 for balance too small)
+        # Minting failed — restore the debited balance
+        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved)
         raise
     except Exception as e:
-        # If refund fails, don't modify the database
+        # Minting failed — restore the debited balance
+        await _restore_balance(session, key.hashed_key, pre_debit_balance, pre_debit_reserved)
         error_msg = str(e)
         if (
             "mint" in error_msg.lower()
@@ -345,12 +391,6 @@ async def refund_wallet_endpoint(
 
     await _refund_cache_set(bearer_value, result)
 
-    previous_reserved_balance = key.reserved_balance
-    key.balance = 0
-    key.reserved_balance = 0
-    session.add(key)
-    await session.commit()
-
     if "token" in result:
         try:
             await store_cashu_transaction(
@@ -361,6 +401,7 @@ async def refund_wallet_endpoint(
                 typ="out",
                 collected=False,
                 source="apikey",
+                api_key_hashed_key=key.hashed_key,
             )
         except Exception:
             pass  # store_cashu_transaction already logs
@@ -369,13 +410,48 @@ async def refund_wallet_endpoint(
         "refund_wallet_endpoint: refund successful",
         extra={
             "refunded_msats": remaining_balance_msats,
-            "previous_reserved_balance": previous_reserved_balance,
+            "previous_reserved_balance": key.reserved_balance,
         },
     )
 
     return result
 
 
+@router.get("/history")
+async def wallet_history(
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict[str, list[dict[str, str | int | bool | None]]]:
+    if key.parent_key_hash:
+        raise HTTPException(
+            status_code=400,
+            detail="Cannot view child key history. Please use the parent key instead.",
+        )
+
+    result = await session.exec(
+        select(CashuTransaction)
+        .where(CashuTransaction.api_key_hashed_key == key.hashed_key)
+        .order_by(col(CashuTransaction.created_at).desc())
+    )
+    transactions = result.all()
+    return {
+        "transactions": [
+            {
+                "id": tx.id,
+                "type": tx.type,
+                "source": tx.source,
+                "amount": tx.amount,
+                "unit": tx.unit,
+                "mint_url": tx.mint_url,
+                "created_at": tx.created_at,
+                "collected": tx.collected,
+                "swept": tx.swept,
+            }
+            for tx in transactions
+        ]
+    }
+
+
 @router.post("/donate")
 async def donate(token: str, ref: str | None = None) -> str:
     try:

routstr/core/admin.py

@@ -1335,41 +1335,56 @@ async def get_transactions_api(
     type: str | None = None,
     status: str | None = None,
     search: str | None = None,
-    limit: int = 100,
+    source: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
 ) -> dict:
     async with create_session() as session:
-        from sqlmodel import col
+        from sqlmodel import col, func
 
-        stmt = select(CashuTransaction)
+        base = select(CashuTransaction)
         if type:
-            stmt = stmt.where(CashuTransaction.type == type)
+            base = base.where(CashuTransaction.type == type)
+        if source:
+            if source == "x-cashu":
+                base = base.where(
+                    (CashuTransaction.source == "x-cashu")
+                    | (CashuTransaction.source == None)  # noqa: E711
+                )
+            else:
+                base = base.where(CashuTransaction.source == source)
         if status:
             if status == "collected":
-                stmt = stmt.where(CashuTransaction.collected == True)  # noqa: E712
+                base = base.where(CashuTransaction.collected == True)  # noqa: E712
             elif status == "swept":
-                stmt = stmt.where(CashuTransaction.swept == True)  # noqa: E712
+                base = base.where(CashuTransaction.swept == True)  # noqa: E712
             elif status == "pending":
-                stmt = stmt.where(
+                base = base.where(
                     CashuTransaction.collected == False,  # noqa: E712
                     CashuTransaction.swept == False,  # noqa: E712
                 )
 
         if search:
             search_pattern = f"%{search}%"
-            stmt = stmt.where(
+            base = base.where(
                 (col(CashuTransaction.id).like(search_pattern))
                 | (col(CashuTransaction.token).like(search_pattern))
                 | (col(CashuTransaction.request_id).like(search_pattern))
+                | (col(CashuTransaction.api_key_hashed_key).like(search_pattern))
             )
 
-        stmt = stmt.order_by(col(CashuTransaction.created_at).desc()).limit(limit)
+        count_result = await session.exec(
+            select(func.count()).select_from(base.subquery())
+        )
+        total = count_result.one()
 
+        stmt = base.order_by(col(CashuTransaction.created_at).desc()).offset(offset).limit(limit)
         results = await session.exec(stmt)
         transactions = results.all()
 
         return {
             "transactions": [tx.dict() for tx in transactions],
-            "total": len(transactions),
+            "total": total,
         }
 
 

routstr/core/db.py

@@ -12,7 +12,7 @@ from alembic.util.exc import CommandError
 from sqlalchemy import UniqueConstraint
 from sqlalchemy.exc import OperationalError
 from sqlalchemy.ext.asyncio.engine import create_async_engine
-from sqlmodel import Field, Relationship, SQLModel, func, select, update
+from sqlmodel import Field, Relationship, SQLModel, col, func, select, update
 from sqlmodel.ext.asyncio.session import AsyncSession
 
 from .logging import get_logger
@@ -159,6 +159,12 @@ class CashuTransaction(SQLModel, table=True):  # type: ignore
         default="x-cashu",
         description="Payment source: x-cashu or apikey",
     )
+    api_key_hashed_key: str | None = Field(
+        default=None,
+        foreign_key="api_keys.hashed_key",
+        index=True,
+        description="Associated API key hash for wallet history",
+    )
 
 
 async def store_cashu_transaction(
@@ -171,6 +177,7 @@ async def store_cashu_transaction(
     collected: bool = False,
     created_at: int | None = None,
     source: str = "x-cashu",
+    api_key_hashed_key: str | None = None,
 ) -> None:
     try:
         async with create_session() as session:
@@ -184,6 +191,7 @@ async def store_cashu_transaction(
                 collected=collected,
                 created_at=created_at or int(time.time()),
                 source=source,
+                api_key_hashed_key=api_key_hashed_key,
             )
             session.add(tx)
             await session.commit()
@@ -223,6 +231,50 @@ class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
     )
 
 
+class RoutstrFee(SQLModel, table=True):  # type: ignore
+    __tablename__ = "routstr_fees"
+    id: int = Field(default=1, primary_key=True)
+    accumulated_msats: int = Field(default=0)
+    total_paid_msats: int = Field(default=0)
+    last_paid_at: int | None = Field(default=None)
+
+
+async def accumulate_routstr_fee(session: AsyncSession, amount_msats: int) -> None:
+    stmt = (
+        update(RoutstrFee)
+        .where(col(RoutstrFee.id) == 1)
+        .values(accumulated_msats=RoutstrFee.accumulated_msats + amount_msats)
+    )
+    result = await session.exec(stmt)  # type: ignore[call-overload]
+    if result.rowcount == 0:
+        session.add(RoutstrFee(id=1, accumulated_msats=amount_msats))
+    await session.commit()
+
+
+async def get_routstr_fee(session: AsyncSession) -> RoutstrFee:
+    fee = await session.get(RoutstrFee, 1)
+    if fee is None:
+        fee = RoutstrFee(id=1, accumulated_msats=0, total_paid_msats=0)
+        session.add(fee)
+        await session.commit()
+        await session.refresh(fee)
+    return fee
+
+
+async def reset_routstr_fee(session: AsyncSession, paid_msats: int) -> None:
+    stmt = (
+        update(RoutstrFee)
+        .where(col(RoutstrFee.id) == 1)
+        .values(
+            accumulated_msats=RoutstrFee.accumulated_msats - paid_msats,
+            total_paid_msats=RoutstrFee.total_paid_msats + paid_msats,
+            last_paid_at=int(time.time()),
+        )
+    )
+    await session.exec(stmt)  # type: ignore[call-overload]
+    await session.commit()
+
+
 async def balances_for_mint_and_unit(
     db_session: AsyncSession, mint_url: str, unit: str
 ) -> int:

routstr/core/main.py

@@ -22,7 +22,7 @@ from ..payment.models import models_router, update_sats_pricing
 from ..payment.price import update_prices_periodically
 from ..proxy import initialize_upstreams, proxy_router, refresh_model_maps_periodically
 from ..upstream.auto_topup import periodic_auto_topup
-from ..wallet import periodic_payout, periodic_refund_sweep
+from ..wallet import periodic_payout, periodic_refund_sweep, periodic_routstr_fee_payout
 from .admin import admin_router
 from .db import create_session, init_db, run_migrations
 from .exceptions import general_exception_handler, http_exception_handler
@@ -36,9 +36,9 @@ setup_logging()
 logger = get_logger(__name__)
 
 if os.getenv("VERSION_SUFFIX") is not None:
-    __version__ = f"0.4.1-{os.getenv('VERSION_SUFFIX')}"
+    __version__ = f"0.4.3-{os.getenv('VERSION_SUFFIX')}"
 else:
-    __version__ = "0.4.1"
+    __version__ = "0.4.3"
 
 
 @asynccontextmanager
@@ -56,6 +56,7 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
     key_reset_task = None
     auto_topup_task = None
     refund_sweep_task = None
+    routstr_fee_task = None
 
     try:
         # Run database migrations on startup
@@ -115,6 +116,7 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
         key_reset_task = asyncio.create_task(periodic_key_reset())
         auto_topup_task = asyncio.create_task(periodic_auto_topup())
         refund_sweep_task = asyncio.create_task(periodic_refund_sweep())
+        routstr_fee_task = asyncio.create_task(periodic_routstr_fee_payout())
 
         yield
 
@@ -152,6 +154,8 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
             auto_topup_task.cancel()
         if refund_sweep_task is not None:
             refund_sweep_task.cancel()
+        if routstr_fee_task is not None:
+            routstr_fee_task.cancel()
 
         try:
             tasks_to_wait = []
@@ -177,6 +181,8 @@ async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
                 tasks_to_wait.append(auto_topup_task)
             if refund_sweep_task is not None:
                 tasks_to_wait.append(refund_sweep_task)
+            if routstr_fee_task is not None:
+                tasks_to_wait.append(routstr_fee_task)
 
             if tasks_to_wait:
                 await asyncio.gather(*tasks_to_wait, return_exceptions=True)

routstr/upstream/base.py

@@ -421,75 +421,83 @@ class BaseUpstreamProvider:
         """
         pass
 
-    async def map_upstream_error_response(
+    async def forward_upstream_error_response(
         self, request: Request, path: str, upstream_response: httpx.Response
     ) -> Response:
-        """Map upstream error responses to appropriate proxy error responses.
-
-        Args:
-            request: Original FastAPI request
-            path: Request path
-            upstream_response: Response from upstream service
-
-        Returns:
-            Mapped error response with appropriate status code and error type
-        """
+        """Log upstream errors and forward the upstream response unchanged."""
         status_code = upstream_response.status_code
         headers = dict(upstream_response.headers)
-        content_type = headers.get("content-type", "")
+        content_type = headers.get("content-type") or headers.get("Content-Type", "")
+        upstream_request_id = (
+            headers.get("request-id")
+            or headers.get("Request-Id")
+            or headers.get("x-request-id")
+            or headers.get("X-Request-Id")
+            or headers.get("anthropic-request-id")
+            or headers.get("openai-request-id")
+        )
+
+        body_read_error = None
         try:
             body_bytes = await upstream_response.aread()
-        except Exception:
+        except Exception as exc:
             body_bytes = b""
+            body_read_error = f"{type(exc).__name__}: {exc}"
 
         message, upstream_code = self._extract_upstream_error_message(body_bytes)
-        lowered_message = message.lower()
-        lowered_code = (upstream_code or "").lower()
+        body_preview = body_bytes.decode("utf-8", errors="ignore").strip()[:500]
 
-        error_type = "upstream_error"
-        mapped_status = 502
-
-        if status_code in (400, 422):
-            error_type = "invalid_request_error"
-            mapped_status = 400
-        elif status_code in (401, 403):
-            error_type = "upstream_auth_error"
-            mapped_status = 502
-        elif status_code == 404:
-            if path.endswith("chat/completions"):
-                error_type = "invalid_model"
-                mapped_status = 400
-                if not message or message == "Upstream request failed":
-                    message = "Requested model is not available upstream"
-            elif "model" in lowered_message or "model" in lowered_code:
-                error_type = "invalid_model"
-                mapped_status = 400
-                if not message or message == "Upstream request failed":
-                    message = "Requested model is not available upstream"
-            else:
-                error_type = "upstream_error"
-                mapped_status = 502
-        elif status_code == 429:
-            error_type = "rate_limit_exceeded"
-            mapped_status = 429
-        elif status_code >= 500:
-            error_type = "upstream_error"
-            mapped_status = 502
-
-        logger.debug(
-            "Mapped upstream error",
+        logger.warning(
+            "Forwarding upstream error response as-is",
             extra={
                 "path": path,
+                "provider": self.provider_type,
                 "upstream_status": status_code,
-                "mapped_status": mapped_status,
-                "error_type": error_type,
+                "upstream_code": upstream_code,
                 "upstream_content_type": content_type,
+                "upstream_request_id": upstream_request_id,
                 "message_preview": message[:200],
+                "body_preview": body_preview,
+                "body_read_error": body_read_error,
+                "method": request.method,
             },
         )
 
-        return create_error_response(
-            error_type, message, mapped_status, request=request
+        for header_name in (
+            "content-length",
+            "Content-Length",
+            "transfer-encoding",
+            "Transfer-Encoding",
+            "content-encoding",
+            "Content-Encoding",
+            "connection",
+            "Connection",
+            "keep-alive",
+            "Keep-Alive",
+            "proxy-authenticate",
+            "Proxy-Authenticate",
+            "proxy-authorization",
+            "Proxy-Authorization",
+            "te",
+            "TE",
+            "trailer",
+            "Trailer",
+            "upgrade",
+            "Upgrade",
+        ):
+            headers.pop(header_name, None)
+
+        if not content_type:
+            headers.pop("content-type", None)
+            headers.pop("Content-Type", None)
+
+        media_type = content_type or None
+
+        return Response(
+            content=body_bytes,
+            status_code=status_code,
+            headers=headers,
+            media_type=media_type,
         )
 
     async def handle_streaming_chat_completion(
@@ -1467,15 +1475,28 @@ class BaseUpstreamProvider:
                     stream=True,
                 )
 
-            logger.info(
-                "Received upstream response",
-                extra={
-                    "status_code": response.status_code,
-                    "path": path,
-                    "key_hash": key.hashed_key[:8] + "...",
-                    "content_type": response.headers.get("content-type", "unknown"),
-                },
-            )
+            if response.status_code != 200:
+                logger.error(
+                    "Received upstream response",
+                    extra={
+                        "reason_phrase": response.reason_phrase,
+                        "status_code": response.status_code,
+                        "path": path,
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "content_type": response.headers.get("content-type", "unknown"),
+                    },
+                )
+            else:
+                logger.info(
+                    "Received upstream response",
+                    extra={
+                        "reason_phrase": response.reason_phrase,
+                        "status_code": response.status_code,
+                        "path": path,
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "content_type": response.headers.get("content-type", "unknown"),
+                    },
+                )
 
             if response.status_code != 200:
                 if response.status_code >= 500:
@@ -1487,7 +1508,7 @@ class BaseUpstreamProvider:
                     )
 
                 try:
-                    mapped_error = await self.map_upstream_error_response(
+                    mapped_error = await self.forward_upstream_error_response(
                         request, path, response
                     )
                 finally:
@@ -1794,7 +1815,7 @@ class BaseUpstreamProvider:
                     )
 
                 try:
-                    mapped_error = await self.map_upstream_error_response(
+                    mapped_error = await self.forward_upstream_error_response(
                         request, path, response
                     )
                 finally:
@@ -1966,7 +1987,7 @@ class BaseUpstreamProvider:
                 )
                 if response.status_code != 200:
                     try:
-                        mapped = await self.map_upstream_error_response(
+                        mapped = await self.forward_upstream_error_response(
                             request, path, response
                         )
                     finally:
@@ -2620,14 +2641,25 @@ class BaseUpstreamProvider:
                     stream=True,
                 )
 
-                logger.debug(
-                    "Received upstream response",
-                    extra={
-                        "status_code": response.status_code,
-                        "path": path,
-                        "response_headers": dict(response.headers),
-                    },
-                )
+                if response.status_code != 200:
+                    logger.error(
+                        "Received upstream response",
+                        extra={
+                            "reason_phrase": response.reason_phrase,
+                            "status_code": response.status_code,
+                            "path": path,
+                            "response_headers": dict(response.headers),
+                        },
+                    )
+                else:
+                    logger.debug(
+                        "Received upstream response",
+                        extra={
+                            "status_code": response.status_code,
+                            "path": path,
+                            "response_headers": dict(response.headers),
+                        },
+                    )
 
                 if response.status_code != 200:
                     logger.warning(

routstr/wallet.py

@@ -8,6 +8,7 @@ from cashu.wallet.wallet import Wallet
 from sqlmodel import col, select, update
 
 from .core import db, get_logger
+from .core.db import store_cashu_transaction
 from .core.settings import settings
 from .payment.lnurl import raw_send_to_lnurl
 
@@ -279,6 +280,8 @@ async def credit_balance(
 
     try:
         amount, unit, mint_url = await recieve_token(cashu_token)
+        original_amount = amount
+        original_unit = unit
         logger.info(
             "credit_balance: Token redeemed successfully",
             extra={"amount": amount, "unit": unit, "mint_url": mint_url},
@@ -310,6 +313,19 @@ async def credit_balance(
             extra={"new_balance": key.balance},
         )
 
+        try:
+            await store_cashu_transaction(
+                token=cashu_token,
+                amount=original_amount,
+                unit=original_unit,
+                mint_url=mint_url,
+                typ="in",
+                source="apikey",
+                api_key_hashed_key=key.hashed_key,
+            )
+        except Exception:
+            pass
+
         logger.info(
             "Cashu token successfully redeemed and stored",
             extra={"amount": amount, "unit": unit, "mint_url": mint_url},
@@ -573,6 +589,46 @@ async def periodic_refund_sweep() -> None:
             )
 
 
+async def periodic_routstr_fee_payout() -> None:
+    from .auth import (
+        ROUTSTR_FEE_DEFAULT_PAYOUT,
+        ROUTSTR_FEE_PAYOUT_INTERVAL_SECONDS,
+        ROUTSTR_LN_ADDRESS,
+    )
+
+    if not ROUTSTR_LN_ADDRESS:
+        logger.info("ROUTSTR_LN_ADDRESS not set, skipping fee payout")
+        return
+    while True:
+        await asyncio.sleep(ROUTSTR_FEE_PAYOUT_INTERVAL_SECONDS)
+        try:
+            async with db.create_session() as session:
+                fee = await db.get_routstr_fee(session)
+                accumulated_sats = fee.accumulated_msats // 1000
+                if accumulated_sats >= ROUTSTR_FEE_DEFAULT_PAYOUT:
+                    wallet = await get_wallet(settings.primary_mint, "sat")
+                    proofs = get_proofs_per_mint_and_unit(
+                        wallet, settings.primary_mint, "sat", not_reserved=True
+                    )
+                    amount_received = await raw_send_to_lnurl(
+                        wallet, proofs, ROUTSTR_LN_ADDRESS, "sat", amount=accumulated_sats
+                    )
+                    paid_msats = accumulated_sats * 1000
+                    await db.reset_routstr_fee(session, paid_msats)
+                    logger.info(
+                        "Routstr fee payout sent",
+                        extra={
+                            "accumulated_sats": accumulated_sats,
+                            "amount_received": amount_received,
+                        },
+                    )
+        except Exception as e:
+            logger.error(
+                f"Error in Routstr fee payout: {type(e).__name__}",
+                extra={"error": str(e)},
+            )
+
+
 async def send_to_lnurl(amount: int, unit: str, mint: str, address: str) -> int:
     wallet = await get_wallet(mint, unit)
     proofs = wallet._get_proofs_per_keyset(wallet.proofs)[wallet.keyset_id]

tests/integration/test_wallet_refund.py

@@ -13,7 +13,7 @@ import pytest
 from httpx import AsyncClient
 from sqlmodel import select
 
-from routstr.core.db import ApiKey
+from routstr.core.db import ApiKey, CashuTransaction
 
 
 @pytest.mark.integration
@@ -356,6 +356,70 @@ async def test_concurrent_refund_requests(
     assert len(successful) + len(failed) == 5
 
 
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_refund_rejects_concurrent_topup_on_same_key(
+    authenticated_client: AsyncClient,
+    testmint_wallet: Any,
+) -> None:
+    """Test refund returns 409 when a concurrent topup changes the balance first."""
+    from routstr import balance as balance_module
+
+    wallet_response = await authenticated_client.get("/v1/wallet/")
+    assert wallet_response.status_code == 200
+    initial_balance = wallet_response.json()["balance"]
+
+    topup_amount_sat = 500
+    topup_token = await testmint_wallet.mint_tokens(topup_amount_sat)
+
+    validate_called = asyncio.Event()
+    allow_refund_to_continue = asyncio.Event()
+    original_validate_bearer_key = balance_module.validate_bearer_key
+    delayed_once = False
+
+    async def delayed_validate_bearer_key(*args: Any, **kwargs: Any) -> ApiKey:
+        nonlocal delayed_once
+        key = await original_validate_bearer_key(*args, **kwargs)
+        if not delayed_once:
+            delayed_once = True
+            validate_called.set()
+            await allow_refund_to_continue.wait()
+        return key
+
+    async def issue_refund() -> Any:
+        return await authenticated_client.post("/v1/wallet/refund")
+
+    async def issue_topup() -> Any:
+        await validate_called.wait()
+        try:
+            return await authenticated_client.post(
+                "/v1/wallet/topup", params={"cashu_token": topup_token}
+            )
+        finally:
+            allow_refund_to_continue.set()
+
+    with patch(
+        "routstr.balance.validate_bearer_key", new=delayed_validate_bearer_key
+    ):
+        refund_response, topup_response = await asyncio.gather(
+            issue_refund(), issue_topup()
+        )
+
+    assert topup_response.status_code == 200
+    assert topup_response.json()["msats"] == topup_amount_sat * 1000
+    assert refund_response.status_code == 409
+    assert (
+        refund_response.json()["detail"]
+        == "Balance changed concurrently. Please retry the refund."
+    )
+
+    final_balance_response = await authenticated_client.get("/v1/wallet/")
+    assert final_balance_response.status_code == 200
+    assert final_balance_response.json()["balance"] == (
+        initial_balance + topup_amount_sat * 1000
+    )
+
+
 @pytest.mark.integration
 @pytest.mark.asyncio
 async def test_refund_during_active_usage(
@@ -394,6 +458,42 @@ async def test_refund_during_active_usage(
     assert response.json()["balance"] == 0
 
 
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_wallet_history_returns_apikey_transactions(
+    authenticated_client: AsyncClient,
+    testmint_wallet: Any,
+    integration_session: Any,
+) -> None:
+    wallet_response = await authenticated_client.get("/v1/wallet/")
+    api_key = wallet_response.json()["api_key"]
+    hashed_key = api_key[3:] if api_key.startswith("sk-") else api_key
+
+    topup_token = await testmint_wallet.mint_tokens(250)
+    topup_response = await authenticated_client.post(
+        "/v1/wallet/topup", params={"cashu_token": topup_token}
+    )
+    assert topup_response.status_code == 200
+
+    refund_response = await authenticated_client.post("/v1/wallet/refund")
+    assert refund_response.status_code == 200
+
+    history_response = await authenticated_client.get("/v1/wallet/history")
+    assert history_response.status_code == 200
+    transactions = history_response.json()["transactions"]
+    assert len(transactions) >= 2
+    assert all("api_key_hashed_key" not in tx for tx in transactions)
+    assert {tx["type"] for tx in transactions} >= {"in", "out"}
+
+    db_result = await integration_session.execute(
+        select(CashuTransaction).where(
+            CashuTransaction.api_key_hashed_key == hashed_key
+        )
+    )
+    db_transactions = db_result.scalars().all()
+    assert len(db_transactions) >= 2
+
+
 @pytest.mark.integration
 @pytest.mark.asyncio
 async def test_mint_unavailability_handling(

tests/integration/test_wallet_topup.py

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

tests/unit/test_balance.py

@@ -6,6 +6,7 @@ from fastapi.responses import JSONResponse
 
 from routstr.balance import refund_wallet_endpoint
 from routstr.core.db import ApiKey, CashuTransaction
+from routstr.wallet import credit_balance
 
 
 def _make_cashu_tx(
@@ -29,6 +30,12 @@ def _exec_result(tx: CashuTransaction | None) -> MagicMock:
     return result
 
 
+def _update_result(rowcount: int) -> MagicMock:
+    result = MagicMock()
+    result.rowcount = rowcount
+    return result
+
+
 @pytest.mark.asyncio
 async def test_refund_x_cashu_returns_token() -> None:
     x_cashu_token = "cashuAtest_token_value"
@@ -161,6 +168,7 @@ async def test_apikey_refund_stores_cashu_transaction_with_apikey_source() -> No
     refund_token = "cashuArefund_apikey_token"
 
     session = MagicMock()
+    session.exec = AsyncMock(return_value=_update_result(1))
     session.add = MagicMock()
     session.commit = AsyncMock()
 
@@ -186,6 +194,7 @@ async def test_apikey_refund_stores_cashu_transaction_with_apikey_source() -> No
     assert call_kwargs["source"] == "apikey"
     assert call_kwargs["token"] == refund_token
     assert call_kwargs["typ"] == "out"
+    assert call_kwargs["api_key_hashed_key"] == key.hashed_key
 
 
 @pytest.mark.asyncio
@@ -194,6 +203,7 @@ async def test_apikey_refund_logs_token() -> None:
     refund_token = "cashuAlogged_token"
 
     session = MagicMock()
+    session.exec = AsyncMock(return_value=_update_result(1))
     session.add = MagicMock()
     session.commit = AsyncMock()
 
@@ -222,6 +232,7 @@ async def test_apikey_refund_log_includes_path() -> None:
     refund_token = "cashuApath_token"
 
     session = MagicMock()
+    session.exec = AsyncMock(return_value=_update_result(1))
     session.add = MagicMock()
     session.commit = AsyncMock()
 
@@ -248,3 +259,99 @@ async def test_apikey_refund_log_includes_path() -> None:
     assert len(token_issued_calls) == 1
     extra = token_issued_calls[0].kwargs.get("extra", {})
     assert extra.get("path") == "/v1/wallet/refund"
+
+
+@pytest.mark.asyncio
+async def test_apikey_refund_rejects_on_concurrent_balance_change() -> None:
+    """When the debit CAS fails (rowcount=0), no token is minted and 409 is returned."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=5000, refund_currency="sat")
+
+    session = MagicMock()
+    # Debit returns rowcount=0 → balance changed concurrently
+    session.exec = AsyncMock(return_value=_update_result(0))
+    session.commit = AsyncMock()
+
+    mock_send_token = AsyncMock(return_value="cashuAshould_not_be_minted")
+
+    with (
+        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.send_token", mock_send_token),
+        patch("routstr.balance.store_cashu_transaction", AsyncMock()),
+        patch("routstr.balance._refund_cache_get", AsyncMock(return_value=None)),
+        patch("routstr.balance._refund_cache_set", AsyncMock()),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await refund_wallet_endpoint(
+                authorization="Bearer sk-testhash",
+                x_cashu=None,
+                session=session,
+            )
+
+    assert exc_info.value.status_code == 409
+    # Crucially: send_token must NOT have been called
+    mock_send_token.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_credit_balance_stores_apikey_transaction_history() -> None:
+    key = _make_api_key(balance=1000)
+    session = MagicMock()
+    session.exec = AsyncMock(return_value=_update_result(1))
+    session.commit = AsyncMock()
+    session.refresh = AsyncMock()
+
+    with (
+        patch(
+            "routstr.wallet.recieve_token",
+            AsyncMock(return_value=(100, "sat", "https://mint.example")),
+        ),
+        patch("routstr.wallet.store_cashu_transaction", AsyncMock()) as mock_store,
+    ):
+        amount = await credit_balance("cashuAtopup_token", key, session)
+
+    assert amount == 100_000
+    mock_store.assert_awaited_once()
+    call_kwargs = mock_store.call_args.kwargs
+    assert call_kwargs["typ"] == "in"
+    assert call_kwargs["source"] == "apikey"
+    assert call_kwargs["api_key_hashed_key"] == key.hashed_key
+    assert call_kwargs["amount"] == 100
+    assert call_kwargs["unit"] == "sat"
+    assert call_kwargs["token"] == "cashuAtopup_token"
+    assert call_kwargs["mint_url"] == "https://mint.example"
+
+
+@pytest.mark.asyncio
+async def test_apikey_refund_restores_balance_on_mint_failure() -> None:
+    """When debit succeeds but minting fails, balance must be restored."""
+    from fastapi import HTTPException
+
+    key = _make_api_key(balance=5000, refund_currency="sat")
+
+    # First exec call = debit (succeeds), second = restore
+    session = MagicMock()
+    session.exec = AsyncMock(side_effect=[_update_result(1), _update_result(1)])
+    session.commit = AsyncMock()
+
+    with (
+        patch("routstr.balance.validate_bearer_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.get_billing_key", AsyncMock(return_value=key)),
+        patch("routstr.balance.send_token", AsyncMock(side_effect=Exception("mint down"))),
+        patch("routstr.balance.store_cashu_transaction", AsyncMock()),
+        patch("routstr.balance._refund_cache_get", AsyncMock(return_value=None)),
+        patch("routstr.balance._refund_cache_set", AsyncMock()),
+        patch("routstr.balance.logger"),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await refund_wallet_endpoint(
+                authorization="Bearer sk-testhash",
+                x_cashu=None,
+                session=session,
+            )
+
+    assert exc_info.value.status_code == 503
+    # Verify two exec calls: debit + restore
+    assert session.exec.await_count == 2

ui/app/transactions/page.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useState, useEffect } from 'react';
-import { useQuery } from '@tanstack/react-query';
+import { useQuery, keepPreviousData } from '@tanstack/react-query';
 import { AppPageShell } from '@/components/app-page-shell';
 import { PageHeader } from '@/components/page-header';
 import {
@@ -31,7 +31,7 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
-import { ScrollArea } from '@/components/ui/scroll-area';
+import { ScrollArea, ScrollBar } from '@/components/ui/scroll-area';
 import { Skeleton } from '@/components/ui/skeleton';
 import {
   Empty,
@@ -50,6 +50,8 @@ import {
   Receipt,
   Key,
   Zap,
+  ChevronLeft,
+  ChevronRight,
 } from 'lucide-react';
 import { AdminService, type Transaction } from '@/lib/api/services/admin';
 import { format } from 'date-fns';
@@ -86,85 +88,114 @@ function TransactionTable({
 
   return (
     <ScrollArea className='h-[55svh] min-h-[420px] w-full sm:h-[600px]'>
-      <Table>
-        <TableHeader>
-          <TableRow>
-            <TableHead>Type</TableHead>
-            <TableHead>Amount</TableHead>
-            <TableHead>Status</TableHead>
-            <TableHead>Request ID</TableHead>
-            <TableHead>Mint</TableHead>
-            <TableHead>Date</TableHead>
-            <TableHead className='text-right'>Actions</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          {transactions.map((tx) => (
-            <TableRow key={tx.id}>
-              <TableCell>
-                <div className='flex items-center gap-2'>
-                  {tx.type === 'in' ? (
-                    <ArrowDownLeft className='h-4 w-4 text-green-500' />
-                  ) : (
-                    <ArrowUpRight className='h-4 w-4 text-blue-500' />
-                  )}
-                  <span className='capitalize'>{tx.type}</span>
-                </div>
-              </TableCell>
-              <TableCell className='font-mono'>
-                {tx.amount} {tx.unit}
-              </TableCell>
-              <TableCell>{getStatusBadge(tx)}</TableCell>
-              <TableCell>
-                {tx.request_id ? (
-                  <div className='flex items-center gap-1 text-xs'>
-                    <span className='max-w-[150px] truncate font-mono'>
-                      {tx.request_id}
-                    </span>
-                    <Button
-                      variant='ghost'
-                      size='icon'
-                      className='h-4 w-4'
-                      onClick={() => onCopy(tx.request_id!, tx.id + '-req')}
-                    >
-                      {copiedId === tx.id + '-req' ? (
-                        <Check className='h-3 w-3' />
-                      ) : (
-                        <Copy className='h-3 w-3' />
-                      )}
-                    </Button>
-                  </div>
-                ) : (
-                  <span className='text-muted-foreground text-xs'>—</span>
-                )}
-              </TableCell>
-              <TableCell>
-                <div className='flex max-w-[150px] items-center gap-1 truncate text-xs'>
-                  <span className='truncate'>{tx.mint_url}</span>
-                </div>
-              </TableCell>
-              <TableCell className='text-xs whitespace-nowrap'>
-                {format(tx.created_at * 1000, 'yyyy-MM-dd HH:mm:ss')}
-              </TableCell>
-              <TableCell className='text-right'>
-                <Button
-                  variant='ghost'
-                  size='icon'
-                  className='h-8 w-8'
-                  onClick={() => onCopy(tx.token, tx.id + '-token')}
-                  title='Copy Token'
-                >
-                  {copiedId === tx.id + '-token' ? (
-                    <Check className='h-4 w-4' />
-                  ) : (
-                    <Copy className='h-4 w-4' />
-                  )}
-                </Button>
-              </TableCell>
+      <div className='min-w-[800px]'>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Type</TableHead>
+              <TableHead>Amount</TableHead>
+              <TableHead>Status</TableHead>
+              <TableHead>API Key</TableHead>
+              <TableHead>Request ID</TableHead>
+              <TableHead>Mint</TableHead>
+              <TableHead>Date</TableHead>
+              <TableHead className='text-right'>Actions</TableHead>
             </TableRow>
-          ))}
-        </TableBody>
-      </Table>
+          </TableHeader>
+          <TableBody>
+            {transactions.map((tx) => (
+              <TableRow key={tx.id}>
+                <TableCell>
+                  <div className='flex items-center gap-2'>
+                    {tx.type === 'in' ? (
+                      <ArrowDownLeft className='h-4 w-4 text-green-500' />
+                    ) : (
+                      <ArrowUpRight className='h-4 w-4 text-blue-500' />
+                    )}
+                    <span className='capitalize'>{tx.type}</span>
+                  </div>
+                </TableCell>
+                <TableCell className='font-mono'>
+                  {tx.amount} {tx.unit}
+                </TableCell>
+                <TableCell>{getStatusBadge(tx)}</TableCell>
+                <TableCell>
+                  {tx.api_key_hashed_key ? (
+                    <div className='flex items-center gap-1 text-xs'>
+                      <span className='max-w-[120px] truncate font-mono'>
+                        {tx.api_key_hashed_key.slice(0, 12)}...
+                      </span>
+                      <Button
+                        variant='ghost'
+                        size='icon'
+                        className='h-4 w-4'
+                        onClick={() =>
+                          onCopy(tx.api_key_hashed_key!, tx.id + '-apikey')
+                        }
+                      >
+                        {copiedId === tx.id + '-apikey' ? (
+                          <Check className='h-3 w-3' />
+                        ) : (
+                          <Copy className='h-3 w-3' />
+                        )}
+                      </Button>
+                    </div>
+                  ) : (
+                    <span className='text-muted-foreground text-xs'>—</span>
+                  )}
+                </TableCell>
+                <TableCell>
+                  {tx.request_id ? (
+                    <div className='flex items-center gap-1 text-xs'>
+                      <span className='max-w-[150px] truncate font-mono'>
+                        {tx.request_id}
+                      </span>
+                      <Button
+                        variant='ghost'
+                        size='icon'
+                        className='h-4 w-4'
+                        onClick={() => onCopy(tx.request_id!, tx.id + '-req')}
+                      >
+                        {copiedId === tx.id + '-req' ? (
+                          <Check className='h-3 w-3' />
+                        ) : (
+                          <Copy className='h-3 w-3' />
+                        )}
+                      </Button>
+                    </div>
+                  ) : (
+                    <span className='text-muted-foreground text-xs'>—</span>
+                  )}
+                </TableCell>
+                <TableCell>
+                  <div className='flex max-w-[150px] items-center gap-1 truncate text-xs'>
+                    <span className='truncate'>{tx.mint_url}</span>
+                  </div>
+                </TableCell>
+                <TableCell className='text-xs whitespace-nowrap'>
+                  {format(tx.created_at * 1000, 'yyyy-MM-dd HH:mm:ss')}
+                </TableCell>
+                <TableCell className='text-right'>
+                  <Button
+                    variant='ghost'
+                    size='icon'
+                    className='h-8 w-8'
+                    onClick={() => onCopy(tx.token, tx.id + '-token')}
+                    title='Copy Token'
+                  >
+                    {copiedId === tx.id + '-token' ? (
+                      <Check className='h-4 w-4' />
+                    ) : (
+                      <Copy className='h-4 w-4' />
+                    )}
+                  </Button>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+      <ScrollBar orientation='horizontal' />
     </ScrollArea>
   );
 }
@@ -196,21 +227,63 @@ export default function TransactionsPage() {
     localStorage.setItem(STORAGE_KEY, JSON.stringify(filters));
   }, [search, type, status]);
 
-  const { data, isLoading, refetch, isRefetching } = useQuery({
-    queryKey: ['transactions', type, status, search],
+  const PAGE_SIZE = 50;
+  const [activeTab, setActiveTab] = useState<string>('x-cashu');
+  const [xcashuPage, setXcashuPage] = useState(0);
+  const [apikeyPage, setApikeyPage] = useState(0);
+
+  const typeParam = type === 'all' ? undefined : type;
+  const statusParam = status === 'all' ? undefined : status;
+  const searchParam = search || undefined;
+
+  const xcashuQuery = useQuery({
+    queryKey: [
+      'transactions',
+      'x-cashu',
+      typeParam,
+      statusParam,
+      searchParam,
+      xcashuPage,
+    ],
     queryFn: () =>
       AdminService.getTransactions(
-        type === 'all' ? undefined : type,
-        status === 'all' ? undefined : status,
-        search || undefined,
-        100
+        typeParam,
+        statusParam,
+        searchParam,
+        'x-cashu',
+        PAGE_SIZE,
+        xcashuPage * PAGE_SIZE
       ),
+    placeholderData: keepPreviousData,
+  });
+
+  const apikeyQuery = useQuery({
+    queryKey: [
+      'transactions',
+      'apikey',
+      typeParam,
+      statusParam,
+      searchParam,
+      apikeyPage,
+    ],
+    queryFn: () =>
+      AdminService.getTransactions(
+        typeParam,
+        statusParam,
+        searchParam,
+        'apikey',
+        PAGE_SIZE,
+        apikeyPage * PAGE_SIZE
+      ),
+    placeholderData: keepPreviousData,
   });
 
   const handleClearFilters = () => {
     setSearch('');
     setType('all');
     setStatus('all');
+    setXcashuPage(0);
+    setApikeyPage(0);
   };
 
   const copyToClipboard = (text: string, id: string) => {
@@ -260,14 +333,20 @@ export default function TransactionsPage() {
     .filter(Boolean)
     .join(' • ');
 
-  const xcashuTxs =
-    data?.transactions.filter((tx) => !tx.source || tx.source === 'x-cashu') ??
-    [];
-  const apikeyTxs =
-    data?.transactions.filter((tx) => tx.source === 'apikey') ?? [];
+  // Reset pages when filters change
+  useEffect(() => {
+    setXcashuPage(0);
+    setApikeyPage(0);
+  }, [type, status, search]);
 
-  const renderCardContent = (txs: Transaction[]) => {
-    if (isLoading) {
+  const isRefetching = xcashuQuery.isRefetching || apikeyQuery.isRefetching;
+
+  const renderCardContent = (
+    query: typeof xcashuQuery,
+    page: number,
+    setPage: (p: number) => void
+  ) => {
+    if (query.isLoading) {
       return (
         <div className='space-y-2'>
           {Array.from({ length: 8 }).map((_, index) => (
@@ -279,13 +358,51 @@ export default function TransactionsPage() {
         </div>
       );
     }
+
+    const transactions = query.data?.transactions ?? [];
+    const total = query.data?.total ?? 0;
+    const totalPages = Math.ceil(total / PAGE_SIZE);
+
     return (
-      <TransactionTable
-        transactions={txs}
-        copiedId={copiedId}
-        onCopy={copyToClipboard}
-        getStatusBadge={getStatusBadge}
-      />
+      <>
+        {totalPages > 1 && (
+          <div className='flex flex-col gap-2 border-b pb-3 sm:flex-row sm:items-center sm:justify-between'>
+            <span className='text-muted-foreground text-xs sm:text-sm'>
+              {page * PAGE_SIZE + 1}–{Math.min((page + 1) * PAGE_SIZE, total)}{' '}
+              of {total}
+            </span>
+            <div className='flex items-center gap-2'>
+              <Button
+                variant='outline'
+                size='sm'
+                disabled={page === 0}
+                onClick={() => setPage(page - 1)}
+              >
+                <ChevronLeft className='h-4 w-4' />
+                <span className='hidden sm:inline'>Previous</span>
+              </Button>
+              <span className='text-xs sm:text-sm'>
+                {page + 1} / {totalPages}
+              </span>
+              <Button
+                variant='outline'
+                size='sm'
+                disabled={page >= totalPages - 1}
+                onClick={() => setPage(page + 1)}
+              >
+                <span className='hidden sm:inline'>Next</span>
+                <ChevronRight className='h-4 w-4' />
+              </Button>
+            </div>
+          </div>
+        )}
+        <TransactionTable
+          transactions={transactions}
+          copiedId={copiedId}
+          onCopy={copyToClipboard}
+          getStatusBadge={getStatusBadge}
+        />
+      </>
     );
   };
 
@@ -297,7 +414,10 @@ export default function TransactionsPage() {
           description='View all incoming and outgoing Cashu token transactions.'
           actions={
             <Button
-              onClick={() => refetch()}
+              onClick={() => {
+                xcashuQuery.refetch();
+                apikeyQuery.refetch();
+              }}
               variant='outline'
               size='sm'
               disabled={isRefetching}
@@ -325,7 +445,7 @@ export default function TransactionsPage() {
                   <Search className='text-muted-foreground absolute top-2.5 left-2.5 h-4 w-4' />
                   <Input
                     id='search'
-                    placeholder='Search by ID, token or request ID...'
+                    placeholder='Search by ID, token, request ID or key hash...'
                     className='pl-8'
                     value={search}
                     onChange={(e) => setSearch(e.target.value)}
@@ -372,23 +492,27 @@ export default function TransactionsPage() {
           </CardContent>
         </Card>
 
-        <Tabs defaultValue='x-cashu'>
+        <Tabs
+          defaultValue='x-cashu'
+          value={activeTab}
+          onValueChange={setActiveTab}
+        >
           <TabsList className='mb-4'>
             <TabsTrigger value='x-cashu' className='flex items-center gap-2'>
               <Zap className='h-4 w-4' />
               X-Cashu
-              {data && (
+              {xcashuQuery.data && (
                 <Badge variant='secondary' className='ml-1'>
-                  {xcashuTxs.length}
+                  {xcashuQuery.data.total}
                 </Badge>
               )}
             </TabsTrigger>
             <TabsTrigger value='apikey' className='flex items-center gap-2'>
               <Key className='h-4 w-4' />
-              API Key Refunds
-              {data && (
+              API Key
+              {apikeyQuery.data && (
                 <Badge variant='secondary' className='ml-1'>
-                  {apikeyTxs.length}
+                  {apikeyQuery.data.total}
                 </Badge>
               )}
             </TabsTrigger>
@@ -407,7 +531,7 @@ export default function TransactionsPage() {
                 </div>
               </CardHeader>
               <CardContent className='overflow-hidden'>
-                {renderCardContent(xcashuTxs)}
+                {renderCardContent(xcashuQuery, xcashuPage, setXcashuPage)}
               </CardContent>
             </Card>
           </TabsContent>
@@ -416,7 +540,7 @@ export default function TransactionsPage() {
             <Card>
               <CardHeader>
                 <div className='flex flex-col items-start gap-2 sm:flex-row sm:items-center sm:justify-between'>
-                  <CardTitle>API Key Refund History</CardTitle>
+                  <CardTitle>API Key Transaction History</CardTitle>
                   {hasActiveFilters && (
                     <CardDescription>
                       Filtered by {activeFilterDescription}
@@ -425,7 +549,7 @@ export default function TransactionsPage() {
                 </div>
               </CardHeader>
               <CardContent className='overflow-hidden'>
-                {renderCardContent(apikeyTxs)}
+                {renderCardContent(apikeyQuery, apikeyPage, setApikeyPage)}
               </CardContent>
             </Card>
           </TabsContent>

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

@@ -540,7 +540,7 @@ export function AddProviderModelDialog({
                   };
                   return (
                     <FormItem>
-                      <FormLabel>Upstream Model ID</FormLabel>
+                      <FormLabel>Client Alias ID</FormLabel>
                       <FormControl>
                         <div className='flex gap-2'>
                           <Input
@@ -565,8 +565,8 @@ export function AddProviderModelDialog({
                         </div>
                       </FormControl>
                       <FormDescription>
-                        Model ID sent to the upstream provider. Defaults to the
-                        model&apos;s own ID.
+                        Alternate ID that clients can use to reference this
+                        model. Defaults to the model&apos;s own ID.
                       </FormDescription>
                       <FormMessage />
                     </FormItem>

ui/lib/api/services/admin.ts

@@ -891,13 +891,17 @@ export class AdminService {
     type?: string,
     status?: string,
     search?: string,
-    limit: number = 100
+    source?: string,
+    limit: number = 50,
+    offset: number = 0
   ): Promise<TransactionsResponse> {
     const params = new URLSearchParams();
     if (type) params.append('type', type);
     if (status) params.append('status', status);
     if (search) params.append('search', search);
+    if (source) params.append('source', source);
     params.append('limit', limit.toString());
+    params.append('offset', offset.toString());
 
     return await apiClient.get<TransactionsResponse>(
       `/admin/api/transactions?${params.toString()}`
@@ -1136,6 +1140,7 @@ export interface Transaction {
   collected: boolean;
   swept: boolean;
   source: 'x-cashu' | 'apikey';
+  api_key_hashed_key?: string;
 }
 
 export interface TransactionsResponse {

uv.lock

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