fix test

Fix reserved balance

.dockerignore

@@ -0,0 +1,13 @@
+.env
+.venv
+.git
+.gitignore
+.dockerignore
+compose.yml
+compose.testing.yml
+.todo
+.github
+.vscode
+.DS_Store
+**/node_modules
+ui/.next

.env.example

@@ -1,48 +1,43 @@
-NAME = "Your Routstr Proxy Name"
+# Core Configuration
+UPSTREAM_BASE_URL=https://api.openai.com/v1
+UPSTREAM_API_KEY=your-upstream-api-key
 
-DESCRIPTION = "A short Description"
+# ADMIN_PASSWORD=secure-admin-password
 
-# Any openai-compatible api endpoint
-UPSTREAM_BASE_URL="https://api.openai.com/v1"
-UPSTREAM_API_KEY="sk-21212121212121212121212121212121"
+# Database
+# DATABASE_URL=sqlite+aiosqlite:///keys.db
 
-# Lightning address used to receive funds
-RECEIVE_LN_ADDRESS="shroominic@walletofsatoshi.com"
+# Node Information
+# NAME=My Routstr Node
+# DESCRIPTION=Fast AI API access with Bitcoin payments
+# NSEC=nsec1...
+# HTTP_URL=https://api.mynode.com
+# ONION_URL=http://mynode.onion (auto fetched from compose)
+# RELAYS="wss://relay.damus.io,wss://relay.nostr.band,wss://eden.nostr.land,wss://relay.routstr.com"
+# CASHU_MINTS="https://mint.minibits.cash/Bitcoin,https://mint.cubabitcoin.org,https://ecashmint.otrta.me"
+# RECEIVE_LN_ADDRESS=
 
-# A prepaid key you can use when you are using it yourself or while testing. Api-key doesn't need to be in any specific format but it should start with "sk-""
-PREPAID_API_KEY="sk-" # Add any string/hash here. Replace with a new string for a new API
-PREPAID_BALANCE="10000" # 10k sats
+# Custom Pricing Configuration
+# MODEL_BASED_PRICING=true
+# COST_PER_REQUEST=1
+# COST_PER_1K_INPUT_TOKENS=0
+# COST_PER_1K_OUTPUT_TOKENS=0
+# EXCHANGE_FEE=1.005
+# UPSTREAM_PROVIDER_FEE=1.05
 
-# When your cashu balance reaches this number of sats, send the funds to RECEIVE_LN_ADDRESS. 
-MINIMUM_PAYOUT = "100"
+# Network Configuration
+# CORS_ORIGINS=*
+# TOR_PROXY_URL=socks5://127.0.0.1:9050
 
-# Costs in Sats, if MODEL_BASED_PRICING is set to false
-COST_PER_REQUEST="10"
-COST_PER_1K_INPUT_TOKENS = "0"
-COST_PER_1K_OUTPUT_TOKENS = "0"
+# Logging
+# LOG_LEVEL=INFO
+# ENABLE_CONSOLE_LOGGING=true
 
-# If set to true, pricing is loaded from the file specified by MODELS_PATH
-# Defaults to "models.json" and falls back to "models.example.json" if missing
-MODEL_BASED_PRICING = "false"
-# MODELS_PATH="models.json"
+# Custom Model Management
+# BASE_URL=https://openrouter.ai/api/v1
+# MODELS_PATH=models.json
+# SOURCE=
 
-# Time in seconds between each automatically refunding funds to users whose API keys have expired
-# Setting this to "0" disables automatic refunds
-REFUND_PROCESSING_INTERVAL = "3600"
-
-
-# password used to log into admin interface
-ADMIN_PASSWORD="XXX"
-
-# NPUB of Nostr account
-NSEC=""
-NPUB="npub..."
-
-# Not used currently
-HTTP_URL=""
-
-# Not used currently
-ONION_URL="XXX.onion"
-
-RELAYS="wss://relay.damus.io,wss://relay.nostr.band"
-CASHU_MINTS="https://mint.minibits.cash/Bitcoin,https://mint.cubabitcoin.org"
+# UI Configuration (for Next.js frontend)
+# These variables are prefixed with NEXT_PUBLIC_ to be accessible in the browser
+# NEXT_PUBLIC_API_URL=http://127.0.0.1:8000

.github/workflows/container.yml

@@ -25,13 +25,11 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Lowercase and set image tag
-        run: echo "IMAGE_TAG=ghcr.io/$(echo $GITHUB_REPOSITORY | tr '[:upper:]' '[:lower:]'):latest" >> $GITHUB_ENV
-
       - name: Build and push Docker image
         uses: docker/build-push-action@v4
         with:
           context: .
           push: true
           tags: |
-            ${{ env.IMAGE_TAG }}
+            ghcr.io/routstr/proxy:latest
+            ghcr.io/routstr/core:latest

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Build MkDocs site
+        run: mkdocs build --strict --verbose
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -7,7 +7,7 @@ on:
     branches: ["*"] # Run on PRs to all branches
 
 jobs:
-  test:
+  backend-test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -36,6 +36,9 @@ jobs:
           uv run mypy .
 
       - name: Run tests with pytest
+        env:
+          UPSTREAM_BASE_URL: "http://test"
+          UPSTREAM_API_KEY: "test"
         run: |
           uv run pytest --verbose --tb=short
 
@@ -48,3 +51,38 @@ jobs:
             pytest.xml
             .coverage
           retention-days: 30
+
+  ui-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "18"
+          cache: "pnpm"
+          cache-dependency-path: ui/pnpm-lock.yaml
+
+      - name: Install UI dependencies
+        working-directory: ./ui
+        run: pnpm install --frozen-lockfile
+
+      - name: Run UI format check
+        working-directory: ./ui
+        run: pnpm run format-check
+
+      - name: Run UI linting
+        working-directory: ./ui
+        run: pnpm run lint
+
+      - name: Run UI build
+        working-directory: ./ui
+        run: pnpm run build

.gitignore

@@ -3,12 +3,25 @@ __pycache__
 keys.db
 wallet.sqlite3
 
+# Python build artifacts
+*.egg-info/
+build/
+dist/
+*.egg
+.mypy_cache/**
+
 # Development 
 .notes
 .*keys.db
+*.db-shm
+*.db-wal
 .*wallet.sqlite3
 *models.json
 .cashu
+.relay
+relay-data
+.dockerignore
+relay-data
 
 compose.override.yml
 
@@ -22,3 +35,6 @@ logs/*
 
 # deployment
 proof_backups
+
+*.todo
+ui_out

.python-version

@@ -0,0 +1 @@
+3.11

.todo

@@ -1,5 +0,0 @@
-- test if currency and payment amount is correct
-- test payout
-
-- make tor work
-- 

CONTRIBUTING.md

@@ -0,0 +1,370 @@
+# Contributing to Routstr Proxy
+
+We welcome contributions to Routstr Proxy! This document provides guidelines and instructions for contributing to the project.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Code Standards](#code-standards)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Project Structure](#project-structure)
+- [Documentation](#documentation)
+- [Release Process](#release-process)
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.11 or higher
+- [uv](https://docs.astral.sh/uv/) package manager
+- Docker and Docker Compose (optional, for integration tests)
+- Git
+
+### Development Setup
+
+1. **Fork and clone the repository**
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/routstr-proxy.git
+   cd routstr-proxy
+   ```
+
+2. **Set up the development environment**
+
+   ```bash
+   make setup
+   ```
+
+   This will:
+   - Install `uv` if not already installed
+   - Create a virtual environment
+   - Install all dependencies including dev tools
+   - Install the project in editable mode
+
+3. **Configure environment variables**
+
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+4. **Verify your setup**
+
+   ```bash
+   make check-deps
+   make test-unit
+   ```
+
+## Code Standards
+
+### Python Style Guide
+
+We use modern Python 3.11+ features and enforce strict type checking:
+
+- **Type Hints**: All functions must have complete type annotations
+
+  ```python
+  # ✅ Good
+  def calculate_cost(tokens: int, price_per_token: float) -> dict[str, float]:
+      return {"total": tokens * price_per_token}
+  
+  # ❌ Bad
+  def calculate_cost(tokens, price_per_token):
+      return {"total": tokens * price_per_token}
+  ```
+
+- **Type Syntax**: Use Python 3.11+ lowercase types
+
+  ```python
+  # ✅ Good
+  def process_items(items: list[dict[str, str | None]]) -> dict[str, int]:
+      ...
+  
+  # ❌ Bad
+  from typing import List, Dict, Optional
+  def process_items(items: List[Dict[str, Optional[str]]]) -> Dict[str, int]:
+      ...
+  ```
+
+- **Comments**: Only add comments for non-obvious logic. Code should be self-documenting
+
+  ```python
+  # ✅ Good - complex business logic explained
+  # Apply exponential backoff with jitter to prevent thundering herd
+  delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay)
+  
+  # ❌ Bad - obvious comment
+  # Increment counter by 1
+  counter += 1
+  ```
+
+### Code Quality Tools
+
+We enforce code quality using:
+
+- **Ruff**: For linting and formatting
+
+  ```bash
+  make lint    # Check for issues
+  make format  # Auto-fix formatting
+  ```
+
+- **Mypy**: For type checking
+
+  ```bash
+  make type-check
+  ```
+
+### Commit Messages
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```text
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+Types:
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Test additions or fixes
+- `chore`: Build process or auxiliary tool changes
+
+Examples:
+
+```text
+feat(proxy): add support for streaming responses
+
+fix(wallet): handle expired tokens correctly
+
+docs: update API documentation for v2 endpoints
+```
+
+## Testing
+
+### Test Structure
+
+Tests are organized into:
+
+- `tests/unit/` - Fast, isolated unit tests
+- `tests/integration/` - Integration tests (can use mocks or real services)
+
+### Running Tests
+
+```bash
+# Run all tests (unit + integration with mocks)
+make test
+
+# Run specific test suites
+make test-unit                    # Unit tests only
+make test-integration             # Integration tests with mocks
+make test-integration-docker      # Integration tests with real services
+make test-performance             # Performance benchmarks
+
+# Advanced testing
+make test-coverage                # Generate coverage report
+make test-fast                    # Skip slow tests
+make test-failed                  # Re-run only failed tests
+```
+
+### Writing Tests
+
+1. **Use pytest fixtures** for reusable test setup
+2. **Mark async tests** with `@pytest.mark.asyncio`
+3. **Use appropriate markers**:
+
+   ```python
+   @pytest.mark.slow
+   @pytest.mark.requires_docker
+   async def test_complex_integration():
+       ...
+   ```
+
+4. **Follow the AAA pattern**: Arrange, Act, Assert
+
+   ```python
+   async def test_token_validation():
+       # Arrange
+       token = create_test_token(amount=1000)
+       
+       # Act
+       result = await validate_token(token)
+       
+       # Assert
+       assert result.is_valid
+       assert result.amount == 1000
+   ```
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Create a feature branch**
+
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+2. **Make your changes**
+   - Write code following our standards
+   - Add or update tests
+   - Update documentation if needed
+
+3. **Run quality checks**
+
+   ```bash
+   make lint
+   make type-check
+   make test
+   ```
+
+4. **Commit your changes**
+   - Use conventional commit messages
+   - Keep commits focused and atomic
+
+5. **Push and create a PR**
+   - Push to your fork
+   - Create a PR against the `main` branch
+   - Fill out the PR template completely
+   - Link any related issues
+
+### PR Review Checklist
+
+Before requesting review, ensure:
+
+- [ ] All tests pass
+- [ ] Code follows style guidelines
+- [ ] Type hints are complete and correct
+- [ ] Documentation is updated
+- [ ] Commit messages follow conventions
+- [ ] No unnecessary changes outside scope
+
+### What to Expect
+
+- Reviews typically happen within 2-3 business days
+- Be prepared to make changes based on feedback
+- Engage constructively in discussions
+- Once approved, a maintainer will merge your PR
+
+## Project Structure
+
+```text
+routstr-proxy/
+├── routstr/                 # Main application code
+│   ├── core/              # Core functionality
+│   │   ├── admin.py       # Admin interface
+│   │   ├── db.py          # Database models and operations
+│   │   ├── logging.py     # Logging configuration
+│   │   └── main.py        # FastAPI app initialization
+│   ├── payment/           # Payment processing
+│   │   ├── cost_calculation.py
+│   │   ├── models.py
+│   │   └── x_cashu.py     # Cashu integration
+│   ├── auth.py            # Authentication
+│   ├── proxy.py           # Request proxying logic
+│   └── wallet.py          # Wallet management
+├── tests/                 # Test suite
+│   ├── unit/              # Unit tests
+│   └── integration/       # Integration tests
+├── scripts/               # Utility scripts
+├── compose.yml            # Docker compose for production
+├── compose.testing.yml    # Docker compose for testing
+├── Makefile              # Development commands
+└── pyproject.toml        # Project configuration
+```
+
+### Key Components
+
+- **FastAPI Application**: Main API server in `routstr/core/main.py`
+- **Database Models**: SQLModel definitions in `routstr/core/db.py`
+- **Payment Logic**: Cashu integration and cost calculation in `routstr/payment/`
+- **Proxy Handler**: Request forwarding logic in `routstr/proxy.py`
+
+## Documentation
+
+### Code Documentation
+
+- Use descriptive variable and function names
+- Add docstrings for public APIs:
+
+  ```python
+  async def redeem_token(token: str, mint_url: str) -> RedemptionResult:
+      """Redeem a Cashu token and credit the account.
+      
+      Args:
+          token: Base64-encoded Cashu token
+          mint_url: URL of the Cashu mint
+          
+      Returns:
+          RedemptionResult with amount and status
+          
+      Raises:
+          TokenInvalidError: If token is malformed or expired
+          MintConnectionError: If mint is unreachable
+      """
+  ```
+
+### API Documentation
+
+- Update OpenAPI schemas when adding endpoints
+- Keep `README.md` examples current
+- Document environment variables in `.env.example`
+
+### Architecture Decisions
+
+For significant changes, create an ADR (Architecture Decision Record) in `docs/adr/`:
+
+```markdown
+# ADR-001: Use SQLite for Local Storage
+
+## Status
+Accepted
+
+## Context
+We need a simple, embedded database for storing API keys and balances.
+
+## Decision
+Use SQLite with SQLModel ORM for type safety and async support.
+
+## Consequences
+- No external database required
+- Simple deployment
+- Limited concurrent write performance
+```
+
+## Release Process
+
+### Version Numbering
+
+We use [Semantic Versioning](https://semver.org/):
+
+- MAJOR: Breaking API changes
+- MINOR: New features, backwards compatible
+- PATCH: Bug fixes and minor improvements
+
+### Release Steps
+
+1. Update version in `pyproject.toml`
+2. Update `CHANGELOG.md` with release notes
+3. Create a git tag: `git tag -a v1.2.3 -m "Release v1.2.3"`
+4. Push tag: `git push origin v1.2.3`
+5. GitHub Actions will build and publish Docker images
+
+## Getting Help
+
+- **Issues**: Check existing issues or create a new one
+- **Discussions**: Use GitHub Discussions for questions
+- **Security**: Report security issues privately to maintainers
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the GPLv3 license.

Dockerfile

@@ -12,8 +12,10 @@ RUN apk add --no-cache \
 RUN apk add git
 
 COPY uv.lock pyproject.toml ./
+RUN mkdir -p /routstr
 
-RUN uv sync
+RUN uv add git+https://github.com/saschanaz/secp256k1-py.git#branch=upgrade060
+# RUN uv sync
 
 WORKDIR /app
 
@@ -24,4 +26,4 @@ ENV PYTHONUNBUFFERED=1
 
 EXPOSE 8000
 
-CMD ["/.venv/bin/fastapi", "run", "router", "--host", "0.0.0.0"]
+CMD ["/.venv/bin/fastapi", "run", "routstr", "--host", "0.0.0.0"]

Makefile

@@ -0,0 +1,285 @@
+# Makefile for Routstr Proxy
+
+# Detect if we're in a virtual environment
+VENV_EXISTS := $(shell test -d .venv && echo 1)
+ifeq ($(VENV_EXISTS), 1)
+    PYTHON := .venv/bin/python
+    PYTEST := .venv/bin/pytest
+    RUFF := .venv/bin/ruff
+    MYPY := .venv/bin/mypy
+    ALEMBIC := .venv/bin/alembic
+else
+    PYTHON := python
+    PYTEST := pytest
+    RUFF := ruff
+    MYPY := mypy
+    ALEMBIC := alembic
+endif
+
+.PHONY: help setup test test-unit test-integration test-integration-docker test-all test-fast test-performance clean docker-up docker-down lint format type-check dev-setup check-deps db-upgrade db-downgrade db-current db-history db-migrate db-revision db-heads db-clean ui-build ui-build-docker ui-dev
+
+# Default target
+help:
+	@echo "Available targets:"
+	@echo "  make test               - Run all tests (unit + integration with mocks)"
+	@echo "  make test-unit          - Run unit tests only"
+	@echo "  make test-integration   - Run integration tests with mocks (fast)"
+	@echo "  make test-integration-docker - Run integration tests with Docker services"
+	@echo "  make test-all           - Run all tests including Docker integration"
+	@echo "  make test-fast          - Run fast tests only (skip slow tests)"
+	@echo "  make test-performance   - Run performance tests"
+	@echo "  make docker-up          - Start Docker test services"
+	@echo "  make docker-down        - Stop Docker test services"
+	@echo "  make clean              - Clean up test artifacts and caches"
+	@echo "  make lint               - Run linting checks"
+	@echo "  make format             - Format code with ruff"
+	@echo "  make type-check         - Run mypy type checking"
+	@echo "  make dev-setup          - Set up development environment"
+	@echo "  make check-deps         - Check system dependencies"
+	@echo "  make setup              - First-time project setup"
+	@echo ""
+	@echo "UI targets:"
+	@echo "  make ui-build           - Build UI for production (static export)"
+	@echo "  make ui-build-docker    - Build UI using Docker (no Node.js needed)"
+	@echo "  make ui-dev             - Start UI development server"
+	@echo ""
+	@echo "Docker UI build requires only Docker, no local Node.js installation needed."
+	@echo "Database migration shortcuts:"
+	@echo "  make create-migration   - Auto-generate new migration"
+	@echo "  make db-upgrade         - Apply all pending migrations"
+	@echo "  make db-downgrade       - Downgrade one migration"
+
+# First-time setup
+setup: check-deps dev-setup
+	@echo ""
+	@echo "🎉 Setup complete! Next steps:"
+	@echo "  1. Run tests:         make test"
+	@echo "  2. Run integration:   make test-integration-docker"
+	@echo "  3. Start developing!"
+
+# Test targets
+test: test-unit test-integration
+
+test-unit:
+	@echo "🧪 Running unit tests..."
+	$(PYTEST) tests/unit/ -v
+
+test-integration:
+	@echo "🎭 Running integration tests with mocks..."
+	$(PYTEST) tests/integration/ -v
+
+test-integration-docker:
+	@echo "🐳 Running integration tests with Docker services..."
+	./tests/run_integration.py
+
+test-all: test-unit test-integration-docker
+
+test-fast:
+	@echo "⚡ Running fast tests only..."
+	$(PYTEST) -m "not slow and not requires_docker" -v
+
+test-performance:
+	@echo "📊 Running performance tests..."
+	$(PYTEST) tests/integration/ -m "performance" -v -s
+
+# Docker management
+docker-up:
+	@echo "🚀 Starting Docker test services..."
+	docker-compose -f compose.testing.yml up -d
+	@echo "Waiting for services to be ready..."
+	@sleep 5
+	@echo "Services started. Run 'make test-integration-docker' to test."
+
+docker-down:
+	@echo "🛑 Stopping Docker test services..."
+	docker-compose -f compose.testing.yml down -v
+
+# Code quality
+lint:
+	@echo "🔍 Running linting checks..."
+	$(RUFF) check .
+	$(MYPY) routstr/ --ignore-missing-imports
+
+format:
+	@echo "✨ Formatting code..."
+	$(RUFF) format .
+	$(RUFF) check --fix .
+
+type-check:
+	@echo "🔎 Running type checks..."
+	$(MYPY) routstr/ --ignore-missing-imports
+
+# Development setup
+dev-setup:
+	@echo "🔧 Setting up development environment..."
+	@# Check if uv is installed
+	@if ! command -v uv >/dev/null 2>&1; then \
+		echo "📦 uv not found. Installing uv..."; \
+		if command -v curl >/dev/null 2>&1; then \
+			curl -LsSf https://astral.sh/uv/install.sh | sh; \
+		elif command -v pip >/dev/null 2>&1; then \
+			pip install uv; \
+		else \
+			echo "❌ Neither curl nor pip found. Please install uv manually:"; \
+			echo "   Visit https://docs.astral.sh/uv/getting-started/installation/"; \
+			exit 1; \
+		fi; \
+		echo "✅ uv installed successfully!"; \
+	else \
+		echo "✅ uv is already installed (version: $$(uv --version))"; \
+	fi
+	uv sync --dev
+	uv pip install -e .
+	@echo "✅ Development environment ready!"
+
+# Check dependencies
+check-deps:
+	@echo "🔍 Checking system dependencies..."
+	@echo ""
+	@echo "Core tools:"
+	@printf "  %-18s" "Python:"; if command -v python >/dev/null 2>&1; then python --version; else echo "❌ Not found"; fi
+	@printf "  %-18s" "uv:"; if command -v uv >/dev/null 2>&1; then uv --version; else echo "❌ Not found - run 'make dev-setup' to install"; fi
+	@printf "  %-18s" "Docker:"; if command -v docker >/dev/null 2>&1; then docker --version; else echo "⚠️  Not found (optional, needed for integration tests)"; fi
+	@printf "  %-18s" "Docker Compose:"; if command -v docker-compose >/dev/null 2>&1; then docker-compose --version; else echo "⚠️  Not found (optional, needed for integration tests)"; fi
+	@echo ""
+	@echo "Development tools:"
+	@printf "  %-18s" "pytest:"; if $(PYTEST) --version >/dev/null 2>&1; then $(PYTEST) --version | head -1; else echo "❌ Not found - run 'make dev-setup'"; fi
+	@printf "  %-18s" "ruff:"; if $(RUFF) --version >/dev/null 2>&1; then $(RUFF) --version; else echo "❌ Not found - run 'make dev-setup'"; fi
+	@printf "  %-18s" "mypy:"; if $(MYPY) --version >/dev/null 2>&1; then $(MYPY) --version; else echo "❌ Not found - run 'make dev-setup'"; fi
+	@printf "  %-18s" "alembic:"; if $(ALEMBIC) --version >/dev/null 2>&1; then $(ALEMBIC) --version; else echo "❌ Not found - run 'make dev-setup'"; fi
+	@echo ""
+	@echo "Virtual environment:"
+	@if [ -d ".venv" ]; then \
+		echo "  ✅ .venv exists"; \
+		echo "  Python: $$(.venv/bin/python --version)"; \
+	else \
+		echo "  ❌ .venv not found - run 'make dev-setup'"; \
+	fi
+	@echo ""
+	@echo "To set up missing dependencies, run: make dev-setup"
+
+# Cleanup
+clean:
+	@echo "🧹 Cleaning up..."
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".mypy_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+	find . -type f -name ".coverage" -delete
+	rm -rf htmlcov/
+	rm -rf dist/
+	rm -rf build/
+	rm -rf *.egg-info
+	@echo "✨ Cleanup complete!"
+
+# Database migration management
+db-upgrade:
+	@echo "⬆️  Applying all pending migrations..."
+	$(ALEMBIC) upgrade head
+	@echo "✅ Database upgraded to latest revision"
+
+db-downgrade:
+	@echo "⬇️  Downgrading one migration..."
+	$(ALEMBIC) downgrade -1
+	@echo "✅ Database downgraded by one revision"
+
+db-current:
+	@echo "📍 Current database revision:"
+	$(ALEMBIC) current -v
+
+db-history:
+	@echo "📜 Migration history:"
+	$(ALEMBIC) history --verbose
+
+db-migrate:
+	@echo "🔍 Auto-generating migration from model changes..."
+	@read -p "Enter migration message: " msg; \
+	$(ALEMBIC) revision --autogenerate -m "$$msg"
+	@echo "✅ Migration generated. Review and edit if needed."
+
+db-revision:
+	@echo "📝 Creating empty migration file..."
+	@read -p "Enter migration message: " msg; \
+	$(ALEMBIC) revision -m "$$msg"
+	@echo "✅ Empty migration created"
+
+db-heads:
+	@echo "🎯 Current migration heads:"
+	$(ALEMBIC) heads
+
+db-clean:
+	@echo "🧹 Cleaning migration cache files..."
+	find migrations/ -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@echo "✅ Migration cache cleaned"
+
+# Advanced testing options
+test-coverage:
+	@echo "📊 Running tests with coverage..."
+	$(PYTEST) --cov=routstr --cov-report=html --cov-report=term
+	@echo "Coverage report generated in htmlcov/"
+
+test-watch:
+	@echo "👁️  Running tests in watch mode..."
+	$(PYTEST)-watch
+
+test-parallel:
+	@echo "🚀 Running tests in parallel..."
+	$(PYTEST) -n auto -v
+
+# CI/CD specific targets
+ci-test:
+	@echo "🤖 Running CI test suite..."
+	$(PYTEST) -m "not requires_docker" --tb=short -v
+
+ci-lint:
+	@echo "🤖 Running CI linting..."
+	$(RUFF) check . --exit-non-zero-on-fix
+	$(MYPY) routstr/ --ignore-missing-imports --no-error-summary
+
+# Debug helpers
+test-debug:
+	@echo "🐛 Running tests with debugging enabled..."
+	$(PYTEST) -vvs --tb=long --pdb-trace
+
+test-failed:
+	@echo "🔄 Re-running failed tests..."
+	$(PYTEST) --lf -v
+
+# Performance profiling
+profile:
+	@echo "🔥 Running with profiling..."
+	$(PYTHON) -m cProfile -o profile.stats -m pytest tests/integration/test_performance_load.py::TestPerformanceBaseline -v
+	@echo "Profile saved to profile.stats. Use '$(PYTHON) -m pstats profile.stats' to analyze."
+
+# Documentation
+docs-build:
+	@echo "📚 Building documentation..."
+	mkdocs build
+
+docs-serve:
+	@echo "📚 Serving documentation at http://localhost:8001..."
+	mkdocs serve -a localhost:8001
+
+docs-deploy:
+	@echo "📚 Deploying documentation to GitHub Pages..."
+	mkdocs gh-deploy --force
+
+docs-install:
+	@echo "📚 Installing documentation dependencies..."
+	pip install -r docs/requirements.txt
+
+# UI build
+ui-build:
+	@echo "🎨 Building UI for static deployment..."
+	./scripts/build-ui.sh
+
+ui-build-docker:
+	@echo "🐳 Building UI using Docker (no Node.js installation required)..."
+	@echo "Building UI with environment variables from .env..."
+	docker build -f ui/Dockerfile.build -t routstr-ui-build --build-arg NEXT_PUBLIC_API_URL=$(NEXT_PUBLIC_API_URL) --build-arg NEXT_PUBLIC_ADMIN_API_KEY=$(NEXT_PUBLIC_ADMIN_API_KEY) .
+	docker run --rm -v $(PWD)/ui_out:/output routstr-ui-build cp -r /ui_out /output/
+	@echo "✅ UI build complete! Static files available in ui_out/"
+
+ui-dev:
+	@echo "🎨 Starting UI development server..."
+	cd ui && (command -v pnpm >/dev/null 2>&1 && pnpm run dev || npm run dev)

README.md

@@ -32,22 +32,33 @@ sequenceDiagram
 - **Cashu Wallet Integration** – Accept Lightning payments and redeem eCash tokens before forwarding requests
 - **API Key Management** – Hashed keys stored in SQLite with balance tracking and optional expiry/refund address
 - **Model-Based Pricing** – Convert USD prices in `models.json` to sats using live BTC/USD rates
-- **Admin Dashboard** – Simple HTML interface at `/admin` to view balances and API keys
-- **Discovery** – Fetch available providers from Nostr relays
+- **Admin Dashboard** – Simple HTML interface at `/admin/` to view balances and API keys
+- **Discovery** – Fetch available providers from Nostr relays using NIP-91 protocol
+- **NIP-91 Auto-Announcement** – Automatically announce this provider to Nostr relays when NSEC is provided
 - **Docker Support** – Provided `Dockerfile` and `compose.yml` for running with an optional Tor hidden service
 
 ## Getting Started
 
-### Requirements
+### Running the proxy using Docker
+
+```bash
+docker run -d \
+--name routstr-proxy \
+-p 8000:8000 \
+-e UPSTREAM_BASE_URL=https://api.openai.com/v1 \
+-e UPSTREAM_API_KEY=your-openai-api-key \
+ghcr.io/routstr/proxy:latest
+```
+
+### Development Requirements
 
 - Python 3.11+
 - [uv](https://github.com/astral-sh/uv) package manager (used in development)
-- A Cashu wallet secret (`NSEC`) and Lightning address for receiving payments
 
 ### Installation
 
 ```bash
-uv sync --dev  # install dependencies
+uv sync  # install dependencies
 ```
 
 Create a `.env` file based on `.env.example` and fill in the required values:
@@ -59,7 +70,7 @@ cp .env.example .env
 ### Running Locally
 
 ```bash
-fastapi run router --host 0.0.0.0 --port 8000
+fastapi run routstr --host 0.0.0.0 --port 8000
 ```
 
 The service forwards requests to `UPSTREAM_BASE_URL`. Supply the upstream API key via the `UPSTREAM_API_KEY` environment variable if required.
@@ -76,13 +87,98 @@ This builds the image and also starts a Tor container exposing the API as a hidd
 
 The most common settings are shown below. See `.env.example` for the full list.
 
+### Core Settings
+
 - `UPSTREAM_BASE_URL` – URL of the OpenAI-compatible service
 - `UPSTREAM_API_KEY` – API key for the upstream service (optional)
-- `RECEIVE_LN_ADDRESS` – Lightning address that receives payouts
-- `MINIMUM_PAYOUT` – Minimum sats before forwarding earnings
-- `MODEL_BASED_PRICING` – Set to `true` to use pricing from `models.json`
-- `REFUND_PROCESSING_INTERVAL` – Seconds between automatic refunds
-- `ADMIN_PASSWORD` – Password for the `/admin` dashboard
+- `FIXED_PRICING` – Set to `true` to use a fixed per-request price; `false` (default) uses model pricing from `models.json`
+- `ADMIN_PASSWORD` – Password for the `/admin/` dashboard
+- `CASHU_MINTS` – Comma-separated list of Cashu mint URLs
+- `NAME` – Name of the proxy
+- `DESCRIPTION` – Description of the proxy
+- `NPUB` – Nostr public key of the proxy
+- `HTTP_URL` – Public-facing URL of the proxy
+- `ONION_URL` – Tor hidden service URL of the proxy
+- `NEXT_PUBLIC_API_URL` - UI Configuration for Next.js frontend (proxy URL, default: 'http://127.0.0.1:8000' )
+
+## Database Migrations
+
+The application uses Alembic for database schema management and **automatically runs migrations on startup**. This ensures your database is always up-to-date when deploying new versions.
+
+### Automatic Migrations in Production
+
+When the FastAPI application starts, it automatically:
+
+1. Runs all pending database migrations
+2. Updates the schema to the latest version
+3. Logs the migration status
+
+This means you don't need to manually run migrations when deploying - just restart the application and migrations will be applied automatically.
+
+### Manual Migration Commands
+
+For development or troubleshooting, you can use these Makefile commands:
+
+```bash
+make db-upgrade         # Apply all pending migrations
+make db-downgrade       # Downgrade one migration
+make db-current         # Show current migration revision
+make db-history         # Show migration history
+make db-migrate         # Auto-generate new migration from model changes
+make db-revision        # Create empty migration file
+make db-heads           # Show current migration heads
+make db-clean           # Clean migration cache files
+```
+
+### Creating New Migrations
+
+When you modify SQLModel models:
+
+```bash
+# Auto-generate a migration from model changes
+make db-migrate
+# Enter a descriptive message when prompted
+
+# Review the generated migration file in migrations/versions/
+# Edit if needed, then test with:
+make db-upgrade
+```
+
+## Admin UI
+
+Routstr includes a modern Next.js admin dashboard that's served directly from the Python backend as static files - no separate Node.js server required.
+
+### Building the UI
+
+```bash
+make ui-build
+```
+
+This compiles the Next.js application into static HTML, CSS, and JavaScript files in `ui/out/`.
+
+### Accessing the Dashboard
+
+Once built, the UI is automatically served by the FastAPI backend:
+
+- **Dashboard**: `http://localhost:8000/`
+- **Login**: `http://localhost:8000/login`
+- **Models Management**: `http://localhost:8000/model`
+- **Providers Management**: `http://localhost:8000/providers`
+- **Settings**: `http://localhost:8000/settings`
+
+The dashboard provides:
+
+- Real-time wallet balance monitoring
+- Model pricing configuration
+- Upstream provider management
+- Transaction history
+- System settings
+
+**Authentication**: Use the `ADMIN_PASSWORD` environment variable to access the dashboard.
+
+## Withdrawing Balance
+
+Go to the admin dashboard at `http://localhost:8000/` and login with your `ADMIN_PASSWORD` to withdraw your balance as a Cashu token.
 
 ## Example Client
 
@@ -143,7 +239,8 @@ The proxy should implement either a dedicated endpoint to communicate minimum eC
 
 To use this feature, you'll need a client that handles both OpenAI API calls and eCash header management. The following clients provide seamless integration:
 
-- **[cashu-402-client](https://github.com/9qeklajc/ecash-402-client)** – rust client with automatic wallet management
+- **[routstr-chat](https://github.com/routstr/routstr-chat)** – chat app for the routstr network
+- **[otrta-client](https://github.com/routstr/otrta-client)** – rust web app for the routstr network
 
 clients automatically:
 

alembic.ini

@@ -0,0 +1,35 @@
+[alembic]
+script_location = migrations
+sqlalchemy.url = 
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s

build-docs.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# Build script for MkDocs documentation
+
+echo "Building Routstr Core documentation..."
+
+# Check if mkdocs is installed
+if ! command -v mkdocs &> /dev/null; then
+    echo "MkDocs not found. Installing dependencies..."
+    pip install -r docs/requirements.txt
+fi
+
+# Build the documentation
+echo "Building docs..."
+mkdocs build
+
+# Serve locally for preview (optional)
+if [ "$1" = "serve" ]; then
+    echo "Starting documentation server at http://localhost:8001"
+    mkdocs serve -a localhost:8001
+elif [ "$1" = "deploy" ]; then
+    echo "Deploying to GitHub Pages..."
+    mkdocs gh-deploy --force
+else
+    echo "Documentation built successfully in ./site/"
+    echo "Run './build-docs.sh serve' to preview locally"
+    echo "Run './build-docs.sh deploy' to deploy to GitHub Pages"
+fi

compose.testing.yml

@@ -0,0 +1,62 @@
+version: '3.8'
+
+services:
+  routstr:
+    build: .
+    command: ["/.venv/bin/fastapi", "dev", "routstr", "--host", "0.0.0.0", "--port", "8000"]
+    ports:
+      - "8000:8000"
+    environment:
+      - "DATABASE_URL=sqlite+aiosqlite:///:memory:"
+      - "NOSTR_RELAY_URL=ws://relay:8080"
+      - "UPSTREAM_BASE_URL=http://mock-openai:3000"
+      - "UPSTREAM_API_KEY=test-upstream-key"
+      - "CASHU_MINTS=http://mint:3338"
+      - "NAME=TestRoutstrNode"
+      - "DESCRIPTION=Test Node for Integration Tests"
+      - "NPUB=npub1test"
+      - "HTTP_URL=http://localhost:8000"
+      - "ONION_URL=http://test.onion"
+      - "CORS_ORIGINS=*"
+      - "RECEIVE_LN_ADDRESS=test@routstr.com"
+      - "FIXED_COST_PER_REQUEST=10"
+      - "FIXED_PER_1K_INPUT_TOKENS=0"
+      - "FIXED_PER_1K_OUTPUT_TOKENS=0"
+      - "FIXED_PRICING=false"
+      - "NSEC=nsec1testkey1234567890abcdef"
+      - "REFUND_PROCESSING_INTERVAL=3600"
+      - "MINIMUM_PAYOUT=1000"
+      - "PAYOUT_INTERVAL=86400"
+    depends_on:
+      - mock-mint
+      - mock-openai
+      - relay
+
+  relay:
+    image: scsibug/nostr-rs-relay:latest
+    restart: unless-stopped
+    ports:
+      - "8088:8080"  # host:container
+    environment:
+      - LISTEN_ADDR=0.0.0.0
+      - LISTEN_PORT=8080
+
+  mock-openai:
+    image: zerob13/mock-openai-api
+    ports:
+      - "3000:3000"
+  
+  mock-mint:
+    image: cashubtc/nutshell:0.17.0
+    container_name: mint
+    ports:
+      - "3338:3338"
+    environment:
+      - MINT_BACKEND_BOLT11_SAT=FakeWallet
+      - MINT_LISTEN_HOST=0.0.0.0
+      - MINT_LISTEN_PORT=3338
+      - MINT_PRIVATE_KEY=TEST_PRIVATE_KEY
+    command: poetry run mint
+    restart: unless-stopped
+    depends_on:
+      - mock-openai

compose.yml

@@ -1,17 +1,35 @@
-version: '3.8'
-
 services:
-  router:
+  ui:
+    env_file:
+      - .env
+    build:
+      context: ./ui
+      dockerfile: Dockerfile.build
+      args:
+        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://127.0.0.1:8000}
+        NEXT_PUBLIC_ADMIN_API_KEY: ${NEXT_PUBLIC_ADMIN_API_KEY:-}
+    volumes:
+      - ./ui_out:/output
+    command:
+      ["sh", "-c", "mkdir -p /output && cp -r /app/built/. /output/ && echo 'UI build copied to mounted volume' && ls -la /output/ && echo 'UI built and ready' && tail -f /dev/null"]
+
+  routstr:
     build: .
+    depends_on:
+      - ui
     volumes:
       - .:/app
       - ./logs:/app/logs
+      - tor-data:/var/lib/tor:ro
+      - ./ui_out:/app/ui_out:ro
     env_file:
       - .env
     environment:
       - TOR_PROXY_URL=socks5://tor:9050
     ports:
       - 8000:8000
+    extra_hosts: # Needed to access locally running models
+      - "host.docker.internal:host-gateway"
 
   tor:
     image: ghcr.io/hundehausen/tor-hidden-service:latest
@@ -19,9 +37,9 @@ services:
       - tor-data:/var/lib/tor
     environment:
       # Format: HS_<NAME>=<TARGET_HOST>:<TARGET_PORT>:<VIRTUAL_PORT>
-      - HS_ROUTER=router:8000:80
+      - HS_ROUTER=routstr:8000:80
     depends_on:
-      - router
+      - routstr
 
 volumes:
   tor-data:

docs/advanced/custom-pricing.md

@@ -0,0 +1,567 @@
+# Custom Pricing
+
+This guide covers advanced pricing strategies and customization options for Routstr Core.
+
+## Pricing Models Overview
+
+Routstr supports three pricing models:
+
+1. **Fixed Pricing** - Simple per-request fee
+2. **Token-Based Pricing** - Charge per input/output token
+3. **Model-Based Pricing** - Dynamic pricing from models.json
+
+## Model-Based Pricing
+
+### Configuration
+
+Enable model-based pricing (default behavior):
+
+```bash
+# .env
+FIXED_PRICING=false
+MODELS_PATH=/app/config/models.json
+EXCHANGE_FEE=1.005         # 0.5% exchange fee
+UPSTREAM_PROVIDER_FEE=1.05  # 5% provider margin
+```
+
+### Custom Models File
+
+Create a `models.json` with your pricing:
+
+```json
+{
+  "models": [
+    {
+      "id": "gpt-4",
+      "name": "GPT-4",
+      "description": "Advanced reasoning model",
+      "context_length": 8192,
+      "pricing": {
+        "prompt": "0.03",        // USD per 1K tokens
+        "completion": "0.06",    // USD per 1K tokens
+        "request": "0.0001",     // Fixed per-request fee
+        "image": "0",            // For multimodal models
+        "web_search": "0.005",   // Additional features
+        "internal_reasoning": "0.01"
+      },
+      "supported_features": [
+        "function_calling",
+        "vision",
+        "json_mode"
+      ],
+      "deprecation_date": null,
+      "replacement_model": null
+    },
+    {
+      "id": "custom-model",
+      "name": "Custom Fine-tuned Model",
+      "pricing": {
+        "prompt": "0.001",
+        "completion": "0.002",
+        "request": "0.00005"
+      },
+      "minimum_charge": "0.0001"  // Minimum charge per request
+    }
+  ],
+  "default_pricing": {
+    "prompt": "0.002",
+    "completion": "0.002",
+    "request": "0"
+  }
+}
+```
+
+### Dynamic Price Updates
+
+Automatically fetch prices from providers:
+
+```python
+# scripts/update_prices.py
+import asyncio
+import httpx
+import json
+
+async def fetch_openrouter_models():
+    """Fetch current model pricing from OpenRouter."""
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            "https://openrouter.ai/api/v1/models"
+        )
+        return response.json()
+
+async def update_models_json():
+    """Update local models.json with latest prices."""
+    data = await fetch_openrouter_models()
+    
+    models = []
+    for model in data['data']:
+        models.append({
+            "id": model['id'],
+            "name": model['name'],
+            "pricing": {
+                "prompt": model['pricing']['prompt'],
+                "completion": model['pricing']['completion'],
+                "request": model['pricing'].get('request', '0')
+            },
+            "context_length": model.get('context_length', 4096)
+        })
+    
+    with open('models.json', 'w') as f:
+        json.dump({"models": models}, f, indent=2)
+
+# Run periodically
+if __name__ == "__main__":
+    asyncio.run(update_models_json())
+```
+
+## Token-Based Pricing
+
+### Configuration
+
+Set up token-based pricing overrides:
+
+```bash
+# .env
+FIXED_PRICING=false                 # use model pricing
+FIXED_COST_PER_REQUEST=1            # optional base fee
+FIXED_PER_1K_INPUT_TOKENS=5         # optional override
+FIXED_PER_1K_OUTPUT_TOKENS=15       # optional override
+```
+
+### Custom Token Counting
+
+Override default token counting:
+
+```python
+from tiktoken import encoding_for_model
+
+class CustomTokenCounter:
+    def __init__(self):
+        self.encodings = {}
+    
+    def count_tokens(
+        self, 
+        text: str, 
+        model: str
+    ) -> int:
+        """Custom token counting logic."""
+        # Cache encodings
+        if model not in self.encodings:
+            try:
+                self.encodings[model] = encoding_for_model(model)
+            except:
+                # Fallback encoding
+                self.encodings[model] = encoding_for_model("gpt-3.5-turbo")
+        
+        encoding = self.encodings[model]
+        
+        # Special handling for certain content
+        if text.startswith("```"):
+            # Code blocks might need special handling
+            tokens = encoding.encode(text)
+            return len(tokens) * 1.1  # 10% markup for code
+        
+        return len(encoding.encode(text))
+```
+
+## Advanced Pricing Strategies
+
+### Time-Based Pricing
+
+Implement peak/off-peak pricing:
+
+```python
+from datetime import datetime
+import pytz
+
+class TimeBased PricingStrategy:
+    def __init__(self):
+        self.timezone = pytz.timezone('US/Eastern')
+        self.peak_hours = [(9, 17)]  # 9 AM - 5 PM
+        self.peak_multiplier = 1.5
+        self.weekend_discount = 0.8
+    
+    def get_price_multiplier(self) -> float:
+        """Calculate price multiplier based on time."""
+        now = datetime.now(self.timezone)
+        
+        # Weekend discount
+        if now.weekday() >= 5:  # Saturday or Sunday
+            return self.weekend_discount
+        
+        # Peak hours surcharge
+        hour = now.hour
+        for start, end in self.peak_hours:
+            if start <= hour < end:
+                return self.peak_multiplier
+        
+        # Off-peak standard pricing
+        return 1.0
+    
+    def apply_to_cost(self, base_cost: int) -> int:
+        """Apply time-based pricing to cost."""
+        multiplier = self.get_price_multiplier()
+        return int(base_cost * multiplier)
+```
+
+### Model-Specific Surcharges
+
+Add custom fees for specific models:
+
+```python
+class ModelSurchargeStrategy:
+    def __init__(self):
+        self.surcharges = {
+            "gpt-4-turbo": 1.1,      # 10% premium
+            "claude-3-opus": 1.15,    # 15% premium
+            "dall-e-3-hd": 1.25,      # 25% premium for HD
+        }
+        
+        self.discounts = {
+            "gpt-3.5-turbo": 0.95,    # 5% discount
+            "deprecated-model": 0.8,   # 20% discount
+        }
+    
+    def get_model_multiplier(self, model: str) -> float:
+        """Get price multiplier for model."""
+        if model in self.surcharges:
+            return self.surcharges[model]
+        elif model in self.discounts:
+            return self.discounts[model]
+        return 1.0
+```
+
+### Geographic Pricing
+
+Adjust pricing based on client location:
+
+```python
+import geoip2.database
+
+class GeographicPricingStrategy:
+    def __init__(self):
+        self.reader = geoip2.database.Reader('GeoLite2-Country.mmdb')
+        self.country_multipliers = {
+            'US': 1.0,
+            'GB': 1.0,
+            'DE': 1.0,
+            'IN': 0.7,  # 30% discount
+            'BR': 0.8,  # 20% discount
+            'NG': 0.6,  # 40% discount
+        }
+        self.default_multiplier = 0.9
+    
+    def get_country_multiplier(self, ip_address: str) -> float:
+        """Get price multiplier based on country."""
+        try:
+            response = self.reader.country(ip_address)
+            country_code = response.country.iso_code
+            return self.country_multipliers.get(
+                country_code, 
+                self.default_multiplier
+            )
+        except:
+            return 1.0  # Default pricing if lookup fails
+```
+
+## Cost Calculation Pipeline
+
+### Implementing Custom Calculator
+
+```python
+from abc import ABC, abstractmethod
+
+class CostCalculator(ABC):
+    @abstractmethod
+    async def calculate(
+        self,
+        request_data: dict,
+        usage_data: dict,
+        context: dict
+    ) -> CostResult:
+        pass
+
+class CompositeCostCalculator(CostCalculator):
+    """Combine multiple pricing strategies."""
+    
+    def __init__(self):
+        self.strategies = [
+            BaseCostCalculator(),
+            TimeBasedPricingStrategy(),
+            ModelSurchargeStrategy(),
+            GeographicPricingStrategy()
+        ]
+    
+    async def calculate(
+        self,
+        request_data: dict,
+        usage_data: dict,
+        context: dict
+    ) -> CostResult:
+        # Start with base cost
+        base_cost = await self.strategies[0].calculate(
+            request_data, usage_data, context
+        )
+        
+        # Apply each strategy
+        final_cost = base_cost.total_msats
+        breakdown = {"base": base_cost.total_msats}
+        
+        for strategy in self.strategies[1:]:
+            multiplier = await strategy.get_multiplier(context)
+            adjustment = final_cost * (multiplier - 1)
+            final_cost += adjustment
+            breakdown[strategy.__class__.__name__] = adjustment
+        
+        return CostResult(
+            total_msats=int(final_cost),
+            breakdown=breakdown
+        )
+```
+
+### Integration with Routstr
+
+```python
+# In routstr/payment/cost_calculation.py
+async def calculate_request_cost(
+    model: str,
+    prompt_tokens: int,
+    completion_tokens: int,
+    request_type: str,
+    context: dict
+) -> CostData:
+    """Enhanced cost calculation with custom strategies."""
+    
+    # Use custom calculator if configured
+    if os.getenv("USE_CUSTOM_PRICING", "false").lower() == "true":
+        calculator = CompositeCostCalculator()
+        result = await calculator.calculate(
+            request_data={
+                "model": model,
+                "type": request_type
+            },
+            usage_data={
+                "prompt_tokens": prompt_tokens,
+                "completion_tokens": completion_tokens
+            },
+            context=context
+        )
+        return result
+    
+    # Fall back to standard calculation
+    return standard_calculate_cost(...)
+```
+
+## Monitoring Pricing
+
+### Price Analytics
+
+Track pricing effectiveness:
+
+```python
+class PricingAnalytics:
+    async def analyze_pricing(
+        self,
+        start_date: datetime,
+        end_date: datetime
+    ):
+        """Analyze pricing performance."""
+        # Average cost per request by model
+        model_costs = await self.get_average_costs_by_model(
+            start_date, end_date
+        )
+        
+        # Revenue by pricing strategy
+        strategy_revenue = await self.get_revenue_by_strategy(
+            start_date, end_date
+        )
+        
+        # Price elasticity
+        elasticity = await self.calculate_price_elasticity()
+        
+        return {
+            "model_costs": model_costs,
+            "strategy_revenue": strategy_revenue,
+            "price_elasticity": elasticity,
+            "recommendations": self.generate_recommendations(
+                model_costs, elasticity
+            )
+        }
+```
+
+### A/B Testing Prices
+
+Test different pricing strategies:
+
+```python
+class PricingExperiment:
+    def __init__(self):
+        self.experiments = {
+            "exp_001": {
+                "name": "10% discount test",
+                "group_a": {"multiplier": 1.0},
+                "group_b": {"multiplier": 0.9},
+                "allocation": 0.5  # 50/50 split
+            }
+        }
+    
+    def assign_group(self, api_key_id: int) -> str:
+        """Assign API key to experiment group."""
+        # Consistent assignment based on key ID
+        import hashlib
+        hash_value = int(hashlib.md5(
+            str(api_key_id).encode()
+        ).hexdigest()[:8], 16)
+        
+        return "group_b" if (hash_value % 100) < 50 else "group_a"
+    
+    def get_experiment_multiplier(
+        self, 
+        api_key_id: int,
+        experiment_id: str
+    ) -> float:
+        """Get price multiplier for experiment."""
+        experiment = self.experiments.get(experiment_id)
+        if not experiment:
+            return 1.0
+        
+        group = self.assign_group(api_key_id)
+        return experiment[group]["multiplier"]
+```
+
+## Configuration Examples
+
+### Enterprise Pricing
+
+```json
+{
+  "models": [
+    {
+      "id": "gpt-4-enterprise",
+      "name": "GPT-4 Enterprise",
+      "pricing": {
+        "prompt": "0.02",
+        "completion": "0.04"
+      },
+      "minimum_commitment": "1000",  // $1000/month minimum
+      "sla": {
+        "uptime": "99.9%",
+        "support_response": "1 hour",
+        "dedicated_capacity": true
+      }
+    }
+  ],
+  "enterprise_features": {
+    "priority_queue": true,
+    "custom_models": true,
+    "audit_logs": true,
+    "sso": true
+  }
+}
+```
+
+### Budget-Friendly Options
+
+```json
+{
+  "models": [
+    {
+      "id": "gpt-3.5-turbo-budget",
+      "name": "GPT-3.5 Turbo Budget",
+      "pricing": {
+        "prompt": "0.0005",
+        "completion": "0.001"
+      },
+      "restrictions": {
+        "max_tokens_per_request": 1000,
+        "requests_per_minute": 10,
+        "peak_hours_blocked": true
+      }
+    }
+  ],
+  "prepaid_packages": [
+    {
+      "name": "Starter Pack",
+      "price_usd": 10,
+      "tokens_included": 10000000,
+      "expires_days": 30
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+### Price Calculation Issues
+
+```python
+# Debug pricing
+async def debug_price_calculation(
+    model: str,
+    tokens: dict,
+    api_key_id: int
+):
+    """Debug price calculation step by step."""
+    print(f"Model: {model}")
+    print(f"Tokens: {tokens}")
+    
+    # Base price
+    base_price = get_model_price(model)
+    print(f"Base price: {base_price}")
+    
+    # Token cost
+    token_cost = calculate_token_cost(base_price, tokens)
+    print(f"Token cost: {token_cost}")
+    
+    # Strategies
+    strategies = get_active_strategies()
+    for strategy in strategies:
+        multiplier = await strategy.get_multiplier(api_key_id)
+        print(f"{strategy.name}: {multiplier}x")
+    
+    # Final cost
+    final_cost = apply_all_strategies(token_cost, api_key_id)
+    print(f"Final cost: {final_cost} msats")
+    
+    return final_cost
+```
+
+### Common Issues
+
+1. **Prices Not Updating**
+   - Check `MODELS_PATH` is correct
+   - Verify file permissions
+   - Check background task logs
+
+2. **Wrong Currency Conversion**
+   - Verify BTC/USD rate source
+   - Check `EXCHANGE_FEE` setting
+   - Monitor rate update frequency
+
+3. **Discounts Not Applied**
+   - Verify strategy configuration
+   - Check API key metadata
+   - Review transaction history
+
+## Best Practices
+
+1. **Transparent Pricing**
+   - Publish pricing clearly
+   - Show cost breakdowns
+   - Notify of price changes
+
+2. **Fair Pricing**
+   - Regular competitive analysis
+   - Consider user feedback
+   - Offer budget options
+
+3. **Performance**
+   - Cache price calculations
+   - Optimize database queries
+   - Monitor calculation time
+
+## Next Steps
+
+- [Migrations](migrations.md) - Database migration guide
+- [API Endpoints](../api/endpoints.md) - Pricing endpoints
+- [Monitoring](../user-guide/admin-dashboard.md) - Track pricing metrics

docs/advanced/migrations.md

@@ -0,0 +1,646 @@
+# Database Migrations
+
+This guide covers database schema management using Alembic migrations in Routstr Core.
+
+## Overview
+
+Routstr uses Alembic for database migrations with these features:
+
+- **Automatic migrations** on startup
+- **Version control** for schema changes
+- **Rollback capability** for safety
+- **Support for multiple databases** (SQLite, PostgreSQL)
+
+## Automatic Migrations
+
+### Startup Behavior
+
+Migrations run automatically when Routstr starts:
+
+```python
+# In routstr/core/main.py
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
+    logger.info("Running database migrations")
+    run_migrations()  # Automatic migration
+    await init_db()   # Initialize connection pool
+    # ... rest of startup
+```
+
+This ensures:
+
+- ✅ Database is always up-to-date
+- ✅ No manual migration steps in production
+- ✅ Zero-downtime deployments
+- ✅ Backwards compatibility
+
+### Migration Safety
+
+Migrations are designed to be safe:
+
+- Idempotent (can run multiple times)
+- Non-destructive by default
+- Tested before release
+- Reversible when possible
+
+## Creating Migrations
+
+### Auto-generating from Models
+
+After modifying SQLModel classes:
+
+```bash
+# Generate migration from model changes
+make db-migrate
+
+# You'll be prompted for a description
+Enter migration message: Add user preferences table
+
+# Review generated file
+cat migrations/versions/xxxx_add_user_preferences_table.py
+```
+
+### Manual Migrations
+
+For complex changes, create manually:
+
+```bash
+# Create empty migration
+alembic revision -m "Complex data transformation"
+
+# Edit the generated file
+vim migrations/versions/xxxx_complex_data_transformation.py
+```
+
+### Migration Template
+
+```python
+"""Add user preferences table
+
+Revision ID: a1b2c3d4e5f6
+Revises: f6e5d4c3b2a1
+Create Date: 2024-01-15 10:30:00.123456
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+# revision identifiers
+revision = 'a1b2c3d4e5f6'
+down_revision = 'f6e5d4c3b2a1'
+branch_labels = None
+depends_on = None
+
+def upgrade() -> None:
+    """Apply migration."""
+    # Create new table
+    op.create_table(
+        'userpreferences',
+        sa.Column('id', sa.Integer(), nullable=False),
+        sa.Column('api_key_id', sa.Integer(), nullable=False),
+        sa.Column('theme', sa.String(), nullable=True),
+        sa.Column('notifications_enabled', sa.Boolean(), default=True),
+        sa.Column('created_at', sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint('id'),
+        sa.ForeignKeyConstraint(['api_key_id'], ['apikey.id'], )
+    )
+    
+    # Create index
+    op.create_index(
+        'ix_userpreferences_api_key_id',
+        'userpreferences',
+        ['api_key_id']
+    )
+
+def downgrade() -> None:
+    """Revert migration."""
+    op.drop_index('ix_userpreferences_api_key_id', table_name='userpreferences')
+    op.drop_table('userpreferences')
+```
+
+## Common Migration Patterns
+
+### Adding Columns
+
+Add column with default value:
+
+```python
+def upgrade():
+    # Add nullable column first
+    op.add_column(
+        'apikey',
+        sa.Column('last_rotation', sa.DateTime(), nullable=True)
+    )
+    
+    # Populate existing rows
+    connection = op.get_bind()
+    connection.execute(
+        "UPDATE apikey SET last_rotation = created_at WHERE last_rotation IS NULL"
+    )
+    
+    # Make non-nullable if needed
+    op.alter_column('apikey', 'last_rotation', nullable=False)
+```
+
+### Renaming Columns
+
+Safe column rename:
+
+```python
+def upgrade():
+    # SQLite doesn't support ALTER COLUMN, so we need a workaround
+    with op.batch_alter_table('apikey') as batch_op:
+        batch_op.alter_column('old_name', new_column_name='new_name')
+```
+
+### Adding Indexes
+
+Performance-improving indexes:
+
+```python
+def upgrade():
+    # Single column index
+    op.create_index(
+        'ix_transaction_timestamp',
+        'transaction',
+        ['timestamp']
+    )
+    
+    # Composite index
+    op.create_index(
+        'ix_transaction_key_time',
+        'transaction',
+        ['api_key_id', 'timestamp']
+    )
+    
+    # Partial index (PostgreSQL only)
+    op.create_index(
+        'ix_apikey_active',
+        'apikey',
+        ['balance'],
+        postgresql_where='balance > 0'
+    )
+```
+
+### Data Migrations
+
+Transform existing data:
+
+```python
+def upgrade():
+    # Add new column
+    op.add_column(
+        'apikey',
+        sa.Column('key_type', sa.String(), nullable=True)
+    )
+    
+    # Migrate data
+    connection = op.get_bind()
+    result = connection.execute('SELECT id, metadata FROM apikey')
+    
+    for row in result:
+        key_type = 'premium' if row.metadata.get('premium') else 'standard'
+        connection.execute(
+            f"UPDATE apikey SET key_type = '{key_type}' WHERE id = {row.id}"
+        )
+    
+    # Make column non-nullable
+    op.alter_column('apikey', 'key_type', nullable=False)
+```
+
+### Enum Types
+
+Add enum column:
+
+```python
+from enum import Enum
+
+class KeyStatus(str, Enum):
+    ACTIVE = "active"
+    SUSPENDED = "suspended"
+    EXPIRED = "expired"
+
+def upgrade():
+    # Create enum type (PostgreSQL)
+    key_status_enum = sa.Enum(KeyStatus, name='keystatus')
+    key_status_enum.create(op.get_bind(), checkfirst=True)
+    
+    # Add column
+    op.add_column(
+        'apikey',
+        sa.Column(
+            'status',
+            key_status_enum,
+            nullable=False,
+            server_default='active'
+        )
+    )
+```
+
+## Database-Specific Considerations
+
+### SQLite Limitations
+
+SQLite has limitations requiring workarounds:
+
+```python
+def upgrade():
+    # SQLite doesn't support ALTER COLUMN directly
+    # Use batch_alter_table for compatibility
+    with op.batch_alter_table('apikey') as batch_op:
+        batch_op.alter_column(
+            'balance',
+            type_=sa.BigInteger(),  # Change from Integer
+            existing_type=sa.Integer()
+        )
+```
+
+### PostgreSQL Features
+
+Leverage PostgreSQL-specific features:
+
+```python
+def upgrade():
+    # Use JSONB for better performance
+    op.add_column(
+        'apikey',
+        sa.Column('metadata', sa.JSON().with_variant(
+            sa.dialects.postgresql.JSONB(), 'postgresql'
+        ))
+    )
+    
+    # Add GIN index for JSONB queries
+    op.create_index(
+        'ix_apikey_metadata',
+        'apikey',
+        ['metadata'],
+        postgresql_using='gin'
+    )
+    
+    # Add check constraint
+    op.create_check_constraint(
+        'ck_apikey_balance_positive',
+        'apikey',
+        'balance >= 0'
+    )
+```
+
+## Migration Commands
+
+### Running Migrations
+
+```bash
+# Apply all pending migrations
+make db-upgrade
+
+# Upgrade to specific revision
+alembic upgrade a1b2c3d4e5f6
+
+# Upgrade one revision
+alembic upgrade +1
+```
+
+### Checking Status
+
+```bash
+# Show current revision
+make db-current
+# Output: a1b2c3d4e5f6 (head)
+
+# Show migration history
+make db-history
+# Output:
+# a1b2c3d4e5f6 -> b2c3d4e5f6a7 (head), Add user preferences
+# f6e5d4c3b2a1 -> a1b2c3d4e5f6, Add indexes
+# e5d4c3b2a1f6 -> f6e5d4c3b2a1, Initial schema
+```
+
+### Rolling Back
+
+```bash
+# Rollback one migration
+make db-downgrade
+
+# Rollback to specific revision
+alembic downgrade f6e5d4c3b2a1
+
+# Rollback all (dangerous!)
+alembic downgrade base
+```
+
+## Testing Migrations
+
+### Unit Testing
+
+Test migrations in isolation:
+
+```python
+import pytest
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import create_engine, inspect
+
+def test_migration_add_user_preferences():
+    """Test user preferences migration."""
+    # Create test database
+    engine = create_engine("sqlite:///:memory:")
+    
+    # Run migrations up to previous version
+    alembic_cfg = Config("alembic.ini")
+    alembic_cfg.set_main_option("sqlalchemy.url", str(engine.url))
+    command.upgrade(alembic_cfg, "f6e5d4c3b2a1")
+    
+    # Verify state before migration
+    inspector = inspect(engine)
+    tables = inspector.get_table_names()
+    assert "userpreferences" not in tables
+    
+    # Run target migration
+    command.upgrade(alembic_cfg, "a1b2c3d4e5f6")
+    
+    # Verify state after migration
+    inspector = inspect(engine)
+    tables = inspector.get_table_names()
+    assert "userpreferences" in tables
+    
+    # Check columns
+    columns = {col['name'] for col in inspector.get_columns('userpreferences')}
+    assert columns == {'id', 'api_key_id', 'theme', 'notifications_enabled', 'created_at'}
+    
+    # Test downgrade
+    command.downgrade(alembic_cfg, "f6e5d4c3b2a1")
+    inspector = inspect(engine)
+    tables = inspector.get_table_names()
+    assert "userpreferences" not in tables
+```
+
+### Integration Testing
+
+Test with real data:
+
+```python
+async def test_migration_with_data():
+    """Test migration preserves existing data."""
+    # Setup test database with data
+    async with test_engine.begin() as conn:
+        # Insert test data
+        await conn.execute(
+            "INSERT INTO apikey (key_hash, balance) VALUES ('test', 1000)"
+        )
+    
+    # Run migration
+    run_migrations()
+    
+    # Verify data integrity
+    async with test_engine.connect() as conn:
+        result = await conn.execute("SELECT * FROM apikey WHERE key_hash = 'test'")
+        row = result.first()
+        assert row.balance == 1000
+        assert row.key_type == 'standard'  # New column with default
+```
+
+## Production Deployment
+
+### Zero-Downtime Migrations
+
+Strategy for seamless updates:
+
+1. **Make migrations backwards compatible**
+
+   ```python
+   # Good: Add nullable column
+   op.add_column('apikey', sa.Column('new_field', sa.String(), nullable=True))
+   
+   # Bad: Drop column immediately
+   # op.drop_column('apikey', 'old_field')
+   ```
+
+2. **Deploy in phases**
+
+   ```bash
+   # Phase 1: Deploy code that works with both schemas
+   # Phase 2: Run migration
+   # Phase 3: Deploy code that requires new schema
+   # Phase 4: Clean up deprecated columns
+   ```
+
+3. **Use feature flags**
+
+   ```python
+   if feature_enabled('use_new_schema'):
+       # Use new column
+       query = select(APIKey.new_field)
+   else:
+       # Use old column
+       query = select(APIKey.old_field)
+   ```
+
+### Migration Monitoring
+
+Track migration execution:
+
+```python
+# Add to migration
+def upgrade():
+    start_time = time.time()
+    logger.info(f"Starting migration {revision}")
+    
+    try:
+        # Migration logic here
+        op.create_table(...)
+        
+        duration = time.time() - start_time
+        logger.info(f"Migration {revision} completed in {duration:.2f}s")
+    except Exception as e:
+        logger.error(f"Migration {revision} failed: {e}")
+        raise
+```
+
+### Backup Before Migration
+
+Always backup before major changes:
+
+```bash
+#!/bin/bash
+# backup_before_migration.sh
+
+# Backup database
+if [[ "$DATABASE_URL" == *"sqlite"* ]]; then
+    cp database.db "backup_$(date +%Y%m%d_%H%M%S).db"
+else
+    pg_dump $DATABASE_URL > "backup_$(date +%Y%m%d_%H%M%S).sql"
+fi
+
+# Run migration
+alembic upgrade head
+
+# Verify
+alembic current
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Migration Conflicts**
+
+```bash
+# Multiple heads detected
+alembic heads
+# a1b2c3d4e5f6 (head)
+# b2c3d4e5f6a7 (head)
+
+# Merge heads
+alembic merge -m "Merge migrations" a1b2c3 b2c3d4
+```
+
+**Failed Migration**
+
+```python
+# Add rollback logic
+def upgrade():
+    try:
+        op.create_table(...)
+    except Exception as e:
+        # Clean up partial changes
+        op.drop_table('partial_table', checkfirst=True)
+        raise
+
+def downgrade():
+    # Ensure clean rollback
+    op.drop_table('new_table', checkfirst=True)
+```
+
+**Lock Timeout**
+
+```python
+# Add timeout handling
+def upgrade():
+    connection = op.get_bind()
+    
+    # Set timeout (PostgreSQL)
+    connection.execute("SET lock_timeout = '10s'")
+    
+    try:
+        op.add_column(...)
+    except OperationalError as e:
+        if 'lock timeout' in str(e):
+            logger.error("Migration failed due to lock timeout")
+            raise
+```
+
+### Recovery Procedures
+
+If migration fails in production:
+
+1. **Check current state**
+
+   ```bash
+   alembic current
+   alembic history
+   ```
+
+2. **Manual rollback if needed**
+
+   ```sql
+   -- Check migration table
+   SELECT * FROM alembic_version;
+   
+   -- Force version if necessary
+   UPDATE alembic_version SET version_num = 'previous_version';
+   ```
+
+3. **Fix and retry**
+
+   ```bash
+   # Fix migration file
+   vim migrations/versions/problematic_migration.py
+   
+   # Retry
+   alembic upgrade head
+   ```
+
+## Best Practices
+
+### Migration Guidelines
+
+1. **Keep migrations small and focused**
+   - One logical change per migration
+   - Easier to review and rollback
+
+2. **Test migrations thoroughly**
+   - Test upgrade and downgrade
+   - Test with production-like data
+   - Test database-specific features
+
+3. **Document breaking changes**
+
+   ```python
+   """BREAKING: Change balance column type
+   
+   This migration requires application update.
+   Deploy order:
+   1. Update application to handle both int and bigint
+   2. Run this migration
+   3. Update application to use only bigint
+   """
+   ```
+
+4. **Make migrations idempotent**
+
+   ```python
+   def upgrade():
+       # Check if column exists
+       inspector = inspect(op.get_bind())
+       columns = [col['name'] for col in inspector.get_columns('apikey')]
+       
+       if 'new_column' not in columns:
+           op.add_column(
+               'apikey',
+               sa.Column('new_column', sa.String())
+           )
+   ```
+
+### Performance Considerations
+
+1. **Add indexes concurrently (PostgreSQL)**
+
+   ```python
+   def upgrade():
+       # Create index without locking table
+       op.create_index(
+           'ix_large_table_column',
+           'large_table',
+           ['column'],
+           postgresql_concurrently=True
+       )
+   ```
+
+2. **Batch large updates**
+
+   ```python
+   def upgrade():
+       connection = op.get_bind()
+       
+       # Process in batches
+       batch_size = 1000
+       offset = 0
+       
+       while True:
+           result = connection.execute(
+               f"UPDATE apikey SET processed = true "
+               f"WHERE id IN (SELECT id FROM apikey WHERE processed = false LIMIT {batch_size})"
+           )
+           
+           if result.rowcount == 0:
+               break
+               
+           offset += batch_size
+           time.sleep(0.1)  # Prevent overload
+   ```
+
+## Next Steps
+
+- [Testing Guide](../contributing/testing.md) - Testing migrations
+- [Deployment](../getting-started/docker.md) - Production deployment

docs/advanced/nostr.md

@@ -0,0 +1,598 @@
+# Nostr Discovery
+
+Routstr Core integrates with Nostr (Notes and Other Stuff Transmitted by Relays) for decentralized provider discovery. This enables users to find Routstr nodes without relying on centralized directories.
+
+## Overview
+
+Nostr integration provides:
+
+- **Decentralized Discovery**: Find providers through relay network
+- **Cryptographic Identity**: Providers identified by public keys
+- **Real-time Updates**: Live provider status and pricing
+- **Censorship Resistance**: No central point of control
+
+## How It Works
+
+```mermaid
+graph LR
+    A[Routstr Node] --> B[Nostr Relay]
+    B --> C[Nostr Relay]
+    B --> D[Nostr Relay]
+    
+    E[User Client] --> B
+    E --> C
+    E --> D
+    
+    B --> F[Provider List]
+    C --> F
+    D --> F
+```
+
+Providers announce themselves by publishing signed events to Nostr relays. Clients can query these relays to discover available providers.
+
+## Provider Configuration
+
+### Setting Up Nostr Identity
+
+1. **Generate Nostr Keys**
+
+   ```bash
+   # Using nostril or similar tool
+   nostril --generate-keypair
+   
+   # Output:
+   # Private key (nsec): nsec1abc...
+   # Public key (npub): npub1xyz...
+   ```
+
+2. **Configure Environment**
+
+   ```bash
+   # .env
+   NPUB=npub1xyz...  # Your public key
+   NSEC=nsec1abc...  # Your private key (keep secret!)
+   NAME=Lightning AI Gateway
+   DESCRIPTION=Fast and reliable AI API with Bitcoin payments
+   HTTP_URL=https://api.lightning-ai.com
+   ONION_URL=http://lightningai.onion
+   ```
+
+### Publishing to Nostr
+
+Routstr automatically publishes provider information to configured relays:
+
+```python
+# Published event structure (NIP-89)
+{
+    "kind": 31990,  # Application handler event
+    "pubkey": "your_public_key",
+    "content": {
+        "name": "Lightning AI Gateway",
+        "description": "Fast and reliable AI API",
+        "endpoints": {
+            "http": "https://api.lightning-ai.com",
+            "onion": "http://lightningai.onion"
+        },
+        "models": ["gpt-3.5-turbo", "gpt-4", "claude-3"],
+        "pricing": {
+            "gpt-3.5-turbo": {
+                "prompt_sats_per_1k": 3,
+                "completion_sats_per_1k": 4
+            }
+        },
+        "cashu_mints": [
+            "https://mint.minibits.cash/Bitcoin"
+        ]
+    },
+    "tags": [
+        ["d", "routstr"],
+        ["t", "ai-api"],
+        ["t", "bitcoin"],
+        ["p", "payment-proxy"]
+    ]
+}
+```
+
+### Relay Configuration
+
+Configure which relays to publish to:
+
+```python
+# Default relays
+DEFAULT_RELAYS = [
+    "wss://relay.damus.io",
+    "wss://relay.nostr.band",
+    "wss://relay.routstr.com",
+    "wss://nos.lol"
+]
+
+# Custom relay configuration
+RELAYS=wss://relay1.com,wss://relay2.com
+```
+
+## Client Discovery
+
+### Using the Discovery Endpoint
+
+Find providers through the API:
+
+```bash
+GET /v1/providers
+
+Response:
+{
+  "providers": [
+    {
+      "name": "Lightning AI Gateway",
+      "npub": "npub1xyz...",
+      "description": "Fast and reliable AI API",
+      "endpoints": {
+        "http": "https://api.lightning-ai.com",
+        "onion": "http://lightningai.onion"
+      },
+      "models": ["gpt-3.5-turbo", "gpt-4"],
+      "pricing": {
+        "gpt-3.5-turbo": {
+          "prompt_sats_per_1k": 3,
+          "completion_sats_per_1k": 4
+        }
+      },
+      "last_seen": "2024-01-01T12:00:00Z",
+      "reliability_score": 0.99
+    }
+  ]
+}
+```
+
+### Direct Nostr Queries
+
+Query Nostr relays directly:
+
+```python
+import json
+import websocket
+
+def discover_providers(relay_url: str):
+    """Discover Routstr providers from Nostr relay."""
+    ws = websocket.create_connection(relay_url)
+    
+    # Subscribe to provider events
+    subscription = {
+        "kinds": [31990],
+        "tags": {
+            "d": ["routstr"]
+        }
+    }
+    
+    ws.send(json.dumps(["REQ", "sub1", subscription]))
+    
+    providers = []
+    while True:
+        response = json.loads(ws.recv())
+        if response[0] == "EVENT":
+            event = response[2]
+            providers.append(parse_provider_event(event))
+        elif response[0] == "EOSE":  # End of stored events
+            break
+    
+    ws.close()
+    return providers
+```
+
+### JavaScript/TypeScript
+
+```typescript
+import { SimplePool } from 'nostr-tools';
+
+async function discoverProviders(): Promise<Provider[]> {
+    const pool = new SimplePool();
+    const relays = [
+        'wss://relay.damus.io',
+        'wss://relay.nostr.band'
+    ];
+    
+    const filter = {
+        kinds: [31990],
+        '#d': ['routstr']
+    };
+    
+    const events = await pool.list(relays, [filter]);
+    
+    return events.map(event => ({
+        name: event.content.name,
+        npub: nip19.npubEncode(event.pubkey),
+        url: event.content.endpoints.http,
+        models: event.content.models,
+        pricing: event.content.pricing
+    }));
+}
+```
+
+## Provider Ranking
+
+### Reliability Scoring
+
+Providers are ranked based on:
+
+```python
+class ProviderScore:
+    def calculate(self, provider: Provider) -> float:
+        score = 1.0
+        
+        # Uptime (based on recent checks)
+        uptime_ratio = provider.successful_pings / provider.total_pings
+        score *= uptime_ratio
+        
+        # Response time
+        if provider.avg_response_time < 500:  # ms
+            score *= 1.0
+        elif provider.avg_response_time < 1000:
+            score *= 0.9
+        else:
+            score *= 0.7
+        
+        # Model availability
+        model_score = len(provider.models) / 10  # Max 10 models
+        score *= min(1.0, 0.5 + model_score * 0.5)
+        
+        # Price competitiveness
+        if provider.is_cheapest_for_any_model():
+            score *= 1.1
+        
+        return min(1.0, score)
+```
+
+### Provider Selection
+
+Choose optimal provider:
+
+```python
+def select_provider(
+    providers: list[Provider],
+    model: str,
+    requirements: dict
+) -> Provider:
+    """Select best provider for requirements."""
+    
+    # Filter by model availability
+    candidates = [p for p in providers if model in p.models]
+    
+    # Filter by requirements
+    if requirements.get('tor_required'):
+        candidates = [p for p in candidates if p.onion_url]
+    
+    if requirements.get('max_price_per_1k'):
+        max_price = requirements['max_price_per_1k']
+        candidates = [
+            p for p in candidates
+            if p.pricing[model]['prompt_sats_per_1k'] <= max_price
+        ]
+    
+    # Sort by score
+    candidates.sort(key=lambda p: p.reliability_score, reverse=True)
+    
+    return candidates[0] if candidates else None
+```
+
+## Publishing Updates
+
+### Automatic Updates
+
+Routstr publishes updates when:
+
+- Node starts up
+- Configuration changes
+- Models are added/removed
+- Pricing updates
+
+### Manual Publishing
+
+Force publish current state:
+
+```python
+async def publish_provider_info():
+    """Manually publish provider information."""
+    event = create_provider_event(
+        name=os.getenv("NAME"),
+        description=os.getenv("DESCRIPTION"),
+        models=get_available_models(),
+        pricing=get_current_pricing()
+    )
+    
+    await publish_to_relays(event, RELAYS)
+```
+
+### Event Lifecycle
+
+```python
+# Publish every 6 hours
+@periodic_task(hours=6)
+async def update_nostr_presence():
+    """Keep provider information fresh."""
+    try:
+        await publish_provider_info()
+        logger.info("Updated Nostr presence")
+    except Exception as e:
+        logger.error(f"Failed to update Nostr: {e}")
+
+# Delete on shutdown
+async def remove_nostr_presence():
+    """Remove provider from discovery."""
+    deletion_event = create_deletion_event()
+    await publish_to_relays(deletion_event, RELAYS)
+```
+
+## Security Considerations
+
+### Key Management
+
+1. **Secure Storage**
+
+   ```python
+   # Never log private keys
+   SENSITIVE_VARS = ['NSEC', 'ADMIN_PASSWORD']
+   
+   def sanitize_env(env_dict: dict) -> dict:
+       return {
+           k: '***' if k in SENSITIVE_VARS else v
+           for k, v in env_dict.items()
+       }
+   ```
+
+2. **Key Rotation**
+
+   ```bash
+   # Generate new keys
+   nostril --generate-keypair
+   
+   # Update configuration
+   # Publish transition event
+   # Update all references
+   ```
+
+### Event Validation
+
+Verify provider events:
+
+```python
+def validate_provider_event(event: dict) -> bool:
+    """Validate provider announcement."""
+    # Check signature
+    if not verify_signature(event):
+        return False
+    
+    # Check required fields
+    required = ['name', 'endpoints', 'models', 'pricing']
+    content = json.loads(event['content'])
+    if not all(field in content for field in required):
+        return False
+    
+    # Verify endpoints are reachable
+    if not await check_endpoints(content['endpoints']):
+        return False
+    
+    return True
+```
+
+### Relay Security
+
+Choose relays carefully:
+
+```python
+TRUSTED_RELAYS = {
+    'wss://relay.damus.io': {
+        'operator': 'Damus',
+        'reputation': 'high',
+        'filters_spam': True
+    },
+    'wss://relay.nostr.band': {
+        'operator': 'Nostr.Band',
+        'reputation': 'high',
+        'paid_tier': True
+    }
+}
+```
+
+## Advanced Features
+
+### Multi-Relay Broadcasting
+
+Ensure wide distribution:
+
+```python
+async def broadcast_to_relays(event: dict, relays: list[str]):
+    """Broadcast event to multiple relays."""
+    tasks = []
+    for relay in relays:
+        task = asyncio.create_task(
+            publish_to_relay(event, relay)
+        )
+        tasks.append(task)
+    
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+    
+    successful = sum(1 for r in results if not isinstance(r, Exception))
+    logger.info(f"Published to {successful}/{len(relays)} relays")
+```
+
+### Provider Metadata
+
+Extended metadata in events:
+
+```json
+{
+    "kind": 31990,
+    "content": {
+        "name": "Lightning AI",
+        "description": "Enterprise AI API",
+        "metadata": {
+            "established": "2024-01-01",
+            "total_requests": 1000000,
+            "average_response_ms": 250,
+            "supported_features": [
+                "streaming",
+                "function_calling",
+                "vision",
+                "embeddings"
+            ],
+            "certifications": ["SOC2", "GDPR"],
+            "contact": {
+                "nostr": "npub1contact...",
+                "email": "support@lightning-ai.com"
+            }
+        }
+    }
+}
+```
+
+### Discovery Filters
+
+Advanced filtering options:
+
+```python
+# Find providers with specific features
+GET /v1/providers?features=streaming,vision&max_price=5&min_reliability=0.95
+
+# Response includes filtered results
+{
+    "providers": [...],
+    "filters_applied": {
+        "features": ["streaming", "vision"],
+        "max_price_sats_per_1k": 5,
+        "min_reliability": 0.95
+    },
+    "total_providers": 50,
+    "matching_providers": 12
+}
+```
+
+## Monitoring
+
+### Discovery Metrics
+
+Track discovery performance:
+
+```python
+class DiscoveryMetrics:
+    def __init__(self):
+        self.relay_health = {}
+        self.provider_count = 0
+        self.query_latency = []
+    
+    async def check_relay_health(self, relay_url: str):
+        """Monitor relay connectivity."""
+        start = time.time()
+        try:
+            await connect_to_relay(relay_url)
+            latency = time.time() - start
+            self.relay_health[relay_url] = {
+                'status': 'healthy',
+                'latency_ms': latency * 1000
+            }
+        except Exception as e:
+            self.relay_health[relay_url] = {
+                'status': 'unhealthy',
+                'error': str(e)
+            }
+```
+
+### Provider Monitoring
+
+```python
+@periodic_task(minutes=5)
+async def monitor_providers():
+    """Check provider health."""
+    providers = await discover_providers()
+    
+    for provider in providers:
+        try:
+            # Test endpoint
+            response = await test_provider_endpoint(provider.http_url)
+            
+            # Update metrics
+            await update_provider_metrics(
+                provider.npub,
+                success=response.status_code == 200,
+                response_time=response.elapsed
+            )
+        except Exception as e:
+            logger.warning(f"Provider {provider.name} check failed: {e}")
+```
+
+## Troubleshooting
+
+### No Providers Found
+
+```python
+# Debug discovery issues
+async def debug_discovery():
+    """Diagnose discovery problems."""
+    issues = []
+    
+    # Check relay connectivity
+    for relay in RELAYS:
+        if not await can_connect_to_relay(relay):
+            issues.append(f"Cannot connect to {relay}")
+    
+    # Check event publishing
+    if not await verify_own_events_visible():
+        issues.append("Own events not visible on relays")
+    
+    # Check filters
+    if len(await get_all_provider_events()) == 0:
+        issues.append("No provider events on any relay")
+    
+    return issues
+```
+
+### Relay Connection Issues
+
+```bash
+# Test relay connection
+wscat -c wss://relay.damus.io
+
+# Send subscription
+["REQ","test",{"kinds":[31990],"#d":["routstr"]}]
+```
+
+## Best Practices
+
+### For Providers
+
+1. **Consistent Identity**
+   - Use same npub across services
+   - Maintain profile metadata
+   - Verify identity on multiple platforms
+
+2. **Regular Updates**
+   - Publish status every few hours
+   - Update pricing promptly
+   - Remove stale information
+
+3. **Relay Diversity**
+   - Publish to 5+ relays
+   - Include regional relays
+   - Monitor relay health
+
+### For Clients
+
+1. **Verify Providers**
+   - Check multiple relays
+   - Verify endpoints work
+   - Monitor reliability over time
+
+2. **Cache Discovery**
+   - Cache provider list
+   - Refresh periodically
+   - Handle stale data gracefully
+
+3. **Fallback Options**
+   - Keep backup providers
+   - Handle discovery failures
+   - Support manual configuration
+
+## Next Steps
+
+- [Tor Support](tor.md) - Anonymous provider access
+- [Custom Pricing](custom-pricing.md) - Dynamic pricing strategies
+- [API Reference](../api/endpoints.md) - Discovery API details

docs/advanced/tor.md

@@ -0,0 +1,530 @@
+# Tor Support
+
+Routstr Core includes built-in support for Tor hidden services, enabling anonymous access to your API and enhanced privacy for users.
+
+## Overview
+
+Tor support provides:
+
+- **Anonymous Access**: Hidden service (.onion) address
+- **Enhanced Privacy**: No IP address logging
+- **Censorship Resistance**: Accessible from restricted networks
+- **Optional Usage**: Regular HTTP/HTTPS access remains available
+
+## Docker Setup
+
+### Using Docker Compose
+
+The included `compose.yml` automatically sets up Tor:
+
+```yaml
+version: '3.8'
+
+services:
+  routstr:
+    build: .
+    environment:
+      - TOR_PROXY_URL=socks5://tor:9050
+    ports:
+      - 8000:8000
+
+  tor:
+    image: ghcr.io/hundehausen/tor-hidden-service:latest
+    volumes:
+      - tor-data:/var/lib/tor
+    environment:
+      - HS_ROUTER=routstr:8000:80
+    depends_on:
+      - routstr
+
+volumes:
+  tor-data:
+```
+
+Start with:
+
+```bash
+docker compose up -d
+```
+
+### Getting Your Onion Address
+
+After starting, retrieve your hidden service address:
+
+```bash
+# View Tor logs
+docker compose logs tor
+
+# Or directly from the hostname file
+docker exec tor cat /var/lib/tor/hidden_service/hostname
+```
+
+Your onion address will look like:
+
+```
+roustrjfsdgfiueghsklchg.onion
+```
+
+## Manual Tor Setup
+
+### Install Tor
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install tor
+
+# macOS
+brew install tor
+
+# Start Tor
+sudo systemctl start tor
+```
+
+### Configure Hidden Service
+
+Edit `/etc/tor/torrc`:
+
+```bash
+# Hidden service configuration
+HiddenServiceDir /var/lib/tor/routstr/
+HiddenServicePort 80 127.0.0.1:8000
+
+# Optional: Restrict to v3 addresses
+HiddenServiceVersion 3
+```
+
+Restart Tor:
+
+```bash
+sudo systemctl restart tor
+```
+
+Get onion address:
+
+```bash
+sudo cat /var/lib/tor/routstr/hostname
+```
+
+## Client Configuration
+
+### Using Tor with Python
+
+```python
+import httpx
+from openai import OpenAI
+
+# Configure SOCKS proxy
+proxies = {
+    "http://": "socks5://127.0.0.1:9050",
+    "https://": "socks5://127.0.0.1:9050"
+}
+
+# Create client with Tor
+http_client = httpx.Client(proxies=proxies)
+
+client = OpenAI(
+    api_key="sk-...",
+    base_url="http://roustrjfsdgfiueghsklchg.onion/v1",
+    http_client=http_client
+)
+
+# Use normally
+response = client.chat.completions.create(
+    model="gpt-3.5-turbo",
+    messages=[{"role": "user", "content": "Hello via Tor!"}]
+)
+```
+
+### Using Tor with cURL
+
+```bash
+# Install torify
+sudo apt-get install torsocks
+
+# Make request through Tor
+torify curl http://roustrjfsdgfiueghsklchg.onion/v1/models
+
+# Or with explicit proxy
+curl --socks5 127.0.0.1:9050 http://roustrjfsdgfiueghsklchg.onion/v1/models
+```
+
+### JavaScript/Node.js
+
+```javascript
+import { SocksProxyAgent } from 'socks-proxy-agent';
+import OpenAI from 'openai';
+
+// Create SOCKS agent
+const agent = new SocksProxyAgent('socks5://127.0.0.1:9050');
+
+// Configure OpenAI client
+const openai = new OpenAI({
+    apiKey: 'sk-...',
+    baseURL: 'http://roustrjfsdgfiueghsklchg.onion/v1',
+    httpAgent: agent
+});
+
+// Use normally
+const response = await openai.chat.completions.create({
+    model: 'gpt-3.5-turbo',
+    messages: [{ role: 'user', content: 'Hello via Tor!' }]
+});
+```
+
+## Configuration
+
+### Environment Variables
+
+Configure Tor proxy for outgoing connections:
+
+```bash
+# .env
+TOR_PROXY_URL=socks5://tor:9050  # Docker
+# or
+TOR_PROXY_URL=socks5://127.0.0.1:9050  # Local
+```
+
+### Publishing Onion Address
+
+Make your onion address discoverable:
+
+```bash
+# .env
+ONION_URL=http://roustrjfsdgfiueghsklchg.onion
+```
+
+This will be included in:
+
+- `/v1/info` endpoint
+- Nostr announcements
+- Admin dashboard
+
+## Security Considerations
+
+### Hidden Service Security
+
+1. **Keep Private Key Secure**
+
+   ```bash
+   # Backup hidden service keys
+   sudo tar -czf tor-keys-backup.tar.gz /var/lib/tor/routstr/
+   
+   # Restore to maintain same address
+   sudo tar -xzf tor-keys-backup.tar.gz -C /
+   ```
+
+2. **Access Control**
+
+   ```bash
+   # Restrict to authenticated clients
+   HiddenServiceAuthorizeClient stealth client1,client2
+   ```
+
+3. **Rate Limiting**
+
+   ```bash
+   # In torrc
+   HiddenServiceMaxStreams 100
+   HiddenServiceMaxStreamsCloseCircuit 1
+   ```
+
+### Operational Security
+
+1. **Separate Tor Instance**
+
+   ```yaml
+   # Use dedicated Tor container
+   tor:
+     image: ghcr.io/hundehausen/tor-hidden-service:latest
+     restart: always
+     networks:
+       - tor_network
+   ```
+
+2. **Monitor Tor Health**
+
+   ```python
+   async def check_tor_connection():
+       """Verify Tor connectivity."""
+       try:
+           async with httpx.AsyncClient(
+               proxies={"all://": TOR_PROXY_URL}
+           ) as client:
+               response = await client.get(
+                   "https://check.torproject.org/api/ip"
+               )
+               data = response.json()
+               return data.get("IsTor", False)
+       except Exception:
+           return False
+   ```
+
+3. **Logging Considerations**
+
+   ```python
+   # Don't log .onion addresses with IPs
+   def sanitize_logs(message: str) -> str:
+       # Remove IP addresses when .onion is present
+       if ".onion" in message:
+           message = re.sub(r'\d+\.\d+\.\d+\.\d+', '[IP]', message)
+       return message
+   ```
+
+## Performance Optimization
+
+### Connection Pooling
+
+```python
+# Reuse Tor circuits
+class TorConnectionPool:
+    def __init__(self, proxy_url: str):
+        self.proxy_url = proxy_url
+        self._clients = []
+    
+    async def get_client(self) -> httpx.AsyncClient:
+        if not self._clients:
+            client = httpx.AsyncClient(
+                proxies={"all://": self.proxy_url},
+                timeout=httpx.Timeout(30.0),
+                limits=httpx.Limits(
+                    max_keepalive_connections=5,
+                    max_connections=10
+                )
+            )
+            self._clients.append(client)
+        return self._clients[0]
+```
+
+### Circuit Management
+
+```python
+# Rotate Tor circuits periodically
+async def rotate_tor_circuit():
+    """Signal Tor to create new circuit."""
+    async with httpx.AsyncClient() as client:
+        # Tor control port (requires configuration)
+        response = await client.post(
+            "http://localhost:9051",
+            data="AUTHENTICATE\r\nSIGNAL NEWNYM\r\n"
+        )
+```
+
+### Caching Strategies
+
+```python
+# Cache responses for Tor users
+@lru_cache(maxsize=1000)
+def get_cached_response(
+    endpoint: str,
+    params_hash: str
+) -> Optional[dict]:
+    """Cache frequently accessed data."""
+    # Longer cache for Tor users due to latency
+    return cache.get(f"tor:{endpoint}:{params_hash}")
+```
+
+## Monitoring
+
+### Tor Metrics
+
+Track Tor-specific metrics:
+
+```python
+class TorMetrics:
+    def __init__(self):
+        self.tor_requests = 0
+        self.tor_errors = 0
+        self.circuit_builds = 0
+        self.average_latency = 0
+    
+    async def record_request(
+        self,
+        duration: float,
+        success: bool
+    ):
+        self.tor_requests += 1
+        if not success:
+            self.tor_errors += 1
+        
+        # Update average latency
+        self.average_latency = (
+            (self.average_latency * (self.tor_requests - 1) + duration)
+            / self.tor_requests
+        )
+```
+
+### Health Checks
+
+```python
+@router.get("/health/tor")
+async def tor_health():
+    """Check Tor service health."""
+    checks = {
+        "tor_proxy": await check_tor_proxy(),
+        "hidden_service": await check_hidden_service(),
+        "circuit_established": await check_circuit()
+    }
+    
+    status = "healthy" if all(checks.values()) else "unhealthy"
+    
+    return {
+        "status": status,
+        "checks": checks,
+        "metrics": {
+            "tor_requests_total": metrics.tor_requests,
+            "tor_error_rate": metrics.tor_errors / max(metrics.tor_requests, 1),
+            "average_latency_ms": metrics.average_latency * 1000
+        }
+    }
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Hidden Service Not Accessible**
+
+```bash
+# Check Tor logs
+docker compose logs tor
+# or
+sudo journalctl -u tor
+
+# Verify service is running
+sudo systemctl status tor
+
+# Test locally
+curl --socks5 127.0.0.1:9050 http://your-onion.onion/v1/info
+```
+
+**Slow Connection**
+
+- Tor adds 3+ hops of latency
+- Use connection pooling
+- Implement aggressive caching
+- Consider increasing timeouts
+
+**Connection Errors**
+
+```python
+# Implement Tor-specific retry logic
+async def tor_retry(func, max_retries=5):
+    for attempt in range(max_retries):
+        try:
+            return await func()
+        except httpx.ProxyError:
+            if attempt < max_retries - 1:
+                # Exponential backoff for circuit building
+                await asyncio.sleep(2 ** attempt)
+            else:
+                raise
+```
+
+### Debugging
+
+Enable Tor debug logging:
+
+```bash
+# In torrc
+Log debug file /var/log/tor/debug.log
+
+# Monitor in real-time
+tail -f /var/log/tor/debug.log
+```
+
+## Best Practices
+
+### For Operators
+
+1. **Backup Hidden Service Keys**
+   - Store securely offline
+   - Enables service recovery
+   - Maintains same .onion address
+
+2. **Monitor Tor Health**
+   - Check circuit establishment
+   - Track request latency
+   - Alert on failures
+
+3. **Separate Concerns**
+   - Run Tor in separate container
+   - Isolate from main application
+   - Use internal networks
+
+### For Users
+
+1. **Verify Onion Addresses**
+   - Check against multiple sources
+   - Bookmark verified addresses
+   - Watch for phishing
+
+2. **Handle Higher Latency**
+   - Increase client timeouts
+   - Implement retries
+   - Use connection pooling
+
+3. **Enhance Privacy**
+   - Use Tor Browser for web access
+   - Avoid mixing Tor/clearnet
+   - Don't include identifying info
+
+## Advanced Configuration
+
+### Multi-Hop Onion Services
+
+For extra security, chain multiple Tor instances:
+
+```yaml
+# compose.yml
+services:
+  tor-entry:
+    image: tor:latest
+    command: tor -f /etc/tor/torrc.entry
+    
+  tor-middle:
+    image: tor:latest
+    command: tor -f /etc/tor/torrc.middle
+    
+  tor-exit:
+    image: tor:latest
+    command: tor -f /etc/tor/torrc.exit
+```
+
+### Onion Service Authentication
+
+Require client authorization:
+
+```bash
+# Generate client auth
+openssl rand -base64 32 > client_auth_key
+
+# In torrc
+HiddenServiceDir /var/lib/tor/routstr/
+HiddenServicePort 80 127.0.0.1:8000
+HiddenServiceAuthorizeClient stealth payments
+```
+
+### Load Balancing
+
+Distribute load across multiple instances:
+
+```nginx
+# Onion service nginx config
+upstream routstr_backends {
+    server routstr1:8000;
+    server routstr2:8000;
+    server routstr3:8000;
+}
+
+server {
+    listen 80;
+    location / {
+        proxy_pass http://routstr_backends;
+    }
+}
+```
+
+## Next Steps
+
+- [Nostr Discovery](nostr.md) - Announce your onion service
+- [Docker Setup](../getting-started/docker.md) - Container configuration

docs/api/authentication.md

@@ -0,0 +1,428 @@
+# Authentication
+
+Routstr uses API key authentication for all protected endpoints. This guide covers how to create, use, and manage API keys.
+
+## API Key Creation
+
+### From eCash Token
+
+Create an API key by depositing an eCash token:
+
+**Note: The POST /v1/wallet/create endpoint is coming soon. Currently, you can use Cashu tokens directly as API credentials in the Authorization header. The token is hashed on the server, and the hash acts as an API key with the token's balance.**
+
+```bash
+POST /v1/wallet/create
+Content-Type: application/json
+
+{
+  "cashu_token": "cashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vbWlu..."
+}
+```
+
+**Request Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `cashu_token` | string | Yes | Base64-encoded Cashu token |
+
+**Response:**
+
+```json
+{
+  "api_key": "sk-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
+  "balance": 10000,
+  "created_at": "2024-01-01T00:00:00Z",
+  "key_id": "key_123456"
+}
+```
+
+### From Lightning Invoice (Coming Soon)
+
+```bash
+POST /v1/wallet/create/lightning
+Content-Type: application/json
+
+{
+  "amount_sats": 10000,
+  "name": "Lightning Key"
+}
+```
+
+Response includes Lightning invoice for payment.
+
+## Using API Keys
+
+### Header Authentication
+
+Include the API key in the Authorization header:
+
+```bash
+curl https://your-node.com/v1/chat/completions \
+  -H "Authorization: Bearer sk-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+### Query Parameter (Not Recommended)
+
+For tools that don't support headers:
+
+```bash
+GET /v1/models?api_key=sk-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
+```
+
+⚠️ **Warning**: Query parameters may be logged. Use headers when possible.
+
+## Key Management
+
+### Check Balance
+
+Get current balance and usage statistics:
+
+```bash
+GET /v1/wallet/balance
+Authorization: Bearer sk-...
+
+Response:
+{
+  "balance": 8546,
+  "total_deposited": 10000,
+  "total_spent": 1454,
+  "last_used": "2024-01-01T12:34:56Z",
+  "created_at": "2024-01-01T00:00:00Z",
+  "expires_at": null,
+  "key_info": {
+    "name": "Production Key",
+    "key_id": "key_123456"
+  }
+}
+```
+
+### Top Up Balance
+
+Add funds to existing key:
+
+```bash
+POST /v1/wallet/topup
+Authorization: Bearer sk-...
+Content-Type: application/json
+
+{
+  "cashu_token": "cashuAeyJ0b2tlbiI6W3..."
+}
+
+Response:
+{
+  "old_balance": 8546,
+  "added_amount": 5000,
+  "new_balance": 13546,
+  "transaction_id": "txn_789"
+}
+```
+
+### List Transactions
+
+View transaction history:
+
+```bash
+GET /v1/wallet/transactions?limit=10
+Authorization: Bearer sk-...
+
+Response:
+{
+  "transactions": [
+    {
+      "id": "txn_123",
+      "type": "usage",
+      "amount": -154,
+      "balance_after": 8546,
+      "description": "gpt-3.5-turbo: 50 prompt + 150 completion tokens",
+      "timestamp": "2024-01-01T12:34:56Z"
+    },
+    {
+      "id": "txn_122",
+      "type": "deposit",
+      "amount": 10000,
+      "balance_after": 10000,
+      "description": "Initial deposit",
+      "timestamp": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "has_more": false,
+  "total": 2
+}
+```
+
+## Security Best Practices
+
+### API Key Storage
+
+**Do:**
+
+- Store keys in environment variables
+- Use secret management systems
+- Encrypt keys at rest
+- Implement key rotation
+
+**Don't:**
+
+- Commit keys to version control
+- Share keys between environments
+- Log keys in plain text
+- Expose keys in client-side code
+
+### Environment Variables
+
+```bash
+# .env file
+ROUTSTR_API_KEY=sk-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
+ROUTSTR_BASE_URL=https://your-node.com/v1
+
+# Usage in code
+import os
+api_key = os.getenv("ROUTSTR_API_KEY")
+```
+
+### Key Rotation
+
+Regularly rotate API keys:
+
+```python
+# 1. Create new key
+new_key = create_api_key(balance=old_key_balance)
+
+# 2. Update applications
+update_environment_variable("ROUTSTR_API_KEY", new_key)
+
+# 3. Test new key
+test_api_connection(new_key)
+
+# 4. Withdraw old key balance
+withdraw_balance(old_key)
+```
+
+## Authentication Errors
+
+### Invalid API Key
+
+```json
+{
+  "error": {
+    "type": "authentication_failed",
+    "message": "Invalid API key",
+    "code": "invalid_api_key"
+  }
+}
+```
+
+**Status Code:** 401
+
+**Common Causes:**
+
+- Typo in API key
+- Key doesn't exist
+- Key has been deleted
+
+### Expired API Key
+
+```json
+{
+  "error": {
+    "type": "authentication_failed",
+    "message": "API key has expired",
+    "code": "key_expired",
+    "details": {
+      "expired_at": "2024-01-01T00:00:00Z"
+    }
+  }
+}
+```
+
+**Status Code:** 401
+
+**Resolution:**
+
+- Create a new API key
+- Contact admin if refund address was set
+
+### Insufficient Balance
+
+```json
+{
+  "error": {
+    "type": "insufficient_balance",
+    "message": "Insufficient balance for request",
+    "code": "payment_required",
+    "details": {
+      "balance": 100,
+      "required": 154,
+      "shortfall": 54
+    }
+  }
+}
+```
+
+**Status Code:** 402
+
+**Resolution:**
+
+- Top up the API key balance
+- Use a more economical model
+- Optimize request parameters
+
+## Advanced Authentication
+
+### Per-Request Tokens (Coming Soon)
+
+Pay per request without maintaining a balance:
+
+```bash
+curl https://your-node.com/v1/chat/completions \
+  -H "X-Cashu: cashuAeyJ0b2tlbiI6W3..." \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-3.5-turbo","messages":[...]}'
+```
+
+Response includes change:
+
+```
+X-Cashu: cashuAeyJjaGFuZ2UiOlt7...
+```
+
+### Multi-Key Authentication
+
+Use multiple keys for different purposes:
+
+```python
+# Production key for main app
+PROD_KEY = os.getenv("ROUTSTR_PROD_KEY")
+
+# Development key for testing
+DEV_KEY = os.getenv("ROUTSTR_DEV_KEY")
+
+# Analytics key with restricted permissions
+ANALYTICS_KEY = os.getenv("ROUTSTR_ANALYTICS_KEY")
+
+# Choose key based on environment
+api_key = PROD_KEY if is_production() else DEV_KEY
+```
+
+### Delegated Authentication
+
+Create sub-keys with limited permissions:
+
+```bash
+POST /v1/wallet/create/subkey
+Authorization: Bearer sk-parent-key
+Content-Type: application/json
+
+{
+  "name": "Limited Subkey",
+  "balance_limit": 1000,
+  "allowed_models": ["gpt-3.5-turbo"],
+  "expires_in_hours": 24
+}
+```
+
+## Rate Limiting
+
+Rate limits are applied per API key:
+
+### Default Limits
+
+| Metric | Limit | Window |
+|--------|-------|--------|
+| Requests | 1000 | 1 minute |
+| Tokens | 1,000,000 | 1 hour |
+| Concurrent | 10 | - |
+
+### Rate Limit Headers
+
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1640995200
+X-RateLimit-Type: requests_per_minute
+```
+
+### Handling Rate Limits
+
+```python
+import time
+from typing import Optional
+
+def make_request_with_retry(
+    client,
+    max_retries: int = 3
+) -> Optional[Response]:
+    for attempt in range(max_retries):
+        try:
+            response = client.chat.completions.create(...)
+            return response
+        except RateLimitError as e:
+            if attempt < max_retries - 1:
+                # Extract retry-after from error
+                retry_after = e.retry_after or 60
+                print(f"Rate limited. Waiting {retry_after}s...")
+                time.sleep(retry_after)
+            else:
+                raise
+```
+
+## IP Whitelisting
+
+Restrict API key usage by IP:
+
+```bash
+POST /v1/wallet/update
+Authorization: Bearer sk-...
+Content-Type: application/json
+
+{
+  "allowed_ips": [
+    "192.168.1.100",
+    "10.0.0.0/24"
+  ]
+}
+```
+
+## Monitoring
+
+### Usage Alerts
+
+Set up usage notifications:
+
+```bash
+POST /v1/wallet/alerts
+Authorization: Bearer sk-...
+Content-Type: application/json
+
+{
+  "low_balance_threshold": 1000,
+  "daily_spend_limit": 5000,
+  "webhook_url": "https://your-app.com/webhook"
+}
+```
+
+### Audit Logging
+
+All API key usage is logged:
+
+```json
+{
+  "timestamp": "2024-01-01T12:34:56Z",
+  "api_key_id": "key_123456",
+  "endpoint": "/v1/chat/completions",
+  "method": "POST",
+  "ip_address": "192.168.1.100",
+  "user_agent": "OpenAI-Python/1.0",
+  "cost_sats": 154,
+  "response_status": 200
+}
+```
+
+## Next Steps
+
+- [Endpoints](endpoints.md) - Complete endpoint reference
+- [Errors](errors.md) - Error handling guide
+- [Using the API](../user-guide/using-api.md) - Integration examples

docs/api/endpoints.md

@@ -0,0 +1,530 @@
+# API Endpoints
+
+Complete reference for all Routstr API endpoints.
+
+## Overview
+
+Routstr provides OpenAI-compatible endpoints with Bitcoin/eCash payment integration.
+
+### Base URL
+
+All endpoints use the base URL:
+
+```text
+https://api.routstr.com/v1
+```
+
+### Authentication
+
+All endpoints require authentication via:
+
+- **Bearer Token**: `Authorization: Bearer sk-...` or `Authorization: Bearer cashuAeyJ0...`
+- **X-Cashu Header**: `X-Cashu: cashuAeyJ0...` (for direct eCash payments)
+
+See [Authentication](authentication.md) for details.
+
+## Chat
+
+### Create Chat Completion
+
+Send messages to generate model responses.
+
+```http
+POST /v1/chat/completions
+```
+
+**Request Body:**
+
+```json
+{
+  "model": "gpt-4",
+  "messages": [
+    {
+      "role": "system",
+      "content": "You are a helpful assistant."
+    },
+    {
+      "role": "user",
+      "content": "Hello!"
+    }
+  ],
+  "temperature": 0.7,
+  "stream": false
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `model` | string | Yes | - | Model ID to use |
+| `messages` | array | Yes | - | Array of message objects |
+| `temperature` | number | No | 1.0 | Sampling temperature (0-2) |
+| `max_tokens` | integer | No | Model default | Maximum tokens to generate |
+| `stream` | boolean | No | false | Stream partial responses |
+| `top_p` | number | No | 1.0 | Nucleus sampling |
+| `n` | integer | No | 1 | Number of completions |
+| `stop` | string/array | No | null | Stop sequences |
+| `presence_penalty` | number | No | 0 | Presence penalty (-2 to 2) |
+| `frequency_penalty` | number | No | 0 | Frequency penalty (-2 to 2) |
+
+**Response:**
+
+```json
+{
+  "id": "chatcmpl-123",
+  "object": "chat.completion",
+  "created": 1677652288,
+  "model": "gpt-4",
+  "choices": [{
+    "index": 0,
+    "message": {
+      "role": "assistant",
+      "content": "Hello! How can I help you today?"
+    },
+    "finish_reason": "stop"
+  }],
+  "usage": {
+    "prompt_tokens": 13,
+    "completion_tokens": 9,
+    "total_tokens": 22
+  }
+}
+```
+
+### Streaming Response
+
+When `stream: true`:
+
+```text
+data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
+
+data: [DONE]
+```
+
+## Completions (Coming Soon)
+
+### Create Completion
+
+**Note: This endpoint is coming soon and not yet available.**
+
+Generate text completion (legacy endpoint).
+
+```http
+POST /v1/completions
+```
+
+**Request Body:**
+
+```json
+{
+  "model": "gpt-3.5-turbo-instruct",
+  "prompt": "Once upon a time",
+  "max_tokens": 50,
+  "temperature": 0.7
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": "cmpl-123",
+  "object": "text_completion",
+  "created": 1677652288,
+  "model": "gpt-3.5-turbo-instruct",
+  "choices": [{
+    "text": " in a faraway land, there lived a brave knight...",
+    "index": 0,
+    "logprobs": null,
+    "finish_reason": "length"
+  }],
+  "usage": {
+    "prompt_tokens": 4,
+    "completion_tokens": 50,
+    "total_tokens": 54
+  }
+}
+```
+
+## Embeddings
+
+### Create Embeddings (Coming Soon)
+
+**Note: This endpoint is coming soon and not yet available.**
+
+Generate vector representations of text.
+
+```http
+POST /v1/embeddings
+```
+
+**Request Body:**
+
+```json
+{
+  "model": "text-embedding-3-small",
+  "input": "The quick brown fox jumps over the lazy dog",
+  "encoding_format": "float"
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `model` | string | Yes | - | Embedding model ID |
+| `input` | string/array | Yes | - | Text(s) to embed |
+| `encoding_format` | string | No | "float" | Format: "float" or "base64" |
+| `dimensions` | integer | No | Model default | Output dimensions |
+
+**Response:**
+
+```json
+{
+  "object": "list",
+  "data": [{
+    "object": "embedding",
+    "index": 0,
+    "embedding": [0.0023064255, -0.009327292, ...] 
+  }],
+  "model": "text-embedding-3-small",
+  "usage": {
+    "prompt_tokens": 9,
+    "total_tokens": 9
+  }
+}
+```
+
+## Images (Coming Soon)
+
+### Create Image
+
+**Note: This endpoint is coming soon and not yet available.**
+
+Generate images from text prompts.
+
+```http
+POST /v1/images/generations
+```
+
+**Request Body:**
+
+```json
+{
+  "model": "dall-e-3",
+  "prompt": "A white siamese cat wearing a space helmet",
+  "n": 1,
+  "size": "1024x1024",
+  "quality": "standard"
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `model` | string | Yes | - | Model: dall-e-2, dall-e-3 |
+| `prompt` | string | Yes | - | Text description |
+| `n` | integer | No | 1 | Number of images |
+| `size` | string | No | "1024x1024" | Image dimensions |
+| `quality` | string | No | "standard" | Quality: standard, hd |
+| `style` | string | No | "vivid" | Style: vivid, natural |
+| `response_format` | string | No | "url" | Format: url, b64_json |
+
+**Response:**
+
+```json
+{
+  "created": 1677652288,
+  "data": [{
+    "url": "https://generated-image-url.com/image.png",
+    "revised_prompt": "A white Siamese cat wearing a detailed space helmet..."
+  }]
+}
+```
+
+## Audio (Coming Soon)
+
+### Create Transcription
+
+**Note: This endpoint is coming soon and not yet available.**
+
+Convert audio to text.
+
+```http
+POST /v1/audio/transcriptions
+Content-Type: multipart/form-data
+```
+
+**Form Data:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | file | Yes | Audio file (mp3, mp4, mpeg, mpga, m4a, wav, webm) |
+| `model` | string | Yes | Model ID (whisper-1) |
+| `language` | string | No | Language code (ISO-639-1) |
+| `prompt` | string | No | Context prompt |
+| `response_format` | string | No | Format: json, text, srt, verbose_json, vtt |
+| `temperature` | number | No | Sampling temperature |
+
+**Response:**
+
+```json
+{
+  "text": "Hello, this is the transcribed audio content."
+}
+```
+
+### Create Translation
+
+**Note: This endpoint is coming soon and not yet available.**
+
+Translate audio to English.
+
+```http
+POST /v1/audio/translations
+Content-Type: multipart/form-data
+```
+
+Same parameters as transcription, but always translates to English.
+
+## Models
+
+### List Models
+
+Get available models and pricing.
+
+```http
+GET /v1/models
+```
+
+**Response:**
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "gpt-3.5-turbo",
+      "object": "model",
+      "created": 1677610602,
+      "owned_by": "openai",
+      "permission": [...],
+      "root": "gpt-3.5-turbo",
+      "parent": null,
+      "pricing": {
+        "prompt": 0.001,
+        "completion": 0.002,
+        "unit": "1k tokens"
+      }
+    }
+  ]
+}
+```
+
+## Wallet Management
+
+### Create Wallet (Coming Soon)
+
+**Note: This endpoint is coming soon. Currently, you can use Cashu tokens directly as API keys.**
+
+Create a new wallet with eCash deposit.
+
+```http
+POST /v1/wallet/create
+```
+
+**Request Body:**
+
+```json
+{
+  "cashu_token": "cashuAeyJ0...",
+  "admin_key": "optional-admin-key"
+}
+```
+
+**Response:**
+
+```json
+{
+  "api_key": "sk-1234567890abcdef",
+  "admin_key": "radmin_fedcba0987654321",
+  "balance": 10000,
+  "mint": "https://mint.example.com",
+  "unit": "sat"
+}
+```
+
+### Check Balance
+
+Get current wallet balance.
+
+```http
+GET /v1/wallet/balance
+Authorization: Bearer sk-...
+```
+
+**Response:**
+
+```json
+{
+  "balance": 8500,
+  "currency": "sat",
+  "reserved": 0
+}
+```
+
+### Top Up Wallet
+
+Add funds to existing wallet.
+
+```http
+POST /v1/wallet/topup
+Authorization: Bearer sk-...
+```
+
+**Request Body:**
+
+```json
+{
+  "cashu_token": "cashuAeyJ0..."
+}
+```
+
+**Response:**
+
+```json
+{
+  "balance": 18500,
+  "amount_added": 10000,
+  "currency": "sat"
+}
+```
+
+### Withdraw Funds
+
+Withdraw balance as eCash.
+
+```http
+POST /v1/wallet/withdraw
+Authorization: Bearer sk-...
+```
+
+**Request Body:**
+
+```json
+{
+  "amount": 5000,
+  "mint": "https://mint.example.com"
+}
+```
+
+**Response:**
+
+```json
+{
+  "cashu_token": "cashuAeyJ0...",
+  "amount": 5000,
+  "mint": "https://mint.example.com"
+}
+```
+
+## Provider Discovery
+
+## Admin Settings
+
+These endpoints are protected by the Admin cookie (`admin_password` set to your configured admin password).
+
+### Get Settings
+
+```http
+GET /admin/api/settings
+```
+
+Returns the current application settings (sensitive values may be redacted).
+
+### Update Settings
+
+```http
+PATCH /admin/api/settings
+Content-Type: application/json
+```
+
+Body is a partial JSON of settings fields to update. Validated and persisted to the database.
+
+### List Providers
+
+Get available upstream providers.
+
+```http
+GET /v1/providers
+```
+
+**Response:**
+
+```json
+{
+  "providers": [
+    {
+      "name": "openai",
+      "models": ["gpt-4", "gpt-3.5-turbo"],
+      "endpoints": ["chat/completions", "completions"],
+      "status": "active"
+    }
+  ]
+}
+```
+
+### Provider Info
+
+Get specific provider details.
+
+```http
+GET /v1/providers/{provider_name}
+```
+
+**Response:**
+
+```json
+{
+  "name": "openai",
+  "display_name": "OpenAI",
+  "description": "Official OpenAI API",
+  "models": [
+    {
+      "id": "gpt-4",
+      "name": "GPT-4",
+      "context_window": 8192,
+      "pricing": {
+        "prompt": 0.03,
+        "completion": 0.06,
+        "unit": "1k tokens"
+      }
+    }
+  ],
+  "endpoints": ["chat/completions", "completions", "embeddings"],
+  "features": ["streaming", "function_calling"],
+  "status": "active"
+}
+```
+
+## Rate Limiting
+
+All endpoints are subject to rate limiting:
+
+- **Per minute**: 60 requests
+- **Per hour**: 1000 requests
+- **Per day**: 10000 requests
+
+Rate limit information is included in response headers.
+
+## Next Steps
+
+- [Errors](errors.md) - Error handling reference
+- [Authentication](authentication.md) - Auth details
+- [Examples](../user-guide/using-api.md) - Code examples

docs/api/errors.md

@@ -0,0 +1,592 @@
+# Error Handling
+
+This guide covers error responses, codes, and handling strategies for the Routstr API.
+
+## Error Response Format
+
+All errors follow a consistent JSON structure:
+
+```json
+{
+  "error": {
+    "type": "error_type",
+    "message": "Human-readable error message",
+    "code": "error_code",
+    "details": {
+      "additional": "context-specific information"
+    }
+  }
+}
+```
+
+## HTTP Status Codes
+
+| Status | Meaning | Common Causes |
+|--------|---------|---------------|
+| 400 | Bad Request | Invalid parameters, malformed JSON |
+| 401 | Unauthorized | Invalid or missing API key |
+| 402 | Payment Required | Insufficient balance |
+| 403 | Forbidden | Access denied to resource |
+| 404 | Not Found | Endpoint or resource doesn't exist |
+| 422 | Unprocessable Entity | Validation errors |
+| 429 | Too Many Requests | Rate limit exceeded |
+| 500 | Internal Server Error | Server-side error |
+| 502 | Bad Gateway | Upstream API error |
+| 503 | Service Unavailable | Temporary outage |
+
+## Error Types
+
+### Authentication Errors
+
+#### Invalid API Key
+
+```json
+{
+  "error": {
+    "type": "authentication_failed",
+    "message": "Invalid API key provided",
+    "code": "invalid_api_key"
+  }
+}
+```
+
+**Status:** 401  
+**Resolution:** Check API key format and validity
+
+#### Expired API Key
+
+```json
+{
+  "error": {
+    "type": "authentication_failed",
+    "message": "API key has expired",
+    "code": "key_expired",
+    "details": {
+      "expired_at": "2024-01-01T00:00:00Z",
+      "refund_available": true
+    }
+  }
+}
+```
+
+**Status:** 401  
+**Resolution:** Create new API key or contact admin for refund
+
+#### Missing Authorization
+
+```json
+{
+  "error": {
+    "type": "authentication_failed",
+    "message": "Authorization header required",
+    "code": "missing_auth"
+  }
+}
+```
+
+**Status:** 401  
+**Resolution:** Include `Authorization: Bearer {api_key}` header
+
+### Payment Errors
+
+#### Insufficient Balance
+
+```json
+{
+  "error": {
+    "type": "insufficient_balance",
+    "message": "Insufficient balance for request",
+    "code": "payment_required",
+    "details": {
+      "balance": 100,
+      "required": 154,
+      "shortfall": 54,
+      "estimated_tokens": {
+        "prompt": 50,
+        "completion": 150
+      }
+    }
+  }
+}
+```
+
+**Status:** 402  
+**Resolution:** Top up API key balance
+
+#### Invalid Token
+
+```json
+{
+  "error": {
+    "type": "payment_error",
+    "message": "Invalid Cashu token",
+    "code": "invalid_token",
+    "details": {
+      "reason": "Token already spent"
+    }
+  }
+}
+```
+
+**Status:** 400  
+**Resolution:** Use a valid, unspent token
+
+#### Mint Unavailable
+
+```json
+{
+  "error": {
+    "type": "payment_error",
+    "message": "Cannot connect to Cashu mint",
+    "code": "mint_unavailable",
+    "details": {
+      "mint_url": "https://mint.example.com",
+      "retry_after": 60
+    }
+  }
+}
+```
+
+**Status:** 503  
+**Resolution:** Try again later or use different mint
+
+### Validation Errors
+
+#### Invalid Parameters
+
+```json
+{
+  "error": {
+    "type": "invalid_request",
+    "message": "Invalid request parameters",
+    "code": "validation_error",
+    "details": {
+      "errors": [
+        {
+          "field": "temperature",
+          "message": "Must be between 0 and 2",
+          "value": 3.5
+        },
+        {
+          "field": "model",
+          "message": "Model 'gpt-5' not found",
+          "value": "gpt-5"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Status:** 422  
+**Resolution:** Fix parameter values
+
+#### Missing Required Fields
+
+```json
+{
+  "error": {
+    "type": "invalid_request",
+    "message": "Missing required fields",
+    "code": "missing_fields",
+    "details": {
+      "missing": ["model", "messages"]
+    }
+  }
+}
+```
+
+**Status:** 400  
+**Resolution:** Include all required fields
+
+### Rate Limiting
+
+#### Rate Limit Exceeded
+
+```json
+{
+  "error": {
+    "type": "rate_limit_exceeded",
+    "message": "Too many requests",
+    "code": "rate_limit",
+    "details": {
+      "limit": 100,
+      "window": "1 minute",
+      "retry_after": 45
+    }
+  }
+}
+```
+
+**Status:** 429  
+**Headers:**
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1640995200
+Retry-After: 45
+```
+
+**Resolution:** Wait for retry_after seconds
+
+### Upstream Errors
+
+#### Model Overloaded
+
+```json
+{
+  "error": {
+    "type": "upstream_error",
+    "message": "Model is currently overloaded",
+    "code": "model_overloaded",
+    "details": {
+      "model": "gpt-4",
+      "retry_after": 5
+    }
+  }
+}
+```
+
+**Status:** 503  
+**Resolution:** Retry request after delay
+
+#### Upstream Timeout
+
+```json
+{
+  "error": {
+    "type": "upstream_error",
+    "message": "Request to upstream API timed out",
+    "code": "upstream_timeout",
+    "details": {
+      "timeout": 30,
+      "endpoint": "chat/completions"
+    }
+  }
+}
+```
+
+**Status:** 504  
+**Resolution:** Retry with shorter prompt or max_tokens
+
+### Content Policy
+
+#### Content Filtered
+
+```json
+{
+  "error": {
+    "type": "content_policy_violation",
+    "message": "Content filtered due to policy violation",
+    "code": "content_filtered",
+    "details": {
+      "reason": "harmful_content",
+      "categories": ["violence", "hate"]
+    }
+  }
+}
+```
+
+**Status:** 400  
+**Resolution:** Modify prompt to comply with policies
+
+## Error Handling Best Practices
+
+### Retry Logic
+
+Implement exponential backoff with jitter:
+
+```python
+import time
+import random
+from typing import Optional, Callable
+
+def retry_with_backoff(
+    func: Callable,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 60.0
+) -> Optional[Any]:
+    """Retry function with exponential backoff."""
+    
+    for attempt in range(max_retries):
+        try:
+            return func()
+        except Exception as e:
+            if attempt == max_retries - 1:
+                raise
+            
+            # Check if error is retryable
+            if hasattr(e, 'status_code'):
+                if e.status_code in [429, 502, 503, 504]:
+                    # Calculate delay with jitter
+                    delay = min(
+                        base_delay * (2 ** attempt) + random.uniform(0, 1),
+                        max_delay
+                    )
+                    
+                    # Use retry_after if provided
+                    if hasattr(e, 'retry_after'):
+                        delay = e.retry_after
+                    
+                    time.sleep(delay)
+                else:
+                    # Non-retryable error
+                    raise
+```
+
+### Error Categories
+
+Group errors for handling:
+
+```python
+class ErrorHandler:
+    # Errors that should be retried
+    RETRYABLE_ERRORS = {
+        'rate_limit',
+        'upstream_timeout',
+        'model_overloaded',
+        'mint_unavailable'
+    }
+    
+    # Errors requiring user action
+    USER_ACTION_ERRORS = {
+        'insufficient_balance',
+        'invalid_api_key',
+        'key_expired'
+    }
+    
+    # Errors requiring code changes
+    CLIENT_ERRORS = {
+        'validation_error',
+        'missing_fields',
+        'invalid_request'
+    }
+    
+    @classmethod
+    def handle_error(cls, error_response: dict) -> None:
+        error_code = error_response['error']['code']
+        
+        if error_code in cls.RETRYABLE_ERRORS:
+            # Implement retry logic
+            pass
+        elif error_code in cls.USER_ACTION_ERRORS:
+            # Alert user
+            pass
+        elif error_code in cls.CLIENT_ERRORS:
+            # Log for debugging
+            pass
+```
+
+### Graceful Degradation
+
+Handle errors without breaking application flow:
+
+```python
+async def get_ai_response(prompt: str) -> str:
+    """Get AI response with fallback handling."""
+    try:
+        # Try primary model
+        response = await client.chat.completions.create(
+            model="gpt-4",
+            messages=[{"role": "user", "content": prompt}]
+        )
+        return response.choices[0].message.content
+    
+    except InsufficientBalanceError:
+        # Fall back to cheaper model
+        try:
+            response = await client.chat.completions.create(
+                model="gpt-3.5-turbo",
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=100  # Limit tokens
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            logger.error(f"Fallback failed: {e}")
+            return "Service temporarily unavailable"
+    
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
+        return "An error occurred processing your request"
+```
+
+### Logging Errors
+
+Structure error logs for debugging:
+
+```python
+import logging
+import json
+
+def log_api_error(error_response: dict, context: dict) -> None:
+    """Log API errors with context."""
+    logger = logging.getLogger(__name__)
+    
+    error_data = {
+        'timestamp': datetime.utcnow().isoformat(),
+        'error': error_response['error'],
+        'context': {
+            'endpoint': context.get('endpoint'),
+            'api_key_id': context.get('api_key_id'),
+            'request_id': context.get('request_id'),
+            'model': context.get('model')
+        }
+    }
+    
+    logger.error(
+        "API Error",
+        extra={'structured_data': json.dumps(error_data)}
+    )
+```
+
+### User-Friendly Messages
+
+Map technical errors to user messages:
+
+```python
+ERROR_MESSAGES = {
+    'insufficient_balance': "Your account balance is too low. Please add funds to continue.",
+    'invalid_api_key': "Invalid API key. Please check your configuration.",
+    'rate_limit': "Too many requests. Please wait a moment and try again.",
+    'model_overloaded': "The AI service is busy. Please try again in a few seconds.",
+    'validation_error': "Invalid request. Please check your input and try again."
+}
+
+def get_user_message(error_code: str) -> str:
+    """Get user-friendly error message."""
+    return ERROR_MESSAGES.get(
+        error_code,
+        "An unexpected error occurred. Please try again later."
+    )
+```
+
+## Common Scenarios
+
+### Handling Balance Errors
+
+```python
+async def make_request_with_balance_check():
+    try:
+        # Check balance first
+        balance_info = await client.get("/v1/wallet/balance")
+        
+        # Estimate cost
+        estimated_cost = calculate_cost(model, prompt_length)
+        
+        if balance_info['balance'] < estimated_cost * 1.1:  # 10% buffer
+            # Proactively top up
+            await top_up_balance()
+        
+        # Make request
+        return await client.chat.completions.create(...)
+        
+    except InsufficientBalanceError as e:
+        # Handle insufficient balance
+        shortfall = e.details['shortfall']
+        await top_up_balance(amount=shortfall * 2)
+        # Retry request
+```
+
+### Handling Rate Limits
+
+```python
+from datetime import datetime, timedelta
+
+class RateLimitTracker:
+    def __init__(self):
+        self.reset_times = {}
+    
+    def is_limited(self, endpoint: str) -> bool:
+        reset_time = self.reset_times.get(endpoint)
+        if reset_time and datetime.now() < reset_time:
+            return True
+        return False
+    
+    def set_limit(self, endpoint: str, reset_timestamp: int):
+        self.reset_times[endpoint] = datetime.fromtimestamp(reset_timestamp)
+    
+    def wait_time(self, endpoint: str) -> float:
+        reset_time = self.reset_times.get(endpoint)
+        if reset_time:
+            return max(0, (reset_time - datetime.now()).total_seconds())
+        return 0
+```
+
+## Testing Error Handling
+
+### Unit Tests
+
+```python
+import pytest
+from unittest.mock import Mock
+
+async def test_insufficient_balance_handling():
+    # Mock API client
+    mock_client = Mock()
+    mock_client.chat.completions.create.side_effect = InsufficientBalanceError(
+        required=100,
+        available=50
+    )
+    
+    # Test error handling
+    handler = ErrorHandler(mock_client)
+    result = await handler.safe_request(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "test"}]
+    )
+    
+    # Verify fallback behavior
+    assert result.fallback_used is True
+    assert result.model == "gpt-3.5-turbo"
+```
+
+### Integration Tests
+
+```python
+async def test_real_error_scenarios():
+    # Test with invalid API key
+    invalid_client = OpenAI(
+        api_key="sk-invalid",
+        base_url=test_url
+    )
+    
+    with pytest.raises(AuthenticationError) as exc_info:
+        await invalid_client.chat.completions.create(
+            model="gpt-3.5-turbo",
+            messages=[{"role": "user", "content": "test"}]
+        )
+    
+    assert exc_info.value.status_code == 401
+    assert "invalid_api_key" in str(exc_info.value)
+```
+
+## Monitoring Errors
+
+Track error rates and patterns:
+
+```python
+class ErrorMetrics:
+    def __init__(self):
+        self.error_counts = defaultdict(int)
+        self.error_timestamps = defaultdict(list)
+    
+    def record_error(self, error_code: str):
+        self.error_counts[error_code] += 1
+        self.error_timestamps[error_code].append(datetime.now())
+    
+    def get_error_rate(self, error_code: str, window_minutes: int = 60) -> float:
+        cutoff = datetime.now() - timedelta(minutes=window_minutes)
+        recent_errors = [
+            ts for ts in self.error_timestamps[error_code]
+            if ts > cutoff
+        ]
+        return len(recent_errors) / window_minutes
+```
+
+## Next Steps
+
+- [Authentication](authentication.md) - Auth error details
+- [Endpoints](endpoints.md) - Endpoint-specific errors
+- [Examples](../user-guide/using-api.md) - Error handling examples

docs/api/overview.md

@@ -0,0 +1,365 @@
+# API Reference Overview
+
+Routstr Core provides a complete OpenAI-compatible API with additional endpoints for payment management. This reference covers all available endpoints, authentication methods, and response formats.
+
+## Base URL
+
+```
+https://api.routstr.com/v1
+```
+
+All API endpoints are prefixed with `/v1` for versioning.
+
+## Authentication
+
+Routstr uses API keys for authentication. Include your key in the Authorization header:
+
+```bash
+Authorization: Bearer sk-...
+```
+
+### API Key Format
+
+- Prefix: `sk-`
+- Length: 32 characters
+- Example: `sk-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p`
+
+### Cashu Tokens as Authentication
+
+You can also use a Cashu eCash token directly in the `Authorization` header. The server hashes the token internally; this hash represents your API key identity and carries the token's balance.
+
+```bash
+Authorization: Bearer cashuAeyJ0b2tlbiI6W3...
+```
+
+## Content Types
+
+### Request
+
+- **Required**: `Content-Type: application/json`
+- **Encoding**: UTF-8
+- **Maximum Size**: 10MB (configurable)
+
+### Response
+
+- **Type**: `application/json` or `text/event-stream` (for streaming)
+- **Encoding**: UTF-8
+- **Compression**: gzip (if accepted)
+
+## Rate Limiting
+
+Rate limits are applied per API key:
+
+- **Requests**: 1000 per minute
+- **Tokens**: 1,000,000 per hour
+- **Concurrent**: 10 simultaneous requests
+
+Rate limit headers:
+
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1640995200
+```
+
+## Error Responses
+
+All errors follow a consistent format:
+
+```json
+{
+  "error": {
+    "type": "insufficient_balance",
+    "message": "Insufficient balance for request",
+    "code": "payment_required",
+    "details": {
+      "required": 154,
+      "available": 100
+    }
+  }
+}
+```
+
+### Error Types
+
+| Type | Status Code | Description |
+|------|-------------|-------------|
+| `invalid_request` | 400 | Malformed request |
+| `authentication_failed` | 401 | Invalid or missing API key |
+| `insufficient_balance` | 402 | Not enough balance |
+| `forbidden` | 403 | Access denied |
+| `not_found` | 404 | Resource not found |
+| `rate_limit_exceeded` | 429 | Too many requests |
+| `internal_error` | 500 | Server error |
+| `upstream_error` | 502 | Upstream API error |
+
+## Endpoint Categories
+
+### AI/ML Endpoints
+
+Standard OpenAI-compatible endpoints:
+
+- **Chat Completions**: `/v1/chat/completions`
+- **Completions**: `/v1/completions` *(Coming soon)*
+- **Embeddings**: `/v1/embeddings` *(Coming soon)*
+- **Images**: `/v1/images/generations` *(Coming soon)*
+- **Audio**: `/v1/audio/transcriptions` *(Coming soon)*
+- **Models**: `/v1/models`
+
+### Payment Endpoints
+
+Routstr-specific payment management:
+
+- **Wallet**: `/v1/wallet/*`
+- **Balance**: `/v1/balance`
+- **Node Info**: `/v1/info`
+
+### Admin Endpoints
+
+Protected administrative functions:
+
+- **Dashboard**: `/admin/`
+- **API Management**: `/admin/api/*`
+
+## Request Headers
+
+### Standard Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Authorization` | Yes | Bearer token with API key |
+| `Content-Type` | Yes | Must be `application/json` |
+| `Accept` | No | Response format preference |
+| `Accept-Encoding` | No | Compression support |
+| `X-Request-ID` | No | Client-provided request ID |
+
+### Custom Headers
+
+| Header | Description |
+|--------|-------------|
+| `X-Routstr-Version` | API version override |
+| `X-Cashu` | eCash token for per-request payment |
+| `X-Max-Cost` | Maximum acceptable cost in sats |
+
+## Response Headers
+
+### Standard Headers
+
+| Header | Description |
+|--------|-------------|
+| `Content-Type` | Response format |
+| `Content-Length` | Response size |
+| `X-Routstr-Request-ID` | Unique request identifier |
+| `X-Routstr-Version` | API version used |
+
+### Cost Headers
+
+| Header | Description |
+|--------|-------------|
+| `X-Routstr-Cost` | Request cost in sats |
+| `X-Routstr-Balance` | Remaining balance |
+| `X-Cashu` | Change token (if applicable) |
+
+## Streaming Responses
+
+For endpoints supporting streaming, responses use Server-Sent Events:
+
+```
+data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" there"},"finish_reason":null}]}
+
+data: [DONE]
+```
+
+## OpenAPI Specification
+
+The complete OpenAPI 3.0 specification is available at:
+
+```
+GET /openapi.json
+```
+
+Interactive documentation:
+
+```
+GET /docs        # Swagger UI
+GET /redoc       # ReDoc
+```
+
+## SDK Support
+
+Routstr is compatible with official OpenAI SDKs:
+
+### Python
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="sk-...",
+    base_url="https://your-node.com/v1"
+)
+```
+
+### JavaScript/TypeScript
+
+```javascript
+import OpenAI from 'openai';
+
+const openai = new OpenAI({
+    apiKey: 'sk-...',
+    baseURL: 'https://your-node.com/v1'
+});
+```
+
+### cURL
+
+```bash
+curl https://your-node.com/v1/chat/completions \
+  -H "Authorization: Bearer sk-..." \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## Webhook Support
+
+Configure webhooks for events:
+
+```json
+POST /v1/webhooks
+{
+  "url": "https://your-app.com/webhook",
+  "events": ["balance.low", "key.expired"],
+  "secret": "whsec_your_secret"
+}
+```
+
+Events are sent with signature verification:
+
+```
+X-Webhook-Signature: sha256=...
+```
+
+## API Versioning
+
+- Current version: `v1`
+- Version in URL path: `/v1/endpoint`
+- Override with header: `X-Routstr-Version: v2`
+- Deprecation notices: 6 months
+
+## Status Codes
+
+| Code | Meaning |
+|------|---------|
+| 200 | Success |
+| 201 | Created |
+| 204 | No content |
+| 400 | Bad request |
+| 401 | Unauthorized |
+| 402 | Payment required |
+| 403 | Forbidden |
+| 404 | Not found |
+| 429 | Rate limited |
+| 500 | Server error |
+| 502 | Upstream error |
+| 503 | Service unavailable |
+
+## CORS Support
+
+CORS is enabled with configurable origins:
+
+```
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+Access-Control-Allow-Headers: Authorization, Content-Type
+Access-Control-Max-Age: 86400
+```
+
+## Compression
+
+Responses are compressed with gzip when:
+
+- Client sends `Accept-Encoding: gzip`
+- Response is larger than 1KB
+- Content type is compressible
+
+## Pagination
+
+List endpoints support pagination:
+
+```
+GET /v1/transactions?limit=50&offset=100
+```
+
+Response includes pagination metadata:
+
+```json
+{
+  "data": [...],
+  "has_more": true,
+  "total": 500,
+  "limit": 50,
+  "offset": 100
+}
+```
+
+## Field Filtering
+
+Select specific fields in responses:
+
+```
+GET /v1/models?fields=id,name,pricing
+```
+
+## Batch Requests
+
+Process multiple operations in one request:
+
+```json
+POST /v1/batch
+{
+  "requests": [
+    {"method": "POST", "endpoint": "/chat/completions", "body": {...}},
+    {"method": "GET", "endpoint": "/models"},
+    {"method": "GET", "endpoint": "/balance"}
+  ]
+}
+```
+
+## Idempotency
+
+Prevent duplicate operations:
+
+```
+Idempotency-Key: unique-request-id
+```
+
+Keys are stored for 24 hours.
+
+## Health Check
+
+Monitor service status:
+
+```
+GET /health
+
+Response:
+{
+  "status": "healthy",
+  "version": "0.2.0",
+  "timestamp": "2024-01-01T00:00:00Z",
+  "checks": {
+    "database": "ok",
+    "upstream": "ok",
+    "mint": "ok"
+  }
+}
+```
+
+## Next Steps
+
+- [Authentication](authentication.md) - Detailed auth guide
+- [Endpoints](endpoints.md) - Complete endpoint reference
+- [Errors](errors.md) - Error handling guide
+- [Examples](../user-guide/using-api.md) - Code examples

docs/contributing/architecture.md

@@ -0,0 +1,381 @@
+# Architecture Overview
+
+This document describes the high-level architecture of Routstr Core, helping contributors understand how the system works.
+
+## System Overview
+
+Routstr Core is a FastAPI-based reverse proxy that adds Bitcoin micropayments to OpenAI-compatible APIs.
+
+```mermaid
+graph TB
+    subgraph "External Services"
+        Client[API Client]
+        Mint[Cashu Mint]
+        Provider[AI Provider]
+        Nostr[Nostr Relays]
+    end
+    
+    subgraph "Routstr Core"
+        API[FastAPI Server]
+        Auth[Auth Module]
+        Payment[Payment Module]
+        Proxy[Proxy Module]
+        DB[(SQLite DB)]
+        
+        API --> Auth
+        Auth --> Payment
+        Auth --> DB
+        Payment --> Proxy
+        Proxy --> Provider
+        Payment --> Mint
+        API --> Nostr
+    end
+    
+    Client --> API
+```
+
+## Core Components
+
+### FastAPI Application
+
+The main application is initialized in `routstr/core/main.py`:
+
+- **Lifespan Management**: Handles startup/shutdown tasks
+- **Middleware**: CORS, logging, error handling
+- **Routers**: Modular endpoint organization
+- **Background Tasks**: Price updates, automatic payouts
+
+### Authentication System
+
+Located in `routstr/auth.py`, handles:
+
+- **API Key Validation**: Hashed key storage and lookup
+- **Balance Checking**: Ensures sufficient funds
+- **Rate Limiting**: Optional request throttling
+- **Token Redemption**: Converts eCash to balance
+
+### Payment Processing
+
+The `routstr/payment/` module manages:
+
+- **Cost Calculation**: Token-based or fixed pricing
+- **Model Pricing**: Dynamic pricing from models.json
+- **Currency Conversion**: BTC/USD rate management
+- **Fee Application**: Exchange and provider fees
+
+### Request Proxying
+
+`routstr/proxy.py` handles:
+
+- **Request Forwarding**: Preserves headers and body
+- **Response Streaming**: Efficient memory usage
+- **Usage Tracking**: Counts tokens and costs
+- **Error Handling**: Graceful upstream failures
+
+### Database Layer
+
+Using SQLModel in `routstr/core/db.py`:
+
+```python
+# Core models
+APIKey:
+  - id: Primary key
+  - key_hash: Hashed API key
+  - balance: Current balance (msats)
+  - created_at: Timestamp
+  - metadata: JSON field
+
+Transaction:
+  - id: Primary key
+  - api_key_id: Foreign key
+  - amount: Transaction amount
+  - type: deposit/usage/withdrawal
+  - timestamp: When occurred
+```
+
+## Request Flow
+
+### Standard API Request
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Routstr
+    participant D as Database
+    participant P as AI Provider
+    
+    C->>R: API Request + Key
+    R->>D: Validate Key
+    D-->>R: Key Info + Balance
+    R->>R: Check Balance
+    R->>P: Forward Request
+    P-->>R: AI Response
+    R->>D: Deduct Cost
+    R-->>C: Return Response
+```
+
+### Payment Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Routstr
+    participant W as Wallet Module
+    participant M as Cashu Mint
+    participant D as Database
+    
+    C->>R: Create Key Request + Token
+    R->>W: Validate Token
+    W->>M: Verify with Mint
+    M-->>W: Token Valid
+    W-->>R: Token Amount
+    R->>D: Create Key + Balance
+    R-->>C: Return API Key
+```
+
+## Key Design Decisions
+
+### 1. Async Architecture
+
+Everything is async for maximum performance:
+
+```python
+async def handle_request(request: Request) -> Response:
+    # Non-blocking database queries
+    api_key = await get_api_key(request.headers["Authorization"])
+    
+    # Concurrent operations
+    balance_check, rate_limit = await asyncio.gather(
+        check_balance(api_key),
+        check_rate_limit(api_key)
+    )
+    
+    # Stream response without blocking
+    async for chunk in proxy_request(request):
+        yield chunk
+```
+
+### 2. Modular Design
+
+Components are loosely coupled:
+
+- **Routers**: Separate files for different endpoints
+- **Dependencies**: Injected via FastAPI's DI system
+- **Models**: Shared data structures
+- **Services**: Business logic separated from routes
+
+### 3. Error Handling
+
+Graceful degradation and clear error messages:
+
+```python
+class RoustrError(Exception):
+    """Base exception with structured error response"""
+    status_code: int = 500
+    error_type: str = "internal_error"
+    
+class InsufficientBalanceError(RoustrError):
+    status_code = 402
+    error_type = "insufficient_balance"
+```
+
+### 4. Database Migrations
+
+Using Alembic for schema management:
+
+- Auto-migrations on startup
+- Version control for schema changes
+- Rollback capability
+- Zero-downtime updates
+
+## Security Architecture
+
+### API Key Security
+
+- **Storage**: SHA-256 hashed keys
+- **Generation**: Cryptographically secure random
+- **Validation**: Constant-time comparison
+- **Rotation**: Support for key expiry
+
+### Payment Security
+
+- **Token Validation**: Cryptographic verification
+- **Double-Spend Prevention**: Mint verification
+- **Balance Protection**: Atomic transactions
+- **Audit Trail**: All transactions logged
+
+### Network Security
+
+- **HTTPS**: Enforced in production
+- **CORS**: Configurable origins
+- **Rate Limiting**: Per-key limits
+- **Input Validation**: Pydantic models
+
+## Performance Considerations
+
+### Caching Strategy
+
+```python
+# Model pricing cache
+@lru_cache(maxsize=100)
+def get_model_price(model_id: str) -> ModelPrice:
+    return MODELS.get(model_id)
+
+# Balance cache with TTL
+balance_cache = TTLCache(maxsize=1000, ttl=60)
+```
+
+### Database Optimization
+
+- **Connection Pooling**: Reuse connections
+- **Indexed Queries**: Key lookups are O(1)
+- **Batch Operations**: Group updates
+- **Async I/O**: Non-blocking queries
+
+### Streaming Responses
+
+Efficient memory usage for large responses:
+
+```python
+async def stream_response(upstream_response):
+    async for chunk in upstream_response.aiter_bytes():
+        # Process chunk without loading full response
+        yield process_chunk(chunk)
+```
+
+## Extension Points
+
+### Adding New Endpoints
+
+1. Create router module
+2. Define Pydantic models
+3. Implement business logic
+4. Register with main app
+5. Add tests
+
+### Custom Pricing Models
+
+1. Extend `ModelPrice` class
+2. Implement calculation logic
+3. Add to pricing registry
+4. Update configuration
+
+### Payment Methods
+
+1. Create payment handler
+2. Implement validation
+3. Add to payment router
+4. Update balance logic
+
+## Testing Strategy
+
+### Unit Tests
+
+- Mock external dependencies
+- Test business logic in isolation
+- Fast execution (< 1 second per test)
+- High coverage target (> 80%)
+
+### Integration Tests
+
+- Test component interactions
+- Use test database
+- Mock external services
+- Verify end-to-end flows
+
+### Performance Tests
+
+- Load testing with locust
+- Memory profiling
+- Database query optimization
+- Response time benchmarks
+
+## Monitoring and Observability
+
+### Structured Logging
+
+```python
+logger.info("api_request", extra={
+    "request_id": request_id,
+    "api_key": api_key_id,
+    "endpoint": endpoint,
+    "model": model,
+    "tokens": token_count,
+    "cost_sats": cost,
+    "duration_ms": duration
+})
+```
+
+### Metrics Collection
+
+Key metrics tracked:
+
+- Request rate by endpoint
+- Token usage by model
+- Balance changes
+- Error rates
+- Response times
+
+### Health Checks
+
+```python
+@app.get("/health")
+async def health_check():
+    return {
+        "status": "healthy",
+        "version": __version__,
+        "database": await check_db(),
+        "upstream": await check_upstream(),
+        "mints": await check_mints()
+    }
+```
+
+## Deployment Architecture
+
+### Container Structure
+
+```dockerfile
+# Multi-stage build
+FROM python:3.11-slim AS builder
+# Install dependencies
+
+FROM python:3.11-slim
+# Copy only runtime needs
+# Run as non-root user
+```
+
+### Environment Configuration
+
+- **Development**: Local SQLite, debug logging
+- **Testing**: In-memory database, mock services
+- **Production**: Persistent storage, structured logs
+
+### Scaling Considerations
+
+- **Horizontal**: Multiple instances behind load balancer
+- **Vertical**: Async handles high concurrency
+- **Database**: Consider PostgreSQL for scale
+- **Caching**: Redis for distributed cache
+
+## Future Architecture
+
+### Planned Improvements
+
+1. **WebSocket Support**: Real-time balance updates
+2. **Plugin System**: Extensible pricing/auth
+3. **Multi-Region**: Geographic distribution
+4. **Event Sourcing**: Complete audit trail
+
+### Technical Debt
+
+Areas for improvement:
+
+- Database query optimization
+- Response caching layer
+- Metric aggregation
+- API versioning strategy
+
+## Next Steps
+
+- Review [Code Structure](code-structure.md) for detailed organization
+- See [Testing Guide](testing.md) for test architecture

docs/contributing/code-structure.md

@@ -0,0 +1,493 @@
+# Code Structure
+
+This guide provides a detailed overview of Routstr Core's codebase organization and key modules.
+
+## Directory Layout
+
+```
+routstr-core/
+├── routstr/                    # Main application package
+│   ├── __init__.py            # Package initialization, loads .env
+│   ├── auth.py                # Authentication and authorization
+│   ├── balance.py             # Balance management endpoints
+│   ├── discovery.py           # Nostr relay discovery
+│   ├── proxy.py               # Request proxying logic
+│   ├── wallet.py              # Cashu wallet operations
+│   │
+│   ├── core/                  # Core infrastructure
+│   │   ├── __init__.py
+│   │   ├── admin.py          # Admin dashboard and API
+│   │   ├── db.py             # Database models and connection
+│   │   ├── exceptions.py     # Custom exception classes
+│   │   ├── logging.py        # Structured logging setup
+│   │   ├── main.py           # FastAPI app initialization
+│   │   └── middleware.py     # HTTP middleware components
+│   │
+│   └── payment/               # Payment processing
+│       ├── __init__.py
+│       ├── cost_calculation.py # Usage cost calculation
+│       ├── helpers.py         # Payment utilities
+│       ├── lnurl.py          # Lightning URL support
+│       ├── models.py         # Model pricing management
+│       ├── price.py          # BTC/USD price handling
+│       └── x_cashu.py        # Cashu header protocol
+│
+├── tests/                     # Test suite
+│   ├── __init__.py
+│   ├── conftest.py           # Pytest configuration
+│   ├── unit/                 # Unit tests
+│   └── integration/          # Integration tests
+│
+├── migrations/               # Alembic database migrations
+│   ├── alembic.ini
+│   ├── env.py
+│   ├── script.py.mako
+│   └── versions/             # Migration files
+│
+├── scripts/                  # Utility scripts
+│   └── models_meta.py       # Fetch model pricing
+│
+├── docs/                    # Documentation
+├── logs/                    # Application logs (git ignored)
+│
+├── .github/                 # GitHub Actions workflows
+├── .env.example            # Environment variable template
+├── .gitignore             # Git ignore rules
+├── .dockerignore          # Docker ignore rules
+├── Dockerfile             # Container definition
+├── Makefile               # Development commands
+├── README.md              # Project overview
+├── alembic.ini            # Migration configuration
+├── compose.yml            # Docker Compose setup
+├── compose.testing.yml    # Testing environment
+├── pyproject.toml         # Project configuration
+└── uv.lock               # Locked dependencies
+```
+
+## Key Modules
+
+### Application Entry Point
+
+#### `routstr/__init__.py`
+
+```python
+# Loads environment variables
+import dotenv
+dotenv.load_dotenv()
+
+# Exports FastAPI app
+from .core.main import app as fastapi_app
+```
+
+#### `routstr/core/main.py`
+
+```python
+# FastAPI application setup
+app = FastAPI(
+    title="Routstr Node",
+    lifespan=lifespan,  # Manages startup/shutdown
+)
+
+# Middleware registration
+app.add_middleware(CORSMiddleware, ...)
+app.add_middleware(LoggingMiddleware)
+
+# Router inclusion
+app.include_router(admin_router)
+app.include_router(balance_router)
+app.include_router(proxy_router)
+```
+
+### Authentication Module
+
+#### `routstr/auth.py`
+
+Handles API key validation and authorization:
+
+```python
+class APIKeyAuth:
+    """FastAPI dependency for API key authentication"""
+    
+    async def __call__(self, request: Request) -> APIKey:
+        # Extract and validate API key
+        # Check balance
+        # Return authenticated key object
+
+# Usage in routes:
+@router.get("/protected")
+async def protected_route(api_key: APIKey = Depends(APIKeyAuth())):
+    pass
+```
+
+Key functions:
+
+- `create_api_key()` - Generate new API keys
+- `validate_api_key()` - Verify and retrieve key
+- `check_balance()` - Ensure sufficient funds
+- `update_last_used()` - Track usage
+
+### Payment Processing
+
+#### `routstr/payment/cost_calculation.py`
+
+Calculates request costs:
+
+```python
+def calculate_request_cost(
+    model: str,
+    prompt_tokens: int,
+    completion_tokens: int,
+    **kwargs
+) -> CostData:
+    """Calculate cost in millisatoshis"""
+    # Model-based or fixed pricing
+    # Token counting
+    # Fee application
+    # Currency conversion
+```
+
+#### `routstr/payment/models.py`
+
+Manages model pricing data:
+
+```python
+class ModelPrice:
+    id: str
+    name: str
+    pricing: dict[str, float]  # USD prices
+    context_length: int
+    
+# Global model registry
+MODELS: dict[str, ModelPrice] = load_models()
+
+# Dynamic price updates
+async def update_sats_pricing():
+    """Background task to update BTC prices"""
+```
+
+#### `routstr/payment/x_cashu.py`
+
+Implements Cashu payment protocol:
+
+```python
+class XCashuHandler:
+    """Handle x-cashu header payments"""
+    
+    async def process_request_payment(
+        self, 
+        token: str,
+        estimated_cost: int
+    ) -> PaymentResult:
+        # Validate token
+        # Check minimum amount
+        # Process payment
+        # Generate change
+```
+
+### Request Proxying
+
+#### `routstr/proxy.py`
+
+Core proxy functionality:
+
+```python
+@router.api_route("/{path:path}", methods=ALL_METHODS)
+async def proxy_request(
+    request: Request,
+    path: str,
+    api_key: APIKey = Depends(APIKeyAuth())
+) -> Response:
+    """Forward requests to upstream provider"""
+    # Build upstream request
+    # Stream response
+    # Track usage
+    # Deduct costs
+```
+
+Key features:
+
+- Streaming support
+- Header preservation
+- Error handling
+- Usage tracking
+
+### Database Layer
+
+#### `routstr/core/db.py`
+
+SQLModel definitions:
+
+```python
+class APIKey(SQLModel, table=True):
+    id: int | None = Field(primary_key=True)
+    key_hash: str = Field(index=True, unique=True)
+    balance: int  # millisatoshis
+    total_deposited: int = 0
+    total_spent: int = 0
+    created_at: datetime
+    expires_at: datetime | None = None
+    metadata: dict = Field(default_factory=dict, sa_column=Column(JSON))
+
+class Transaction(SQLModel, table=True):
+    id: int | None = Field(primary_key=True)
+    api_key_id: int = Field(foreign_key="apikey.id")
+    amount: int  # can be negative
+    balance_after: int
+    type: TransactionType
+    description: str
+    timestamp: datetime
+```
+
+### Admin Interface
+
+#### `routstr/core/admin.py`
+
+Web dashboard and admin API:
+
+```python
+@admin_router.get("/admin/")
+async def admin_dashboard(request: Request):
+    """Render admin HTML interface"""
+    # Authentication check
+    # Load statistics
+    # Render template
+
+@admin_router.post("/admin/api/withdraw")
+async def withdraw_balance(
+    api_key: str,
+    amount: int | None = None
+) -> WithdrawalResponse:
+    """Generate eCash token for withdrawal"""
+```
+
+Features:
+
+- HTML dashboard
+- API key management
+- Balance withdrawals
+- Usage statistics
+
+### Wallet Integration
+
+#### `routstr/wallet.py`
+
+Cashu wallet operations:
+
+```python
+class WalletManager:
+    """Manage Cashu wallet instances"""
+    
+    async def redeem_token(
+        self, 
+        token: str,
+        mint_url: str | None = None
+    ) -> int:
+        """Redeem eCash token and return value"""
+        
+    async def create_token(
+        self,
+        amount: int,
+        mint_url: str
+    ) -> str:
+        """Create eCash token for withdrawal"""
+```
+
+### Utility Modules
+
+#### `routstr/core/logging.py`
+
+Structured logging configuration:
+
+```python
+def setup_logging():
+    """Configure JSON structured logging"""
+    # Set log level
+    # Configure formatters
+    # Add handlers
+    
+class RequestIdMiddleware:
+    """Add request ID to all logs"""
+```
+
+#### `routstr/core/middleware.py`
+
+HTTP middleware components:
+
+```python
+class LoggingMiddleware:
+    """Log all HTTP requests/responses"""
+    
+class ErrorHandlingMiddleware:
+    """Consistent error responses"""
+```
+
+#### `routstr/core/exceptions.py`
+
+Custom exception hierarchy:
+
+```python
+class RoustrError(Exception):
+    """Base exception with error details"""
+    status_code: int
+    error_type: str
+    detail: str
+
+class PaymentError(RoustrError):
+    """Payment-related errors"""
+
+class UpstreamError(RoustrError):
+    """Upstream API errors"""
+```
+
+## Configuration Files
+
+### `pyproject.toml`
+
+Project metadata and dependencies:
+
+```toml
+[project]
+name = "routstr"
+version = "0.2.0"
+dependencies = [
+    "fastapi[standard]>=0.115",
+    "sqlmodel>=0.0.24",
+    "cashu",
+    # ...
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+```
+
+### `alembic.ini`
+
+Database migration configuration:
+
+```ini
+[alembic]
+script_location = migrations
+prepend_sys_path = .
+version_path_separator = os
+
+[loggers]
+keys = root,sqlalchemy,alembic
+```
+
+### `Makefile`
+
+Development commands:
+
+```makefile
+# Setup commands
+setup:
+    uv sync
+    uv pip install -e .
+
+# Development server
+dev:
+    fastapi dev routstr --host 0.0.0.0
+
+# Testing
+test:
+    uv run pytest
+
+# Code quality
+lint:
+    uv run ruff check .
+```
+
+## Code Patterns
+
+### Dependency Injection
+
+Using FastAPI's DI system:
+
+```python
+# Define dependency
+async def get_db() -> AsyncSession:
+    async with async_session() as session:
+        yield session
+
+# Use in routes
+@router.get("/items")
+async def get_items(db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(Item))
+    return result.scalars().all()
+```
+
+### Async Context Managers
+
+For resource management:
+
+```python
+async with httpx.AsyncClient() as client:
+    response = await client.get(url)
+    
+async with database.transaction():
+    # Atomic operations
+```
+
+### Type Safety
+
+Leveraging Python 3.11+ features:
+
+```python
+# Union types with |
+def process(value: str | int) -> dict[str, Any]:
+    pass
+
+# Type aliases
+Balance = int  # millisatoshis
+TokenList = list[dict[str, str]]
+```
+
+### Error Handling
+
+Consistent error responses:
+
+```python
+try:
+    result = await risky_operation()
+except SpecificError as e:
+    logger.error("Operation failed", exc_info=True)
+    raise HTTPException(
+        status_code=400,
+        detail={
+            "error": "specific_error",
+            "message": str(e)
+        }
+    )
+```
+
+## Best Practices
+
+### Module Organization
+
+1. **Single Responsibility**: Each module has one clear purpose
+2. **Minimal Imports**: Import only what's needed
+3. **Circular Dependencies**: Avoid by using dependency injection
+4. **Public API**: Expose through `__init__.py`
+
+### Function Design
+
+1. **Type Hints**: Always include complete type annotations
+2. **Async First**: Use async/await for I/O operations
+3. **Error Handling**: Raise specific exceptions
+4. **Documentation**: Docstrings for public functions
+
+### Testing Structure
+
+1. **Mirror Source**: Test structure matches source
+2. **Fixtures**: Reusable test data in conftest.py
+3. **Mocking**: Mock external dependencies
+4. **Coverage**: Aim for >80% coverage
+
+## Next Steps
+
+- Review [Testing Guide](testing.md) for test structure
+- Read [Architecture](architecture.md) for system design

docs/contributing/setup.md

@@ -0,0 +1,389 @@
+# Development Setup
+
+This guide will help you set up a development environment for contributing to Routstr Core.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- **Python 3.11+** - Required for type hints and modern features
+- **Git** - For version control
+- **Docker** (optional) - For running integration tests
+- **Make** - For running development commands
+
+## Quick Start
+
+### 1. Fork and Clone
+
+First, fork the repository on GitHub, then clone your fork:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/routstr-core.git
+cd routstr-core
+```
+
+### 2. Install uv
+
+We use [uv](https://github.com/astral-sh/uv) for fast, reliable Python package management:
+
+```bash
+# Using the installer script
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or with pip
+pip install uv
+
+# Or with Homebrew (macOS)
+brew install uv
+```
+
+### 3. Set Up Environment
+
+Run the setup command:
+
+```bash
+make setup
+```
+
+This will:
+
+- ✅ Install uv if not present
+- ✅ Create a virtual environment
+- ✅ Install all dependencies
+- ✅ Install dev tools (mypy, ruff, pytest)
+- ✅ Install project in editable mode
+
+### 4. Configure Environment
+
+Create your environment file:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your configuration:
+
+```bash
+# Minimum required for development
+UPSTREAM_BASE_URL=https://api.openai.com/v1
+UPSTREAM_API_KEY=your-api-key  # Optional for mock testing
+ADMIN_PASSWORD=development-password
+DATABASE_URL=sqlite+aiosqlite:///dev.db
+```
+
+### 5. Verify Installation
+
+Run these commands to verify your setup:
+
+```bash
+# Check dependencies
+make check-deps
+
+# Run unit tests
+make test-unit
+
+# Start development server
+make dev
+```
+
+## Development Workflow
+
+### Running the Server
+
+For development with auto-reload:
+
+```bash
+make dev
+# Server starts at http://localhost:8000
+# Auto-reloads on code changes
+```
+
+For production-like environment:
+
+```bash
+make run
+```
+
+### Code Quality
+
+Before committing, always run:
+
+```bash
+# Format code
+make format
+
+# Check linting
+make lint
+
+# Type checking
+make type-check
+
+# All checks at once
+make check
+```
+
+### Testing
+
+Run different test suites:
+
+```bash
+# Unit tests only (fast)
+make test-unit
+
+# Integration tests with mocks
+make test-integration
+
+# All tests
+make test
+
+# With coverage report
+make test-coverage
+
+# Run specific test
+uv run pytest tests/unit/test_auth.py::test_token_validation -v
+```
+
+### Database Management
+
+Work with database migrations:
+
+```bash
+# Create new migration
+make db-migrate
+
+# Apply migrations
+make db-upgrade
+
+# Rollback one migration
+make db-downgrade
+
+# View current revision
+make db-current
+```
+
+## Project Structure
+
+Understanding the codebase:
+
+```
+routstr-core/
+├── routstr/                    # Main package
+│   ├── __init__.py            # Package initialization
+│   ├── auth.py                # Authentication logic
+│   ├── balance.py             # Balance management
+│   ├── discovery.py           # Nostr discovery
+│   ├── proxy.py               # Request proxying
+│   ├── wallet.py              # Cashu wallet integration
+│   │
+│   ├── core/                  # Core modules
+│   │   ├── admin.py          # Admin dashboard
+│   │   ├── db.py             # Database models
+│   │   ├── exceptions.py     # Custom exceptions
+│   │   ├── logging.py        # Logging setup
+│   │   ├── main.py           # FastAPI app
+│   │   └── middleware.py     # HTTP middleware
+│   │
+│   └── payment/               # Payment processing
+│       ├── cost_calculation.py # Cost logic
+│       ├── helpers.py         # Utilities
+│       ├── lnurl.py          # Lightning URLs
+│       ├── models.py         # Model pricing
+│       ├── price.py          # BTC pricing
+│       └── x_cashu.py        # Cashu headers
+│
+├── tests/                     # Test suite
+│   ├── unit/                 # Unit tests
+│   └── integration/          # Integration tests
+│
+├── migrations/               # Database migrations
+├── scripts/                  # Utility scripts
+├── docs/                     # Documentation
+│
+├── Makefile                  # Dev commands
+├── pyproject.toml           # Project config
+└── compose.yml              # Docker setup
+```
+
+## Common Tasks
+
+### Adding a New Endpoint
+
+1. Create route in appropriate module
+2. Add request/response models
+3. Write unit tests
+4. Update API documentation
+5. Add integration tests
+
+Example:
+
+```python
+# In routstr/core/main.py or appropriate router
+@app.get("/v1/stats")
+async def get_stats(
+    user: User = Depends(get_current_user)
+) -> StatsResponse:
+    """Get usage statistics for the current user."""
+    # Implementation
+    pass
+```
+
+### Adding a Database Model
+
+1. Define model in `routstr/core/db.py`
+2. Create migration: `make db-migrate`
+3. Review generated migration
+4. Apply: `make db-upgrade`
+
+Example:
+
+```python
+class Transaction(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    api_key_id: int = Field(foreign_key="apikey.id")
+    amount: int  # millisatoshis
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    description: str
+```
+
+### Writing Tests
+
+Follow the AAA pattern:
+
+```python
+async def test_balance_deduction():
+    # Arrange
+    api_key = await create_test_api_key(balance=1000)
+    
+    # Act
+    result = await deduct_balance(api_key.key, amount=100)
+    
+    # Assert
+    assert result.success
+    assert result.new_balance == 900
+    assert result.deducted == 100
+```
+
+## Development Tools
+
+### Makefile Commands
+
+Key commands for development:
+
+```bash
+make help         # Show all commands
+make setup        # Initial setup
+make dev          # Run dev server
+make test         # Run all tests
+make lint         # Check code style
+make format       # Fix code style
+make type-check   # Check types
+make clean        # Clean temp files
+make docker-build # Build Docker image
+```
+
+### IDE Setup
+
+#### VS Code
+
+Recommended extensions:
+
+- Python
+- Pylance
+- Ruff
+- GitLens
+
+Settings (`.vscode/settings.json`):
+
+```json
+{
+    "python.linting.enabled": true,
+    "python.linting.ruffEnabled": true,
+    "python.formatting.provider": "ruff",
+    "python.analysis.typeCheckingMode": "strict",
+    "editor.formatOnSave": true
+}
+```
+
+#### PyCharm
+
+1. Set Python interpreter to uv venv
+2. Enable type checking
+3. Configure Ruff as external tool
+4. Set up file watchers for formatting
+
+### Debugging
+
+#### Debug Server
+
+```bash
+# Run with debug logging
+LOG_LEVEL=DEBUG make dev
+
+# Or with debugger
+uv run python -m debugpy --listen 5678 --wait-for-client \
+    -m uvicorn routstr:fastapi_app --reload
+```
+
+#### Debug Tests
+
+```bash
+# Run specific test with output
+uv run pytest tests/unit/test_auth.py -v -s
+
+# With debugger
+uv run pytest tests/unit/test_auth.py --pdb
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Import Errors**
+
+```bash
+# Ensure project is installed in editable mode
+uv sync
+uv pip install -e .
+```
+
+**Database Errors**
+
+```bash
+# Reset database
+rm dev.db
+make db-upgrade
+```
+
+**Type Checking Fails**
+
+```bash
+# Clear mypy cache
+make clean
+make type-check
+```
+
+**Tests Fail Locally**
+
+```bash
+# Ensure test dependencies are installed
+uv sync --dev
+
+# Check for leftover test data
+rm -rf test_*.db
+```
+
+### Getting Help
+
+- Check existing [GitHub Issues](https://github.com/routstr/routstr-core/issues)
+- Ask in [GitHub Discussions](https://github.com/routstr/routstr-core/discussions)
+- Read the [Architecture Guide](architecture.md)
+
+## Next Steps
+
+Now that you're set up:
+
+1. Read the [Architecture Overview](architecture.md)
+3. Check [open issues](https://github.com/routstr/routstr-core/issues)
+4. Start with a small contribution
+
+Happy coding! 🚀

docs/contributing/testing.md

@@ -0,0 +1,581 @@
+# Testing Guide
+
+This guide covers testing practices, patterns, and tools used in Routstr Core development.
+
+## Testing Philosophy
+
+We follow these principles:
+
+- **Test Behavior, Not Implementation** - Tests should survive refactoring
+- **Fast Feedback** - Unit tests run in milliseconds
+- **Reliable Tests** - No flaky tests allowed
+- **Clear Failures** - Tests should clearly indicate what broke
+
+## Test Structure
+
+```
+tests/
+├── __init__.py
+├── conftest.py              # Shared fixtures and configuration
+├── unit/                    # Fast, isolated unit tests
+│   ├── test_auth.py
+│   ├── test_balance.py
+│   ├── test_cost_calculation.py
+│   ├── test_models.py
+│   └── test_wallet.py
+└── integration/             # Component integration tests
+    ├── test_api_endpoints.py
+    ├── test_payment_flow.py
+    ├── test_proxy_streaming.py
+    └── test_real_mint.py
+```
+
+## Running Tests
+
+### Quick Test Commands
+
+```bash
+# Run all tests
+make test
+
+# Run unit tests only (fast)
+make test-unit
+
+# Run integration tests
+make test-integration
+
+# Run with coverage
+make test-coverage
+
+# Run specific test file
+uv run pytest tests/unit/test_auth.py -v
+
+# Run specific test
+uv run pytest tests/unit/test_auth.py::test_create_api_key -v
+
+# Run tests matching pattern
+uv run pytest -k "balance" -v
+```
+
+### Test Markers
+
+Use markers to categorize tests:
+
+```python
+@pytest.mark.slow
+async def test_heavy_computation():
+    pass
+
+@pytest.mark.requires_docker
+async def test_real_services():
+    pass
+
+# Run without slow tests
+pytest -m "not slow"
+
+# Run only integration tests
+pytest -m "integration"
+```
+
+## Writing Tests
+
+### Unit Test Example
+
+```python
+# tests/unit/test_auth.py
+import pytest
+from routstr.auth import create_api_key, validate_api_key
+
+class TestAPIKeyAuth:
+    """Test API key authentication functionality"""
+    
+    async def test_create_api_key(self, test_db):
+        """Test creating a new API key"""
+        # Arrange
+        initial_balance = 10000
+        
+        # Act
+        api_key = await create_api_key(
+            balance=initial_balance,
+            name="Test Key"
+        )
+        
+        # Assert
+        assert api_key.key.startswith("sk-")
+        assert len(api_key.key) == 32
+        assert api_key.balance == initial_balance
+        
+    async def test_validate_invalid_key(self, test_db):
+        """Test validation fails for invalid key"""
+        # Act & Assert
+        with pytest.raises(InvalidAPIKeyError):
+            await validate_api_key("invalid_key")
+```
+
+### Integration Test Example
+
+```python
+# tests/integration/test_payment_flow.py
+import pytest
+from httpx import AsyncClient
+
+class TestPaymentFlow:
+    """Test end-to-end payment flows"""
+    
+    @pytest.mark.asyncio
+    async def test_token_redemption_flow(
+        self, 
+        app_client: AsyncClient,
+        mock_cashu_wallet
+    ):
+        """Test complete token redemption and API usage"""
+        # Arrange
+        token = create_test_token(amount=5000)
+        mock_cashu_wallet.redeem.return_value = 5000
+        
+        # Act - Create API key
+        response = await app_client.post(
+            "/v1/wallet/create",
+            json={"cashu_token": token}
+        )
+        
+        # Assert - Key created
+        assert response.status_code == 200
+        api_key = response.json()["api_key"]
+        assert response.json()["balance"] == 5000
+        
+        # Act - Use API key
+        response = await app_client.post(
+            "/v1/chat/completions",
+            headers={"Authorization": f"Bearer {api_key}"},
+            json={
+                "model": "gpt-3.5-turbo",
+                "messages": [{"role": "user", "content": "Hi"}]
+            }
+        )
+        
+        # Assert - Request successful
+        assert response.status_code == 200
+        assert "choices" in response.json()
+```
+
+## Test Fixtures
+
+### Common Fixtures
+
+Located in `tests/conftest.py`:
+
+```python
+@pytest.fixture
+async def test_db():
+    """Provide a clean test database"""
+    # Create in-memory SQLite database
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+    
+    async_session = sessionmaker(engine, class_=AsyncSession)
+    
+    async with async_session() as session:
+        yield session
+    
+    await engine.dispose()
+
+@pytest.fixture
+async def app_client(test_db):
+    """Provide test client with test database"""
+    app.dependency_overrides[get_db] = lambda: test_db
+    
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+    
+    app.dependency_overrides.clear()
+
+@pytest.fixture
+def mock_cashu_wallet(mocker):
+    """Mock Cashu wallet for testing"""
+    mock = mocker.patch("routstr.wallet.Wallet")
+    mock.return_value.redeem.return_value = 1000
+    return mock
+```
+
+### Using Fixtures
+
+```python
+async def test_with_fixtures(
+    test_db,          # Get test database
+    app_client,       # Get test HTTP client
+    mock_cashu_wallet # Get mocked wallet
+):
+    # Use fixtures in test
+    pass
+```
+
+## Mocking Strategies
+
+### Mocking External Services
+
+```python
+# Mock upstream API
+@pytest.fixture
+def mock_openai(mocker):
+    mock_response = mocker.Mock()
+    mock_response.json.return_value = {
+        "choices": [{
+            "message": {"content": "Hello!"},
+            "finish_reason": "stop"
+        }],
+        "usage": {
+            "prompt_tokens": 10,
+            "completion_tokens": 20,
+            "total_tokens": 30
+        }
+    }
+    
+    mocker.patch(
+        "httpx.AsyncClient.post",
+        return_value=mock_response
+    )
+
+# Mock Cashu mint
+@pytest.fixture
+def mock_mint(mocker):
+    mint = mocker.patch("routstr.wallet.Mint")
+    mint.return_value.check_proof_state.return_value = True
+    return mint
+```
+
+### Mocking Time
+
+```python
+from freezegun import freeze_time
+
+@freeze_time("2024-01-01 12:00:00")
+async def test_time_dependent():
+    # Time is frozen during test
+    key = await create_api_key(expires_in_days=30)
+    assert key.expires_at == datetime(2024, 1, 31, 12, 0, 0)
+```
+
+## Test Patterns
+
+### Testing Async Code
+
+```python
+# Always mark async tests
+@pytest.mark.asyncio
+async def test_async_function():
+    result = await async_operation()
+    assert result == expected
+
+# Test async context managers
+async def test_async_context():
+    async with create_resource() as resource:
+        assert resource.is_active
+```
+
+### Testing Exceptions
+
+```python
+# Test specific exception
+async def test_raises_specific_error():
+    with pytest.raises(InsufficientBalanceError) as exc_info:
+        await deduct_balance(api_key, amount=999999)
+    
+    assert "Insufficient balance" in str(exc_info.value)
+    assert exc_info.value.status_code == 402
+
+# Test exception details
+async def test_exception_details():
+    with pytest.raises(RoustrError) as exc_info:
+        await risky_operation()
+    
+    error = exc_info.value
+    assert error.error_type == "validation_error"
+    assert error.detail == "Invalid input"
+```
+
+### Testing Streaming Responses
+
+```python
+async def test_streaming_response():
+    """Test streaming chat completion"""
+    chunks = []
+    
+    async with app_client.stream(
+        "POST",
+        "/v1/chat/completions",
+        json={"model": "gpt-3.5-turbo", "stream": True}
+    ) as response:
+        async for line in response.aiter_lines():
+            if line.startswith("data: "):
+                chunks.append(json.loads(line[6:]))
+    
+    # Verify chunks
+    assert len(chunks) > 0
+    assert chunks[-1] == "[DONE]"
+```
+
+### Database Testing
+
+```python
+async def test_database_transaction(test_db):
+    """Test atomic transactions"""
+    async with test_db.begin():
+        # Create test data
+        api_key = APIKey(key_hash="test", balance=1000)
+        test_db.add(api_key)
+        await test_db.flush()
+        
+        # Test rollback
+        try:
+            async with test_db.begin_nested():
+                api_key.balance = -100  # Invalid
+                await test_db.flush()
+                raise ValueError("Rollback")
+        except ValueError:
+            pass
+        
+        # Verify rollback worked
+        await test_db.refresh(api_key)
+        assert api_key.balance == 1000
+```
+
+## Performance Testing
+
+### Benchmark Tests
+
+```python
+@pytest.mark.benchmark
+def test_performance(benchmark):
+    """Benchmark critical functions"""
+    result = benchmark(expensive_function, arg1, arg2)
+    assert result == expected
+
+# Run benchmarks
+pytest --benchmark-only
+```
+
+### Load Testing
+
+```python
+# tests/integration/test_load.py
+async def test_concurrent_requests(app_client):
+    """Test handling multiple concurrent requests"""
+    async def make_request(i):
+        response = await app_client.get(f"/test/{i}")
+        return response.status_code
+    
+    # Make 100 concurrent requests
+    tasks = [make_request(i) for i in range(100)]
+    results = await asyncio.gather(*tasks)
+    
+    # All should succeed
+    assert all(status == 200 for status in results)
+```
+
+## Test Data
+
+### Factories
+
+```python
+# tests/factories.py
+from datetime import datetime, timedelta
+
+def create_test_api_key(**kwargs):
+    """Factory for test API keys"""
+    defaults = {
+        "key": f"sk-test-{uuid4().hex[:8]}",
+        "balance": 10000,
+        "created_at": datetime.utcnow(),
+        "expires_at": datetime.utcnow() + timedelta(days=30)
+    }
+    defaults.update(kwargs)
+    return APIKey(**defaults)
+
+def create_test_token(amount: int = 1000, mint: str = None):
+    """Factory for test Cashu tokens"""
+    # Create valid test token structure
+    return base64.encode(...)
+```
+
+### Test Constants
+
+```python
+# tests/constants.py
+TEST_MODELS = {
+    "gpt-3.5-turbo": {
+        "prompt": 0.0015,
+        "completion": 0.002
+    },
+    "gpt-4": {
+        "prompt": 0.03,
+        "completion": 0.06
+    }
+}
+
+TEST_API_KEY = "sk-test-1234567890"
+TEST_MINT_URL = "https://testmint.example.com"
+```
+
+## Coverage
+
+### Running Coverage
+
+```bash
+# Generate coverage report
+make test-coverage
+
+# View HTML report
+open htmlcov/index.html
+
+# Coverage with specific tests
+pytest --cov=routstr --cov-report=html tests/unit/
+```
+
+### Coverage Configuration
+
+In `pyproject.toml`:
+
+```toml
+[tool.coverage.run]
+source = ["routstr"]
+omit = ["tests/*", "*/migrations/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:"
+]
+```
+
+## Debugging Tests
+
+### Print Debugging
+
+```python
+# Use -s flag to see print output
+pytest -s tests/unit/test_auth.py
+
+# In test
+async def test_debug():
+    print(f"Value: {value}")  # Will show with -s
+    assert value == expected
+```
+
+### Interactive Debugging
+
+```python
+# Drop into debugger on failure
+pytest --pdb
+
+# Set breakpoint in test
+async def test_debug():
+    import pdb; pdb.set_trace()
+    # Execution stops here
+```
+
+### Logging in Tests
+
+```python
+# Enable debug logging in tests
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Or use caplog fixture
+async def test_logging(caplog):
+    with caplog.at_level(logging.INFO):
+        await function_that_logs()
+    
+    assert "Expected message" in caplog.text
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+Tests run automatically on:
+
+- Pull requests
+- Pushes to main
+- Nightly schedules
+
+See `.github/workflows/test.yml` for configuration.
+
+### Pre-commit Hooks
+
+Install pre-commit hooks:
+
+```bash
+pre-commit install
+
+# Run manually
+pre-commit run --all-files
+```
+
+## Best Practices
+
+### Do's
+
+1. ✅ Write tests first (TDD)
+2. ✅ Keep tests simple and focused
+3. ✅ Use descriptive test names
+4. ✅ Test edge cases
+5. ✅ Mock external dependencies
+6. ✅ Use fixtures for setup
+7. ✅ Assert specific values
+
+### Don'ts
+
+1. ❌ Don't test implementation details
+2. ❌ Don't use production services
+3. ❌ Don't rely on test order
+4. ❌ Don't ignore flaky tests
+5. ❌ Don't skip error cases
+6. ❌ Don't use hard-coded waits
+7. ❌ Don't commit commented tests
+
+## Troubleshooting
+
+### Common Issues
+
+**Async Test Errors**
+
+```python
+# Wrong
+def test_async():  # Missing async
+    await function()
+
+# Right
+async def test_async():
+    await function()
+```
+
+**Database State**
+
+```python
+# Ensure clean state
+@pytest.fixture(autouse=True)
+async def cleanup(test_db):
+    yield
+    # Cleanup after each test
+    await test_db.execute("DELETE FROM apikey")
+    await test_db.commit()
+```
+
+**Mock Not Working**
+
+```python
+# Check import path
+mocker.patch("routstr.wallet.Wallet")  # Full path
+# Not just "Wallet"
+```
+
+## Next Steps
+
+- See [Architecture](architecture.md) for system design
+- Read [Setup Guide](setup.md) for environment setup

docs/getting-started/configuration.md

@@ -0,0 +1,260 @@
+# Configuration
+
+Routstr Core is configured via a single settings row in the database. Environment variables are only used on first run to seed that row (with a few computed defaults like `ONION_URL`). After that, the database is the source of truth. You can update settings at runtime via the admin API. `DATABASE_URL` is always env-only.
+
+## Environment Variables
+
+### Core Settings
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `UPSTREAM_BASE_URL` | Base URL of the OpenAI-compatible API to proxy | - | ✅ |
+| `UPSTREAM_API_KEY` | API key for the upstream service | - | ❌ |
+| `ADMIN_PASSWORD` | Password for admin dashboard access | - | ⚠️ |
+
+### Node Information
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `NAME` | Public name of your Routstr node | `ARoutstrNode` | ❌ |
+| `DESCRIPTION` | Description of your node | `A Routstr Node` | ❌ |
+| `NPUB` | Nostr public key for node identity | - | ❌ |
+| `HTTP_URL` | Public HTTP URL of your node | - | ❌ |
+| `ONION_URL` | Tor hidden service URL | - | ❌ |
+
+### Cashu Configuration
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `CASHU_MINTS` | Comma-separated list of trusted Cashu mint URLs | `https://mint.minibits.cash/Bitcoin` | ❌ |
+| `RECEIVE_LN_ADDRESS` | Lightning address for automatic payouts | - | ❌ |
+
+### Pricing Configuration
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `FIXED_PRICING` | Force fixed per-request pricing (ignore model token pricing) | `false` | ❌ |
+| `FIXED_COST_PER_REQUEST` | Fixed cost per API request in sats | `1` | ❌ |
+| `FIXED_PER_1K_INPUT_TOKENS` | Optional override: sats per 1000 input tokens | `0` | ❌ |
+| `FIXED_PER_1K_OUTPUT_TOKENS` | Optional override: sats per 1000 output tokens | `0` | ❌ |
+| `EXCHANGE_FEE` | Exchange rate markup (1.005 = 0.5% fee) | `1.005` | ❌ |
+| `UPSTREAM_PROVIDER_FEE` | Provider fee markup (1.05 = 5% fee) | `1.05` | ❌ |
+
+### Network & Discovery
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `CORS_ORIGINS` | Comma-separated list of allowed CORS origins | `*` | ❌ |
+| `TOR_PROXY_URL` | SOCKS5 proxy URL for Tor connections | `socks5://127.0.0.1:9050` | ❌ |
+| `RELAYS` | Comma-separated nostr relays used for provider discovery | sane defaults | ❌ |
+| `PROVIDERS_REFRESH_INTERVAL_SECONDS` | Provider cache refresh interval | `300` | ❌ |
+
+### Logging Configuration
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | `INFO` | ❌ |
+| `ENABLE_CONSOLE_LOGGING` | Enable console log output | `true` | ❌ |
+
+### Other
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `CHAT_COMPLETIONS_API_VERSION` | Append `api-version` to `/chat/completions` (Azure OpenAI) | - | ❌ |
+| `DATABASE_URL` | SQLite database connection string | `sqlite+aiosqlite:///keys.db` | ❌ |
+| `REFUND_CACHE_TTL_SECONDS` | Cache TTL for refund responses (seconds) | `3600` | ❌ |
+
+## Configuration Examples
+
+### Basic OpenAI Proxy
+
+```bash
+# .env
+UPSTREAM_BASE_URL=https://api.openai.com/v1
+UPSTREAM_API_KEY=sk-...
+ADMIN_PASSWORD=my-secure-password
+```
+
+### Custom AI Provider
+
+```bash
+# .env
+UPSTREAM_BASE_URL=https://api.anthropic.com/v1
+UPSTREAM_API_KEY=your-anthropic-key
+MODELS_PATH=/app/config/anthropic-models.json
+```
+
+### Azure OpenAI (optional)
+
+```bash
+# .env
+UPSTREAM_BASE_URL=https://<resource>.openai.azure.com/openai/deployments/<deployment>
+UPSTREAM_API_KEY=<azure_api_key>
+CHAT_COMPLETIONS_API_VERSION=2024-05-01-preview
+```
+
+### High-Security Setup
+
+```bash
+# .env
+UPSTREAM_BASE_URL=https://api.openai.com/v1
+UPSTREAM_API_KEY=sk-...
+ADMIN_PASSWORD=very-long-secure-password-here
+CORS_ORIGINS=https://myapp.com,https://app.myapp.com
+TOR_PROXY_URL=socks5://tor:9050
+LOG_LEVEL=WARNING
+```
+
+### Public Node Configuration
+
+```bash
+# .env
+NAME=Lightning AI Gateway
+DESCRIPTION=Fast and reliable AI API access with Bitcoin payments
+NPUB=npub1abcd...
+HTTP_URL=https://api.lightning-ai.com
+ONION_URL=http://lightningai.onion
+CASHU_MINTS=https://mint1.com,https://mint2.com
+```
+
+## Pricing
+
+- Default: pricing comes from your `models.json`.
+- Force fixed per-request pricing: set `FIXED_PRICING=true` and `FIXED_COST_PER_REQUEST`.
+- Optional token overrides when using model pricing: set
+  `FIXED_PER_1K_INPUT_TOKENS` and/or `FIXED_PER_1K_OUTPUT_TOKENS`.
+- Legacy envs are still accepted and mapped automatically:
+  `MODEL_BASED_PRICING` → `!FIXED_PRICING`, `COST_PER_REQUEST` → `FIXED_COST_PER_REQUEST`,
+  `COST_PER_1K_*` → `FIXED_PER_1K_*`.
+
+Example fixed pricing:
+
+```bash
+FIXED_PRICING=true
+FIXED_COST_PER_REQUEST=10
+```
+
+## Custom Models Configuration
+
+Create a `models.json` file:
+
+```json
+{
+  "models": [
+    {
+      "id": "gpt-4",
+      "name": "GPT-4",
+      "pricing": {
+        "prompt": "0.00003",
+        "completion": "0.00006",
+        "request": "0"
+      }
+    },
+    {
+      "id": "gpt-3.5-turbo",
+      "name": "GPT-3.5 Turbo",
+      "pricing": {
+        "prompt": "0.0000015",
+        "completion": "0.000002",
+        "request": "0"
+      }
+    }
+  ]
+}
+```
+
+## Security Best Practices
+
+### Admin Password
+
+Generate a strong password:
+
+```bash
+openssl rand -base64 32
+```
+
+### API Keys
+
+- Rotate upstream API keys regularly
+- Use read-only keys when possible
+- Monitor key usage
+
+### Network Security
+
+- Restrict CORS origins in production
+- Use HTTPS for public endpoints
+- Enable Tor for anonymity
+
+### Database Security
+
+- Regular backups
+- Encrypted storage volumes
+- Restricted file permissions
+
+## Troubleshooting
+
+### Check Current Configuration
+
+```bash
+# View all environment variables
+docker exec routstr env | sort
+
+# Test configuration
+curl http://localhost:8000/v1/info
+```
+
+### Common Issues
+
+**Missing Upstream URL**
+
+```
+ERROR: UPSTREAM_BASE_URL not set
+Solution: Set UPSTREAM_BASE_URL in .env
+```
+
+**Invalid Cashu Mint**
+
+```
+ERROR: Failed to connect to mint
+Solution: Verify CASHU_MINTS URLs are accessible
+```
+
+**Database Errors**
+
+```
+ERROR: Database connection failed
+Solution: Check DATABASE_URL and file permissions
+```
+
+## Advanced Configuration
+
+### Multiple Mints
+
+Configure fallback mints:
+
+```bash
+CASHU_MINTS=https://primary.mint,https://backup1.mint,https://backup2.mint
+```
+
+### Custom Database
+
+Use PostgreSQL instead of SQLite:
+
+```bash
+DATABASE_URL=postgresql+asyncpg://user:pass@localhost/routstr
+```
+
+### Proxy Settings
+
+For corporate environments:
+
+```bash
+HTTP_PROXY=http://proxy.company.com:8080
+HTTPS_PROXY=http://proxy.company.com:8080
+```
+
+## Next Steps
+
+- [User Guide](../user-guide/introduction.md) - Start using Routstr
+- [Admin Dashboard](../user-guide/admin-dashboard.md) - Manage your node
+- [Custom Pricing](../advanced/custom-pricing.md) - Advanced pricing strategies

docs/getting-started/docker.md

@@ -0,0 +1,337 @@
+# Docker Setup
+
+This guide covers deploying Routstr Core using Docker for production environments.
+
+## Docker Images
+
+Official images are available on GitHub Container Registry:
+
+```bash
+ghcr.io/routstr/proxy:latest
+```
+
+## Basic Docker Run
+
+### Minimal Setup
+
+```bash
+docker run -d \
+  --name routstr \
+  -p 8000:8000 \
+  -e UPSTREAM_BASE_URL=https://api.openai.com/v1 \
+  -e UPSTREAM_API_KEY=sk-... \
+  -e ADMIN_PASSWORD=secure-password \
+  ghcr.io/routstr/proxy:latest
+```
+
+### With Persistent Storage
+
+```bash
+docker run -d \
+  --name routstr \
+  -p 8000:8000 \
+  -v routstr-data:/app/data \
+  -v routstr-logs:/app/logs \
+  -e UPSTREAM_BASE_URL=https://api.openai.com/v1 \
+  -e UPSTREAM_API_KEY=sk-... \
+  -e DATABASE_URL=sqlite+aiosqlite:///data/keys.db \
+  ghcr.io/routstr/proxy:latest
+```
+
+## Docker Compose Setup
+
+### Basic Configuration
+
+Create `compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  routstr:
+    image: ghcr.io/routstr/proxy:latest
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./data:/app/data
+      - ./logs:/app/logs
+    env_file:
+      - .env
+    restart: unless-stopped
+```
+
+### With Tor Hidden Service
+
+The included `compose.yml` provides Tor support:
+
+```yaml
+version: '3.8'
+
+services:
+  routstr:
+    build: .  # Or use image: ghcr.io/routstr/proxy:latest
+    volumes:
+      - .:/app
+      - ./logs:/app/logs
+    env_file:
+      - .env
+    environment:
+      - TOR_PROXY_URL=socks5://tor:9050
+    ports:
+      - 8000:8000
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+  tor:
+    image: ghcr.io/hundehausen/tor-hidden-service:latest
+    volumes:
+      - tor-data:/var/lib/tor
+    environment:
+      - HS_ROUTER=routstr:8000:80
+    depends_on:
+      - routstr
+
+volumes:
+  tor-data:
+```
+
+### Environment File
+
+Create `.env` file:
+
+```bash
+# Required
+UPSTREAM_BASE_URL=https://api.openai.com/v1
+UPSTREAM_API_KEY=your-api-key
+ADMIN_PASSWORD=secure-admin-password
+
+# Cashu Configuration
+CASHU_MINTS=https://mint.minibits.cash/Bitcoin
+
+# Optional
+NAME=My Routstr Node
+DESCRIPTION=Pay-per-use AI API proxy
+NPUB=npub1...
+HTTP_URL=https://api.mynode.com
+ONION_URL=http://mynode.onion
+
+# Pricing (optional)
+FIXED_PRICING=false
+EXCHANGE_FEE=1.005
+UPSTREAM_PROVIDER_FEE=1.05
+```
+
+## Building Custom Image
+
+### Dockerfile Overview
+
+The provided Dockerfile:
+
+- Uses Alpine Linux for small size
+- Installs required dependencies for secp256k1
+- Runs as non-root user
+- Exposes port 8000
+
+### Build Locally
+
+```bash
+# Clone repository
+git clone https://github.com/routstr/routstr-core.git
+cd routstr-core
+
+# Build image
+docker build -t my-routstr:latest .
+
+# Run custom image
+docker run -d \
+  --name routstr \
+  -p 8000:8000 \
+  --env-file .env \
+  my-routstr:latest
+```
+
+## Deployment Considerations
+
+### Resource Requirements
+
+- **CPU**: 1-2 cores recommended
+- **Memory**: 512MB-1GB
+- **Storage**: 1GB + database growth
+- **Network**: Low latency to upstream provider
+
+### Health Checks
+
+Add health check to compose.yml:
+
+```yaml
+services:
+  routstr:
+    # ... other config ...
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/v1/info"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+```
+
+### Reverse Proxy Setup
+
+#### Nginx Example
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name api.yournode.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # For streaming responses
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_set_header Connection '';
+        proxy_http_version 1.1;
+        chunked_transfer_encoding off;
+    }
+}
+```
+
+#### Caddy Example
+
+```caddy
+api.yournode.com {
+    reverse_proxy localhost:8000 {
+        flush_interval -1
+    }
+}
+```
+
+## Monitoring
+
+### Log Management
+
+View logs:
+
+```bash
+# Docker
+docker logs -f routstr
+
+# Docker Compose
+docker compose logs -f routstr
+
+# Log files
+tail -f ./logs/routstr.log
+```
+
+### Metrics
+
+Monitor key metrics:
+
+- Request count and latency
+- Token validation success rate
+- Upstream API errors
+- Database size growth
+
+## Backup and Recovery
+
+### Database Backup
+
+```bash
+# Backup SQLite database
+docker exec routstr sqlite3 /app/data/keys.db ".backup /app/data/backup.db"
+
+# Copy backup locally
+docker cp routstr:/app/data/backup.db ./backup-$(date +%Y%m%d).db
+```
+
+### Restore from Backup
+
+```bash
+# Stop service
+docker compose down
+
+# Restore database
+docker cp ./backup.db routstr:/app/data/keys.db
+
+# Restart service
+docker compose up -d
+```
+
+## Security Considerations
+
+### Environment Variables
+
+- Never commit `.env` files
+- Use Docker secrets for sensitive data
+- Rotate API keys regularly
+- Use strong admin passwords
+
+### Network Security
+
+- Use HTTPS/TLS termination
+- Restrict admin interface access
+- Enable firewall rules
+- Monitor for suspicious activity
+
+### Container Security
+
+- Run as non-root user
+- Use read-only filesystem where possible
+- Limit container capabilities
+- Keep base image updated
+
+## Troubleshooting
+
+### Container Won't Start
+
+```bash
+# Check logs
+docker logs routstr
+
+# Verify environment
+docker exec routstr env | grep -E "(UPSTREAM|CASHU|ADMIN)"
+
+# Test database connection
+docker exec routstr sqlite3 /app/data/keys.db ".tables"
+```
+
+### Permission Issues
+
+```bash
+# Fix volume permissions
+sudo chown -R 1000:1000 ./data ./logs
+```
+
+### Network Issues
+
+```bash
+# Test upstream connectivity
+docker exec routstr curl -I https://api.openai.com
+
+# Check DNS resolution
+docker exec routstr nslookup api.openai.com
+```
+
+## Production Checklist
+
+- [ ] Set strong `ADMIN_PASSWORD`
+- [ ] Configure proper `UPSTREAM_BASE_URL` and `UPSTREAM_API_KEY`
+- [ ] Set up persistent volumes for data and logs
+- [ ] Configure reverse proxy with TLS
+- [ ] Set up monitoring and alerting
+- [ ] Implement backup strategy
+- [ ] Test disaster recovery
+- [ ] Document deployment process
+
+## Next Steps
+
+- [Configuration Guide](configuration.md) - All environment variables
+- [Admin Dashboard](../user-guide/admin-dashboard.md) - Manage your node

docs/getting-started/overview.md

@@ -0,0 +1,156 @@
+# Overview
+
+Routstr Core is a powerful payment proxy that brings Bitcoin micropayments to AI APIs. This overview will help you understand the core concepts and architecture.
+
+## Core Concepts
+
+### Payment Proxy
+
+Routstr acts as a transparent proxy between your application and OpenAI-compatible APIs. It:
+
+- Intercepts API requests
+- Validates payment tokens
+- Forwards requests to the upstream provider
+- Tracks usage and deducts costs
+- Returns responses to the client
+
+### Cashu eCash Protocol
+
+[Cashu](https://cashu.space) is a Bitcoin eCash protocol that enables:
+
+- **Privacy**: Payments are unlinkable and untraceable
+- **Instant Settlement**: No waiting for blockchain confirmations
+- **Micropayments**: Send fractions of a satoshi
+- **Offline Capability**: Tokens can be transferred without internet
+
+### Lightning Network Integration
+
+Routstr connects to the Lightning Network through Cashu mints, enabling:
+
+- Fast Bitcoin deposits and withdrawals
+- Global payment reach
+- Low transaction fees
+- No minimum payment amounts
+
+## Architecture
+
+### System Components
+
+```mermaid
+graph TB
+    subgraph "Client Side"
+        A[AI Application]
+        B[OpenAI SDK]
+        C[eCash Wallet]
+    end
+    
+    subgraph "Routstr Core"
+        D[FastAPI Server]
+        E[Auth Module]
+        F[Payment Module]
+        G[Proxy Module]
+        H[SQLite Database]
+    end
+    
+    subgraph "External Services"
+        I[Upstream AI Provider]
+        J[Cashu Mint]
+        K[Bitcoin/Lightning]
+    end
+    
+    A --> B
+    B --> D
+    C --> D
+    D --> E
+    E --> F
+    F --> J
+    D --> G
+    G --> I
+    D --> H
+    J --> K
+```
+
+### Key Modules
+
+1. **Authentication** (`auth.py`)
+   - API key validation
+   - Balance checking
+   - Request authorization
+
+2. **Payment Processing** (`payment/`)
+   - Token validation
+   - Cost calculation
+   - Balance updates
+   - Pricing models
+
+3. **Proxy Handler** (`proxy.py`)
+   - Request forwarding
+   - Response streaming
+   - Usage tracking
+   - Error handling
+
+4. **Wallet Management** (`wallet.py`)
+   - Cashu wallet integration
+   - Token redemption
+   - Balance management
+   - Automatic payouts
+
+5. **Admin Interface** (`core/admin.py`)
+   - Web dashboard
+   - Balance viewing
+   - Key management
+   - Withdrawal interface
+
+## Payment Flow
+
+### Standard Flow (API Key)
+
+1. User deposits eCash tokens to create an API key
+2. Client sends requests with the API key
+3. Routstr checks balance and forwards request
+4. Cost is deducted based on actual usage
+5. Response is returned to client
+
+### Per-Request Flow (Coming Soon)
+
+1. Client includes eCash token in request header
+2. Routstr validates token meets minimum amount
+3. Request is processed
+4. Change is returned in response header
+5. No account or balance needed
+
+## Supported Features
+
+### API Compatibility
+
+- ✅ Chat completions (streaming and non-streaming)
+- ✅ Text completions
+- ✅ Embeddings
+- ✅ Image generation
+- ✅ Audio transcription/translation
+- ✅ Model listing
+- ✅ Custom endpoints
+
+### Payment Features
+
+- ✅ Multiple Cashu mint support
+- ✅ Automatic balance tracking
+- ✅ Model-based pricing
+- ✅ USD to BTC conversion
+- ✅ Configurable fees
+- ✅ Balance withdrawals
+
+### Operational Features
+
+- ✅ Docker deployment
+- ✅ Tor hidden service support
+- ✅ Nostr relay discovery
+- ✅ Database migrations
+- ✅ Comprehensive logging
+- ✅ Admin dashboard
+
+## Next Steps
+
+- [Quick Start](quickstart.md) - Get running in minutes
+- [Docker Setup](docker.md) - Deploy with containers
+- [Configuration](configuration.md) - Customize your instance

docs/getting-started/quickstart.md

@@ -0,0 +1,226 @@
+# Quick Start
+
+Get Routstr Core up and running in minutes with Docker or local development setup.
+
+## Prerequisites
+
+- Docker and Docker Compose (for production)
+- Python 3.11+ (for development)
+- A Cashu-compatible wallet (optional for testing)
+
+## Option 1: Docker (Recommended)
+
+### Quick Run
+
+The fastest way to start Routstr Core:
+
+```bash
+docker run -d \
+  --name routstr-proxy \
+  -p 8000:8000 \
+  -e UPSTREAM_BASE_URL=https://api.openai.com/v1 \
+  -e UPSTREAM_API_KEY=your-openai-api-key \
+  ghcr.io/routstr/proxy:latest
+```
+
+### Docker Compose
+
+For a full setup with Tor support:
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/routstr/routstr-core.git
+cd routstr-core
+```
+
+2. Create environment file:
+
+```bash
+cp .env.example .env
+# Edit .env with your settings
+```
+
+3. Start the services:
+
+```bash
+docker compose up -d
+```
+
+This will start:
+
+- Routstr proxy on port 8000
+- Tor hidden service (optional)
+- Automatic database migrations
+
+### Verify Installation
+
+Check that Routstr is running:
+
+```bash
+curl http://localhost:8000/v1/info
+```
+
+You should see:
+
+```json
+{
+  "name": "ARoutstrNode",
+  "description": "A Routstr Node",
+  "version": "0.2.0",
+  "npub": "",
+  "mints": ["https://mint.minibits.cash/Bitcoin"],
+  "models": {...}
+}
+```
+
+## Option 2: Local Development
+
+### Install Dependencies
+
+1. Install [uv](https://github.com/astral-sh/uv) package manager:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+2. Clone and setup:
+
+```bash
+git clone https://github.com/routstr/routstr-core.git
+cd routstr-core
+uv sync
+```
+
+3. Configure environment:
+
+```bash
+cp .env.example .env
+# Edit .env with your settings
+```
+
+### Run the Server
+
+```bash
+fastapi run routstr --host 0.0.0.0 --port 8000
+```
+
+## First API Call
+
+### 1. Get an eCash Token
+
+You'll need a Cashu token to pay for API calls. Options:
+
+- Use a [Cashu wallet](https://cashu.space) to create tokens
+- Get test tokens from a testnet mint
+- Use the example token (for testing only)
+
+### 2. Create an API Key
+
+Send your eCash token to create an API key:
+
+```bash
+curl -X POST http://localhost:8000/v1/wallet/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "cashu_token": "cashuAeyJ0b2..."
+  }'
+```
+
+Response:
+
+```json
+{
+  "api_key": "rUvK7...",
+  "balance": 10000
+}
+```
+
+### 3. Make an API Call
+
+Use your API key like a normal OpenAI key:
+
+```python
+import openai
+
+client = openai.OpenAI(
+    api_key="rUvK7...",  # Your Routstr API key
+    base_url="http://localhost:8000/v1"
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+
+print(response.choices[0].message.content)
+```
+
+## Example Client
+
+Run the included example:
+
+```bash
+CASHU_TOKEN="your-token" python example.py
+```
+
+This demonstrates:
+
+- Creating an API key from a token
+- Making streaming chat requests
+- Automatic balance deduction
+
+## Testing the Setup
+
+### Check Available Models
+
+```bash
+curl http://localhost:8000/v1/models
+```
+
+### View Admin Dashboard
+
+Open <http://localhost:8000/admin/> in your browser.
+
+Default password is set in `ADMIN_PASSWORD` environment variable.
+
+### Monitor Logs
+
+Docker:
+
+```bash
+docker compose logs -f routstr
+```
+
+Local:
+
+```bash
+# Logs are in ./logs/ directory
+tail -f logs/routstr.log
+```
+
+## Common Issues
+
+### Connection Refused
+
+- Ensure the service is running: `docker ps`
+- Check firewall settings
+- Verify port 8000 is not in use
+
+### Invalid API Key
+
+- Ensure you've created an API key with sufficient balance
+- Check the token was valid and had value
+- Verify the mint URL is accessible
+
+### Upstream Errors
+
+- Check `UPSTREAM_BASE_URL` is correct
+- Verify `UPSTREAM_API_KEY` if required
+- Test upstream service directly
+
+## Next Steps
+
+- [Configuration Guide](configuration.md) - Customize settings
+- [Docker Setup](docker.md) - Production deployment
+- [User Guide](../user-guide/introduction.md) - Detailed usage

docs/getting-started/ui-configuration.md

@@ -0,0 +1,53 @@
+# UI Configuration
+
+This guide explains how to configure the Routstr UI for different environments.
+
+## Environment Variables
+
+The UI uses Next.js environment variables to configure API endpoints and authentication.
+
+### Centralized Configuration
+
+This project uses a centralized configuration approach with a single `.env` file in the project root. This file contains both backend and frontend configuration variables.
+
+Create or update your `.env` file in the project root:
+
+```bash
+# .env (in project root)
+
+# UI Configuration (NEXT_PUBLIC_ variables are exposed to the browser)
+NEXT_PUBLIC_API_URL=http://127.0.0.1:8000
+```
+
+### Development vs Production
+
+The same `.env` file is used for both development and production. Simply change the values:
+
+**Development:**
+
+```bash
+NEXT_PUBLIC_API_URL=http://127.0.0.1:8000
+```
+
+**Production:**
+
+```bash
+NEXT_PUBLIC_API_URL=https://api.yourroutstr.com
+```
+
+## Building the UI
+
+The build process automatically reads configuration from the root `.env` file:
+
+```bash
+# From the project root
+make ui-build
+# or
+./scripts/build-ui.sh
+```
+
+The build script will automatically:
+
+- Load `NEXT_PUBLIC_*` variables from the root `.env` file
+- Use them during the Next.js build process
+- Display warnings if the `.env` file is missing

docs/index.md

@@ -0,0 +1,83 @@
+# Routstr Core Documentation
+
+Welcome to the official documentation for **Routstr Core** - a FastAPI-based reverse proxy that enables Bitcoin micropayments for OpenAI-compatible APIs using the Cashu eCash protocol.
+
+## What is Routstr Core?
+
+Routstr Core is a payment proxy that sits between API clients and OpenAI-compatible services. It enables:
+
+- **Pay-per-request billing** using Bitcoin eCash tokens
+- **Seamless integration** with existing OpenAI clients
+- **Privacy-preserving payments** through the Cashu protocol
+- **Flexible pricing models** with per-token or per-request billing
+- **Multi-provider support** for various AI model providers
+
+### Key Features
+
+- 🪙 **Cashu Wallet Integration** - Accept Lightning payments and redeem eCash tokens
+- 🔑 **API Key Management** - Secure key storage with balance tracking
+- 💰 **Dynamic Pricing** - Model-based pricing with live BTC/USD conversion
+- 🎛️ **Admin Dashboard** - Web interface for balance and key management
+- 🌐 **Nostr Discovery** - Find providers through decentralized relay network
+- 🐋 **Docker Support** - Easy deployment with optional Tor hidden service
+- ⚡ **Lightning Fast** - Minimal latency overhead for API requests
+
+## How It Works
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Routstr as Routstr Proxy
+    participant DB as Database
+    participant Upstream as AI Provider
+    participant Wallet as Cashu Wallet
+
+    Client->>Routstr: API Request + eCash Token
+    Routstr->>Wallet: Validate & Redeem Token
+    Wallet-->>Routstr: Token Value (sats)
+    Routstr->>DB: Store/Update Balance
+    Routstr->>Upstream: Forward API Request
+    Upstream-->>Routstr: API Response + Usage Data
+    Routstr->>DB: Deduct Actual Cost
+    Routstr-->>Client: API Response
+```
+
+## Quick Links
+
+<div class="grid cards" markdown>
+
+- :rocket: **[Quick Start](getting-started/quickstart.md)**
+
+    Get up and running with Docker in minutes
+
+- :gear: **[Configuration](getting-started/configuration.md)**
+
+    Learn about environment variables and settings
+
+- :book: **[User Guide](user-guide/introduction.md)**
+
+    Comprehensive guide for using Routstr
+
+- :hammer: **[Contributing](contributing/setup.md)**
+
+    Help improve Routstr Core
+
+</div>
+
+## Use Cases
+
+- **AI Application Developers** - Add Bitcoin payments to your AI apps without managing infrastructure
+- **API Resellers** - Resell API access with custom pricing and profit margins
+- **Privacy-Focused Users** - Access AI models without revealing personal information
+- **Micropayment Experiments** - Test new business models with instant, small payments
+
+## Getting Help
+
+- 📖 Browse the [User Guide](user-guide/introduction.md) for detailed usage instructions
+- 🐛 Report issues on [GitHub](https://github.com/routstr/routstr-core/issues)
+- 💬 Join the community discussions
+- 🔧 Check the [API Reference](api/overview.md) for technical details
+
+## License
+
+Routstr Core is open source software licensed under the GPLv3. See the [LICENSE](https://github.com/routstr/routstr-core/blob/main/LICENSE) file for details.

docs/requirements.txt

@@ -0,0 +1,4 @@
+mkdocs>=1.5.3
+mkdocs-material>=9.5.0
+mkdocs-mermaid2-plugin>=1.1.1
+pymdown-extensions>=10.5

docs/user-guide/admin-dashboard.md

@@ -0,0 +1,216 @@
+# Admin Dashboard
+
+The Routstr admin dashboard is a modern web interface for managing your node, monitoring wallet balances, configuring AI models and providers, and handling Bitcoin Lightning payments through Cashu eCash.
+
+## Accessing the Dashboard
+
+### Authentication
+
+The dashboard is protected by password authentication:
+
+1. Navigate to `/admin/` in your browser
+2. Enter the admin password
+3. Optional: Configure custom base URL if not pre-configured
+4. Click "Login"
+
+The interface supports both environment-configured URLs and manual URL entry for deployment flexibility.
+
+## Dashboard Overview
+
+The main dashboard consists of four primary sections accessible through a collapsible sidebar:
+
+- **Dashboard** - Wallet balance monitoring and fund management
+- **Models** - AI model management and testing
+- **Providers** - Upstream provider configuration
+- **Settings** - Node configuration and admin preferences
+
+### Navigation
+
+## Dashboard Page
+
+### Wallet Balance Management
+
+#### Balance Display Options
+
+Switch between display units using the toggle buttons:
+
+- **msat** - Millisatoshis (highest precision)
+- **sat** - Satoshis (standard Bitcoin unit)
+- **usd** - US Dollar equivalent (when exchange rate available)
+
+#### Balance Overview
+
+The dashboard displays three key metrics:
+
+- **Your Balance (Total)** - Available funds for node operator
+- **Total Wallet** - Combined balance across all Cashu mints
+- **User Balance** - Funds held for API key holders
+
+#### Detailed Balance Breakdown
+
+View balances by mint with the following information:
+
+| Column      | Description                           |
+| ----------- | ------------------------------------- |
+| Mint / Unit | Cashu mint URL and currency unit      |
+| Wallet      | Total funds in this mint              |
+| Users       | Funds belonging to API key holders    |
+| Owner       | Your available funds (Wallet - Users) |
+
+### Temporary Balances
+
+Monitor API key activity with:
+
+- **Summary Cards** - Total balance, total spent, total requests
+- **Search Functionality** - Filter by key hash or refund address
+- **Detailed Table** - Individual key balances with expiry times
+- **Auto-refresh** - Updates every 60 seconds
+
+### Fund Management
+
+#### Withdrawing Funds
+
+To withdraw your available balance:
+
+1. Click the **Withdraw** button
+2. Select which mint to withdraw from
+3. Specify the amount (or withdraw full balance)
+4. Click **Generate Token**
+5. Copy the generated eCash token
+6. Import the token into your Cashu wallet
+
+#### Real-time Updates
+
+- Balances refresh automatically every 30 seconds
+- Manual refresh option available
+- Live Bitcoin/USD exchange rate integration
+- Error handling for mint connectivity issues
+
+## Models Management Page
+
+### Model Organization
+
+Models are organized by provider groups with tabs:
+
+- **All Models** - Combined view of all available models
+- **Provider-specific tabs** - Individual providers (OpenRouter, Azure, etc.)
+- Badge indicators showing active/total model counts
+
+### Model Management Features
+
+#### Individual Model Operations
+
+For each model you can:
+
+- **Toggle Enable/Disable** - Control model availability
+- **View Details** - Context length, pricing, description
+- **Edit Configuration** - Model-specific settings
+- **Status Indicators** - Green badges for enabled, gray for disabled
+
+#### Bulk Operations
+
+- **Select All/Deselect All** - Quick selection controls
+- **Bulk Enable/Disable** - Mass model management
+- **Bulk Delete** - Remove model overrides
+- **Provider-level Actions** - Apply settings to all models in a provider
+
+#### Model Information Display
+
+- **Model Types** - Text, embedding, image, audio, multimodal indicators
+- **Pricing Information** - Per-million-token costs for input/output
+- **Context Length** - Maximum tokens supported
+- **API Key Status** - Whether credentials are configured
+- **Free Model Indicators** - No-cost models clearly marked
+
+## Providers Management Page
+
+### Upstream Provider Configuration
+
+Manage AI provider connections and credentials:
+
+#### Provider Types Supported
+
+- **OpenRouter** - Multi-model aggregator
+- **Azure OpenAI** - Microsoft's OpenAI service
+- **OpenAI** - Direct OpenAI integration
+- **Custom Providers** - Any OpenAI-compatible API
+
+#### Adding New Providers
+
+1. Click **Add Provider**
+2. Select **Provider Type** from dropdown
+3. Enter **Base URL** (auto-populated for known providers)
+4. Add **API Key** for authentication
+5. Set **API Version** (required for Azure)
+6. Toggle **Enabled** status
+7. Click **Create**
+
+#### Provider Management
+
+**Provider Cards Display:**
+
+- Provider type and status (Enabled/Disabled)
+- Base URL configuration
+- Action buttons (Models, Edit, Delete)
+
+**Available Actions:**
+
+- **Edit** - Modify provider configuration
+- **Delete** - Remove provider (with confirmation)
+- **View Models** - Expand model discovery interface
+- **Enable/Disable** - Toggle provider availability
+
+#### Model Discovery
+
+Each provider shows two types of models:
+
+**Provided Models Tab:**
+
+- Auto-discovered from provider's catalog
+- Read-only model information
+- Real-time availability updates
+
+**Custom Models Tab:**
+
+- Manually configured model overrides
+- Extend or override provider catalog
+- Individual enable/disable controls
+
+## Settings Page
+
+### Node Configuration
+
+Configure core node settings and preferences:
+
+#### Basic Information
+
+- **Node Name** - Identifier for your node
+- **Node Description** - Descriptive text for your service
+- **HTTP URL** - Public HTTP endpoint
+- **Onion URL** - Tor hidden service address
+
+#### Nostr Integration
+
+- **Public Key (npub)** - Your Nostr public identity
+- **Private Key (nsec)** - Nostr private key with show/hide toggle
+- **Nostr Relays** - Configure relays for provider announcements
+
+#### Cashu Mint Management
+
+- **Add Mint URLs** - Configure multiple Cashu mint endpoints
+- **Remove Mints** - Delete unused mint configurations
+- **Mint Validation** - Verify mint endpoint connectivity
+
+#### Settings Features
+
+- **Real-time Save** - Changes apply immediately
+- **Validation** - Form validation with error feedback
+- **Secure Fields** - Password masking with reveal toggles
+- **Reload Functionality** - Refresh configuration from server
+
+## Next Steps
+
+- [Payment Flow](payment-flow.md) - Understanding Bitcoin payment processing
+- [Using the API](using-api.md) - Making API requests to your node
+- [Models & Pricing](models-pricing.md) - Configuring model pricing and fees
+- [API Reference](../api/overview.md) - Complete API documentation

docs/user-guide/introduction.md

@@ -0,0 +1,245 @@
+# User Guide Introduction
+
+Welcome to the Routstr Core User Guide. This guide will help you understand how to use Routstr to access AI APIs with Bitcoin micropayments.
+
+## What You'll Learn
+
+- How the payment system works
+- Creating and managing API keys
+- Making API calls through Routstr
+- Using the admin dashboard
+- Managing your balance
+
+## Prerequisites
+
+Before starting, you'll need:
+
+1. **A Running Routstr Instance**
+   - Either your own deployment or access to a public node
+   - The base URL (e.g., `https://api.routstr.com/v1`)
+
+2. **A Cashu Wallet** (optional but recommended)
+   - [Nutstash](https://nutstash.app) - Web wallet
+   - [Minibits](https://www.minibits.cash) - Mobile wallet
+   - [Cashu.me](https://cashu.me) - Simple web wallet
+
+3. **An API Client**
+   - OpenAI Python/JavaScript SDK
+   - Any HTTP client (curl, Postman, etc.)
+   - Your application code
+
+## How Routstr Works
+
+### Traditional API Access
+
+```mermaid
+graph LR
+    A[Your App] --> B[OpenAI API]
+    B --> A
+```
+
+- Direct connection to provider
+- Monthly billing
+- Credit card required
+- Usage limits
+
+### With Routstr
+
+```mermaid
+graph LR
+    A[Your App] --> B[Routstr Proxy]
+    B --> C[OpenAI API]
+    C --> B
+    B --> A
+    D[Bitcoin/eCash] --> B
+```
+
+- Pay per request with Bitcoin
+- No credit card needed
+- Anonymous payments
+- Instant settlement
+
+## Key Concepts
+
+### eCash Tokens
+
+- Digital bearer tokens backed by Bitcoin
+- Can be sent like cash - whoever has the token owns it
+- Redeemable at Cashu mints for Bitcoin
+- Perfect for micropayments
+
+### API Keys
+
+- Created by depositing eCash tokens
+- Track your balance and usage
+- Can be topped up anytime
+- Optional expiry and refund address
+
+### Balance Management
+
+- Measured in millisatoshis (msats)
+- 1 Bitcoin = 100,000,000 sats = 100,000,000,000 msats
+- Deducted based on actual usage
+- Withdrawable as eCash tokens
+
+## Typical Workflow
+
+### 1. Get Bitcoin/eCash
+
+Options:
+
+- Buy Bitcoin and deposit to a Cashu mint
+- Receive eCash tokens from someone else
+- Use a testnet mint for testing
+
+### 2. Use Your eCash
+
+You have two options for using your eCash tokens with Routstr:
+
+#### Option A: Create a Persistent Wallet
+
+Create a wallet with an API key for multiple requests:
+
+```bash
+POST /v1/wallet/create
+{
+  "cashu_token": "cashuAeyJ0..."
+}
+```
+
+This returns an API key (`sk-...`) and your balance. The wallet persists between requests.
+
+#### Option B: Direct Token Usage
+
+Use your Cashu token directly as the API key:
+
+```python
+client = OpenAI(
+    api_key="cashuAeyJ0...",  # Your Cashu token directly
+    base_url="https://api.routstr.com/v1"
+)
+```
+
+Routstr automatically converts the token to access the associated wallet. Each request consumes from the token's balance.
+
+### 3. Make API Calls
+
+With either method:
+
+```python
+# Using persistent wallet API key
+client = OpenAI(
+    api_key="sk-...",
+    base_url="https://api.routstr.com/v1"
+)
+
+# Or using Cashu token directly
+client = OpenAI(
+    api_key="cashuAeyJ0...",
+    base_url="https://api.routstr.com/v1"
+)
+```
+
+### 4. Monitor Usage
+
+- Check balance: `GET /v1/wallet/balance`
+- View admin dashboard
+- Track costs per request
+
+### 5. Withdraw Funds
+
+When done, withdraw remaining balance as eCash through the admin interface.
+
+## Supported Endpoints
+
+Routstr supports all standard OpenAI endpoints:
+
+- ✅ `/v1/chat/completions` - Chat models
+- 🚧 `/v1/completions` - Text completion (Coming soon)
+- 🚧 `/v1/embeddings` - Text embeddings (Coming soon)
+- 🚧 `/v1/images/generations` - Image generation (Coming soon)
+- 🚧 `/v1/audio/transcriptions` - Audio to text (Coming soon)
+- 🚧 `/v1/audio/translations` - Audio translation (Coming soon)
+- ✅ `/v1/models` - List available models
+- ✅ Custom provider endpoints
+
+## Cost Structure
+
+### Pricing Models
+
+1. **Fixed Cost Per Request**
+   - Simple flat fee per API call
+   - Good for uniform usage
+
+2. **Token-Based Pricing**
+   - Pay per input/output token
+   - More accurate for varied usage
+
+3. **Model-Based Pricing**
+   - Different rates per model
+   - Reflects actual provider costs
+
+### Cost Calculation
+
+```
+Total Cost = Base Fee + (Input Tokens * Input Rate) + (Output Tokens * Output Rate)
+```
+
+Fees may include:
+
+- Exchange rate markup (BTC/USD conversion)
+- Provider margin
+- Node operator fee
+
+## Getting Support
+
+### Documentation
+
+- This user guide for general usage
+- [API Reference](../api/overview.md) for technical details
+- [Contributing Guide](../contributing/setup.md) for developers
+
+### Community
+
+- GitHub Issues for bugs and features
+- Nostr for decentralized discussion
+- Node operator contact info
+
+### Troubleshooting
+
+Common issues and solutions:
+
+- [Payment Flow](payment-flow.md) - Understanding the payment process
+- [Using the API](using-api.md) - API integration guide
+- [Admin Dashboard](admin-dashboard.md) - Managing your node
+
+## Security Considerations
+
+### API Key Security
+
+- Treat API keys like passwords
+- Never share or commit them
+- Rotate keys regularly
+- Use environment variables
+
+### Payment Security
+
+- eCash tokens are bearer instruments
+- Verify mint trustworthiness
+- Keep backups of tokens
+- Use small amounts for testing
+
+### Network Security
+
+- Always use HTTPS connections
+- Verify SSL certificates
+- Consider using Tor for privacy
+- Monitor for unusual activity
+
+## Next Steps
+
+Ready to start? Continue with:
+
+1. [Payment Flow](payment-flow.md) - Detailed payment process
+2. [Using the API](using-api.md) - Making your first calls
+3. [Admin Dashboard](admin-dashboard.md) - Managing your account

docs/user-guide/models-pricing.md

@@ -0,0 +1,466 @@
+# Models & Pricing
+
+Understanding how Routstr calculates costs is essential for managing your API usage efficiently. This guide explains the pricing models and how to configure them.
+
+## Pricing Models
+
+Routstr supports three pricing models:
+
+### 1. Fixed Pricing
+
+Simple per-request charging:
+
+```bash
+FIXED_PRICING=true
+FIXED_COST_PER_REQUEST=10  # 10 sats per request
+```
+
+**Best for:**
+
+- Uniform API usage
+- Simple applications
+- Predictable costs
+
+### 2. Token-Based Pricing
+
+Charge based on actual token usage:
+
+```bash
+FIXED_PRICING=false             # use model pricing
+FIXED_COST_PER_REQUEST=1        # optional base fee
+FIXED_PER_1K_INPUT_TOKENS=5     # optional override
+FIXED_PER_1K_OUTPUT_TOKENS=15   # optional override
+```
+
+**Best for:**
+
+- Varied request sizes
+- Fair usage billing
+- Cost optimization
+
+### 3. Model-Based Pricing
+
+Dynamic pricing based on model costs:
+
+```bash
+FIXED_PRICING=false
+EXCHANGE_FEE=1.005      # 0.5% exchange fee
+UPSTREAM_PROVIDER_FEE=1.05  # 5% provider fee
+```
+
+**Best for:**
+
+- Multiple models
+- Market-based pricing
+- Automatic updates
+
+## Model Configuration
+
+### Default Models
+
+Routstr includes pricing for popular models:
+
+| Model | Input ($/1K) | Output ($/1K) | Context | Notes |
+|-------|--------------|---------------|---------|-------|
+| gpt-3.5-turbo | $0.0015 | $0.002 | 16K | Fast, economical |
+| gpt-4 | $0.03 | $0.06 | 8K | Advanced reasoning |
+| gpt-4-turbo | $0.01 | $0.03 | 128K | Large context |
+| claude-3-opus | $0.015 | $0.075 | 200K | Best quality |
+| claude-3-sonnet | $0.003 | $0.015 | 200K | Balanced |
+| llama-2-70b | $0.0007 | $0.0009 | 4K | Open source |
+
+### Custom Models File
+
+Create `models.json` to override defaults:
+
+```json
+{
+  "models": [
+    {
+      "id": "gpt-4-vision",
+      "name": "GPT-4 Vision",
+      "pricing": {
+        "prompt": "0.00003",
+        "completion": "0.00006",
+        "request": "0",
+        "image": "0.00255"
+      },
+      "context_length": 128000,
+      "supports_vision": true
+    },
+    {
+      "id": "custom-model",
+      "name": "My Custom Model",
+      "pricing": {
+        "prompt": "0.001",
+        "completion": "0.002",
+        "request": "0.0001"
+      },
+      "context_length": 8192
+    }
+  ]
+}
+```
+
+### Auto-updating Models
+
+Fetch latest models from OpenRouter:
+
+```bash
+# Update models from API
+python scripts/models_meta.py
+
+# Or manually
+curl https://openrouter.ai/api/v1/models > models.json
+```
+
+## Cost Calculation
+
+### Understanding the Formula
+
+```
+Base Cost = (Input Tokens × Input Rate) + (Output Tokens × Output Rate) + Request Fee
+
+Bitcoin Price = Current BTC/USD rate (e.g., $50,000)
+Sats Cost = (Base Cost / Bitcoin Price) × 100,000,000
+
+Final Cost = Sats Cost × Exchange Fee × Provider Fee
+```
+
+### Example Calculations
+
+**Example 1: Simple Chat (gpt-3.5-turbo)**
+
+```
+Input: 50 tokens
+Output: 150 tokens
+Model rates: $0.0015/1K input, $0.002/1K output
+
+USD Cost = (50/1000 × 0.0015) + (150/1000 × 0.002)
+         = $0.000075 + $0.0003
+         = $0.000375
+
+At $50,000/BTC: 0.75 sats
+With 5.5% total fees: 0.79 sats
+```
+
+**Example 2: Large Context (gpt-4)**
+
+```
+Input: 2,000 tokens
+Output: 500 tokens
+Model rates: $0.03/1K input, $0.06/1K output
+
+USD Cost = (2000/1000 × 0.03) + (500/1000 × 0.06)
+         = $0.06 + $0.03
+         = $0.09
+
+At $50,000/BTC: 180 sats
+With 5.5% total fees: 190 sats
+```
+
+**Example 3: Image Generation (dall-e-3)**
+
+```
+Model: dall-e-3
+Size: 1024x1024
+Quality: standard
+Cost: $0.04 per image
+
+At $50,000/BTC: 80 sats
+With 5.5% fees: 84 sats
+```
+
+## Fee Structure
+
+### Exchange Fee
+
+Covers Bitcoin/USD conversion costs:
+
+```bash
+EXCHANGE_FEE=1.005  # 0.5% default
+```
+
+Factors:
+
+- Exchange rate volatility
+- Conversion costs
+- Price update frequency
+
+### Provider Fee
+
+Node operator's margin:
+
+```bash
+UPSTREAM_PROVIDER_FEE=1.05  # 5% default
+```
+
+Covers:
+
+- Infrastructure costs
+- Maintenance
+- Support
+- Profit margin
+
+### Calculating Total Fees
+
+```
+Total Multiplier = EXCHANGE_FEE × UPSTREAM_PROVIDER_FEE
+Example: 1.005 × 1.05 = 1.05525 (5.525% total)
+```
+
+## Special Pricing
+
+### Image Models
+
+Image generation uses per-image pricing:
+
+| Model | Size | Quality | Price |
+|-------|------|---------|-------|
+| dall-e-2 | 256x256 | - | $0.016 |
+| dall-e-2 | 512x512 | - | $0.018 |
+| dall-e-2 | 1024x1024 | - | $0.02 |
+| dall-e-3 | 1024x1024 | standard | $0.04 |
+| dall-e-3 | 1024x1024 | hd | $0.08 |
+| dall-e-3 | 1024x1792 | standard | $0.08 |
+| dall-e-3 | 1024x1792 | hd | $0.12 |
+
+### Audio Models
+
+Audio pricing by duration:
+
+| Model | Type | Price |
+|-------|------|-------|
+| whisper-1 | Transcription | $0.006/minute |
+| whisper-1 | Translation | $0.006/minute |
+| tts-1 | Text-to-speech | $0.015/1K chars |
+| tts-1-hd | HD speech | $0.03/1K chars |
+
+### Embedding Models
+
+Lower costs for embeddings:
+
+| Model | Price/1K tokens |
+|-------|-----------------|
+| text-embedding-3-small | $0.00002 |
+| text-embedding-3-large | $0.00013 |
+| text-embedding-ada-002 | $0.0001 |
+
+## Monitoring Costs
+
+### Per-Request Tracking
+
+Each API response includes usage data:
+
+```json
+{
+  "usage": {
+    "prompt_tokens": 50,
+    "completion_tokens": 150,
+    "total_tokens": 200
+  },
+  "x-routstr-cost": {
+    "sats": 79,
+    "usd": 0.000375,
+    "breakdown": {
+      "prompt_cost": 15,
+      "completion_cost": 60,
+      "fees": 4
+    }
+  }
+}
+```
+
+### Daily Summaries
+
+View in admin dashboard:
+
+- Total requests
+- Token usage by model
+- Cost distribution
+- Trending patterns
+
+### Cost Alerts
+
+Set up notifications:
+
+```python
+# Example monitoring script
+def check_daily_spend(api_key):
+    balance_start = get_balance(api_key, "00:00")
+    balance_now = get_balance(api_key)
+    spent = balance_start - balance_now
+    
+    if spent > DAILY_LIMIT:
+        send_alert(f"Daily spend exceeded: {spent} sats")
+```
+
+## Optimization Strategies
+
+### Model Selection
+
+Choose the right model for each task:
+
+| Task | Recommended Model | Why |
+|------|-------------------|-----|
+| Simple Q&A | gpt-3.5-turbo | Fast, cheap, sufficient |
+| Code generation | gpt-4 | Better reasoning |
+| Summarization | claude-3-haiku | Good balance |
+| Creative writing | claude-3-opus | Best quality |
+| Embeddings | text-embedding-3-small | Optimized for vectors |
+
+### Prompt Engineering
+
+Reduce costs with efficient prompts:
+
+```python
+# Expensive
+prompt = """
+You are an AI assistant. Your task is to help users.
+Please provide detailed, comprehensive answers.
+Now, answer this question: What is 2+2?
+"""
+
+# Economical
+prompt = "Calculate: 2+2"
+```
+
+### Caching Strategies
+
+Implement smart caching:
+
+```python
+# Cache embedding results
+@lru_cache(maxsize=1000)
+def get_embedding(text):
+    return client.embeddings.create(
+        model="text-embedding-3-small",
+        input=text
+    )
+
+# Cache common responses
+COMMON_RESPONSES = {
+    "greeting": "Hello! How can I help you?",
+    "goodbye": "Goodbye! Have a great day!"
+}
+```
+
+### Batch Processing
+
+Process multiple items efficiently:
+
+```python
+# Instead of multiple calls
+for item in items:
+    response = client.chat.completions.create(...)
+
+# Use single call with formatted prompt
+prompt = "\n".join([f"{i+1}. {item}" for i, item in enumerate(items)])
+response = client.chat.completions.create(
+    messages=[{"role": "user", "content": f"Process these items:\n{prompt}"}]
+)
+```
+
+## Custom Pricing Rules
+
+### Time-Based Pricing
+
+Implement off-peak discounts:
+
+```python
+def calculate_multiplier():
+    hour = datetime.now().hour
+    if 2 <= hour <= 6:  # 2 AM - 6 AM
+        return 0.8  # 20% discount
+    elif 18 <= hour <= 22:  # 6 PM - 10 PM
+        return 1.2  # 20% premium
+    return 1.0
+```
+
+### Model-Specific Rules
+
+Custom pricing logic:
+
+```python
+def adjust_model_price(model, base_price):
+    # Premium for latest models
+    if "turbo" in model or "latest" in model:
+        return base_price * 1.1
+    
+    # Discount for older models
+    if "legacy" in model:
+        return base_price * 0.8
+    
+    return base_price
+```
+
+## Pricing Transparency
+
+### Public Pricing Page
+
+Display current rates:
+
+```html
+<!-- Available at /pricing -->
+<table>
+  <tr>
+    <th>Model</th>
+    <th>Input (sats/1K)</th>
+    <th>Output (sats/1K)</th>
+  </tr>
+  <!-- Dynamically generated from models.json -->
+</table>
+```
+
+### Cost Estimation API
+
+Provide cost estimates:
+
+```bash
+POST /v1/estimate
+{
+  "model": "gpt-4",
+  "prompt_tokens": 500,
+  "max_tokens": 200
+}
+
+Response:
+{
+  "estimated_cost_sats": 45,
+  "breakdown": {
+    "prompt": 30,
+    "completion": 12,
+    "fees": 3
+  }
+}
+```
+
+## Troubleshooting
+
+### Pricing Mismatches
+
+**Issue**: Costs don't match expectations
+
+- Check current BTC/USD rate
+- Verify fee settings
+- Review model configuration
+
+**Issue**: Models not found
+
+- Update models.json
+- Check model ID spelling
+- Verify upstream support
+
+### Fee Calculations
+
+**Issue**: Fees seem too high
+
+- Review EXCHANGE_FEE setting
+- Check UPSTREAM_PROVIDER_FEE
+- Calculate total multiplier
+
+## Next Steps
+
+- [API Reference](../api/overview.md) - Technical details
+- [Custom Pricing](../advanced/custom-pricing.md) - Advanced configuration
+- [Contributing](../contributing/setup.md) - Help improve Routstr

docs/user-guide/payment-flow.md

@@ -0,0 +1,373 @@
+# Payment Flow
+
+Understanding how payments work in Routstr is key to using the system effectively. This guide explains the payment process in detail.
+
+## Overview
+
+Routstr uses a pre-funded account model where:
+
+1. Users deposit eCash tokens to create an API key
+2. Each API request deducts from the balance
+3. Users can withdraw remaining balance as eCash
+
+## Creating an API Key
+
+### Step 1: Obtain eCash Token
+
+Get a Cashu token from any compatible source:
+
+**Option A: From a Cashu Wallet**
+
+```bash
+# Example: Creating a 10,000 sat token
+cashu send 10000
+```
+
+**Option B: Lightning Invoice**
+
+```bash
+# Some mints support direct Lightning deposits
+curl -X POST https://mint.example.com/v1/mint/quote/bolt11 \
+  -d '{"amount": 10000, "unit": "sat"}'
+```
+
+**Option C: Test Tokens**
+
+```bash
+# Get test tokens from testnet mints
+# Check mint documentation for faucets
+```
+
+### Step 2: Create API Key
+
+**Note: The POST /v1/wallet/create endpoint is coming soon. Currently, you can use Cashu tokens directly as API keys in the Authorization header.**
+
+Send your token to Routstr:
+
+```bash
+curl -X POST https://api.routstr.com/v1/wallet/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "cashu_token": "cashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vbWlu..."
+  }'
+```
+
+**Request Parameters:**
+
+- `cashu_token` (required): The eCash token to deposit
+
+**Response:**
+
+```json
+{
+  "api_key": "sk-1234567890abcdef",
+  "balance": 10000000,
+  "created_at": "2024-01-01T00:00:00Z"
+}
+```
+
+### Step 3: Verify Balance
+
+Check your key's balance:
+
+```bash
+curl -X GET https://api.routstr.com/v1/wallet/balance \
+  -H "Authorization: Bearer sk-1234567890abcdef"
+```
+
+Response:
+
+```json
+{
+  "balance": 10000000,
+  "total_deposited": 10000000,
+  "total_spent": 0,
+  "last_used": null
+}
+```
+
+## Making API Requests
+
+### Cost Calculation
+
+Costs are calculated based on:
+
+1. **Request Type**
+   - Chat completions
+   - Embeddings
+   - Image generation
+   - Audio processing
+
+2. **Token Usage**
+   - Input tokens (prompt)
+   - Output tokens (response)
+   - Model-specific rates
+
+3. **Additional Costs**
+   - Base request fee
+   - Image generation fees
+   - Audio processing time
+
+### Example: Chat Completion
+
+```python
+import openai
+
+client = openai.OpenAI(
+    api_key="sk-1234567890abcdef",
+    base_url="https://api.routstr.com/v1"
+)
+
+# Make request
+response = client.chat.completions.create(
+    model="gpt-3.5-turbo",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ]
+)
+
+# Check usage
+print(f"Input tokens: {response.usage.prompt_tokens}")
+print(f"Output tokens: {response.usage.completion_tokens}")
+print(f"Total tokens: {response.usage.total_tokens}")
+```
+
+### Cost Breakdown
+
+For the above request:
+
+```
+Model: gpt-3.5-turbo
+Input tokens: 13
+Output tokens: 27
+Model rates: $0.0015/1K input, $0.002/1K output
+
+USD Cost = (13/1000 * 0.0015) + (27/1000 * 0.002) = $0.0000735
+BTC/USD Rate: $50,000
+BTC Cost = 0.0000735 / 50000 = 0.00000000147 BTC = 147 sats
+With fees (5%): 154 sats
+
+Final cost: 154 sats
+```
+
+## Balance Management
+
+### Monitoring Usage
+
+Track your usage in real-time:
+
+```bash
+# Get current balance
+curl -X GET https://api.routstr.com/v1/wallet/balance \
+  -H "Authorization: Bearer your-api-key"
+
+# View recent transactions (through admin dashboard)
+# Access at https://api.routstr.com/admin/
+```
+
+### Low Balance Handling
+
+When balance is insufficient:
+
+```json
+{
+  "error": {
+    "type": "insufficient_balance",
+    "message": "Insufficient balance. Current: 100 sats, Required: 154 sats",
+    "code": "payment_required"
+  }
+}
+```
+
+### Topping Up
+
+Add funds to existing key:
+
+```bash
+curl -X POST https://api.routstr.com/v1/wallet/topup \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "cashu_token": "cashuAeyJ0b2..."
+  }'
+```
+
+## Withdrawing Balance
+
+### Via Admin Dashboard
+
+1. Navigate to `/admin/`
+2. Enter admin password
+3. Find your API key
+4. Click "Withdraw"
+5. Receive eCash token
+
+### Via API (if enabled)
+
+```bash
+curl -X POST https://api.routstr.com/v1/wallet/withdraw \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "amount": 5000,
+    "mint": "https://mint.minibits.cash/Bitcoin"
+  }'
+```
+
+## Payment Security
+
+### Token Validation
+
+Routstr validates tokens by:
+
+1. Checking signature validity
+2. Verifying with the issuing mint
+3. Ensuring no double-spending
+4. Confirming sufficient value
+
+### Failed Payments
+
+Common failure reasons:
+
+- Invalid token signature
+- Already spent token
+- Untrusted mint
+- Network issues with mint
+
+### Refund Policy
+
+- Unused balance can be withdrawn anytime
+- Expired keys with balance can be refunded
+- Node operators may have additional policies
+
+## Advanced Features
+
+### Multi-Mint Support
+
+Routstr accepts tokens from multiple mints:
+
+```bash
+CASHU_MINTS=https://mint1.com,https://mint2.com,https://mint3.com
+```
+
+Benefits:
+
+- Redundancy if one mint is down
+- User choice of mints
+- Geographic distribution
+
+### Automatic Payouts
+
+Configure automatic Lightning payouts:
+
+```bash
+RECEIVE_LN_ADDRESS=satoshi@getalby.com
+```
+
+When enabled:
+
+- Balances above threshold are swept
+- Converted to Lightning payments
+- Sent to configured address
+
+### Per-Request Payments (Coming Soon)
+
+Future support for Nut-24 headers:
+
+```bash
+curl -X POST https://api.routstr.com/v1/chat/completions \
+  -H "x-cashu: cashuAeyJ0..." \
+  -H "Content-Type: application/json" \
+  -d '{...}'
+```
+
+Response includes change:
+
+```
+HTTP/1.1 200 OK
+x-cashu: cashuAeyJjaGFuZ2Ui...
+```
+
+## Best Practices
+
+### API Key Management
+
+1. **Separate Keys per Application**
+   - Easier tracking
+   - Better security
+   - Independent budgets
+
+2. **Set Expiration Dates**
+   - Automatic cleanup
+   - Security improvement
+   - Budget control
+
+3. **Monitor Balances**
+   - Set up alerts
+   - Regular checks
+   - Usage analytics
+
+### Cost Optimization
+
+1. **Choose Appropriate Models**
+   - Smaller models for simple tasks
+   - Larger models only when needed
+
+2. **Optimize Prompts**
+   - Concise, clear instructions
+   - Avoid unnecessary tokens
+
+3. **Use Streaming**
+   - Early termination possible
+   - Better user experience
+
+### Security
+
+1. **Secure Storage**
+   - Environment variables
+   - Secrets management
+   - Never in code
+
+2. **Network Security**
+   - Always use HTTPS
+   - Verify certificates
+   - Consider Tor for privacy
+
+3. **Regular Rotation**
+   - Change keys periodically
+   - Withdraw unused funds
+   - Audit usage logs
+
+## Troubleshooting
+
+### Payment Rejected
+
+**Error:** "Invalid token"
+
+- Check token format
+- Verify mint is trusted
+- Ensure not already spent
+
+**Error:** "Insufficient value"
+
+- Token value too low
+- Check current pricing
+- Add larger token
+
+### Balance Discrepancies
+
+- Allow for price fluctuations
+- Check model pricing updates
+- Review transaction history
+
+### Mint Issues
+
+- Try different mint from list
+- Check mint status
+- Contact mint operator
+
+## Next Steps
+
+- [Using the API](using-api.md) - Integration guide
+- [Admin Dashboard](admin-dashboard.md) - Account management
+- [Models & Pricing](models-pricing.md) - Cost details

docs/user-guide/using-api.md

@@ -0,0 +1,545 @@
+# Using the API
+
+This guide shows how to integrate Routstr with your applications using various programming languages and tools.
+
+## API Compatibility
+
+Routstr maintains full compatibility with the OpenAI API, meaning:
+
+- Existing OpenAI client libraries work without modification
+- Only the base URL and API key need to change
+- All parameters and responses match OpenAI's format
+
+## Basic Setup
+
+### Python
+
+Using the official OpenAI Python library:
+
+```python
+from openai import OpenAI
+
+# Initialize client with Routstr endpoint
+client = OpenAI(
+    api_key="sk-...",
+    base_url="https://api.routstr.com/v1"
+)
+
+# Use exactly like OpenAI
+response = client.chat.completions.create(
+    model="gpt-3.5-turbo",
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Hello!"}
+    ]
+)
+
+print(response.choices[0].message.content)
+```
+
+### JavaScript/TypeScript
+
+Using the official OpenAI Node.js library:
+
+```javascript
+import OpenAI from 'openai';
+
+// Initialize client
+const openai = new OpenAI({
+    apiKey: 'sk-...',
+    baseURL: 'https://api.routstr.com/v1'
+});
+
+// Make a request
+async function main() {
+    const completion = await openai.chat.completions.create({
+        model: 'gpt-3.5-turbo',
+        messages: [
+            { role: 'system', content: 'You are a helpful assistant.' },
+            { role: 'user', content: 'Hello!' }
+        ]
+    });
+    
+    console.log(completion.choices[0].message.content);
+}
+
+main();
+```
+
+### cURL
+
+Direct HTTP requests:
+
+```bash
+curl https://api.routstr.com/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk-..." \
+  -d '{
+    "model": "gpt-3.5-turbo",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+## Common Use Cases
+
+### Chat Completions
+
+Standard chat with conversation history:
+
+```python
+messages = []
+
+def chat(user_input):
+    # Add user message
+    messages.append({"role": "user", "content": user_input})
+    
+    # Get AI response
+    response = client.chat.completions.create(
+        model="gpt-3.5-turbo",
+        messages=messages,
+        temperature=0.7,
+        max_tokens=150
+    )
+    
+    # Add AI response to history
+    ai_message = response.choices[0].message
+    messages.append({"role": "assistant", "content": ai_message.content})
+    
+    return ai_message.content
+
+# Usage
+print(chat("What's the weather like?"))
+print(chat("How should I dress?"))  # Maintains context
+```
+
+### Streaming Responses
+
+For real-time output:
+
+```python
+stream = client.chat.completions.create(
+    model="gpt-3.5-turbo",
+    messages=[{"role": "user", "content": "Write a short story"}],
+    stream=True
+)
+
+for chunk in stream:
+    if chunk.choices[0].delta.content is not None:
+        print(chunk.choices[0].delta.content, end="", flush=True)
+```
+
+### Function Calling
+
+Using OpenAI's function calling feature:
+
+```python
+tools = [{
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "Get current weather",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "location": {"type": "string"},
+                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
+            },
+            "required": ["location"]
+        }
+    }
+}]
+
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
+    tools=tools,
+    tool_choice="auto"
+)
+
+# Check if function was called
+if response.choices[0].message.tool_calls:
+    tool_call = response.choices[0].message.tool_calls[0]
+    print(f"Function: {tool_call.function.name}")
+    print(f"Arguments: {tool_call.function.arguments}")
+```
+
+### Embeddings
+
+Generate text embeddings:
+
+```python
+response = client.embeddings.create(
+    model="text-embedding-3-small",
+    input="The quick brown fox jumps over the lazy dog"
+)
+
+embedding = response.data[0].embedding
+print(f"Embedding dimension: {len(embedding)}")
+```
+
+### Image Generation
+
+Create images with DALL-E:
+
+```python
+response = client.images.generate(
+    model="dall-e-3",
+    prompt="A futuristic city with flying cars",
+    size="1024x1024",
+    quality="standard",
+    n=1
+)
+
+image_url = response.data[0].url
+print(f"Image URL: {image_url}")
+```
+
+### Audio Transcription
+
+Convert speech to text:
+
+```python
+with open("audio.mp3", "rb") as audio_file:
+    response = client.audio.transcriptions.create(
+        model="whisper-1",
+        file=audio_file,
+        response_format="text"
+    )
+    
+print(response.text)
+```
+
+## Error Handling
+
+### Balance Errors
+
+Handle insufficient balance gracefully:
+
+```python
+try:
+    response = client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+except Exception as e:
+    if "insufficient_balance" in str(e):
+        print("Low balance! Please top up your API key.")
+        # Implement top-up logic
+    else:
+        raise
+```
+
+### Rate Limiting
+
+Implement exponential backoff:
+
+```python
+import time
+from typing import Optional
+
+def make_request_with_retry(
+    func, 
+    max_retries: int = 3,
+    initial_delay: float = 1.0
+) -> Optional[any]:
+    for attempt in range(max_retries):
+        try:
+            return func()
+        except Exception as e:
+            if "rate_limit" in str(e) and attempt < max_retries - 1:
+                delay = initial_delay * (2 ** attempt)
+                print(f"Rate limited. Waiting {delay}s...")
+                time.sleep(delay)
+            else:
+                raise
+    return None
+```
+
+### Connection Errors
+
+Handle network issues:
+
+```python
+import httpx
+
+# Configure timeout and retries
+client = OpenAI(
+    api_key="sk-...",
+    base_url="https://your-node.com/v1",
+    timeout=httpx.Timeout(60.0, connect=5.0),
+    max_retries=2
+)
+```
+
+## Advanced Features
+
+### Using Tor
+
+Route requests through Tor for privacy:
+
+```python
+import httpx
+
+# Configure Tor proxy
+proxies = {
+    "http://": "socks5://127.0.0.1:9050",
+    "https://": "socks5://127.0.0.1:9050"
+}
+
+http_client = httpx.Client(proxies=proxies)
+
+client = OpenAI(
+    api_key="sk-...",
+    base_url="http://your-onion-address.onion/v1",
+    http_client=http_client
+)
+```
+
+### Custom Headers
+
+Add custom headers if needed:
+
+```python
+import httpx
+
+class CustomClient(httpx.Client):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.headers["X-Custom-Header"] = "value"
+
+client = OpenAI(
+    api_key="sk-...",
+    base_url="https://your-node.com/v1",
+    http_client=CustomClient()
+)
+```
+
+### Azure OpenAI compatibility
+
+To use Azure OpenAI through Routstr with minimal changes:
+
+- Set `UPSTREAM_BASE_URL` to your Azure deployments URL, for example: `https://<resource>.openai.azure.com/openai/deployments/<deployment>`
+- Set `CHAT_COMPLETIONS_API_VERSION=2024-05-01-preview`
+
+When this env var is set, Routstr automatically appends `api-version=2024-05-01-preview` to all upstream `/chat/completions` requests.
+
+### Async Operations
+
+For high-performance applications:
+
+```python
+import asyncio
+from openai import AsyncOpenAI
+
+async_client = AsyncOpenAI(
+    api_key="sk-...",
+    base_url="https://your-node.com/v1"
+)
+
+async def process_messages(messages):
+    tasks = []
+    for msg in messages:
+        task = async_client.chat.completions.create(
+            model="gpt-3.5-turbo",
+            messages=[{"role": "user", "content": msg}]
+        )
+        tasks.append(task)
+    
+    responses = await asyncio.gather(*tasks)
+    return [r.choices[0].message.content for r in responses]
+
+# Run async
+messages = ["Hello", "How are you?", "What's 2+2?"]
+results = asyncio.run(process_messages(messages))
+```
+
+## Best Practices
+
+### 1. Environment Variables
+
+Never hardcode API keys:
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.getenv("ROUTSTR_API_KEY"),
+    base_url=os.getenv("ROUTSTR_BASE_URL", "https://api.routstr.com/v1")
+)
+```
+
+### 2. Error Logging
+
+Implement comprehensive logging:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+try:
+    response = client.chat.completions.create(...)
+    logger.info(f"Request successful. Tokens used: {response.usage.total_tokens}")
+except Exception as e:
+    logger.error(f"API request failed: {e}")
+    raise
+```
+
+### 3. Cost Tracking
+
+Monitor your usage:
+
+```python
+class UsageTracker:
+    def __init__(self):
+        self.total_tokens = 0
+        self.total_requests = 0
+    
+    def track(self, response):
+        self.total_tokens += response.usage.total_tokens
+        self.total_requests += 1
+        
+        # Estimate cost (example rates)
+        cost_per_1k = 0.002  # $0.002 per 1K tokens
+        estimated_cost = (self.total_tokens / 1000) * cost_per_1k
+        
+        logger.info(f"Total usage: {self.total_tokens} tokens, "
+                   f"${estimated_cost:.4f} (~{estimated_cost * 50000:.0f} sats)")
+
+tracker = UsageTracker()
+response = client.chat.completions.create(...)
+tracker.track(response)
+```
+
+### 4. Caching Responses
+
+Reduce costs with intelligent caching:
+
+```python
+import hashlib
+import json
+from functools import lru_cache
+
+@lru_cache(maxsize=100)
+def cached_completion(prompt: str, model: str = "gpt-3.5-turbo"):
+    response = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": prompt}],
+        temperature=0  # Deterministic for caching
+    )
+    return response.choices[0].message.content
+
+# Repeated calls with same prompt use cache
+result1 = cached_completion("What is 2+2?")
+result2 = cached_completion("What is 2+2?")  # From cache, no API call
+```
+
+## Testing
+
+### Mock Responses
+
+For development without spending sats:
+
+```python
+class MockOpenAI:
+    class Completions:
+        def create(self, **kwargs):
+            return type('Response', (), {
+                'choices': [type('Choice', (), {
+                    'message': type('Message', (), {
+                        'content': 'Mock response'
+                    })()
+                })],
+                'usage': type('Usage', (), {
+                    'total_tokens': 10
+                })()
+            })()
+    
+    def __init__(self):
+        self.chat = type('Chat', (), {
+            'completions': self.Completions()
+        })()
+
+# Use mock in tests
+if os.getenv('TESTING'):
+    client = MockOpenAI()
+else:
+    client = OpenAI(...)
+```
+
+### Integration Tests
+
+Test your Routstr integration:
+
+```python
+def test_routstr_connection():
+    try:
+        # Test models endpoint
+        models = client.models.list()
+        assert len(models.data) > 0
+        
+        # Test simple completion
+        response = client.chat.completions.create(
+            model="gpt-3.5-turbo",
+            messages=[{"role": "user", "content": "test"}],
+            max_tokens=5
+        )
+        assert response.choices[0].message.content
+        
+        print("✅ Routstr integration working!")
+        return True
+    except Exception as e:
+        print(f"❌ Integration test failed: {e}")
+        return False
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**SSL Certificate Errors**
+
+```python
+# For development only - not for production!
+import ssl
+import httpx
+
+client = OpenAI(
+    api_key="sk-...",
+    base_url="https://localhost:8000/v1",
+    http_client=httpx.Client(verify=False)
+)
+```
+
+**Timeout Issues**
+
+```python
+# Increase timeout for slow connections
+client = OpenAI(
+    api_key="sk-...",
+    base_url="https://your-node.com/v1",
+    timeout=httpx.Timeout(120.0)  # 2 minutes
+)
+```
+
+**Debugging Requests**
+
+```python
+import logging
+import httpx
+
+# Enable debug logging
+logging.basicConfig(level=logging.DEBUG)
+httpx_logger = logging.getLogger("httpx")
+httpx_logger.setLevel(logging.DEBUG)
+```
+
+## Next Steps
+
+- [Admin Dashboard](admin-dashboard.md) - Manage your account
+- [Models & Pricing](models-pricing.md) - Understanding costs
+- [API Reference](../api/overview.md) - Technical details

example.py

@@ -1,37 +0,0 @@
-import os
-
-import openai
-
-client = openai.OpenAI(
-    api_key=os.environ["CASHU_TOKEN"],
-    base_url=os.environ.get("ROUTSTR_API_URL", "https://api.routstr.com/v1"),
-    # base_url="http://roustrjfsdgfiueghsklchg.onion/v1",
-    # client=httpx.AsyncClient(
-    #     proxies={"http": "socks5://localhost:9050"},
-    # ),  # to use onion proxy (tor)
-)
-history: list = []
-
-
-def chat() -> None:
-    while True:
-        user_msg = {"role": "user", "content": input("\nYou: ")}
-        history.append(user_msg)
-        ai_msg = {"role": "assistant", "content": ""}
-
-        for chunk in client.chat.completions.create(
-            model=os.environ.get("MODEL", "openai/gpt-4o-mini"),
-            messages=history,
-            stream=True,
-        ):
-            if len(chunk.choices) > 0:
-                content = chunk.choices[0].delta.content
-                if content is not None:
-                    ai_msg["content"] += content
-                    print(content, end="", flush=True)
-        print()
-        history.append(ai_msg)
-
-
-if __name__ == "__main__":
-    chat()

examples/balance/check_balance.py

@@ -0,0 +1,11 @@
+import os
+
+import httpx
+
+# Use your Cashu token or API key as the Bearer token,
+# cashu token is hashed on the server and acts as an Temporary API key
+headers = {"Authorization": f"Bearer {os.environ.get('TOKEN')}"}
+base_url = os.environ.get("API_URL", "https://api.routstr.com/v1")
+
+resp = httpx.get(f"{base_url}/balance/info", headers=headers)
+print(resp.json())

examples/balance/create_balance.py

@@ -0,0 +1,15 @@
+import os
+
+import httpx
+
+# Send a Cashu token to the /create endpoint to get a persistent API key
+token = os.environ.get("TOKEN")
+if not token:
+    print("Please set TOKEN environment variable with a Cashu token")
+    exit(1)
+
+base_url = os.environ.get("API_URL", "https://api.routstr.com/v1")
+
+resp = httpx.get(f"{base_url}/balance/create", params={"initial_balance_token": token})
+
+print(resp.json())

examples/balance/refund_balance.py

@@ -0,0 +1,12 @@
+import os
+
+import httpx
+
+# Use your Cashu token or API key as the Bearer token
+headers = {"Authorization": f"Bearer {os.environ.get('TOKEN')}"}
+base_url = os.environ.get("API_URL", "https://api.routstr.com/v1")
+
+resp = httpx.post(f"{base_url}/balance/refund", headers=headers)
+
+print("Refund successful!")
+print(resp.json())

examples/balance/topup_balance.py

@@ -0,0 +1,16 @@
+import os
+
+import httpx
+
+# Use your Cashu token or API key as the Bearer token
+headers = {"Authorization": f"Bearer {os.environ.get('TOKEN')}"}
+base_url = os.environ.get("API_URL", "https://api.routstr.com/v1")
+
+# The Cashu token to top up with
+cashu_token = input("Enter Cashu token to top up: ")
+
+resp = httpx.post(
+    f"{base_url}/balance/topup", headers=headers, json={"cashu_token": cashu_token}
+)
+
+print(resp.json())

examples/chat_completions.py

@@ -0,0 +1,15 @@
+import os
+
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.environ.get("TOKEN"),
+    base_url=os.environ.get("API_URL", "https://api.routstr.com/v1"),
+)
+
+response = client.chat.completions.create(
+    model=os.environ.get("MODEL", "gpt-5-nano"),
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(response.choices[0].message.content)

examples/list_models.py

@@ -0,0 +1,19 @@
+import os
+
+import httpx
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.environ.get("TOKEN", ""),
+    base_url=os.environ.get("API_URL", "https://api.routstr.com/v1"),
+)
+
+for model in client.models.list():
+    print(model.id)
+
+# OR
+
+models = httpx.get(
+    f"{client.base_url}/v1/models",
+    headers={"Authorization": f"Bearer {client.api_key}"},
+).json()

examples/responses/conversation.py

@@ -0,0 +1,31 @@
+import os
+
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.environ.get("TOKEN"),
+    base_url=os.environ.get("API_URL", "https://api.routstr.com/v1"),
+)
+
+conversation = []  # type: ignore
+
+# First turn
+response1 = client.responses.create(  # type: ignore
+    model="o4-mini",
+    input="Hi, my name is Alice.",
+    conversation=conversation,
+)
+print("Response 1:", response1.output)
+
+# Note: The 'conversation' parameter might need to be constructed differently
+# depending on exact SDK/API spec. Typically, you pass back the previous turn's data.
+# Assuming the SDK manages or returns a conversation object/ID:
+# conversation.append(response1)
+
+# Second turn - demonstrating intent, actual implementation depends on strict API spec
+# response2 = client.responses.create(
+#     model="openai/gpt-4o-mini",
+#     input="What is my name?",
+#     conversation=conversation,
+# )
+# print("Response 2:", response2.output)

examples/responses/create.py

@@ -0,0 +1,17 @@
+import os
+
+from openai import OpenAI
+
+# The OpenAI SDK handles the 'responses' endpoint if it's updated to the latest version
+# and the base_url points to a compatible proxy like Routstr.
+client = OpenAI(
+    api_key=os.environ.get("TOKEN"),
+    base_url=os.environ.get("API_URL", "https://api.routstr.com/v1"),
+)
+
+response = client.responses.create(
+    model="gpt-5-mini",
+    input="Tell me a three sentence bedtime story about a unicorn.",
+)
+
+print(response.output)

examples/responses/streaming_response.py

@@ -0,0 +1,20 @@
+import os
+
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.environ.get("TOKEN"),
+    base_url=os.environ.get("API_URL", "https://api.routstr.com/v1"),
+)
+
+stream = client.responses.create(
+    model="claude-4.5-sonnet",
+    input="Write a short poem about rust.",
+    stream=True,
+)
+
+for event in stream:
+    # Note: Depending on the SDK version and response structure,
+    # you might access event.output_delta or similar fields
+    print(event, end="", flush=True)
+print()

examples/responses/web_search.py

@@ -0,0 +1,16 @@
+import os
+
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.environ.get("TOKEN"),
+    base_url=os.environ.get("API_URL", "https://api.routstr.com/v1"),
+)
+
+response = client.responses.create(
+    model="gpt-5-mini",
+    input="What is the latest news about AI?",
+    tools=[{"type": "web_search"}],  # type: ignore
+)
+
+print(response.output)

examples/streaming.py

@@ -0,0 +1,28 @@
+import os
+
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.environ.get("TOKEN"),
+    base_url=os.environ.get("API_URL", "https://api.routstr.com/v1"),
+)
+
+messages = []
+while True:
+    messages.append({"role": "user", "content": input("\nYou: ")})
+
+    stream = client.chat.completions.create(
+        model=os.environ.get("MODEL", "gpt-5.1-mini"),
+        messages=messages,  # type: ignore
+        stream=True,
+    )
+
+    print("AI: ", end="")
+    response_content = ""
+    for chunk in stream:
+        if content := chunk.choices[0].delta.content:  # type: ignore
+            print(content, end="", flush=True)
+            response_content += content
+    print()
+
+    messages.append({"role": "assistant", "content": response_content})

examples/tor.py

@@ -0,0 +1,20 @@
+import os
+
+import httpx
+from openai import OpenAI
+
+# Requires `pip install "httpx[socks]"` and a running Tor proxy on port 9050
+client = OpenAI(
+    api_key=os.environ.get("TOKEN"),
+    base_url=os.environ.get("ONION_URL", "http://roustrjfsdgfiueghsklchg.onion/v1"),
+    http_client=httpx.Client(proxies="socks5://localhost:9050"),
+)
+
+print(
+    client.chat.completions.create(
+        model="openai/gpt-4o-mini",
+        messages=[{"role": "user", "content": "Hello from Tor!"}],
+    )
+    .choices[0]
+    .message.content
+)

migrations/env.py

@@ -0,0 +1,73 @@
+import asyncio
+import pathlib
+import sys
+
+# from logging.config import fileConfig
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlmodel import SQLModel
+
+from routstr.core.db import DATABASE_URL
+
+# Add the parent directory to the Python path so we can import routstr modules
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+
+config = context.config
+if config.config_file_name is None:
+    raise ValueError("config_file_name is None")
+
+# Skip loading alembic's logging configuration to preserve our custom logging
+# fileConfig(config.config_file_name)
+
+config.set_main_option("sqlalchemy.url", DATABASE_URL)
+
+target_metadata = SQLModel.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=DATABASE_URL,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    context.configure(
+        connection=connection, target_metadata=target_metadata, compare_type=True
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_migrations_online() -> None:
+    connectable = create_async_engine(DATABASE_URL, poolclass=pool.NullPool)
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    # Check if we're already in an event loop (e.g., being called from FastAPI)
+    try:
+        loop = asyncio.get_running_loop()
+        # If we're in an existing loop, create a new thread to run migrations
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            future = executor.submit(asyncio.run, run_migrations_online())
+            future.result()
+    except RuntimeError:
+        # No event loop running, we can use asyncio.run directly
+        asyncio.run(run_migrations_online())

migrations/script.py.mako

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+${imports if imports else ""}
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

migrations/versions/042f6b77d69d_introduce_reserved_balance.py

@@ -0,0 +1,30 @@
+"""introduce reserved balance
+
+Revision ID: 042f6b77d69d
+Revises: 898f00ea481e
+Create Date: 2025-08-18 19:03:09.507368
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "042f6b77d69d"
+down_revision = "898f00ea481e"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        "api_keys",
+        sa.Column("reserved_balance", sa.Integer(), nullable=False, server_default="0"),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("api_keys", "reserved_balance")
+    # ### end Alembic commands ###

migrations/versions/7bc4e8b02b9d_add_mint_field.py

@@ -0,0 +1,31 @@
+"""add mint field
+
+Revision ID: 7bc4e8b02b9d
+Revises: f6ce1348e266
+Create Date: 2025-08-09 13:48:40.648729
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlmodel.sql import sqltypes
+
+# revision identifiers, used by Alembic.
+revision = "7bc4e8b02b9d"
+down_revision = "f6ce1348e266"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        "api_keys",
+        sa.Column("mint_url", sqltypes.AutoString(), nullable=True),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("api_keys", "mint_url")
+    # ### end Alembic commands ###

migrations/versions/898f00ea481e_add_mint_currency_refund_details.py

@@ -0,0 +1,38 @@
+"""add mint+currency refund details
+
+Revision ID: 898f00ea481e
+Revises: 7bc4e8b02b9d
+Create Date: 2025-08-13 16:45:42.148314
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlmodel.sql import sqltypes
+
+# revision identifiers, used by Alembic.
+revision = "898f00ea481e"
+down_revision = "7bc4e8b02b9d"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        "api_keys",
+        sa.Column("refund_mint_url", sqltypes.AutoString(), nullable=True),
+    )
+    op.add_column(
+        "api_keys",
+        sa.Column("refund_currency", sqltypes.AutoString(), nullable=True),
+    )
+    op.drop_column("api_keys", "mint_url")
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column("api_keys", sa.Column("mint_url", sa.VARCHAR(), nullable=True))
+    op.drop_column("api_keys", "refund_currency")
+    op.drop_column("api_keys", "refund_mint_url")
+    # ### end Alembic commands ###

migrations/versions/a1a1a1a1a1a1_composite_pk_for_models.py

@@ -0,0 +1,64 @@
+"""change models to composite primary key (id, upstream_provider_id)
+
+Revision ID: a1a1a1a1a1a1
+Revises: f7a8b9c0d1e2
+Create Date: 2025-10-20 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "a1a1a1a1a1a1"
+down_revision = "f7a8b9c0d1e2"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    if "models" in inspector.get_table_names():
+        op.drop_table("models")
+
+    op.create_table(
+        "models",
+        sa.Column("id", sa.String(), nullable=False),
+        sa.Column("upstream_provider_id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("created", sa.Integer(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False),
+        sa.Column("context_length", sa.Integer(), nullable=False),
+        sa.Column("architecture", sa.Text(), nullable=False),
+        sa.Column("pricing", sa.Text(), nullable=False),
+        sa.Column("sats_pricing", sa.Text(), nullable=True),
+        sa.Column("per_request_limits", sa.Text(), nullable=True),
+        sa.Column("top_provider", sa.Text(), nullable=True),
+        sa.Column("enabled", sa.Boolean(), nullable=False, server_default="1"),
+        sa.PrimaryKeyConstraint("id", "upstream_provider_id"),
+        sa.ForeignKeyConstraint(
+            ["upstream_provider_id"], ["upstream_providers.id"], ondelete="CASCADE"
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("models")
+    op.create_table(
+        "models",
+        sa.Column("id", sa.String(), primary_key=True, nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("created", sa.Integer(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False),
+        sa.Column("context_length", sa.Integer(), nullable=False),
+        sa.Column("architecture", sa.Text(), nullable=False),
+        sa.Column("pricing", sa.Text(), nullable=False),
+        sa.Column("sats_pricing", sa.Text(), nullable=True),
+        sa.Column("per_request_limits", sa.Text(), nullable=True),
+        sa.Column("top_provider", sa.Text(), nullable=True),
+        sa.Column("enabled", sa.Boolean(), nullable=False, server_default="1"),
+        sa.Column("upstream_provider_id", sa.Integer(), nullable=True),
+        sa.ForeignKeyConstraint(["upstream_provider_id"], ["upstream_providers.id"]),
+    )

migrations/versions/a1b2c3d4e5f6_add_settings_table.py

@@ -0,0 +1,35 @@
+"""add settings table
+
+Revision ID: a1b2c3d4e5f6
+Revises: 042f6b77d69d
+Create Date: 2025-09-06 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "a1b2c3d4e5f6"
+down_revision = "042f6b77d69d"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "settings",
+        sa.Column("id", sa.Integer(), primary_key=True, nullable=False),
+        sa.Column("data", sa.Text(), nullable=False),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(),
+            nullable=True,
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("settings")

migrations/versions/b9667ffc5701_alias_ids.py

@@ -0,0 +1,37 @@
+"""alias-ids
+
+Revision ID: b9667ffc5701
+Revises: lightning_invoices
+Create Date: 2025-12-25 19:30:44.673350
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "b9667ffc5701"
+down_revision = "lightning_invoices"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic ###
+    op.add_column(
+        "models",
+        sa.Column("canonical_slug", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    )
+    op.add_column(
+        "models",
+        sa.Column("alias_ids", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    )
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("models", "alias_ids")
+    op.drop_column("models", "canonical_slug")
+    # ### end Alembic commands ###

migrations/versions/c0ffee123456_create_models_table.py

@@ -0,0 +1,37 @@
+"""create models table
+
+Revision ID: c0ffee123456
+Revises: a1b2c3d4e5f6
+Create Date: 2025-09-10 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "c0ffee123456"
+down_revision = "a1b2c3d4e5f6"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "models",
+        sa.Column("id", sa.String(), primary_key=True, nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("created", sa.Integer(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False),
+        sa.Column("context_length", sa.Integer(), nullable=False),
+        sa.Column("architecture", sa.Text(), nullable=False),
+        sa.Column("pricing", sa.Text(), nullable=False),
+        sa.Column("sats_pricing", sa.Text(), nullable=True),
+        sa.Column("per_request_limits", sa.Text(), nullable=True),
+        sa.Column("top_provider", sa.Text(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("models")

migrations/versions/d1e2f3a4b5c6_create_upstream_providers_table.py

@@ -0,0 +1,45 @@
+"""create upstream_providers table
+
+Revision ID: d1e2f3a4b5c6
+Revises: c0ffee123456
+Create Date: 2025-10-09 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "d1e2f3a4b5c6"
+down_revision = "c0ffee123456"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    if "upstream_providers" not in inspector.get_table_names():
+        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, unique=True),
+            sa.Column("api_key", sa.String(), nullable=False),
+            sa.Column("api_version", sa.String(), nullable=True),
+            sa.Column("enabled", sa.Boolean(), nullable=False, default=True),
+        )
+        op.create_index(
+            "ix_upstream_providers_base_url",
+            "upstream_providers",
+            ["base_url"],
+            unique=True,
+        )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_upstream_providers_base_url", "upstream_providers")
+    op.drop_table("upstream_providers")

migrations/versions/e1f2a3b4c5d6_add_upstream_provider_to_models.py

@@ -0,0 +1,53 @@
+"""add upstream_provider and enabled to models
+
+Revision ID: e1f2a3b4c5d6
+Revises: d1e2f3a4b5c6
+Create Date: 2025-10-13 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "e1f2a3b4c5d6"
+down_revision = "d1e2f3a4b5c6"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_table("models")
+    op.create_table(
+        "models",
+        sa.Column("id", sa.String(), primary_key=True, nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("created", sa.Integer(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False),
+        sa.Column("context_length", sa.Integer(), nullable=False),
+        sa.Column("architecture", sa.Text(), nullable=False),
+        sa.Column("pricing", sa.Text(), nullable=False),
+        sa.Column("sats_pricing", sa.Text(), nullable=True),
+        sa.Column("per_request_limits", sa.Text(), nullable=True),
+        sa.Column("top_provider", sa.Text(), nullable=True),
+        sa.Column("enabled", sa.Boolean(), nullable=False, server_default="1"),
+        sa.Column("upstream_provider_id", sa.Integer(), nullable=True),
+        sa.ForeignKeyConstraint(["upstream_provider_id"], ["upstream_providers.id"]),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("models")
+    op.create_table(
+        "models",
+        sa.Column("id", sa.String(), primary_key=True, nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("created", sa.Integer(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False),
+        sa.Column("context_length", sa.Integer(), nullable=False),
+        sa.Column("architecture", sa.Text(), nullable=False),
+        sa.Column("pricing", sa.Text(), nullable=False),
+        sa.Column("sats_pricing", sa.Text(), nullable=True),
+        sa.Column("per_request_limits", sa.Text(), nullable=True),
+        sa.Column("top_provider", sa.Text(), nullable=True),
+    )

migrations/versions/f6ce1348e266_init.py

@@ -0,0 +1,40 @@
+"""init
+
+Revision ID: f6ce1348e266
+Revises:
+Create Date: 2025-08-09 13:28:38.537652
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlmodel.sql import sqltypes
+
+# revision identifiers, used by Alembic.
+revision = "f6ce1348e266"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    if "api_keys" not in sa.inspect(op.get_bind()).get_table_names():
+        op.create_table(
+            "api_keys",
+            sa.Column("hashed_key", sqltypes.AutoString(), nullable=False),
+            sa.Column("balance", sa.Integer(), nullable=False),
+            sa.Column("refund_address", sqltypes.AutoString(), nullable=True),
+            sa.Column("key_expiry_time", sa.Integer(), nullable=True),
+            sa.Column("total_spent", sa.Integer(), nullable=False),
+            sa.Column("total_requests", sa.Integer(), nullable=False),
+            sa.PrimaryKeyConstraint("hashed_key"),
+        )
+
+
+def downgrade() -> None:
+    # Only drop the table if it exists
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    tables = inspector.get_table_names()
+
+    if "api_keys" in tables:
+        op.drop_table("api_keys")

migrations/versions/f7a8b9c0d1e2_add_fees_to_upstream_providers.py

@@ -0,0 +1,27 @@
+"""add provider_fee to upstream_providers
+
+Revision ID: f7a8b9c0d1e2
+Revises: e1f2a3b4c5d6
+Create Date: 2025-10-13 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "f7a8b9c0d1e2"
+down_revision = "e1f2a3b4c5d6"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "upstream_providers",
+        sa.Column("provider_fee", sa.Float(), nullable=False, server_default="1.01"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("upstream_providers", "provider_fee")

migrations/versions/lightning_invoices_table.py

@@ -0,0 +1,39 @@
+"""Add lightning_invoices table
+
+Revision ID: lightning_invoices
+Revises: a1a1a1a1a1a1
+Create Date: 2025-12-10 21:00:00.000000
+"""
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+revision = "lightning_invoices"
+down_revision = "a1a1a1a1a1a1"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "lightning_invoices",
+        sa.Column("id", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("bolt11", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("amount_sats", sa.Integer(), nullable=False),
+        sa.Column("description", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("payment_hash", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("status", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("api_key_hash", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+        sa.Column("purpose", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("created_at", sa.Integer(), nullable=False),
+        sa.Column("expires_at", sa.Integer(), nullable=False),
+        sa.Column("paid_at", sa.Integer(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("bolt11"),
+        sa.UniqueConstraint("payment_hash"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("lightning_invoices")

mkdocs.yml

@@ -0,0 +1,105 @@
+site_name: Routstr Core Documentation
+site_url: https://docs.routstr.com
+site_description: FastAPI-based reverse proxy for OpenAI-compatible APIs with Bitcoin eCash micropayments
+site_author: Routstr Team
+
+repo_name: routstr/routstr-core
+repo_url: https://github.com/routstr/routstr-core
+edit_uri: tree/main/docs
+
+theme:
+  name: material
+  language: en
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: orange
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: orange
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - navigation.indexes
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.copy
+    - content.code.annotate
+  icon:
+    logo: material/lightning-bolt
+    repo: fontawesome/brands/github
+
+plugins:
+  - search
+  - mermaid2
+
+markdown_extensions:
+  - admonition
+  - codehilite:
+      guess_lang: false
+  - toc:
+      permalink: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.details
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - attr_list
+  - md_in_html
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/routstr
+    - icon: fontawesome/brands/bitcoin
+      link: https://cashu.space
+
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Overview: getting-started/overview.md
+      - Quick Start: getting-started/quickstart.md
+      - Docker Setup: getting-started/docker.md
+      - Configuration: getting-started/configuration.md
+  - User Guide:
+      - Introduction: user-guide/introduction.md
+      - Payment Flow: user-guide/payment-flow.md
+      - Using the API: user-guide/using-api.md
+      - Admin Dashboard: user-guide/admin-dashboard.md
+      - Models & Pricing: user-guide/models-pricing.md
+  - Contributing:
+      - Setup Development: contributing/setup.md
+      - Architecture: contributing/architecture.md
+      - Code Structure: contributing/code-structure.md
+      - Testing: contributing/testing.md
+  - API Reference:
+      - Overview: api/overview.md
+      - Authentication: api/authentication.md
+      - Endpoints: api/endpoints.md
+      - Errors: api/errors.md
+  - Advanced:
+      - Tor Support: advanced/tor.md
+      - Nostr Discovery: advanced/nostr.md
+      - Custom Pricing: advanced/custom-pricing.md
+      - Migrations: advanced/migrations.md

models.example.json

@@ -1,11 +1,12 @@
 {
     "models": [
         {
-            "id": "google/gemini-2.5-pro-preview",
+            "id": "google/gemini-2.5-flash",
+            "canonical_slug": "google/gemini-2.5-flash",
             "hugging_face_id": "",
-            "name": "Google: Gemini 2.5 Pro Preview 06-05",
-            "created": 1749137257,
-            "description": "Gemini 2.5 Pro is Google\u2019s state-of-the-art AI model designed for advanced reasoning, coding, mathematics, and scientific tasks. It employs \u201cthinking\u201d capabilities, enabling it to reason through responses with enhanced accuracy and nuanced context handling. Gemini 2.5 Pro achieves top-tier performance on multiple benchmarks, including first-place positioning on the LMArena leaderboard, reflecting superior human-preference alignment and complex problem-solving abilities.\n",
+            "name": "Google: Gemini 2.5 Flash",
+            "created": 1750172488,
+            "description": "Gemini 2.5 Flash is Google's state-of-the-art workhorse model, specifically designed for advanced reasoning, coding, mathematics, and scientific tasks. It includes built-in \"thinking\" capabilities, enabling it to provide responses with greater accuracy and nuanced context handling. \n\nAdditionally, Gemini 2.5 Flash is configurable through the \"max tokens for reasoning\" parameter, as described in the documentation (https://openrouter.ai/docs/use-cases/reasoning-tokens#max-tokens-for-reasoning).",
             "context_length": 1048576,
             "architecture": {
                 "modality": "text+image->text",
@@ -21,18 +22,107 @@
                 "instruct_type": null
             },
             "pricing": {
-                "prompt": "0.00000125",
-                "completion": "0.00001",
+                "prompt": "0.0000003",
+                "completion": "0.0000025",
                 "request": "0",
-                "image": "0.00516",
+                "image": "0.001238",
                 "web_search": "0",
                 "internal_reasoning": "0",
-                "input_cache_read": "0.00000031",
-                "input_cache_write": "0.000001625"
+                "input_cache_read": "0.000000075",
+                "input_cache_write": "0.0000003833"
             },
             "top_provider": {
                 "context_length": 1048576,
-                "max_completion_tokens": 65536,
+                "max_completion_tokens": 65535,
+                "is_moderated": false
+            },
+            "per_request_limits": null,
+            "supported_parameters": [
+                "max_tokens",
+                "temperature",
+                "top_p",
+                "tools",
+                "tool_choice",
+                "stop",
+                "response_format",
+                "structured_outputs"
+            ]
+        },
+        {
+            "id": "openai/o3-pro",
+            "canonical_slug": "openai/o3-pro-2025-06-10",
+            "hugging_face_id": "",
+            "name": "OpenAI: o3 Pro",
+            "created": 1749598352,
+            "description": "The o-series of models are trained with reinforcement learning to think before they answer and perform complex reasoning. The o3-pro model uses more compute to think harder and provide consistently better answers.\n\nNote that BYOK is required for this model. Set up here: https://openrouter.ai/settings/integrations",
+            "context_length": 200000,
+            "architecture": {
+                "modality": "text+image->text",
+                "input_modalities": [
+                    "text",
+                    "file",
+                    "image"
+                ],
+                "output_modalities": [
+                    "text"
+                ],
+                "tokenizer": "Other",
+                "instruct_type": null
+            },
+            "pricing": {
+                "prompt": "0.00002",
+                "completion": "0.00008",
+                "request": "0",
+                "image": "0.0153",
+                "web_search": "0",
+                "internal_reasoning": "0"
+            },
+            "top_provider": {
+                "context_length": 200000,
+                "max_completion_tokens": 100000,
+                "is_moderated": true
+            },
+            "per_request_limits": null,
+            "supported_parameters": [
+                "tools",
+                "tool_choice",
+                "seed",
+                "max_tokens",
+                "response_format",
+                "structured_outputs"
+            ]
+        },
+        {
+            "id": "x-ai/grok-3-mini",
+            "canonical_slug": "x-ai/grok-3-mini",
+            "hugging_face_id": "",
+            "name": "xAI: Grok 3 Mini",
+            "created": 1749583245,
+            "description": "A lightweight model that thinks before responding. Fast, smart, and great for logic-based tasks that do not require deep domain knowledge. The raw thinking traces are accessible.",
+            "context_length": 131072,
+            "architecture": {
+                "modality": "text->text",
+                "input_modalities": [
+                    "text"
+                ],
+                "output_modalities": [
+                    "text"
+                ],
+                "tokenizer": "Grok",
+                "instruct_type": null
+            },
+            "pricing": {
+                "prompt": "0.0000003",
+                "completion": "0.0000005",
+                "request": "0",
+                "image": "0",
+                "web_search": "0",
+                "internal_reasoning": "0",
+                "input_cache_read": "0.000000075"
+            },
+            "top_provider": {
+                "context_length": 131072,
+                "max_completion_tokens": null,
                 "is_moderated": false
             },
             "per_request_limits": null,
@@ -45,11 +135,11 @@
                 "reasoning",
                 "include_reasoning",
                 "structured_outputs",
-                "response_format",
                 "stop",
-                "frequency_penalty",
-                "presence_penalty",
-                "seed"
+                "seed",
+                "logprobs",
+                "top_logprobs",
+                "response_format"
             ]
         }
     ]

pyproject.toml

@@ -1,17 +1,26 @@
 [project]
 name = "routstr"
-version = "0.0.1"
+version = "0.2.1"
 description = "Payment proxy for your LLM endpoint using cashu and nostr."
 readme = "README.md"
 requires-python = ">=3.11"
+
 dependencies = [
     "fastapi[standard]>=0.115",
     "aiosqlite>=0.20",
-    "sixty-nuts>=0.1.4",
     "sqlmodel>=0.0.24",
     "httpx[socks]>=0.25.2",
     "greenlet>=3.2.1",
+    "alembic>=1.13",
     "python-json-logger>=2.0.0",
+    "cashu",
+    "secp256k1",
+    "marshmallow>=3.13,<4.0",
+    "websockets>=12.0",
+    "nostr>=0.0.2",
+    "mdurl==0.1.2",
+    "pillow>=10",
+    "openai>=1.98.0",
 ]
 
 [dependency-groups]
@@ -23,6 +32,10 @@ dev = [
     "pytest-asyncio>=0.24.0",
     "pytest-cov>=6.1.1",
     "httpx>=0.25.2",
+    "psutil>=5.9.0",
+    "aiohttp>=3.9.0",
+    "pytest-benchmark>=4.0.0",
+    "routstr",
 ]
 
 [tool.pytest.ini_options]
@@ -42,13 +55,25 @@ addopts = [
 ]
 markers = [
     "asyncio: marks tests as async (deselect with '-m \"not asyncio\"')",
-    "integration: marks tests as integration tests",
+    "integration: marks tests as integration tests (deselect with '-m \"not integration\"')",
     "unit: marks tests as unit tests",
+    "slow: marks tests as slow running (deselect with '-m \"not slow\"')",
+    "requires_real_mint: marks tests that require a running Cashu mint instance",
+    "requires_docker: marks tests that require Docker services running (deselect with '-m \"not requires_docker\"')",
+    "performance: marks tests that measure performance metrics",
 ]
 
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["routstr"]
+
 [tool.ruff.lint]
 select = ["E", "F", "I"]
 ignore = ["E501"]
+exclude = ["examples"]
 
 [tool.mypy]
 python_version = "3.11"
@@ -58,3 +83,7 @@ check_untyped_defs = true
 disallow_untyped_calls = true
 disallow_incomplete_defs = true
 disallow_untyped_decorators = true
+
+[tool.uv.sources]
+routstr = { workspace = true }
+secp256k1 = { git = "https://github.com/saschanaz/secp256k1-py", branch = "upgrade060" }

router/__init__.py

@@ -1,7 +0,0 @@
-import dotenv
-
-dotenv.load_dotenv()
-
-from .main import app as fastapi_app  # noqa
-
-__all__ = ["fastapi_app"]

router/account.py

@@ -1,102 +0,0 @@
-from typing import Annotated, NoReturn
-
-from fastapi import APIRouter, Depends, Header, HTTPException
-
-from .auth import validate_bearer_key
-from .cashu import (
-    credit_balance,
-    delete_key_if_zero_balance,
-    refund_balance,
-    wallet,
-)
-from .db import ApiKey, AsyncSession, get_session
-
-wallet_router = APIRouter(prefix="/v1/wallet")
-
-
-async def get_key_from_header(
-    authorization: Annotated[str, Header(...)],
-    session: AsyncSession = Depends(get_session),
-) -> ApiKey:
-    if authorization.startswith("Bearer "):
-        return await validate_bearer_key(authorization[7:], session)
-
-    raise HTTPException(
-        status_code=401,
-        detail="Invalid authorization. Use 'Bearer <cashu-token>' or 'Bearer <api-key>'",
-    )
-
-
-# TODO: remove this endpoint when frontend is updated
-@wallet_router.get("/")
-async def account_info(key: ApiKey = Depends(get_key_from_header)) -> dict:
-    return {
-        "api_key": "sk-" + key.hashed_key,
-        "balance": key.balance,
-    }
-
-
-@wallet_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,
-    }
-
-
-@wallet_router.post("/topup")
-async def topup_wallet_endpoint(
-    cashu_token: str,
-    key: ApiKey = Depends(get_key_from_header),
-    session: AsyncSession = Depends(get_session),
-) -> dict[str, int]:
-    amount_msats = await credit_balance(cashu_token, key, session)
-    return {"msats": amount_msats}
-
-
-@wallet_router.post("/refund")
-async def refund_wallet_endpoint(
-    key: ApiKey = Depends(get_key_from_header),
-    session: AsyncSession = Depends(get_session),
-) -> dict:
-    remaining_balance_msats = key.balance
-
-    if remaining_balance_msats == 0:
-        raise HTTPException(status_code=400, detail="No balance to refund")
-
-    # Perform refund operation first, before modifying balance
-    if key.refund_address:
-        await refund_balance(remaining_balance_msats, key, session)
-        result = {"recipient": key.refund_address, "msats": remaining_balance_msats}
-    else:
-        # Convert msats to sats for cashu wallet
-        remaining_balance_sats = remaining_balance_msats // 1000
-        if remaining_balance_sats == 0:
-            raise HTTPException(
-                status_code=400, detail="Balance too small to refund (less than 1 sat)"
-            )
-
-        # TODO: choose currency and mint based on what user has configured
-        token = await wallet().send(remaining_balance_sats)
-
-        result = {"msats": remaining_balance_msats, "recipient": None, "token": token}
-
-    # Only after successful refund, zero out the balance
-    key.balance = 0
-    session.add(key)
-    await session.commit()
-    await delete_key_if_zero_balance(key, session)
-
-    return result
-
-
-@wallet_router.api_route(
-    "/{path:path}",
-    methods=["GET", "POST", "PUT", "DELETE"],
-    include_in_schema=False,
-    response_model=None,
-)
-async def wallet_catch_all(path: str) -> NoReturn:
-    raise HTTPException(
-        status_code=404, detail="Not found check /docs for available endpoints"
-    )

router/admin.py

@@ -1,162 +0,0 @@
-import os
-from datetime import datetime, timezone
-
-from fastapi import APIRouter, Request
-from fastapi.responses import HTMLResponse
-from sqlmodel import select
-
-from .cashu import wallet
-from .db import ApiKey, create_session
-
-admin_router = APIRouter(prefix="/admin")
-
-
-def login_form() -> str:
-    return """<!DOCTYPE html>
-    <html>
-        <head>
-            <style>
-                body {
-                    font-family: Arial, sans-serif;
-                    display: flex;
-                    justify-content: center;
-                    align-items: center;
-                    height: 100vh;
-                    margin: 0;
-                }
-                form {
-                    display: flex;
-                    flex-direction: column;
-                    gap: 10px;
-                }
-                input[type="password"] {
-                    padding: 8px;
-                }
-                button {
-                    padding: 8px;
-                    cursor: pointer;
-                }
-            </style>
-            <script>
-                function handleSubmit(e) {
-                    e.preventDefault();
-                    const password = document.getElementById('password').value;
-                    document.cookie = `admin_password=${password}; path=/; max-age=86400`;
-                    window.location.reload();
-                }
-            </script>
-        </head>
-        <body>
-            <form onsubmit="handleSubmit(event)">
-                <input type="password" id="password" placeholder="Admin Password" required>
-                <button type="submit">Login</button>
-            </form>
-        </body>
-    </html>
-    """
-
-
-def info(content: str) -> str:
-    return f"""<!DOCTYPE html>
-    <html>
-        <head>
-            <style>
-                body {{
-                    font-family: Arial, sans-serif;
-                    display: flex;
-                    justify-content: center;
-                    align-items: center;
-                    height: 100vh;
-                    margin: 0;
-                }}
-            </style>
-        </head>
-        <body>
-            <div style="text-align: center;">
-                {content}
-            </div>
-        </body>
-    </html>
-    """
-
-
-def admin_auth() -> str:
-    if os.getenv("ADMIN_PASSWORD", "") == "":
-        return info("Please set a secure ADMIN_PASSWORD= in your ENV variables.")
-    else:
-        return login_form()
-
-
-async def dashboard(request: Request) -> str:
-    # fetch cashu / api-key data from database
-    async with create_session() as session:
-        result = await session.exec(select(ApiKey))
-        api_keys = result.all()
-
-    api_keys_table_rows = []
-    for key in api_keys:
-        expiry_time_utc = (
-            datetime.fromtimestamp(key.key_expiry_time, tz=timezone.utc)
-            if key.key_expiry_time is not None
-            else None
-        )
-        expiry_time_human_readable = (
-            expiry_time_utc.strftime("%Y-%m-%d %H:%M:%S") if expiry_time_utc else ""
-        )
-
-        api_keys_table_rows.append(
-            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>{'{} ({} UTC)'.format(key.key_expiry_time, expiry_time_human_readable) if key.key_expiry_time else key.key_expiry_time}</td></tr>"
-        )
-
-    # Calculate the total balance of all API keys using integer arithmetic to
-    # avoid rounding issues.
-    total_user_balance = sum(key.balance for key in api_keys) // 1000
-    # Fetch balance from cashu
-    current_balance = await wallet().get_balance()
-    owner_balance = current_balance - total_user_balance
-
-    return f"""<!DOCTYPE html>
-    <html>
-        <head>
-            <style>
-                table {{
-                    width: 100%;
-                    border-collapse: collapse;
-                }}
-                th, td {{
-                    border: 1px solid black;
-                    padding: 8px;
-                    text-align: left;
-                }}
-            </style>
-        </head>
-        <body>
-            <h1>Admin Dashboard</h1>
-            <h2>Current Cashu Balance</h2>
-            <p>Your Balance: {owner_balance} sats</p>
-            <p>The balance is calculated by subtracting the combined user balance from the total Cashu wallet balance.</p>
-            <p>Total Cashu Balance: {current_balance} sats</p>
-            <p>User Balance: {total_user_balance} sats</p>
-            <h2>User's API Keys</h2>
-            <table>
-                <tr>
-                    <th>Hashed Key</th>
-                    <th>Balance (mSats)</th>
-                    <th>Total Spent (mSats)</th>
-                    <th>Total Requests</th>
-                    <th>Refund Address</th>
-                    <th>Refund Time</th>
-                </tr>
-                {"".join(api_keys_table_rows)}
-            </table>
-        </body>
-    </html>
-    """
-
-
-@admin_router.get("/", response_class=HTMLResponse)
-async def admin(request: Request) -> str:
-    admin_cookie = request.cookies.get("admin_password")
-    if admin_cookie and admin_cookie == os.getenv("ADMIN_PASSWORD"):
-        return await dashboard(request)
-    return admin_auth()

router/cashu.py

@@ -1,536 +0,0 @@
-import asyncio
-import os
-import time
-from typing import cast
-
-from sixty_nuts import Wallet
-from sixty_nuts.types import CurrencyUnit
-from sqlmodel import col, func, select, update
-
-from .db import ApiKey, AsyncSession, get_session
-from .logging.logging_config import get_logger
-
-logger = get_logger(__name__)
-
-RECEIVE_LN_ADDRESS = os.environ["RECEIVE_LN_ADDRESS"]
-MINT = os.environ.get("MINT", "https://mint.minibits.cash/Bitcoin")
-MINIMUM_PAYOUT = int(os.environ.get("MINIMUM_PAYOUT", 100))
-REFUND_PROCESSING_INTERVAL = int(os.environ.get("REFUND_PROCESSING_INTERVAL", 3600))
-PAYOUT_INTERVAL = int(os.environ.get("PAYOUT_INTERVAL", 300))  # Default 5 minutes
-DEV_LN_ADDRESS = "routstr@minibits.cash"
-DEVS_DONATION_RATE = float(os.environ.get("DEVS_DONATION_RATE", 0.021))  # 2.1%
-NSEC = os.environ["NSEC"]  # Nostr private key for the wallet
-
-logger.info(
-    "Cashu module initialized",
-    extra={
-        "mint": MINT,
-        "minimum_payout": MINIMUM_PAYOUT,
-        "refund_processing_interval": REFUND_PROCESSING_INTERVAL,
-        "payout_interval": PAYOUT_INTERVAL,
-        "devs_donation_rate": DEVS_DONATION_RATE,
-    },
-)
-
-wallet_instance: Wallet | None = None
-
-
-async def init_wallet() -> None:
-    """Initialize the Cashu wallet."""
-    global wallet_instance
-    try:
-        logger.info("Initializing Cashu wallet", extra={"mint": MINT})
-        wallet_instance = await Wallet.create(nsec=NSEC)
-        logger.info("Cashu wallet initialized successfully")
-    except Exception as e:
-        logger.error(
-            "Failed to initialize Cashu wallet",
-            extra={"error": str(e), "error_type": type(e).__name__, "mint": MINT},
-        )
-        raise
-
-
-def wallet() -> Wallet:
-    """Get the wallet instance."""
-    global wallet_instance
-    if wallet_instance is None:
-        logger.error("Wallet not initialized - call init_wallet() first")
-        raise ValueError("Wallet not initialized")
-    return wallet_instance
-
-
-async def delete_key_if_zero_balance(key: ApiKey, session: AsyncSession) -> None:
-    """Delete the given API key if its balance is zero."""
-    if key.balance == 0:
-        logger.info(
-            "Deleting API key with zero balance",
-            extra={"key_hash": key.hashed_key[:8] + "...", "balance": key.balance},
-        )
-        await session.delete(key)
-        await session.commit()
-
-
-async def pay_out() -> None:
-    """
-    Calculates the pay-out amount based on the spent balance, profit, and donation rate.
-    """
-    try:
-        logger.debug("Starting payout process")
-        from .db import create_session
-
-        async with create_session() as session:
-            result = await session.exec(
-                select(func.sum(col(ApiKey.balance))).where(ApiKey.balance > 0)
-            )
-            balance = result.one_or_none()
-            if not balance:
-                logger.debug("No balance to pay out")
-                return
-
-            user_balance_sats = balance // 1000
-            wallet_balance_sats = await wallet().get_balance()
-
-            logger.debug(
-                "Payout calculation",
-                extra={
-                    "user_balance_sats": user_balance_sats,
-                    "wallet_balance_sats": wallet_balance_sats,
-                },
-            )
-
-            # Handle edge cases more gracefully
-            if wallet_balance_sats < user_balance_sats:
-                logger.warning(
-                    "Insufficient wallet balance for payout",
-                    extra={
-                        "wallet_balance_sats": wallet_balance_sats,
-                        "user_balance_sats": user_balance_sats,
-                        "shortfall_sats": user_balance_sats - wallet_balance_sats,
-                    },
-                )
-                return
-
-            if (revenue := wallet_balance_sats - user_balance_sats) <= MINIMUM_PAYOUT:
-                logger.debug(
-                    "Revenue below minimum payout threshold",
-                    extra={"revenue_sats": revenue, "minimum_payout": MINIMUM_PAYOUT},
-                )
-                return
-
-            devs_donation = int(revenue * DEVS_DONATION_RATE)
-            owners_draw = revenue - devs_donation
-
-            logger.info(
-                "Processing payout",
-                extra={
-                    "revenue_sats": revenue,
-                    "devs_donation_sats": devs_donation,
-                    "owners_draw_sats": owners_draw,
-                    "donation_rate": DEVS_DONATION_RATE,
-                },
-            )
-
-            # Send payouts
-            try:
-                await wallet().send_to_lnurl(RECEIVE_LN_ADDRESS, owners_draw)
-                logger.info(
-                    "Owner payout sent successfully",
-                    extra={
-                        "amount_sats": owners_draw,
-                        "address": RECEIVE_LN_ADDRESS[:10] + "...",
-                    },
-                )
-
-                await wallet().send_to_lnurl(DEV_LN_ADDRESS, devs_donation)
-                logger.info(
-                    "Developer donation sent successfully",
-                    extra={"amount_sats": devs_donation, "address": DEV_LN_ADDRESS},
-                )
-            except Exception as payout_error:
-                logger.error(
-                    "Failed to send payouts",
-                    extra={
-                        "error": str(payout_error),
-                        "error_type": type(payout_error).__name__,
-                        "owners_draw_sats": owners_draw,
-                        "devs_donation_sats": devs_donation,
-                    },
-                )
-                raise
-
-    except Exception as e:
-        logger.error(
-            "Error in payout process",
-            extra={"error": str(e), "error_type": type(e).__name__},
-        )
-
-
-# Periodic payout task
-async def periodic_payout() -> None:
-    """Periodically process payouts."""
-    logger.info("Starting periodic payout task", extra={"interval_seconds": 300})
-    while True:
-        try:
-            await asyncio.sleep(300)  # Run every 5 minutes
-            await pay_out()
-        except asyncio.CancelledError:
-            logger.info("Periodic payout task cancelled")
-            break
-        except Exception as e:
-            logger.error(
-                "Error in periodic payout",
-                extra={"error": str(e), "error_type": type(e).__name__},
-            )
-            # Continue running even if payout fails
-
-
-async def credit_balance(cashu_token: str, key: ApiKey, session: AsyncSession) -> int:
-    """Redeem a Cashu token and credit the amount to the API key balance."""
-    logger.debug(
-        "Starting token redemption",
-        extra={
-            "key_hash": key.hashed_key[:8] + "...",
-            "token_preview": cashu_token[:20] + "..."
-            if len(cashu_token) > 20
-            else cashu_token,
-        },
-    )
-
-    try:
-        amount, unit = await wallet().redeem(cashu_token)
-        logger.info(
-            "Token redeemed successfully",
-            extra={
-                "amount": amount,
-                "unit": unit,
-                "key_hash": key.hashed_key[:8] + "...",
-            },
-        )
-    except Exception as e:
-        logger.error(
-            "Token redemption failed",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "key_hash": key.hashed_key[:8] + "...",
-                "token_preview": cashu_token[:20] + "..."
-                if len(cashu_token) > 20
-                else cashu_token,
-            },
-        )
-        return 0
-
-    if amount <= 0:
-        logger.warning(
-            "Zero or negative amount redeemed",
-            extra={
-                "amount": amount,
-                "unit": unit,
-                "key_hash": key.hashed_key[:8] + "...",
-            },
-        )
-        return 0
-
-    if unit == "msat":
-        amount_msats = amount
-    else:
-        amount_msats = amount * 1000
-
-    logger.debug(
-        "Crediting balance",
-        extra={
-            "amount_msats": amount_msats,
-            "original_amount": amount,
-            "unit": unit,
-            "key_hash": key.hashed_key[:8] + "...",
-        },
-    )
-
-    # Apply the balance change atomically to avoid race conditions when topping
-    # up the same key concurrently.
-    stmt = (
-        update(ApiKey)
-        .where(col(ApiKey.hashed_key) == key.hashed_key)
-        .values(balance=col(ApiKey.balance) + amount_msats)
-    )
-    await session.exec(stmt)  # type: ignore[call-overload]
-    await session.commit()
-    await session.refresh(key)
-
-    logger.info(
-        "Balance credited successfully",
-        extra={
-            "credited_msats": amount_msats,
-            "new_balance_msats": key.balance,
-            "key_hash": key.hashed_key[:8] + "...",
-        },
-    )
-
-    return amount_msats
-
-
-async def check_for_refunds() -> None:
-    """
-    Periodically checks for API keys that are eligible for refunds and processes them.
-
-    Raises:
-        Exception: If an error occurs during the refund check process.
-    """
-    # Setting REFUND_PROCESSING_INTERVAL to 0 disables it
-    if REFUND_PROCESSING_INTERVAL == 0:
-        logger.info("Automatic refund processing is disabled")
-        return
-
-    logger.info(
-        "Starting refund monitoring task",
-        extra={"interval_seconds": REFUND_PROCESSING_INTERVAL},
-    )
-
-    while True:
-        try:
-            logger.debug("Checking for expired keys requiring refunds")
-            async for session in get_session():
-                result = await session.exec(select(ApiKey))
-                keys = result.all()
-                current_time = int(time.time())
-
-                expired_keys = []
-                for key in keys:
-                    if (
-                        key.balance > 0
-                        and key.refund_address
-                        and key.key_expiry_time
-                        and key.key_expiry_time < current_time
-                    ):
-                        expired_keys.append(key)
-
-                if expired_keys:
-                    logger.info(
-                        "Found expired keys for refund",
-                        extra={
-                            "expired_count": len(expired_keys),
-                            "current_time": current_time,
-                        },
-                    )
-
-                for key in expired_keys:
-                    logger.info(
-                        "Processing refund for expired key",
-                        extra={
-                            "key_hash": key.hashed_key[:8] + "...",
-                            "balance_msats": key.balance,
-                            "expiry_time": key.key_expiry_time,
-                            "current_time": current_time,
-                            "expired_seconds": current_time
-                            - (key.key_expiry_time or 0),
-                        },
-                    )
-
-                    try:
-                        await refund_balance(key.balance, key, session)
-                        await delete_key_if_zero_balance(key, session)
-                        logger.info(
-                            "Refund processed successfully",
-                            extra={"key_hash": key.hashed_key[:8] + "..."},
-                        )
-                    except Exception as refund_error:
-                        logger.error(
-                            "Failed to process refund",
-                            extra={
-                                "error": str(refund_error),
-                                "error_type": type(refund_error).__name__,
-                                "key_hash": key.hashed_key[:8] + "...",
-                                "balance_msats": key.balance,
-                            },
-                        )
-
-            # Sleep for the specified interval before checking again
-            await asyncio.sleep(REFUND_PROCESSING_INTERVAL)
-        except asyncio.CancelledError:
-            logger.info("Refund monitoring task cancelled")
-            break
-        except Exception as e:
-            logger.error(
-                "Error during refund check",
-                extra={"error": str(e), "error_type": type(e).__name__},
-            )
-
-
-async def refund_balance(amount_msats: int, key: ApiKey, session: AsyncSession) -> int:
-    """Process a refund for an API key."""
-    if amount_msats <= 0:
-        amount_msats = key.balance
-
-    logger.info(
-        "Processing balance refund",
-        extra={
-            "amount_msats": amount_msats,
-            "key_hash": key.hashed_key[:8] + "...",
-            "refund_address": key.refund_address[:20] + "..."
-            if key.refund_address and len(key.refund_address) > 20
-            else key.refund_address,
-        },
-    )
-
-    # Convert msats to sats for cashu wallet
-    amount_sats = amount_msats // 1000
-    if amount_sats == 0:
-        logger.error(
-            "Amount too small to refund",
-            extra={
-                "amount_msats": amount_msats,
-                "amount_sats": amount_sats,
-                "key_hash": key.hashed_key[:8] + "...",
-            },
-        )
-        raise ValueError("Amount too small to refund (less than 1 sat)")
-
-    # Atomically deduct the balance to avoid race conditions when multiple
-    # refunds are triggered concurrently.
-    stmt = (
-        update(ApiKey)
-        .where(col(ApiKey.hashed_key) == key.hashed_key)
-        .where(col(ApiKey.balance) >= amount_msats)
-        .values(balance=col(ApiKey.balance) - amount_msats)
-    )
-    result = await session.exec(stmt)  # type: ignore[call-overload]
-    await session.commit()
-
-    if result.rowcount == 0:
-        logger.error(
-            "Insufficient balance for refund",
-            extra={
-                "requested_msats": amount_msats,
-                "key_hash": key.hashed_key[:8] + "...",
-                "current_balance": key.balance,
-            },
-        )
-        raise ValueError("Insufficient balance.")
-
-    await session.refresh(key)
-    await delete_key_if_zero_balance(key, session)
-
-    if key.refund_address is None:
-        logger.error(
-            "Refund address not set", extra={"key_hash": key.hashed_key[:8] + "..."}
-        )
-        raise ValueError("Refund address not set.")
-
-    try:
-        result = await wallet().send_to_lnurl(key.refund_address, amount=amount_sats)
-        logger.info(
-            "Refund sent successfully",
-            extra={
-                "amount_sats": amount_sats,
-                "refund_address": key.refund_address[:20] + "..."
-                if len(key.refund_address) > 20
-                else key.refund_address,
-                "key_hash": key.hashed_key[:8] + "...",
-                "transaction_result": str(result),
-            },
-        )
-        return result
-    except Exception as e:
-        logger.error(
-            "Failed to send refund",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "amount_sats": amount_sats,
-                "refund_address": key.refund_address,
-                "key_hash": key.hashed_key[:8] + "...",
-            },
-        )
-        raise
-
-
-async def x_cashu_refund(key: ApiKey, session: AsyncSession, unit: CurrencyUnit) -> str:
-    """Process an X-Cashu refund token."""
-    logger.info(
-        "Processing X-Cashu refund",
-        extra={
-            "balance_msats": key.balance,
-            "unit": unit,
-            "key_hash": key.hashed_key[:8] + "...",
-        },
-    )
-
-    try:
-        refund_token = await wallet().send(key.balance, unit=unit)
-        logger.info(
-            "X-Cashu refund token created",
-            extra={
-                "amount": key.balance,
-                "unit": unit,
-                "key_hash": key.hashed_key[:8] + "...",
-                "token_preview": refund_token[:20] + "..."
-                if len(refund_token) > 20
-                else refund_token,
-            },
-        )
-
-        await session.delete(key)
-        await session.commit()
-
-        logger.info(
-            "X-Cashu refund completed", extra={"key_hash": key.hashed_key[:8] + "..."}
-        )
-
-        return refund_token
-    except Exception as e:
-        logger.error(
-            "Failed to create X-Cashu refund",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "balance": key.balance,
-                "unit": unit,
-                "key_hash": key.hashed_key[:8] + "...",
-            },
-        )
-        raise
-
-
-async def redeem(cashu_token: str, lnurl: str) -> int:
-    """Redeem a Cashu token and send to LNURL."""
-    logger.info(
-        "Starting token redemption for LNURL",
-        extra={
-            "token_preview": cashu_token[:20] + "..."
-            if len(cashu_token) > 20
-            else cashu_token,
-            "lnurl_preview": lnurl[:20] + "..." if len(lnurl) > 20 else lnurl,
-        },
-    )
-
-    try:
-        amount, unit = await wallet().redeem(cashu_token)
-        logger.info("Token redeemed for LNURL", extra={"amount": amount, "unit": unit})
-
-        unit = cast(CurrencyUnit, unit)
-        result = await wallet().send_to_lnurl(lnurl, amount=amount, unit=unit)
-
-        logger.info(
-            "Successfully sent to LNURL",
-            extra={
-                "amount": amount,
-                "unit": unit,
-                "lnurl_preview": lnurl[:20] + "..." if len(lnurl) > 20 else lnurl,
-                "transaction_result": str(result),
-            },
-        )
-
-        return amount
-    except Exception as e:
-        logger.error(
-            "Failed to redeem and send to LNURL",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "token_preview": cashu_token[:20] + "..."
-                if len(cashu_token) > 20
-                else cashu_token,
-                "lnurl_preview": lnurl[:20] + "..." if len(lnurl) > 20 else lnurl,
-            },
-        )
-        raise

router/db.py

@@ -1,48 +0,0 @@
-import os
-from contextlib import asynccontextmanager
-from typing import AsyncGenerator
-
-from sqlalchemy.ext.asyncio.engine import create_async_engine
-from sqlmodel import Field, SQLModel
-from sqlmodel.ext.asyncio.session import AsyncSession
-
-DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite+aiosqlite:///keys.db")
-
-
-engine = create_async_engine(DATABASE_URL, echo=False)  # echo=True for debugging SQL
-
-
-class ApiKey(SQLModel, table=True):  # type: ignore
-    __tablename__ = "api_keys"
-
-    hashed_key: str = Field(primary_key=True)
-    balance: int = Field(default=0, description="Balance in millisatoshis (msats)")
-    refund_address: str | None = Field(
-        default=None,
-        description="Lightning address to refund remaining balance after key expires",
-    )
-    key_expiry_time: int | None = Field(
-        default=None,
-        description="Unix-timestamp after which the cashu-token's balance gets refunded to the refund_address",
-    )
-    total_spent: int = Field(
-        default=0, description="Total spent in millisatoshis (msats)"
-    )
-    total_requests: int = Field(default=0)
-
-
-async def init_db() -> None:
-    """Initializes the database and creates tables if they don't exist."""
-    async with engine.begin() as conn:
-        await conn.run_sync(SQLModel.metadata.create_all)
-
-
-async def get_session() -> AsyncGenerator[AsyncSession, None]:
-    async with AsyncSession(engine, expire_on_commit=False) as session:
-        yield session
-
-
-@asynccontextmanager
-async def create_session() -> AsyncGenerator[AsyncSession, None]:
-    async with AsyncSession(engine, expire_on_commit=False) as session:
-        yield session

router/discovery.py

@@ -1,207 +0,0 @@
-import asyncio
-import json
-import os
-import random
-import re
-import string
-
-import httpx
-import websockets
-from fastapi import APIRouter
-
-providers_router = APIRouter(prefix="/v1/providers")
-
-
-def generate_subscription_id() -> str:
-    """Generate a random subscription ID."""
-    return "".join(random.choices(string.ascii_lowercase + string.digits, k=10))
-
-
-def extract_onion_urls(content: str) -> list[str]:
-    """Extract onion URLs from content."""
-    pattern = r"http?://[a-zA-Z0-9\-._~]+\.onion"
-    return re.findall(pattern, content)
-
-
-async def query_nostr_relay_with_search(
-    search_term: str,
-    relay_url: str,
-    kinds: list[int] | None = None,
-    limit: int = 1000,
-    timeout: int = 30,
-) -> list[dict]:
-    """
-    Query a Nostr relay and filter for events containing a search term.
-    """
-    if kinds is None:
-        kinds = [1]
-
-    events = []
-
-    # If searching for an npub mention, try tag-based search first
-    if search_term.startswith("nostr:npub"):
-        # Extract the npub and convert to hex
-        npub = search_term.replace("nostr:", "")
-        try:
-            # Convert npub to hex (you might need to implement or import this)
-            # For now, try tag-based search with the npub
-            filter_obj = {
-                "kinds": kinds,
-                "limit": limit,
-                "#p": [npub],  # Posts that tag this pubkey
-            }
-        except Exception:
-            # If conversion fails, try regular search
-            filter_obj = {
-                "kinds": kinds,
-                "limit": limit,
-            }
-    else:
-        # Try relay's search functionality (NIP-50)
-        filter_obj = {
-            "kinds": kinds,
-            "search": search_term,
-            "limit": limit,
-        }
-
-    sub_id = generate_subscription_id()
-    req_message = json.dumps(["REQ", sub_id, filter_obj])
-
-    try:
-        async with websockets.connect(relay_url, timeout=timeout) as websocket:
-            print(f"Connected to relay, sending request with filter: {filter_obj}")
-            await websocket.send(req_message)
-
-            while True:
-                try:
-                    message = await asyncio.wait_for(websocket.recv(), timeout=5)
-                    data = json.loads(message)
-
-                    if data[0] == "EVENT" and data[1] == sub_id:
-                        # For tag-based search, also check content
-                        if search_term.startswith("nostr:npub"):
-                            if search_term.lower() in data[2]["content"].lower():
-                                print(f"Found matching event: {data[2]['id']}")
-                                events.append(data[2])
-                        else:
-                            print(f"Found matching event: {data[2]['id']}")
-                            events.append(data[2])
-                    elif data[0] == "EOSE" and data[1] == sub_id:
-                        print("Received EOSE message")
-                        break
-                    elif data[0] == "NOTICE":
-                        print(f"Relay notice: {data[1]}")
-                        # If search not supported, could break and try different approach
-                        if "unrecognised filter item" in data[1] and "search" in str(
-                            filter_obj
-                        ):
-                            print("Search not supported on this relay")
-                            break
-
-                except asyncio.TimeoutError:
-                    print("Timeout waiting for message")
-                    break
-                except json.JSONDecodeError:
-                    print("Failed to decode message as JSON")
-                    continue
-
-            await websocket.send(json.dumps(["CLOSE", sub_id]))
-
-    except Exception as e:
-        print(f"Query failed: {e}")
-
-    print(f"Query complete. Found {len(events)} matching events")
-    return events
-
-
-async def get_cache() -> list[dict]:
-    return []  # TODO: Implement cache
-
-
-async def fetch_onion(provider: str) -> dict:
-    """Check if an onion service is healthy by making a GET request to its root."""
-    try:
-        # Get Tor proxy URL from environment variable, default to local Tor SOCKS5 proxy
-        tor_proxy = os.getenv("TOR_PROXY_URL", "socks5://127.0.0.1:9050")
-
-        # Configure httpx to use Tor SOCKS5 proxy
-        async with httpx.AsyncClient(
-            proxies={"http://": tor_proxy, "https://": tor_proxy},  # type: ignore
-            timeout=httpx.Timeout(30.0),
-            follow_redirects=True,
-        ) as client:
-            response = await client.get(provider)
-            # Consider 2xx and 3xx status codes as healthy
-            return {"status_code": response.status_code, "json": response.json()}
-    except Exception:
-        # Any exception means the service is not healthy
-        return {"status_code": 500, "json": {"error": "Failed to fetch onion"}}
-
-
-@providers_router.get("/")
-async def get_providers(include_json: bool = False) -> dict[str, list[dict | str]]:
-    npub = "npub130mznv74rxs032peqym6g3wqavh472623mt3z5w73xq9r6qqdufs7ql29s"
-
-    # Relays that support NIP-50 text search
-    search_relays = [
-        "wss://relay.nostr.band",  # Known to support search
-        "wss://nostr.wine",  # Known to support search
-        "wss://relay.damus.io",
-        "wss://nos.lol",
-    ]
-
-    # Search for the mention format that appears in posts
-    search_term = f"nostr:{npub}"
-
-    all_events = []
-    event_ids = set()  # To avoid duplicates
-
-    # Try multiple relays
-    for relay_url in search_relays:
-        print(f"\nTrying relay: {relay_url}")
-        try:
-            events = await query_nostr_relay_with_search(
-                search_term=search_term,
-                relay_url=relay_url,
-                kinds=[1],  # Text notes
-                limit=500,
-            )
-
-            # Add unique events
-            for event in events:
-                if event["id"] not in event_ids:
-                    event_ids.add(event["id"])
-                    all_events.append(event)
-
-            print(f"Got {len(events)} events from {relay_url}")
-
-            # If we have enough events, we can stop
-            if len(all_events) >= 100:
-                break
-
-        except Exception as e:
-            print(f"Failed to query {relay_url}: {e}")
-            continue
-
-    print(f"Found {len(all_events)} total unique events mentioning routstr")
-
-    providers = []
-    for event in all_events:
-        onion_urls = extract_onion_urls(event["content"])
-        providers.extend(onion_urls)
-
-    unique_providers = list(set(providers))
-
-    print(f"Found {len(unique_providers)} unique onion URLs")
-    print(unique_providers)
-
-    healthy_providers: list[dict | str] = []
-    for provider in unique_providers:
-        response = await fetch_onion(provider)
-
-        if include_json:
-            healthy_providers.append({provider: response["json"]})
-        else:
-            healthy_providers.append(provider)
-
-    return {"providers": healthy_providers}

router/main.py

@@ -1,119 +0,0 @@
-import asyncio
-import os
-from contextlib import asynccontextmanager
-from typing import AsyncGenerator
-
-from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-
-from .account import wallet_router
-from .admin import admin_router
-from .cashu import check_for_refunds, init_wallet, periodic_payout
-from .db import init_db
-from .discovery import providers_router
-from .logging.logging_config import get_logger, setup_logging
-from .models import MODELS, models_router, update_sats_pricing
-from .proxy import proxy_router
-
-# Initialize logging first
-setup_logging()
-logger = get_logger(__name__)
-
-__version__ = "0.0.1"
-
-
-@asynccontextmanager
-async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
-    logger.info("Application startup initiated", extra={"version": __version__})
-
-    try:
-        await init_db()
-        logger.info("Database initialized successfully")
-
-        await init_wallet()
-        logger.info("Wallet initialized successfully")
-
-        pricing_task = asyncio.create_task(update_sats_pricing())
-        refund_task = asyncio.create_task(check_for_refunds())
-        payout_task = asyncio.create_task(periodic_payout())
-
-        logger.info(
-            "Background tasks started successfully",
-            extra={"tasks": ["pricing", "refunds", "payouts"]},
-        )
-
-        yield
-
-    except Exception as e:
-        logger.error(
-            "Application startup failed",
-            extra={"error": str(e), "error_type": type(e).__name__},
-        )
-        raise
-    finally:
-        logger.info("Application shutdown initiated")
-
-        refund_task.cancel()
-        pricing_task.cancel()
-        payout_task.cancel()
-
-        try:
-            await asyncio.gather(
-                pricing_task, refund_task, payout_task, return_exceptions=True
-            )
-            logger.info("Background tasks stopped successfully")
-        except Exception as e:
-            logger.error(
-                "Error stopping background tasks",
-                extra={"error": str(e), "error_type": type(e).__name__},
-            )
-
-
-app = FastAPI(
-    version=__version__,
-    title=os.environ.get("NAME", "ARoutstrNode" + __version__),
-    description=os.environ.get("DESCRIPTION", "A Routstr Node"),
-    contact={"name": os.environ.get("NAME", ""), "npub": os.environ.get("NPUB", "")},
-    lifespan=lifespan,
-)
-
-# Configure CORS
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=os.environ.get("CORS_ORIGINS", "*").split(","),
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-logger.info(
-    "CORS middleware configured",
-    extra={"allowed_origins": os.environ.get("CORS_ORIGINS", "*").split(",")},
-)
-
-
-@app.get("/")
-async def info() -> dict:
-    logger.info("Info endpoint accessed")
-    return {
-        "name": app.title,
-        "description": app.description,
-        "version": __version__,
-        "npub": os.environ.get("NPUB", ""),
-        "mint": os.environ.get("MINT", ""),
-        "http_url": os.environ.get("HTTP_URL", ""),
-        "onion_url": os.environ.get("ONION_URL", ""),
-        "models": MODELS,
-    }
-
-
-app.include_router(models_router)
-app.include_router(admin_router)
-app.include_router(wallet_router)
-app.include_router(providers_router)
-app.include_router(proxy_router)
-
-logger.info(
-    "Application initialized successfully",
-    extra={"version": __version__, "routers_count": 5},
-)

router/models.py

@@ -1,150 +0,0 @@
-import asyncio
-import json
-import os
-from pathlib import Path
-
-from fastapi import APIRouter
-from pydantic.v1 import BaseModel
-
-from .price import sats_usd_ask_price
-
-models_router = APIRouter()
-
-
-class Architecture(BaseModel):
-    modality: str
-    input_modalities: list[str]
-    output_modalities: list[str]
-    tokenizer: str
-    instruct_type: str | None
-
-
-class Pricing(BaseModel):
-    prompt: float
-    completion: float
-    request: float
-    image: float
-    web_search: float
-    internal_reasoning: float
-    max_cost: float = 0.0  # in sats not msats
-
-
-class TopProvider(BaseModel):
-    context_length: int | None = None
-    max_completion_tokens: int | None = None
-    is_moderated: bool | None = None
-
-
-class Model(BaseModel):
-    id: str
-    name: str
-    created: int
-    description: str
-    context_length: int
-    architecture: Architecture
-    pricing: Pricing
-    sats_pricing: Pricing | None = None
-    per_request_limits: dict | None = None
-    top_provider: TopProvider | None = None
-
-
-MODELS: list[Model] = []
-
-
-def load_models() -> list[Model]:
-    """Load model definitions from a JSON file.
-
-    The file path can be specified via the ``MODELS_PATH`` environment variable.
-    If ``models.json`` is not found, the bundled ``models.example.json`` is used
-    as a fallback. If neither file exists or an error occurs while loading, an
-    empty list is returned.
-    """
-
-    models_path = Path(os.environ.get("MODELS_PATH", "models.json"))
-    if not models_path.exists():
-        example = Path(__file__).resolve().parent.parent / "models.example.json"
-        if example.exists():
-            models_path = example
-        else:
-            return []
-
-    try:
-        with models_path.open("r") as f:
-            data = json.load(f)
-    except Exception as e:  # pragma: no cover - log and continue
-        print(f"Error loading models from {models_path}: {e}")
-        return []
-
-    return [Model(**model) for model in data.get("models", [])]
-
-
-MODELS = load_models()
-
-
-async def update_sats_pricing() -> None:
-    while True:
-        try:
-            sats_to_usd = await sats_usd_ask_price()
-            for model in MODELS:
-                model.sats_pricing = Pricing(
-                    **{k: v / sats_to_usd for k, v in model.pricing.dict().items()}
-                )
-                if model.top_provider:
-                    if (
-                        model.top_provider.context_length
-                        and model.top_provider.max_completion_tokens
-                    ):
-                        max_context_cost = (
-                            model.top_provider.context_length
-                            * model.sats_pricing.prompt
-                        )
-                        max_completion_cost = (
-                            model.top_provider.max_completion_tokens
-                            * model.sats_pricing.completion
-                        )
-                        model.sats_pricing.max_cost = (
-                            max_context_cost + max_completion_cost
-                        )
-                    elif model.top_provider.context_length:
-                        max_context_cost = (
-                            model.top_provider.context_length
-                            * model.sats_pricing.prompt
-                        )
-                        max_completion_cost = 32_000 * model.sats_pricing.completion
-                        model.sats_pricing.max_cost = (
-                            max_context_cost + max_completion_cost
-                        )
-                    elif model.top_provider.max_completion_tokens:
-                        max_completion_cost = (
-                            model.top_provider.max_completion_tokens
-                            * model.sats_pricing.completion
-                        )
-                        max_context_cost = 1_048_576 * model.sats_pricing.prompt
-                        model.sats_pricing.max_cost = max_completion_cost
-                    else:
-                        model.sats_pricing.max_cost = (
-                            1_048_576 * model.sats_pricing.prompt
-                            + 32_000 * model.sats_pricing.completion
-                        )
-                else:
-                    p = model.sats_pricing.prompt * 1_000_000
-                    c = model.sats_pricing.completion * 32_000
-                    r = model.sats_pricing.request * 100_000
-                    i = model.sats_pricing.image * 100
-                    w = model.sats_pricing.web_search * 1000
-                    ir = model.sats_pricing.internal_reasoning * 100
-                    model.sats_pricing.max_cost = p + c + r + i + w + ir
-        except asyncio.CancelledError:
-            break
-        except Exception as e:
-            print("Error updating sats pricing: ", e)
-        try:
-            await asyncio.sleep(10)
-        except asyncio.CancelledError:
-            break
-
-
-@models_router.get("/models")
-@models_router.get("/v1/models")
-async def models() -> dict:
-    return {"data": MODELS}

router/payment/cost_caculation.py

@@ -1,169 +0,0 @@
-import os
-
-from pydantic import BaseModel
-
-from router.logging.logging_config import get_logger
-from router.models import MODELS
-
-logger = get_logger(__name__)
-
-COST_PER_REQUEST = (
-    int(os.environ.get("COST_PER_REQUEST", "1")) * 1000
-)  # Convert to msats
-COST_PER_1K_INPUT_TOKENS = (
-    int(os.environ.get("COST_PER_1K_INPUT_TOKENS", "0")) * 1000
-)  # Convert to msats
-COST_PER_1K_OUTPUT_TOKENS = (
-    int(os.environ.get("COST_PER_1K_OUTPUT_TOKENS", "0")) * 1000
-)  # Convert to msats
-MODEL_BASED_PRICING = os.environ.get("MODEL_BASED_PRICING", "false").lower() == "true"
-
-logger.info(
-    "Cost calculation initialized",
-    extra={
-        "cost_per_request_msats": COST_PER_REQUEST,
-        "cost_per_1k_input_tokens_msats": COST_PER_1K_INPUT_TOKENS,
-        "cost_per_1k_output_tokens_msats": COST_PER_1K_OUTPUT_TOKENS,
-        "model_based_pricing": MODEL_BASED_PRICING,
-    },
-)
-
-
-class CostData(BaseModel):
-    base_msats: int
-    input_msats: int
-    output_msats: int
-    total_msats: int
-
-
-class MaxCostData(CostData):
-    pass
-
-
-class CostDataError(BaseModel):
-    message: str
-    code: str
-
-
-def calculate_cost(
-    response_data: dict, max_cost: int
-) -> CostData | MaxCostData | CostDataError:
-    """
-    Calculate the cost of an API request based on token usage.
-
-    Args:
-        response_data: Response data containing usage information
-        max_cost: Maximum cost in millisats
-
-    Returns:
-        Cost data or error information
-    """
-    logger.debug(
-        "Starting cost calculation",
-        extra={
-            "max_cost_msats": max_cost,
-            "has_usage_data": "usage" in response_data,
-            "response_model": response_data.get("model", "unknown"),
-        },
-    )
-
-    cost_data = MaxCostData(
-        base_msats=max_cost,
-        input_msats=0,
-        output_msats=0,
-        total_msats=max_cost,
-    )
-
-    if "usage" not in response_data or response_data["usage"] is None:
-        logger.warning(
-            "No usage data in response, using base cost only",
-            extra={
-                "max_cost_msats": max_cost,
-                "model": response_data.get("model", "unknown"),
-            },
-        )
-        return cost_data
-
-    MSATS_PER_1K_INPUT_TOKENS = COST_PER_1K_INPUT_TOKENS
-    MSATS_PER_1K_OUTPUT_TOKENS = COST_PER_1K_OUTPUT_TOKENS
-
-    if MODEL_BASED_PRICING and MODELS:
-        response_model = response_data.get("model", "")
-        logger.debug(
-            "Using model-based pricing",
-            extra={
-                "model": response_model,
-                "available_models": [model.id for model in MODELS],
-            },
-        )
-
-        if response_model not in [model.id for model in MODELS]:
-            logger.error(
-                "Invalid model in response",
-                extra={
-                    "response_model": response_model,
-                    "available_models": [model.id for model in MODELS],
-                },
-            )
-            return CostDataError(
-                message=f"Invalid model in response: {response_model}",
-                code="model_not_found",
-            )
-
-        model = next(model for model in MODELS if model.id == response_model)
-        if model.sats_pricing is None:
-            logger.error(
-                "Model pricing not defined",
-                extra={"model": response_model, "model_id": model.id},
-            )
-            return CostDataError(
-                message="Model pricing not defined", code="pricing_not_found"
-            )
-
-        MSATS_PER_1K_INPUT_TOKENS = model.sats_pricing.prompt * 1_000_000  # type: ignore
-        MSATS_PER_1K_OUTPUT_TOKENS = model.sats_pricing.completion * 1_000_000  # type: ignore
-
-        logger.info(
-            "Applied model-specific pricing",
-            extra={
-                "model": response_model,
-                "input_price_msats_per_1k": MSATS_PER_1K_INPUT_TOKENS,
-                "output_price_msats_per_1k": MSATS_PER_1K_OUTPUT_TOKENS,
-            },
-        )
-
-    if not (MSATS_PER_1K_OUTPUT_TOKENS and MSATS_PER_1K_INPUT_TOKENS):
-        logger.warning(
-            "No token pricing configured, using base cost",
-            extra={
-                "base_cost_msats": max_cost,
-                "model": response_data.get("model", "unknown"),
-            },
-        )
-        return cost_data
-
-    input_tokens = response_data.get("usage", {}).get("prompt_tokens", 0)
-    output_tokens = response_data.get("usage", {}).get("completion_tokens", 0)
-
-    input_msats = int(round(input_tokens / 1000 * MSATS_PER_1K_INPUT_TOKENS, 0))
-    output_msats = int(round(output_tokens / 1000 * MSATS_PER_1K_OUTPUT_TOKENS, 0))
-    token_based_cost = int(round(input_msats + output_msats, 0))
-
-    logger.info(
-        "Calculated token-based cost",
-        extra={
-            "input_tokens": input_tokens,
-            "output_tokens": output_tokens,
-            "input_cost_msats": input_msats,
-            "output_cost_msats": output_msats,
-            "total_cost_msats": token_based_cost,
-            "model": response_data.get("model", "unknown"),
-        },
-    )
-
-    return CostData(
-        base_msats=0,
-        input_msats=input_msats,
-        output_msats=output_msats,
-        total_msats=token_based_cost,
-    )

router/payment/helpers.py

@@ -1,385 +0,0 @@
-import base64
-import json
-import os
-
-import cbor2
-from fastapi import HTTPException, Response
-from sixty_nuts.types import CurrencyUnit
-
-from router.logging.logging_config import get_logger
-from router.models import MODELS
-from router.payment.cost_caculation import COST_PER_REQUEST, MODEL_BASED_PRICING
-
-logger = get_logger(__name__)
-
-UPSTREAM_BASE_URL = os.environ["UPSTREAM_BASE_URL"]
-UPSTREAM_API_KEY = os.environ.get("UPSTREAM_API_KEY", "")
-
-logger.info(
-    "Payment helpers initialized",
-    extra={
-        "upstream_base_url": UPSTREAM_BASE_URL,
-        "has_upstream_api_key": bool(UPSTREAM_API_KEY),
-        "model_based_pricing": MODEL_BASED_PRICING,
-    },
-)
-
-
-def get_cost_per_request(model: str | None = None) -> int:
-    """Get the cost per request for a given model."""
-    logger.debug(
-        "Calculating cost per request",
-        extra={
-            "model": model,
-            "model_based_pricing": MODEL_BASED_PRICING,
-            "has_models": bool(MODELS),
-        },
-    )
-
-    if MODEL_BASED_PRICING and MODELS and model:
-        cost = get_max_cost_for_model(model=model)
-        logger.debug(
-            "Using model-based cost", extra={"model": model, "cost_msats": cost}
-        )
-        return cost
-
-    logger.debug(
-        "Using default cost per request", extra={"cost_msats": COST_PER_REQUEST}
-    )
-    return COST_PER_REQUEST
-
-
-def check_token_balance(headers: dict, body: dict) -> CurrencyUnit:
-    """Check if the provided token has sufficient balance."""
-    logger.debug(
-        "Checking token balance",
-        extra={
-            "has_x_cashu": "x-cashu" in headers,
-            "has_authorization": "authorization" in headers,
-            "model": body.get("model", "unknown"),
-        },
-    )
-
-    if x_cashu := headers.get("x-cashu", None):
-        cashu_token = x_cashu
-        logger.debug(
-            "Using X-Cashu token",
-            extra={
-                "token_preview": cashu_token[:20] + "..."
-                if len(cashu_token) > 20
-                else cashu_token
-            },
-        )
-    elif auth := headers.get("authorization", None):
-        cashu_token = auth.split(" ")[1] if len(auth.split(" ")) > 1 else ""
-        logger.debug(
-            "Using Authorization header token",
-            extra={
-                "token_preview": cashu_token[:20] + "..."
-                if len(cashu_token) > 20
-                else cashu_token
-            },
-        )
-    else:
-        logger.error("No authentication token provided")
-        raise HTTPException(status_code=401, detail="Unauthorized")
-
-    # Handle empty token
-    if not cashu_token:
-        logger.error("Empty token provided")
-        raise HTTPException(
-            status_code=401,
-            detail={
-                "error": {
-                    "message": "API key or Cashu token required",
-                    "type": "invalid_request_error",
-                    "code": "missing_api_key",
-                }
-            },
-        )
-
-    # Handle regular API keys (sk-*)
-    if cashu_token.startswith("sk-"):
-        logger.debug(
-            "Regular API key detected", extra={"key_preview": cashu_token[:10] + "..."}
-        )
-        return "sat"
-
-    cost = get_cost_per_request(model=body.get("model", None))
-
-    if cashu_token.startswith("cashuA"):
-        logger.debug("Processing CashuA token", extra={"required_cost_msats": cost})
-
-        try:
-            _token = base64_token_json(cashu_token)
-            amount = sum(p["amount"] for t in _token["token"] for p in t["proofs"])
-            unit: CurrencyUnit = _token["unit"]
-
-            if unit == "sat":
-                amount *= 1000
-
-            logger.info(
-                "CashuA token parsed successfully",
-                extra={
-                    "amount": amount,
-                    "unit": _token["unit"],
-                    "amount_msats": amount,
-                    "required_cost_msats": cost,
-                    "sufficient_balance": amount >= cost,
-                },
-            )
-
-            if amount < cost:
-                logger.warning(
-                    "Insufficient token balance",
-                    extra={
-                        "amount_msats": amount,
-                        "required_msats": cost,
-                        "shortfall_msats": cost - amount,
-                        "unit": unit,
-                    },
-                )
-                raise HTTPException(status_code=413, detail="Insufficient balance")
-
-        except Exception as e:
-            logger.error(
-                "Failed to parse CashuA token",
-                extra={
-                    "error": str(e),
-                    "error_type": type(e).__name__,
-                    "token_preview": cashu_token[:20] + "...",
-                },
-            )
-            raise HTTPException(status_code=401, detail="Invalid token format")
-
-    elif cashu_token.startswith("cashuB"):
-        logger.debug("Processing CashuB token", extra={"required_cost_msats": cost})
-
-        try:
-            _token = base64_token_cbor(cashu_token)
-            amount = sum(p["a"] for t in _token["t"] for p in t["p"])
-            unit = _token["u"]
-
-            if unit == "sat":
-                amount *= 1000
-
-            logger.info(
-                "CashuB token parsed successfully",
-                extra={
-                    "amount": amount,
-                    "unit": unit,
-                    "amount_msats": amount,
-                    "required_cost_msats": cost,
-                    "sufficient_balance": amount >= cost,
-                },
-            )
-
-            if amount < cost:
-                logger.warning(
-                    "Insufficient token balance",
-                    extra={
-                        "amount_msats": amount,
-                        "required_msats": cost,
-                        "shortfall_msats": cost - amount,
-                        "unit": unit,
-                    },
-                )
-                raise HTTPException(status_code=413, detail="Insufficient balance")
-
-        except Exception as e:
-            logger.error(
-                "Failed to parse CashuB token",
-                extra={
-                    "error": str(e),
-                    "error_type": type(e).__name__,
-                    "token_preview": cashu_token[:20] + "...",
-                },
-            )
-            raise HTTPException(status_code=401, detail="Invalid token format")
-
-    else:
-        logger.error(
-            "Unknown token format",
-            extra={"token_prefix": cashu_token[:10] if cashu_token else "empty"},
-        )
-        raise HTTPException(status_code=401, detail="Unauthorized")
-
-    return unit
-
-
-def base64_token_json(cashu_token: str) -> dict:
-    """Decode a CashuA (JSON) token."""
-    logger.debug("Decoding CashuA token", extra={"token_length": len(cashu_token)})
-
-    try:
-        # Version 3 - JSON format
-        encoded = cashu_token[6:]  # Remove "cashuA"
-        # Add correct padding – (-len) % 4 equals 0,1,2,3
-        encoded += "=" * ((-len(encoded)) % 4)
-
-        decoded = base64.urlsafe_b64decode(encoded).decode()
-        token_data = json.loads(decoded)
-
-        logger.debug(
-            "CashuA token decoded successfully",
-            extra={
-                "token_proofs_count": sum(
-                    len(t.get("proofs", [])) for t in token_data.get("token", [])
-                ),
-                "unit": token_data.get("unit", "unknown"),
-            },
-        )
-
-        return token_data
-    except Exception as e:
-        logger.error(
-            "Failed to decode CashuA token",
-            extra={"error": str(e), "error_type": type(e).__name__},
-        )
-        raise
-
-
-def base64_token_cbor(cashu_token: str) -> dict:
-    """Decode a CashuB (CBOR) token."""
-    logger.debug("Decoding CashuB token", extra={"token_length": len(cashu_token)})
-
-    try:
-        encoded = cashu_token[6:]  # Remove "cashuB"
-        encoded += "=" * ((-len(encoded)) % 4)
-        decoded_bytes = base64.urlsafe_b64decode(encoded)
-        token_data = cbor2.loads(decoded_bytes)
-
-        logger.debug(
-            "CashuB token decoded successfully",
-            extra={
-                "token_proofs_count": sum(
-                    len(t.get("p", [])) for t in token_data.get("t", [])
-                ),
-                "unit": token_data.get("u", "unknown"),
-            },
-        )
-
-        return token_data
-    except Exception as e:
-        logger.error(
-            "Failed to decode CashuB token",
-            extra={"error": str(e), "error_type": type(e).__name__},
-        )
-        raise
-
-
-def get_max_cost_for_model(model: str) -> int:
-    """Get the maximum cost for a specific model."""
-    logger.debug(
-        "Getting max cost for model",
-        extra={
-            "model": model,
-            "model_based_pricing": MODEL_BASED_PRICING,
-            "has_models": bool(MODELS),
-        },
-    )
-
-    if not MODEL_BASED_PRICING or not MODELS:
-        logger.debug(
-            "Using default cost (no model-based pricing)",
-            extra={"cost_msats": COST_PER_REQUEST, "model": model},
-        )
-        return COST_PER_REQUEST
-
-    if model not in [model.id for model in MODELS]:
-        logger.warning(
-            "Model not found in available models",
-            extra={
-                "requested_model": model,
-                "available_models": [m.id for m in MODELS],
-                "using_default_cost": COST_PER_REQUEST,
-            },
-        )
-        return COST_PER_REQUEST
-
-    for m in MODELS:
-        if m.id == model:
-            max_cost = m.sats_pricing.max_cost * 1000  # type: ignore
-            logger.debug(
-                "Found model-specific max cost",
-                extra={"model": model, "max_cost_msats": max_cost},
-            )
-            return int(max_cost)
-
-    logger.warning(
-        "Model pricing not found, using default",
-        extra={"model": model, "default_cost_msats": COST_PER_REQUEST},
-    )
-    return COST_PER_REQUEST
-
-
-def create_error_response(error_type: str, message: str, status_code: int) -> Response:
-    """Create a standardized error response."""
-    logger.info(
-        "Creating error response",
-        extra={
-            "error_type": error_type,
-            "error_message": message,
-            "status_code": status_code,
-        },
-    )
-
-    return Response(
-        content=json.dumps(
-            {
-                "error": {
-                    "message": message,
-                    "type": error_type,
-                    "code": status_code,
-                }
-            }
-        ),
-        status_code=status_code,
-        media_type="application/json",
-    )
-
-
-def prepare_upstream_headers(request_headers: dict) -> dict:
-    """Prepare headers for upstream request, removing sensitive/problematic ones."""
-    logger.debug(
-        "Preparing upstream headers",
-        extra={
-            "original_headers_count": len(request_headers),
-            "has_upstream_api_key": bool(UPSTREAM_API_KEY),
-        },
-    )
-
-    headers = dict(request_headers)
-
-    # Remove headers that shouldn't be forwarded
-    removed_headers = []
-    for header in [
-        "host",
-        "content-length",
-        "refund-lnurl",
-        "key-expiry-time",
-        "x-cashu",
-    ]:
-        if headers.pop(header, None) is not None:
-            removed_headers.append(header)
-
-    # Handle authorization
-    if UPSTREAM_API_KEY:
-        headers["Authorization"] = f"Bearer {UPSTREAM_API_KEY}"
-        if headers.pop("authorization", None) is not None:
-            removed_headers.append("authorization (replaced with upstream key)")
-    else:
-        for auth_header in ["Authorization", "authorization"]:
-            if headers.pop(auth_header, None) is not None:
-                removed_headers.append(auth_header)
-
-    logger.debug(
-        "Headers prepared for upstream",
-        extra={
-            "final_headers_count": len(headers),
-            "removed_headers": removed_headers,
-            "added_upstream_auth": bool(UPSTREAM_API_KEY),
-        },
-    )
-
-    return headers

router/payment/x_cashu.py

@@ -1,617 +0,0 @@
-import json
-import traceback
-from typing import AsyncGenerator, Literal, cast
-
-import httpx
-from fastapi import BackgroundTasks, HTTPException, Request
-from fastapi.responses import Response, StreamingResponse
-from sixty_nuts.types import CurrencyUnit
-
-from router.cashu import wallet
-from router.logging.logging_config import get_logger
-from router.payment.cost_caculation import (
-    CostData,
-    CostDataError,
-    MaxCostData,
-    calculate_cost,
-)
-from router.payment.helpers import (
-    UPSTREAM_BASE_URL,
-    create_error_response,
-    get_max_cost_for_model,
-    prepare_upstream_headers,
-)
-
-logger = get_logger(__name__)
-
-
-async def x_cashu_handler(
-    request: Request, x_cashu_token: str, path: str
-) -> Response | StreamingResponse:
-    """Handle X-Cashu token payment requests."""
-    logger.info(
-        "Processing X-Cashu payment request",
-        extra={
-            "path": path,
-            "method": request.method,
-            "token_preview": x_cashu_token[:20] + "..."
-            if len(x_cashu_token) > 20
-            else x_cashu_token,
-        },
-    )
-
-    try:
-        headers = dict(request.headers)
-        amount, unit = await redeem_token(x_cashu_token)
-        headers = prepare_upstream_headers(dict(request.headers))
-
-        logger.info(
-            "X-Cashu token redeemed successfully",
-            extra={"amount": amount, "unit": unit, "path": path},
-        )
-
-        return await forward_to_upstream(request, path, headers, amount, unit)
-    except Exception as e:
-        logger.error(
-            "X-Cashu payment request failed",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "path": path,
-                "method": request.method,
-            },
-        )
-        raise
-
-
-async def forward_to_upstream(
-    request: Request, path: str, headers: dict, amount: int, unit: CurrencyUnit
-) -> Response | StreamingResponse:
-    """Forward request to upstream and handle the response."""
-    if path.startswith("v1/"):
-        path = path.replace("v1/", "")
-
-    url = f"{UPSTREAM_BASE_URL}/{path}"
-
-    logger.debug(
-        "Forwarding request to upstream",
-        extra={
-            "url": url,
-            "method": request.method,
-            "path": path,
-            "amount": amount,
-            "unit": unit,
-        },
-    )
-
-    async with httpx.AsyncClient(
-        transport=httpx.AsyncHTTPTransport(retries=1),
-        timeout=None,
-    ) as client:
-        try:
-            response = await client.send(
-                client.build_request(
-                    request.method,
-                    url,
-                    headers=headers,
-                    content=request.stream(),
-                    params=request.query_params,
-                ),
-                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.warning(
-                    "Upstream request failed, processing refund",
-                    extra={
-                        "status_code": response.status_code,
-                        "path": path,
-                        "amount": amount,
-                        "unit": unit,
-                    },
-                )
-
-                refund_token = await send_refund(amount - 60, unit)
-
-                logger.info(
-                    "Refund processed for failed upstream request",
-                    extra={
-                        "status_code": response.status_code,
-                        "refund_amount": amount,
-                        "unit": unit,
-                        "refund_token_preview": refund_token[:20] + "..."
-                        if len(refund_token) > 20
-                        else refund_token,
-                    },
-                )
-
-                error_response = Response(
-                    content=json.dumps(
-                        {
-                            "error": {
-                                "message": "Error forwarding request to upstream",
-                                "type": "upstream_error",
-                                "code": response.status_code,
-                                "refund_token": refund_token,
-                            }
-                        }
-                    ),
-                    status_code=response.status_code,
-                    media_type="application/json",
-                )
-                error_response.headers["X-Cashu"] = refund_token
-                return error_response
-
-            if path.endswith("chat/completions"):
-                logger.debug(
-                    "Processing chat completion response",
-                    extra={"path": path, "amount": amount, "unit": unit},
-                )
-
-                result = await handle_x_cashu_chat_completion(response, amount, unit)
-                background_tasks = BackgroundTasks()
-                background_tasks.add_task(response.aclose)
-                result.background = background_tasks
-                return result
-
-            background_tasks = BackgroundTasks()
-            background_tasks.add_task(response.aclose)
-            background_tasks.add_task(client.aclose)
-
-            logger.debug(
-                "Streaming non-chat response",
-                extra={"path": path, "status_code": response.status_code},
-            )
-
-            return StreamingResponse(
-                response.aiter_bytes(),
-                status_code=response.status_code,
-                headers=dict(response.headers),
-                background=background_tasks,
-            )
-        except Exception as exc:
-            tb = traceback.format_exc()
-            logger.error(
-                "Unexpected error in upstream forwarding",
-                extra={
-                    "error": str(exc),
-                    "error_type": type(exc).__name__,
-                    "method": request.method,
-                    "url": url,
-                    "path": path,
-                    "query_params": dict(request.query_params),
-                    "traceback": tb,
-                },
-            )
-            return create_error_response(
-                "internal_error", "An unexpected server error occurred", 500
-            )
-
-
-async def handle_x_cashu_chat_completion(
-    response: httpx.Response, amount: int, unit: CurrencyUnit
-) -> StreamingResponse | Response:
-    """Handle both streaming and non-streaming chat completion responses with token-based pricing."""
-    logger.debug(
-        "Handling chat completion response",
-        extra={"amount": amount, "unit": unit, "status_code": response.status_code},
-    )
-
-    try:
-        content = await response.aread()
-        content_str = content.decode("utf-8") if isinstance(content, bytes) else content
-        is_streaming = content_str.startswith("data:") or "data:" in content_str
-
-        logger.debug(
-            "Chat completion response analysis",
-            extra={
-                "is_streaming": is_streaming,
-                "content_length": len(content_str),
-                "amount": amount,
-                "unit": unit,
-            },
-        )
-
-        if is_streaming:
-            return await handle_streaming_response(content_str, response, amount, unit)
-        else:
-            return await handle_non_streaming_response(
-                content_str, response, amount, unit
-            )
-
-    except Exception as e:
-        logger.error(
-            "Error processing chat completion response",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "amount": amount,
-                "unit": unit,
-            },
-        )
-        # Return the original response if we can't process it
-        return StreamingResponse(
-            response.aiter_bytes(),
-            status_code=response.status_code,
-            headers=dict(response.headers),
-        )
-
-
-async def handle_streaming_response(
-    content_str: str, response: httpx.Response, amount: int, unit: CurrencyUnit
-) -> StreamingResponse:
-    """Handle Server-Sent Events (SSE) streaming response."""
-    logger.debug(
-        "Processing streaming response",
-        extra={
-            "amount": amount,
-            "unit": unit,
-            "content_lines": len(content_str.strip().split("\n")),
-        },
-    )
-
-    # Initialize response headers early so they can be modified during processing
-    response_headers = dict(response.headers)
-    if "transfer-encoding" in response_headers:
-        del response_headers["transfer-encoding"]
-    if "content-encoding" in response_headers:
-        del response_headers["content-encoding"]
-
-    # For streaming responses, we'll extract the final usage data
-    # and calculate cost based on that
-    usage_data = None
-    model = None
-
-    # Parse SSE format to extract usage information
-    lines = content_str.strip().split("\n")
-    for line in lines:
-        if line.startswith("data: "):
-            try:
-                data_json = json.loads(line[6:])  # Remove 'data: ' prefix
-                # Look for usage information in the final chunks
-                if "usage" in data_json:
-                    usage_data = data_json["usage"]
-                    model = data_json.get("model")
-                elif "model" in data_json and not model:
-                    model = data_json["model"]
-            except json.JSONDecodeError:
-                continue
-
-    response_headers = dict(response.headers)
-    # If we found usage data, calculate cost and refund
-    if usage_data and model:
-        logger.debug(
-            "Found usage data in streaming response",
-            extra={
-                "model": model,
-                "usage_data": usage_data,
-                "amount": amount,
-                "unit": unit,
-            },
-        )
-
-        response_data = {"usage": usage_data, "model": model}
-        try:
-            cost_data = await get_cost(response_data)
-            if cost_data:
-                refund_amount = amount - cost_data.total_msats
-                if refund_amount > 0:
-                    logger.info(
-                        "Processing refund for streaming response",
-                        extra={
-                            "original_amount": amount,
-                            "cost_msats": cost_data.total_msats,
-                            "refund_amount": refund_amount,
-                            "unit": unit,
-                            "model": model,
-                        },
-                    )
-
-                    refund_token = await send_refund(refund_amount - 60, unit)
-                    response_headers["X-Cashu"] = refund_token
-
-                    logger.info(
-                        "Refund processed for streaming response",
-                        extra={
-                            "refund_amount": refund_amount,
-                            "unit": unit,
-                            "refund_token_preview": refund_token[:20] + "..."
-                            if len(refund_token) > 20
-                            else refund_token,
-                        },
-                    )
-                else:
-                    logger.debug(
-                        "No refund needed for streaming response",
-                        extra={
-                            "amount": amount,
-                            "cost_msats": cost_data.total_msats,
-                            "model": model,
-                        },
-                    )
-        except Exception as e:
-            logger.error(
-                "Error calculating cost for streaming response",
-                extra={
-                    "error": str(e),
-                    "error_type": type(e).__name__,
-                    "model": model,
-                    "amount": amount,
-                    "unit": unit,
-                },
-            )
-
-    async def generate() -> AsyncGenerator[bytes, None]:
-        for line in lines:
-            yield (line + "\n").encode("utf-8")
-
-    return StreamingResponse(
-        generate(),
-        status_code=response.status_code,
-        headers=response_headers,
-        media_type="text/plain",
-    )
-
-
-async def handle_non_streaming_response(
-    content_str: str, response: httpx.Response, amount: int, unit: CurrencyUnit
-) -> Response:
-    """Handle regular JSON response."""
-    logger.debug(
-        "Processing non-streaming response",
-        extra={"amount": amount, "unit": unit, "content_length": len(content_str)},
-    )
-
-    try:
-        response_json = json.loads(content_str)
-
-        cost_data = await get_cost(response_json)
-
-        if not cost_data:
-            logger.error(
-                "Failed to calculate cost for response",
-                extra={
-                    "amount": amount,
-                    "unit": unit,
-                    "response_model": response_json.get("model", "unknown"),
-                },
-            )
-            return Response(
-                content=json.dumps(
-                    {
-                        "error": {
-                            "message": "Error forwarding request to upstream",
-                            "type": "upstream_error",
-                            "code": response.status_code,
-                        }
-                    }
-                ),
-                status_code=response.status_code,
-                media_type="application/json",
-            )
-
-        response_headers = dict(response.headers)
-        if "transfer-encoding" in response_headers:
-            del response_headers["transfer-encoding"]
-        if "content-encoding" in response_headers:
-            del response_headers["content-encoding"]
-
-        refund_amount = amount - cost_data.total_msats
-
-        logger.info(
-            "Processing non-streaming response cost calculation",
-            extra={
-                "original_amount": amount,
-                "cost_msats": cost_data.total_msats,
-                "refund_amount": refund_amount,
-                "unit": unit,
-                "model": response_json.get("model", "unknown"),
-            },
-        )
-
-        if refund_amount > 0:
-            refund_token = await send_refund(refund_amount - 60, unit)
-            response_headers["X-Cashu"] = refund_token
-
-            logger.info(
-                "Refund processed for non-streaming response",
-                extra={
-                    "refund_amount": refund_amount,
-                    "unit": unit,
-                    "refund_token_preview": refund_token[:20] + "..."
-                    if len(refund_token) > 20
-                    else refund_token,
-                },
-            )
-
-        return Response(
-            content=content_str,
-            status_code=response.status_code,
-            headers=response_headers,
-            media_type="application/json",
-        )
-    except json.JSONDecodeError as e:
-        logger.error(
-            "Failed to parse JSON from upstream response",
-            extra={
-                "error": str(e),
-                "content_preview": content_str[:200] + "..."
-                if len(content_str) > 200
-                else content_str,
-                "amount": amount,
-                "unit": unit,
-            },
-        )
-
-        # Emergency refund with small deduction for processing
-        emergency_refund = amount - 60
-        refund_token = await wallet().send(emergency_refund)
-        response.headers["X-Cashu"] = refund_token
-
-        logger.warning(
-            "Emergency refund issued due to JSON parse error",
-            extra={
-                "original_amount": amount,
-                "refund_amount": emergency_refund,
-                "deduction": 60,
-            },
-        )
-
-        # Return original content if JSON parsing fails
-        return Response(
-            content=content_str,
-            status_code=response.status_code,
-            headers=dict(response.headers),
-            media_type="application/json",
-        )
-
-
-async def get_cost(response_data: dict) -> MaxCostData | CostData | None:
-    """
-    Adjusts the payment based on token usage in the response.
-    This is called after the initial payment and the upstream request is complete.
-    Returns cost data to be included in the response.
-    """
-    model = response_data.get("model", "unknown")
-    logger.debug(
-        "Calculating cost for response",
-        extra={"model": model, "has_usage": "usage" in response_data},
-    )
-
-    max_cost = get_max_cost_for_model(model=model)
-
-    match calculate_cost(response_data, max_cost):
-        case MaxCostData() as cost:
-            logger.debug(
-                "Using max cost pricing",
-                extra={"model": model, "max_cost_msats": cost.total_msats},
-            )
-            return cost
-        case CostData() as cost:
-            logger.debug(
-                "Using token-based pricing",
-                extra={
-                    "model": model,
-                    "total_cost_msats": cost.total_msats,
-                    "input_msats": cost.input_msats,
-                    "output_msats": cost.output_msats,
-                },
-            )
-            return cost
-        case CostDataError() as error:
-            logger.error(
-                "Cost calculation error",
-                extra={
-                    "model": model,
-                    "error_message": error.message,
-                    "error_code": error.code,
-                },
-            )
-            raise HTTPException(
-                status_code=400,
-                detail={
-                    "error": {
-                        "message": error.message,
-                        "type": "invalid_request_error",
-                        "code": error.code,
-                    }
-                },
-            )
-
-
-async def redeem_token(x_cashu_token: str) -> tuple[int, Literal["sat", "msat"]]:
-    """Redeem X-Cashu token and return amount and unit."""
-    logger.debug(
-        "Redeeming X-Cashu token",
-        extra={
-            "token_preview": x_cashu_token[:20] + "..."
-            if len(x_cashu_token) > 20
-            else x_cashu_token
-        },
-    )
-
-    try:
-        result = await wallet().redeem(x_cashu_token)
-        amount, unit = cast(tuple[int, Literal["sat", "msat"]], result)
-
-        logger.info(
-            "X-Cashu token redeemed successfully",
-            extra={"amount": amount, "unit": unit},
-        )
-
-        return amount, unit
-    except Exception as e:
-        logger.error(
-            "X-Cashu token redemption failed",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "token_preview": x_cashu_token[:20] + "..."
-                if len(x_cashu_token) > 20
-                else x_cashu_token,
-            },
-        )
-        raise HTTPException(
-            status_code=401,
-            detail={
-                "error": {
-                    "message": f"Invalid or expired Cashu key: {str(e)}",
-                    "type": "invalid_request_error",
-                    "code": "invalid_api_key",
-                }
-            },
-        )
-
-
-async def send_refund(amount: int, unit: CurrencyUnit, mint: str | None = None) -> str:
-    """Send a refund using Cashu tokens."""
-    logger.debug(
-        "Creating refund token", extra={"amount": amount, "unit": unit, "mint": mint}
-    )
-
-    try:
-        refund_token = await wallet().send(amount, unit=unit, mint_url=mint)
-
-        logger.info(
-            "Refund token created successfully",
-            extra={
-                "amount": amount,
-                "unit": unit,
-                "mint": mint,
-                "token_preview": refund_token[:20] + "..."
-                if len(refund_token) > 20
-                else refund_token,
-            },
-        )
-
-        return refund_token
-    except Exception as e:
-        logger.error(
-            "Failed to create refund token",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "amount": amount,
-                "unit": unit,
-                "mint": mint,
-            },
-        )
-        raise HTTPException(
-            status_code=401,
-            detail={
-                "error": {
-                    "message": f"failed to create refund: {str(e)}",
-                    "type": "invalid_request_error",
-                    "code": "send_token_failed",
-                }
-            },
-        )

router/proxy.py

@@ -1,730 +0,0 @@
-import json
-import re
-import traceback
-from typing import AsyncGenerator
-
-import httpx
-from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
-from fastapi.responses import Response, StreamingResponse
-
-from router.logging.logging_config import get_logger
-from router.payment.helpers import (
-    UPSTREAM_BASE_URL,
-    check_token_balance,
-    create_error_response,
-    prepare_upstream_headers,
-)
-from router.payment.x_cashu import x_cashu_handler
-
-from .auth import (
-    adjust_payment_for_tokens,
-    pay_for_request,
-    revert_pay_for_request,
-    validate_bearer_key,
-)
-from .db import ApiKey, AsyncSession, create_session, get_session
-
-logger = get_logger(__name__)
-proxy_router = APIRouter()
-
-
-async def handle_streaming_chat_completion(
-    response: httpx.Response, key: ApiKey, session: AsyncSession
-) -> StreamingResponse:
-    """Handle streaming chat completion responses with token-based pricing."""
-    logger.info(
-        "Processing streaming chat completion",
-        extra={
-            "key_hash": key.hashed_key[:8] + "...",
-            "key_balance": key.balance,
-            "response_status": response.status_code,
-        },
-    )
-
-    async def stream_with_cost() -> AsyncGenerator[bytes, None]:
-        # Store all chunks to analyze
-        stored_chunks = []
-
-        async for chunk in response.aiter_bytes():
-            # Store chunk for later analysis
-            stored_chunks.append(chunk)
-
-            # Pass through each chunk to client
-            yield chunk
-
-        logger.debug(
-            "Streaming completed, analyzing usage data",
-            extra={
-                "key_hash": key.hashed_key[:8] + "...",
-                "chunks_count": len(stored_chunks),
-            },
-        )
-
-        # Process stored chunks to find usage data
-        # Start from the end and work backwards
-        for i in range(len(stored_chunks) - 1, -1, -1):
-            chunk = stored_chunks[i]
-            if not chunk or chunk == b"":
-                continue
-
-            try:
-                # Split by "data: " to get individual SSE events
-                events = re.split(b"data: ", chunk)
-                for event_data in events:
-                    if (
-                        not event_data
-                        or event_data.strip() == b"[DONE]"
-                        or event_data.strip() == b""
-                    ):
-                        continue
-
-                    try:
-                        data = json.loads(event_data)
-                        if (
-                            "usage" in data
-                            and data["usage"] is not None
-                            and isinstance(data["usage"], dict)
-                        ):
-                            logger.info(
-                                "Found usage data in streaming response",
-                                extra={
-                                    "key_hash": key.hashed_key[:8] + "...",
-                                    "usage_data": data["usage"],
-                                    "model": data.get("model", "unknown"),
-                                },
-                            )
-
-                            # Found usage data, calculate cost
-                            # Create a new session for this operation
-                            async with create_session() as new_session:
-                                # Re-fetch the key in the 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
-                                        )
-                                        logger.info(
-                                            "Token adjustment completed for streaming",
-                                            extra={
-                                                "key_hash": key.hashed_key[:8] + "...",
-                                                "cost_data": cost_data,
-                                                "balance_after_adjustment": fresh_key.balance,
-                                            },
-                                        )
-                                        # Format as SSE and yield
-                                        cost_json = json.dumps({"cost": cost_data})
-                                        yield f"data: {cost_json}\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] + "...",
-                    },
-                )
-
-    return StreamingResponse(
-        stream_with_cost(),
-        status_code=response.status_code,
-        headers=dict(response.headers),
-    )
-
-
-async def handle_non_streaming_chat_completion(
-    response: httpx.Response, key: ApiKey, session: AsyncSession
-) -> Response:
-    """Handle non-streaming chat completion responses with token-based pricing."""
-    logger.info(
-        "Processing non-streaming chat completion",
-        extra={
-            "key_hash": key.hashed_key[:8] + "...",
-            "key_balance": key.balance,
-            "response_status": response.status_code,
-        },
-    )
-
-    try:
-        content = await response.aread()
-        response_json = json.loads(content)
-
-        logger.debug(
-            "Parsed response JSON",
-            extra={
-                "key_hash": key.hashed_key[:8] + "...",
-                "model": response_json.get("model", "unknown"),
-                "has_usage": "usage" in response_json,
-            },
-        )
-
-        cost_data = await adjust_payment_for_tokens(key, response_json, session)
-        response_json["cost"] = cost_data
-
-        logger.info(
-            "Token adjustment completed for non-streaming",
-            extra={
-                "key_hash": key.hashed_key[:8] + "...",
-                "cost_data": cost_data,
-                "model": response_json.get("model", "unknown"),
-                "balance_after_adjustment": key.balance,
-            },
-        )
-
-        # Keep only standard headers that are safe to pass through
-        allowed_headers = {
-            "content-type",
-            "cache-control",
-            "date",
-            "vary",
-            "access-control-allow-origin",
-            "access-control-allow-methods",
-            "access-control-allow-headers",
-            "access-control-allow-credentials",
-            "access-control-expose-headers",
-            "access-control-max-age",
-        }
-
-        response_headers = {
-            k: v for k, v in response.headers.items() if k.lower() in allowed_headers
-        }
-
-        return Response(
-            content=json.dumps(response_json).encode(),
-            status_code=response.status_code,
-            headers=response_headers,
-            media_type="application/json",
-        )
-    except json.JSONDecodeError as e:
-        logger.error(
-            "Failed to parse JSON from upstream response",
-            extra={
-                "error": str(e),
-                "key_hash": key.hashed_key[:8] + "...",
-                "content_preview": content[:200].decode(errors="ignore")
-                if content
-                else "empty",
-            },
-        )
-        raise
-    except Exception as e:
-        logger.error(
-            "Error processing non-streaming chat completion",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "key_hash": key.hashed_key[:8] + "...",
-            },
-        )
-        raise
-
-
-async def forward_to_upstream(
-    request: Request,
-    path: str,
-    headers: dict,
-    request_body: bytes | None,
-    key: ApiKey,
-    session: AsyncSession,
-) -> Response | StreamingResponse:
-    """Forward request to upstream and handle the response."""
-    if path.startswith("v1/"):
-        path = path.replace("v1/", "")
-
-    url = f"{UPSTREAM_BASE_URL}/{path}"
-
-    logger.info(
-        "Forwarding request to upstream",
-        extra={
-            "url": url,
-            "method": request.method,
-            "path": path,
-            "key_hash": key.hashed_key[:8] + "...",
-            "key_balance": key.balance,
-            "has_request_body": request_body is not None,
-        },
-    )
-
-    client = httpx.AsyncClient(
-        transport=httpx.AsyncHTTPTransport(retries=1),
-        timeout=None,  # No timeout - requests can take as long as needed
-    )
-
-    try:
-        # Use the pre-read body if available, otherwise stream
-        if request_body is not None:
-            response = await client.send(
-                client.build_request(
-                    request.method,
-                    url,
-                    headers=headers,
-                    content=request_body,
-                    params=request.query_params,
-                ),
-                stream=True,
-            )
-        else:
-            response = await client.send(
-                client.build_request(
-                    request.method,
-                    url,
-                    headers=headers,
-                    content=request.stream(),
-                    params=request.query_params,
-                ),
-                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"),
-            },
-        )
-
-        # For chat completions, we need to handle token-based pricing
-        if path.endswith("chat/completions"):
-            # Check if client requested streaming
-            client_wants_streaming = False
-            if request_body:
-                try:
-                    request_data = json.loads(request_body)
-                    client_wants_streaming = request_data.get("stream", False)
-                    logger.debug(
-                        "Chat completion request analysis",
-                        extra={
-                            "client_wants_streaming": client_wants_streaming,
-                            "model": request_data.get("model", "unknown"),
-                            "key_hash": key.hashed_key[:8] + "...",
-                        },
-                    )
-                except json.JSONDecodeError:
-                    logger.warning(
-                        "Failed to parse request body JSON for streaming detection"
-                    )
-
-            # Handle both streaming and non-streaming responses
-            content_type = response.headers.get("content-type", "")
-            upstream_is_streaming = "text/event-stream" in content_type
-            is_streaming = client_wants_streaming and upstream_is_streaming
-
-            logger.debug(
-                "Response type analysis",
-                extra={
-                    "is_streaming": is_streaming,
-                    "client_wants_streaming": client_wants_streaming,
-                    "upstream_is_streaming": upstream_is_streaming,
-                    "content_type": content_type,
-                    "key_hash": key.hashed_key[:8] + "...",
-                },
-            )
-
-            if is_streaming and response.status_code == 200:
-                # Process streaming response and extract cost from the last chunk
-                result = await handle_streaming_chat_completion(response, key, session)
-                background_tasks = BackgroundTasks()
-                background_tasks.add_task(response.aclose)
-                background_tasks.add_task(client.aclose)
-                result.background = background_tasks
-                return result
-
-            elif response.status_code == 200:
-                # Handle non-streaming response
-                try:
-                    return await handle_non_streaming_chat_completion(
-                        response, key, session
-                    )
-                finally:
-                    await response.aclose()
-                    await client.aclose()
-
-        # For all other responses, stream the response
-        background_tasks = BackgroundTasks()
-        background_tasks.add_task(response.aclose)
-        background_tasks.add_task(client.aclose)
-
-        logger.debug(
-            "Streaming non-chat response",
-            extra={
-                "path": path,
-                "status_code": response.status_code,
-                "key_hash": key.hashed_key[:8] + "...",
-            },
-        )
-
-        return StreamingResponse(
-            response.aiter_bytes(),
-            status_code=response.status_code,
-            headers=dict(response.headers),
-            background=background_tasks,
-        )
-
-    except httpx.RequestError as exc:
-        await client.aclose()
-        error_type = type(exc).__name__
-        error_details = str(exc)
-
-        logger.error(
-            "HTTP request error to upstream",
-            extra={
-                "error_type": error_type,
-                "error_details": error_details,
-                "method": request.method,
-                "url": url,
-                "path": path,
-                "query_params": dict(request.query_params),
-                "key_hash": key.hashed_key[:8] + "...",
-            },
-        )
-
-        # Provide more specific error messages based on the error type
-        if isinstance(exc, httpx.ConnectError):
-            error_message = "Unable to connect to upstream service"
-        elif isinstance(exc, httpx.TimeoutException):
-            error_message = "Upstream service request timed out"
-        elif isinstance(exc, httpx.NetworkError):
-            error_message = "Network error while connecting to upstream service"
-        else:
-            error_message = f"Error connecting to upstream service: {error_type}"
-
-        return create_error_response("upstream_error", error_message, 502)
-
-    except Exception as exc:
-        await client.aclose()
-        tb = traceback.format_exc()
-
-        logger.error(
-            "Unexpected error in upstream forwarding",
-            extra={
-                "error": str(exc),
-                "error_type": type(exc).__name__,
-                "method": request.method,
-                "url": url,
-                "path": path,
-                "query_params": dict(request.query_params),
-                "key_hash": key.hashed_key[:8] + "...",
-                "traceback": tb,
-            },
-        )
-
-        return create_error_response(
-            "internal_error", "An unexpected server error occurred", 500
-        )
-
-
-@proxy_router.api_route("/{path:path}", methods=["GET", "POST"], response_model=None)
-async def proxy(
-    request: Request, path: str, session: AsyncSession = Depends(get_session)
-) -> Response | StreamingResponse:
-    """Main proxy endpoint handler."""
-    logger.info(
-        "Received proxy request",
-        extra={
-            "method": request.method,
-            "path": path,
-            "client_host": request.client.host if request.client else "unknown",
-            "user_agent": request.headers.get("user-agent", "unknown")[:100],
-        },
-    )
-
-    request_body = await request.body()
-    headers = dict(request.headers)
-
-    # Parse JSON body if present, handle empty/invalid JSON
-    request_body_dict = {}
-    if request_body:
-        try:
-            request_body_dict = json.loads(request_body)
-            logger.debug(
-                "Request body parsed",
-                extra={
-                    "path": path,
-                    "body_keys": list(request_body_dict.keys()),
-                    "model": request_body_dict.get("model", "not_specified"),
-                },
-            )
-        except json.JSONDecodeError as e:
-            logger.error(
-                "Invalid JSON in request body",
-                extra={
-                    "error": str(e),
-                    "path": path,
-                    "body_preview": request_body[:200].decode(errors="ignore")
-                    if request_body
-                    else "empty",
-                },
-            )
-            return Response(
-                content=json.dumps(
-                    {"error": {"type": "invalid_request_error", "code": "invalid_json"}}
-                ),
-                status_code=400,
-                media_type="application/json",
-            )
-
-    # Check token balance for all requests to get currency unit
-    try:
-        unit = check_token_balance(headers, request_body_dict)
-        logger.debug(
-            "Token balance check completed", extra={"path": path, "unit": unit}
-        )
-    except HTTPException as e:
-        logger.warning(
-            "Token balance check failed",
-            extra={"path": path, "status_code": e.status_code, "detail": str(e.detail)},
-        )
-        raise
-
-    # Handle authentication
-    if x_cashu := headers.get("x-cashu", None):
-        logger.info(
-            "Processing X-Cashu payment",
-            extra={
-                "path": path,
-                "token_preview": x_cashu[:20] + "..." if len(x_cashu) > 20 else x_cashu,
-            },
-        )
-        return await x_cashu_handler(request, x_cashu, path)
-
-    elif auth := headers.get("authorization", None):
-        logger.debug(
-            "Processing bearer token authentication",
-            extra={
-                "path": path,
-                "token_preview": auth[:20] + "..." if len(auth) > 20 else auth,
-            },
-        )
-        key = await get_bearer_token_key(headers, path, session, auth)
-
-    else:
-        if request.method not in ["GET"]:
-            logger.warning(
-                "Unauthorized request - no authentication provided",
-                extra={"method": request.method, "path": path},
-            )
-            return Response(
-                content=json.dumps({"detail": "Unauthorized"}),
-                status_code=401,
-                media_type="application/json",
-            )
-
-        logger.debug("Processing unauthenticated GET request", extra={"path": path})
-        # Prepare headers for upstream
-        headers = prepare_upstream_headers(dict(request.headers))
-        return await forward_get_to_upstream(request, path, headers)
-
-    cost_per_request = 0
-    # Only pay for request if we have request body data (for completions endpoints)
-    if request_body_dict:
-        logger.info(
-            "Processing payment for request",
-            extra={
-                "path": path,
-                "key_hash": key.hashed_key[:8] + "...",
-                "key_balance_before": key.balance,
-                "model": request_body_dict.get("model", "unknown"),
-            },
-        )
-
-        try:
-            await pay_for_request(key, session, request_body_dict)
-            logger.info(
-                "Payment processed successfully",
-                extra={
-                    "path": path,
-                    "key_hash": key.hashed_key[:8] + "...",
-                    "key_balance_after": key.balance,
-                    "model": request_body_dict.get("model", "unknown"),
-                },
-            )
-        except Exception as e:
-            logger.error(
-                "Payment processing failed",
-                extra={
-                    "error": str(e),
-                    "error_type": type(e).__name__,
-                    "path": path,
-                    "key_hash": key.hashed_key[:8] + "...",
-                },
-            )
-            raise
-
-    # Prepare headers for upstream
-    headers = prepare_upstream_headers(dict(request.headers))
-
-    # Forward to upstream and handle response
-    response = await forward_to_upstream(
-        request, path, headers, request_body, key, session
-    )
-
-    if response.status_code != 200:
-        await revert_pay_for_request(key, session, cost_per_request)
-        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,
-            },
-        )
-
-    return response
-
-
-async def get_bearer_token_key(
-    headers: dict, path: str, session: AsyncSession, auth: str
-) -> ApiKey:
-    """Handle bearer token authentication proxy requests."""
-    bearer_key = auth.replace("Bearer ", "") if auth.startswith("Bearer ") else ""
-    refund_address = headers.get("Refund-LNURL", None)
-    key_expiry_time = headers.get("Key-Expiry-Time", None)
-
-    logger.debug(
-        "Processing bearer token",
-        extra={
-            "path": path,
-            "has_refund_address": bool(refund_address),
-            "has_expiry_time": bool(key_expiry_time),
-            "bearer_key_preview": bearer_key[:20] + "..."
-            if len(bearer_key) > 20
-            else bearer_key,
-        },
-    )
-
-    # Validate key_expiry_time header
-    if key_expiry_time:
-        try:
-            key_expiry_time = int(key_expiry_time)  # type: ignore
-            logger.debug(
-                "Key expiry time validated",
-                extra={"expiry_time": key_expiry_time, "path": path},
-            )
-        except ValueError:
-            logger.error(
-                "Invalid Key-Expiry-Time header",
-                extra={"key_expiry_time": key_expiry_time, "path": path},
-            )
-            raise HTTPException(
-                status_code=400,
-                detail="Invalid Key-Expiry-Time: must be a valid Unix timestamp",
-            )
-        if not refund_address:
-            logger.error(
-                "Missing Refund-LNURL header with Key-Expiry-Time",
-                extra={"path": path, "expiry_time": key_expiry_time},
-            )
-            raise HTTPException(
-                status_code=400,
-                detail="Error: Refund-LNURL header required when using Key-Expiry-Time",
-            )
-    else:
-        key_expiry_time = None
-
-    try:
-        key = await validate_bearer_key(
-            bearer_key,
-            session,
-            refund_address,
-            key_expiry_time,  # type: ignore
-        )
-        logger.info(
-            "Bearer token validated successfully",
-            extra={
-                "path": path,
-                "key_hash": key.hashed_key[:8] + "...",
-                "key_balance": key.balance,
-            },
-        )
-        return key
-    except Exception as e:
-        logger.error(
-            "Bearer token validation failed",
-            extra={
-                "error": str(e),
-                "error_type": type(e).__name__,
-                "path": path,
-                "bearer_key_preview": bearer_key[:20] + "..."
-                if len(bearer_key) > 20
-                else bearer_key,
-            },
-        )
-        raise
-
-
-async def forward_get_to_upstream(
-    request: Request,
-    path: str,
-    headers: dict,
-) -> Response | StreamingResponse:
-    """Forward request to upstream and handle the response."""
-    if path.startswith("v1/"):
-        path = path.replace("v1/", "")
-
-    url = f"{UPSTREAM_BASE_URL}/{path}"
-
-    logger.info(
-        "Forwarding GET request to upstream",
-        extra={"url": url, "method": request.method, "path": path},
-    )
-
-    async with httpx.AsyncClient(
-        transport=httpx.AsyncHTTPTransport(retries=1),
-        timeout=None,
-    ) as client:
-        try:
-            response = await client.send(
-                client.build_request(
-                    request.method,
-                    url,
-                    headers=headers,
-                    content=request.stream(),
-                    params=request.query_params,
-                ),
-            )
-
-            logger.info(
-                "GET request forwarded successfully",
-                extra={"path": path, "status_code": response.status_code},
-            )
-
-            return StreamingResponse(
-                response.aiter_bytes(),
-                status_code=response.status_code,
-                headers=dict(response.headers),
-            )
-        except Exception as exc:
-            tb = traceback.format_exc()
-            logger.error(
-                "Error forwarding GET request",
-                extra={
-                    "error": str(exc),
-                    "error_type": type(exc).__name__,
-                    "method": request.method,
-                    "url": url,
-                    "path": path,
-                    "query_params": dict(request.query_params),
-                    "traceback": tb,
-                },
-            )
-            return create_error_response(
-                "internal_error", "An unexpected server error occurred", 500
-            )

routstr/__init__.py

@@ -0,0 +1,3 @@
+from .core.main import app as fastapi_app  # noqa
+
+__all__ = ["fastapi_app"]

routstr/algorithm.py

@@ -0,0 +1,290 @@
+"""Model prioritization algorithm for selecting cheapest upstream providers."""
+
+from typing import TYPE_CHECKING
+
+from .core.logging import get_logger
+
+if TYPE_CHECKING:
+    from .payment.models import Model
+    from .upstream import BaseUpstreamProvider
+
+logger = get_logger(__name__)
+
+
+def calculate_model_cost_score(model: "Model") -> float:
+    """Calculate a representative cost score for a model.
+
+    This score is used to compare models when multiple providers offer the same model.
+    Lower scores indicate cheaper models.
+
+    The score is calculated as a weighted average of:
+    - Input token cost (weighted by typical input usage)
+    - Output token cost (weighted by typical output usage)
+    - Fixed request cost
+
+    Args:
+        model: Model instance with pricing information
+
+    Returns:
+        Float representing the cost score. Lower is better.
+    """
+    pricing = model.pricing
+
+    # Weight costs by typical usage patterns
+    # Assume average request: 1000 input tokens, 500 output tokens
+    TYPICAL_INPUT_TOKENS = 1000.0
+    TYPICAL_OUTPUT_TOKENS = 500.0
+
+    # Calculate weighted cost in USD
+    input_cost = pricing.prompt * (TYPICAL_INPUT_TOKENS / 1000.0)
+    output_cost = pricing.completion * (TYPICAL_OUTPUT_TOKENS / 1000.0)
+    request_cost = pricing.request
+
+    # Include additional costs if present
+    image_cost = (
+        getattr(pricing, "image", 0.0) * 0.1
+    )  # Weight lower as not every request uses images
+    web_search_cost = getattr(pricing, "web_search", 0.0) * 0.1
+    reasoning_cost = getattr(pricing, "internal_reasoning", 0.0) * 0.2
+
+    total_cost = (
+        input_cost
+        + output_cost
+        + request_cost
+        + image_cost
+        + web_search_cost
+        + reasoning_cost
+    )
+
+    return total_cost
+
+
+def get_provider_penalty(provider: "BaseUpstreamProvider") -> float:
+    """Calculate a penalty multiplier for certain providers.
+
+    This allows applying policy-based adjustments beyond pure cost.
+    For example, preferring certain providers for reliability or features.
+
+    Args:
+        provider: UpstreamProvider instance
+
+    Returns:
+        Float multiplier to apply to cost (1.0 = no penalty, >1.0 = penalize)
+    """
+    # Default: no penalty
+    penalty = 1.0
+
+    # Check if this is OpenRouter (can be identified by base URL)
+    base_url = getattr(provider, "base_url", "")
+    if "openrouter.ai" in base_url.lower():
+        # Small penalty for OpenRouter to prefer other providers when costs are very close
+        # This maintains the original behavior of preferring non-OpenRouter providers
+        penalty = 1.001  # 0.1% penalty
+
+    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"]]:
+    """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)
+    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
+
+    Args:
+        upstreams: List of all upstream provider instances
+        overrides_by_id: Dict of model overrides from database {model_id: (ModelRow, fee)}
+        disabled_model_ids: Set of model IDs that should be excluded
+
+    Returns:
+        Tuple of (model_instances, provider_map, unique_models)
+    """
+    from .payment.models import _row_to_model
+    from .upstream.helpers import resolve_model_alias
+
+    model_instances: dict[str, "Model"] = {}
+    provider_map: dict[str, "BaseUpstreamProvider"] = {}
+    unique_models: dict[str, "Model"] = {}
+
+    # Separate OpenRouter from other providers
+    openrouter: "BaseUpstreamProvider" | None = None
+    other_upstreams: list["BaseUpstreamProvider"] = []
+
+    for upstream in upstreams:
+        base_url = getattr(upstream, "base_url", "")
+        if base_url == "https://openrouter.ai/api/v1":
+            openrouter = upstream
+        else:
+            other_upstreams.append(upstream)
+
+    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 _maybe_set_alias(
+        alias: str, model: "Model", provider: "BaseUpstreamProvider"
+    ) -> None:
+        """Set alias to model/provider if not set or if new model is preferred."""
+        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
+
+    def process_provider_models(
+        upstream: "BaseUpstreamProvider", is_openrouter: bool = False
+    ) -> None:
+        """Process all models from a given provider."""
+        upstream_prefix = getattr(upstream, "upstream_name", None)
+
+        for model in upstream.get_cached_models():
+            if not model.enabled or model.id in disabled_model_ids:
+                continue
+
+            # Apply overrides if present
+            if model.id in overrides_by_id:
+                override_row, provider_fee = overrides_by_id[model.id]
+                model_to_use = _row_to_model(
+                    override_row, apply_provider_fee=True, provider_fee=provider_fee
+                )
+            else:
+                model_to_use = model
+
+            # Add to unique models
+            base_id = get_base_model_id(model_to_use.id)
+            if not is_openrouter or base_id not in unique_models:
+                unique_model = model_to_use.copy(
+                    update={
+                        "id": base_id,
+                        "upstream_provider_id": upstream.provider_type,
+                    }
+                )
+                unique_models[base_id] = unique_model
+
+            # Get all aliases for this model
+            aliases = resolve_model_alias(
+                model_to_use.id,
+                model_to_use.canonical_slug,
+                alias_ids=model_to_use.alias_ids,
+            )
+
+            # Add prefixed alias if applicable
+            if upstream_prefix and "/" not in model_to_use.id:
+                prefixed_id = f"{upstream_prefix}/{model_to_use.id}"
+                if prefixed_id not in aliases:
+                    aliases.append(prefixed_id)
+
+            # Try to set each alias
+            for alias in aliases:
+                _maybe_set_alias(alias, model_to_use, upstream)
+
+    # Process non-OpenRouter providers first (they're typically cheaper)
+    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
+    if openrouter:
+        process_provider_models(openrouter, is_openrouter=True)
+
+    # Log provider distribution
+    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
+
+    logger.debug(
+        f"Updated model mappings with ({len(unique_models)} unique models and {len(model_instances)} aliases)",
+        extra={"provider_distribution": provider_counts},
+    )
+
+    return model_instances, provider_map, unique_models

routstr/auth.py

@@ -1,19 +1,21 @@
 import hashlib
+import math
 from typing import Optional
 
 from fastapi import HTTPException
+from sqlalchemy.exc import IntegrityError
 from sqlmodel import col, update
 
-from .cashu import credit_balance
-from .db import ApiKey, AsyncSession
-from .logging.logging_config import get_logger
-from .payment.cost_caculation import (
+from .core import get_logger
+from .core.db import ApiKey, AsyncSession
+from .core.settings import settings
+from .payment.cost_calculation import (
     CostData,
     CostDataError,
     MaxCostData,
     calculate_cost,
 )
-from .payment.helpers import get_max_cost_for_model
+from .wallet import credit_balance, deserialize_token_from_string
 
 logger = get_logger(__name__)
 
@@ -113,6 +115,7 @@ async def validate_bearer_key(
 
         try:
             hashed_key = hashlib.sha256(bearer_key.encode()).hexdigest()
+            token_obj = deserialize_token_from_string(bearer_key)
             logger.debug(
                 "Generated token hash", extra={"hash_preview": hashed_key[:16] + "..."}
             )
@@ -159,22 +162,66 @@ async def validate_bearer_key(
                     "has_expiry_time": bool(key_expiry_time),
                 },
             )
+            if token_obj.mint in settings.cashu_mints:
+                refund_currency = token_obj.unit
+                refund_mint_url = token_obj.mint
+            else:
+                refund_currency = "sat"
+                refund_mint_url = settings.primary_mint
 
             new_key = ApiKey(
                 hashed_key=hashed_key,
                 balance=0,
                 refund_address=refund_address,
                 key_expiry_time=key_expiry_time,
+                refund_currency=refund_currency,
+                refund_mint_url=refund_mint_url,
             )
             session.add(new_key)
-            await session.flush()
+
+            try:
+                await session.flush()
+            except IntegrityError:
+                await session.rollback()
+                logger.info(
+                    "Concurrent key creation detected, fetching existing key",
+                    extra={"key_hash": hashed_key[:8] + "..."},
+                )
+                existing_key = await session.get(ApiKey, hashed_key)
+                if not existing_key:
+                    raise Exception("Failed to fetch existing key after IntegrityError")
+
+                if key_expiry_time is not None:
+                    existing_key.key_expiry_time = key_expiry_time
+                if refund_address is not None:
+                    existing_key.refund_address = refund_address
+
+                return existing_key
 
             logger.debug(
                 "New key created, starting token redemption",
                 extra={"key_hash": hashed_key[:8] + "..."},
             )
 
-            msats = await credit_balance(bearer_key, new_key, session)
+            logger.info(
+                "AUTH: About to call credit_balance",
+                extra={"token_preview": bearer_key[:50]},
+            )
+            try:
+                msats = await credit_balance(bearer_key, new_key, session)
+                logger.info(
+                    "AUTH: credit_balance returned successfully", extra={"msats": msats}
+                )
+            except Exception as credit_error:
+                logger.error(
+                    "AUTH: credit_balance failed",
+                    extra={
+                        "error": str(credit_error),
+                        "error_type": type(credit_error).__name__,
+                    },
+                )
+                raise credit_error
+
             if msats <= 0:
                 logger.error(
                     "Token redemption returned zero or negative amount",
@@ -239,10 +286,10 @@ async def validate_bearer_key(
     )
 
 
-async def pay_for_request(key: ApiKey, session: AsyncSession, body: dict) -> int:
+async def pay_for_request(
+    key: ApiKey, cost_per_request: int, session: AsyncSession
+) -> int:
     """Process payment for a request."""
-    model = body["model"]
-    cost_per_request = get_max_cost_for_model(model=model)
 
     logger.info(
         "Processing payment for request",
@@ -250,20 +297,19 @@ async def pay_for_request(key: ApiKey, session: AsyncSession, body: dict) -> int
             "key_hash": key.hashed_key[:8] + "...",
             "current_balance": key.balance,
             "required_cost": cost_per_request,
-            "model": model,
             "sufficient_balance": key.balance >= cost_per_request,
         },
     )
 
-    if key.balance < cost_per_request:
+    if 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,
                 "required": cost_per_request,
-                "shortfall": cost_per_request - key.balance,
-                "model": model,
+                "shortfall": cost_per_request - key.total_balance,
             },
         )
 
@@ -271,7 +317,7 @@ async def pay_for_request(key: ApiKey, session: AsyncSession, body: dict) -> int
             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. {key.total_balance} available. (reserved: {key.reserved_balance})",
                     "type": "insufficient_quota",
                     "code": "insufficient_balance",
                 }
@@ -291,10 +337,9 @@ async def pay_for_request(key: ApiKey, session: AsyncSession, body: dict) -> int
     stmt = (
         update(ApiKey)
         .where(col(ApiKey.hashed_key) == key.hashed_key)
-        .where(col(ApiKey.balance) >= cost_per_request)
+        .where(col(ApiKey.balance) - col(ApiKey.reserved_balance) >= cost_per_request)
         .values(
-            balance=col(ApiKey.balance) - cost_per_request,
-            total_spent=col(ApiKey.total_spent) + cost_per_request,
+            reserved_balance=col(ApiKey.reserved_balance) + cost_per_request,
             total_requests=col(ApiKey.total_requests) + 1,
         )
     )
@@ -333,7 +378,6 @@ async def pay_for_request(key: ApiKey, session: AsyncSession, body: dict) -> int
             "new_balance": key.balance,
             "total_spent": key.total_spent,
             "total_requests": key.total_requests,
-            "model": model,
         },
     )
 
@@ -347,8 +391,7 @@ async def revert_pay_for_request(
         update(ApiKey)
         .where(col(ApiKey.hashed_key) == key.hashed_key)
         .values(
-            balance=col(ApiKey.balance) + cost_per_request,
-            total_spent=col(ApiKey.total_spent) - cost_per_request,
+            reserved_balance=col(ApiKey.reserved_balance) - cost_per_request,
             total_requests=col(ApiKey.total_requests) - 1,
         )
     )
@@ -356,6 +399,14 @@ async def revert_pay_for_request(
     result = await session.exec(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] + "...",
+                "cost_to_revert": cost_per_request,
+                "current_reserved_balance": key.reserved_balance,
+            },
+        )
         raise HTTPException(
             status_code=402,
             detail={
@@ -370,7 +421,7 @@ async def revert_pay_for_request(
 
 
 async def adjust_payment_for_tokens(
-    key: ApiKey, response_data: dict, session: AsyncSession
+    key: ApiKey, response_data: dict, session: AsyncSession, deducted_max_cost: int
 ) -> dict:
     """
     Adjusts the payment based on token usage in the response.
@@ -378,20 +429,42 @@ async def adjust_payment_for_tokens(
     Returns cost data to be included in the response.
     """
     model = response_data.get("model", "unknown")
-    max_cost = get_max_cost_for_model(model=model)
 
     logger.debug(
         "Starting payment adjustment for tokens",
         extra={
             "key_hash": key.hashed_key[:8] + "...",
             "model": model,
-            "max_cost": max_cost,
+            "deducted_max_cost": deducted_max_cost,
             "current_balance": key.balance,
             "has_usage": "usage" in response_data,
         },
     )
 
-    match calculate_cost(response_data, max_cost):
+    async def release_reservation_only() -> None:
+        """Fallback to release reservation without charging when main update fails."""
+        try:
+            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(release_stmt)  # type: ignore[call-overload]
+            await session.commit()
+            logger.warning(
+                "Released reservation without charging (fallback)",
+                extra={
+                    "key_hash": 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] + "..."},
+            )
+
+    match await calculate_cost(response_data, deducted_max_cost, session):
         case MaxCostData() as cost:
             logger.debug(
                 "Using max cost data (no token adjustment)",
@@ -401,12 +474,48 @@ async def adjust_payment_for_tokens(
                     "max_cost": cost.total_msats,
                 },
             )
+            # Finalize by releasing reservation and charging max cost
+            finalize_stmt = (
+                update(ApiKey)
+                .where(col(ApiKey.hashed_key) == key.hashed_key)
+                .values(
+                    reserved_balance=col(ApiKey.reserved_balance) - deducted_max_cost,
+                    balance=col(ApiKey.balance) - cost.total_msats,
+                    total_spent=col(ApiKey.total_spent) + cost.total_msats,
+                )
+            )
+            result = await session.exec(finalize_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] + "...",
+                        "deducted_max_cost": deducted_max_cost,
+                        "current_reserved_balance": key.reserved_balance,
+                        "total_cost": cost.total_msats,
+                        "model": model,
+                    },
+                )
+                await release_reservation_only()
+            else:
+                await session.refresh(key)
+                logger.info(
+                    "Max cost payment finalized",
+                    extra={
+                        "key_hash": key.hashed_key[:8] + "...",
+                        "charged_amount": cost.total_msats,
+                        "new_balance": key.balance,
+                        "model": model,
+                    },
+                )
             return cost.dict()
 
         case CostData() as cost:
             # If token-based pricing is enabled and base cost is 0, use token-based cost
             # Otherwise, token cost is additional to the base cost
-            cost_difference = cost.total_msats - max_cost
+            cost_difference = cost.total_msats - deducted_max_cost
+            total_cost_msats: int = math.ceil(cost.total_msats)
 
             logger.info(
                 "Calculated token-based cost",
@@ -414,7 +523,7 @@ async def adjust_payment_for_tokens(
                     "key_hash": key.hashed_key[:8] + "...",
                     "model": model,
                     "token_cost": cost.total_msats,
-                    "max_cost": max_cost,
+                    "deducted_max_cost": deducted_max_cost,
                     "cost_difference": cost_difference,
                     "input_msats": cost.input_msats,
                     "output_msats": cost.output_msats,
@@ -423,14 +532,27 @@ async def adjust_payment_for_tokens(
 
             if cost_difference == 0:
                 logger.debug(
-                    "No cost adjustment needed",
+                    "Finalizing with exact reserved cost",
                     extra={"key_hash": key.hashed_key[:8] + "...", "model": model},
                 )
+                finalize_stmt = (
+                    update(ApiKey)
+                    .where(col(ApiKey.hashed_key) == key.hashed_key)
+                    .values(
+                        reserved_balance=col(ApiKey.reserved_balance)
+                        - deducted_max_cost,
+                        balance=col(ApiKey.balance) - total_cost_msats,
+                        total_spent=col(ApiKey.total_spent) + total_cost_msats,
+                    )
+                )
+                await session.exec(finalize_stmt)  # type: ignore[call-overload]
                 await session.commit()
+                await session.refresh(key)
                 return cost.dict()
 
+            # this should never happen why do we handle this???
             if cost_difference > 0:
-                # Need to charge more
+                # Need to charge more than reserved, finalize by releasing reservation and charging total
                 logger.info(
                     "Additional charge required for token usage",
                     extra={
@@ -442,54 +564,42 @@ async def adjust_payment_for_tokens(
                     },
                 )
 
-                if key.balance < cost_difference:
-                    logger.warning(
-                        "Insufficient balance for token-based pricing adjustment",
+                finalize_stmt = (
+                    update(ApiKey)
+                    .where(col(ApiKey.hashed_key) == key.hashed_key)
+                    .values(
+                        reserved_balance=col(ApiKey.reserved_balance)
+                        - deducted_max_cost,
+                        balance=col(ApiKey.balance) - total_cost_msats,
+                        total_spent=col(ApiKey.total_spent) + total_cost_msats,
+                    )
+                )
+                result = await session.exec(finalize_stmt)  # type: ignore[call-overload]
+                await session.commit()
+
+                if result.rowcount:
+                    cost.total_msats = total_cost_msats
+                    await session.refresh(key)
+
+                    logger.info(
+                        "Finalized payment with additional charge",
                         extra={
                             "key_hash": key.hashed_key[:8] + "...",
-                            "required": cost_difference,
-                            "available": key.balance,
-                            "shortfall": cost_difference - key.balance,
+                            "charged_amount": total_cost_msats,
+                            "new_balance": key.balance,
                             "model": model,
                         },
                     )
-                    await session.commit()
                 else:
-                    charge_stmt = (
-                        update(ApiKey)
-                        .where(col(ApiKey.hashed_key) == key.hashed_key)
-                        .where(col(ApiKey.balance) >= cost_difference)
-                        .values(
-                            balance=col(ApiKey.balance) - cost_difference,
-                            total_spent=col(ApiKey.total_spent) + cost_difference,
-                        )
+                    logger.warning(
+                        "Failed to finalize additional charge - releasing reservation",
+                        extra={
+                            "key_hash": key.hashed_key[:8] + "...",
+                            "attempted_charge": total_cost_msats,
+                            "model": model,
+                        },
                     )
-                    result = await session.exec(charge_stmt)  # type: ignore[call-overload]
-                    await session.commit()
-
-                    if result.rowcount:
-                        cost.total_msats = max_cost + cost_difference
-                        await session.refresh(key)
-
-                        logger.info(
-                            "Additional charge applied successfully",
-                            extra={
-                                "key_hash": key.hashed_key[:8] + "...",
-                                "charged_amount": cost_difference,
-                                "new_balance": key.balance,
-                                "total_cost": cost.total_msats,
-                                "model": model,
-                            },
-                        )
-                    else:
-                        logger.warning(
-                            "Failed to apply additional charge (concurrent operation)",
-                            extra={
-                                "key_hash": key.hashed_key[:8] + "...",
-                                "attempted_charge": cost_difference,
-                                "model": model,
-                            },
-                        )
+                    await release_reservation_only()
             else:
                 # Refund some of the base cost
                 refund = abs(cost_difference)
@@ -507,31 +617,47 @@ async def adjust_payment_for_tokens(
                     update(ApiKey)
                     .where(col(ApiKey.hashed_key) == key.hashed_key)
                     .values(
-                        balance=col(ApiKey.balance) + refund,
-                        total_spent=col(ApiKey.total_spent) - refund,
+                        reserved_balance=col(ApiKey.reserved_balance)
+                        - deducted_max_cost,
+                        balance=col(ApiKey.balance) - total_cost_msats,
+                        total_spent=col(ApiKey.total_spent) + total_cost_msats,
                     )
                 )
-                await session.exec(refund_stmt)  # type: ignore[call-overload]
+                result = await session.exec(refund_stmt)  # type: ignore[call-overload]
                 await session.commit()
-                cost.total_msats = max_cost - refund
-                await session.refresh(key)
 
-                logger.info(
-                    "Refund processed successfully",
-                    extra={
-                        "key_hash": key.hashed_key[:8] + "...",
-                        "refunded_amount": refund,
-                        "new_balance": key.balance,
-                        "final_cost": cost.total_msats,
-                        "model": model,
-                    },
-                )
+                if result.rowcount == 0:
+                    logger.error(
+                        "Failed to finalize payment - releasing reservation",
+                        extra={
+                            "key_hash": key.hashed_key[:8] + "...",
+                            "deducted_max_cost": deducted_max_cost,
+                            "current_reserved_balance": key.reserved_balance,
+                            "total_cost": total_cost_msats,
+                            "model": model,
+                        },
+                    )
+                    await release_reservation_only()
+                else:
+                    cost.total_msats = total_cost_msats
+                    await session.refresh(key)
+
+                    logger.info(
+                        "Refund processed successfully",
+                        extra={
+                            "key_hash": key.hashed_key[:8] + "...",
+                            "refunded_amount": refund,
+                            "new_balance": key.balance,
+                            "final_cost": cost.total_msats,
+                            "model": model,
+                        },
+                    )
 
             return cost.dict()
 
         case CostDataError() as error:
             logger.error(
-                "Cost calculation error during payment adjustment",
+                "Cost calculation error during payment adjustment - releasing reservation",
                 extra={
                     "key_hash": key.hashed_key[:8] + "...",
                     "model": model,
@@ -539,6 +665,7 @@ async def adjust_payment_for_tokens(
                     "error_code": error.code,
                 },
             )
+            await release_reservation_only()
 
             raise HTTPException(
                 status_code=400,
@@ -550,3 +677,15 @@ async def adjust_payment_for_tokens(
                     }
                 },
             )
+    # Fallback: should not reach here, but release reservation just in case
+    logger.error(
+        "Unexpected fallback in adjust_payment_for_tokens - releasing reservation",
+        extra={"key_hash": key.hashed_key[:8] + "...", "model": model},
+    )
+    await release_reservation_only()
+    return {
+        "base_msats": deducted_max_cost,
+        "input_msats": 0,
+        "output_msats": 0,
+        "total_msats": deducted_max_cost,
+    }

routstr/balance.py

@@ -0,0 +1,246 @@
+import asyncio
+import hashlib
+from time import monotonic
+from typing import Annotated, NoReturn
+
+from fastapi import APIRouter, Depends, Header, HTTPException
+from pydantic import BaseModel
+
+from .auth import validate_bearer_key
+from .core.db import ApiKey, AsyncSession, get_session
+from .core.logging import get_logger
+from .core.settings import settings
+from .lightning import lightning_router
+from .wallet import credit_balance, recieve_token, send_to_lnurl, send_token
+
+router = APIRouter()
+balance_router = APIRouter(prefix="/v1/balance")
+
+logger = get_logger(__name__)
+
+
+async def get_key_from_header(
+    authorization: Annotated[str, Header(...)],
+    session: AsyncSession = Depends(get_session),
+) -> ApiKey:
+    if authorization.startswith("Bearer "):
+        return await validate_bearer_key(authorization[7:], session)
+
+    raise HTTPException(
+        status_code=401,
+        detail="Invalid authorization. Use 'Bearer <cashu-token>' or 'Bearer <api-key>'",
+    )
+
+
+# TODO: remove this endpoint when frontend is updated
+@router.get("/", include_in_schema=False)
+async def account_info(key: ApiKey = Depends(get_key_from_header)) -> dict:
+    return {
+        "api_key": "sk-" + key.hashed_key,
+        "balance": key.balance,
+        "reserved": key.reserved_balance,
+    }
+
+
+# TODO: Implement POST /v1/wallet/create endpoint
+# This endpoint should accept:
+# - cashu_token (required): The eCash token to deposit
+# - refund_lnurl (optional): LNURL for refunds (instead of refund_address in validate_bearer_key)
+# - refund_expiry (optional): Expiry timestamp for the key (maps to key_expiry_time in validate_bearer_key)
+# The endpoint should:
+# 1. Create a new wallet/API key from the cashu_token
+# 2. Store refund_lnurl and refund_expiry in the database
+# 3. Return the API key (rstr_...) and balance
+# Note: validate_bearer_key already supports refund_address and key_expiry_time params
+
+
+@router.get("/create")
+async def create_balance(
+    initial_balance_token: str, session: AsyncSession = Depends(get_session)
+) -> dict:
+    key = await validate_bearer_key(initial_balance_token, session)
+    return {
+        "api_key": "sk-" + key.hashed_key,
+        "balance": key.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,
+    }
+
+
+class TopupRequest(BaseModel):
+    cashu_token: str
+
+
+@router.post("/topup")
+async def topup_wallet_endpoint(
+    cashu_token: str | None = None,
+    topup_request: TopupRequest | None = None,
+    key: ApiKey = Depends(get_key_from_header),
+    session: AsyncSession = Depends(get_session),
+) -> dict[str, int]:
+    if topup_request is not None:
+        cashu_token = topup_request.cashu_token
+    if cashu_token is None:
+        raise HTTPException(status_code=400, detail="A cashu_token is required.")
+
+    cashu_token = cashu_token.replace("\n", "").replace("\r", "").replace("\t", "")
+    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)
+    except ValueError as e:
+        error_msg = str(e)
+        if "already spent" in error_msg.lower():
+            raise HTTPException(status_code=400, detail="Token already spent")
+        elif "invalid" in error_msg.lower() or "decode" in error_msg.lower():
+            raise HTTPException(status_code=400, detail="Invalid token format")
+        else:
+            raise HTTPException(status_code=400, detail="Failed to redeem token")
+    except Exception:
+        raise HTTPException(status_code=500, detail="Internal server error")
+    return {"msats": amount_msats}
+
+
+_REFUND_CACHE_TTL_SECONDS: int = settings.refund_cache_ttl_seconds
+_refund_cache_lock: asyncio.Lock = asyncio.Lock()
+_refund_cache: dict[str, tuple[float, dict[str, str]]] = {}
+
+
+def _cache_key_for_authorization(authorization: str) -> str:
+    return hashlib.sha256(authorization.strip().encode()).hexdigest()
+
+
+async def _refund_cache_get(authorization: str) -> dict[str, str] | None:
+    key = _cache_key_for_authorization(authorization)
+    async with _refund_cache_lock:
+        item = _refund_cache.get(key)
+        if item is None:
+            return None
+        expires_at, value = item
+        if expires_at <= monotonic():
+            del _refund_cache[key]
+            return None
+        return value
+
+
+async def _refund_cache_set(authorization: str, value: dict[str, str]) -> None:
+    key = _cache_key_for_authorization(authorization)
+    expiry = monotonic() + _REFUND_CACHE_TTL_SECONDS
+    async with _refund_cache_lock:
+        _refund_cache[key] = (expiry, value)
+
+
+@router.post("/refund")
+async def refund_wallet_endpoint(
+    authorization: Annotated[str, Header(...)],
+    session: AsyncSession = Depends(get_session),
+) -> dict[str, str]:
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid authorization. Use 'Bearer <cashu-token>' or 'Bearer <api-key>'",
+        )
+
+    bearer_value: str = authorization[7:]
+
+    if cached := await _refund_cache_get(bearer_value):
+        return cached
+
+    key: ApiKey = await validate_bearer_key(bearer_value, session)
+    remaining_balance_msats: int = key.balance
+
+    if key.refund_currency == "sat":
+        remaining_balance = remaining_balance_msats // 1000
+    else:
+        remaining_balance = remaining_balance_msats
+
+    if remaining_balance_msats > 0 and remaining_balance <= 0:
+        raise HTTPException(status_code=400, detail="Balance too small to refund")
+    elif remaining_balance <= 0:
+        raise HTTPException(status_code=400, detail="No balance to refund")
+
+    # Perform refund operation first, before modifying balance
+    try:
+        if key.refund_address:
+            from .core.settings import settings as global_settings
+
+            await send_to_lnurl(
+                remaining_balance,
+                key.refund_currency or "sat",
+                key.refund_mint_url or global_settings.primary_mint,
+                key.refund_address,
+            )
+            result = {"recipient": key.refund_address}
+        else:
+            refund_currency = key.refund_currency or "sat"
+            token = await send_token(
+                remaining_balance, refund_currency, key.refund_mint_url
+            )
+            result = {"token": token}
+
+        if key.refund_currency == "sat":
+            result["sats"] = str(remaining_balance_msats // 1000)
+        else:
+            result["msats"] = str(remaining_balance_msats)
+
+    except HTTPException:
+        # Re-raise HTTP exceptions (like 400 for balance too small)
+        raise
+    except Exception as e:
+        # If refund fails, don't modify the database
+        error_msg = str(e)
+        if (
+            "mint" in error_msg.lower()
+            or "connection" in error_msg.lower()
+            or isinstance(e, Exception)
+            and "ConnectError" in str(type(e))
+        ):
+            raise HTTPException(status_code=503, detail="Mint service unavailable")
+        else:
+            raise HTTPException(status_code=500, detail="Refund failed")
+
+    await _refund_cache_set(bearer_value, result)
+
+    await session.delete(key)
+    await session.commit()
+
+    return result
+
+
+@router.post("/donate")
+async def donate(token: str, ref: str | None = None) -> str:
+    try:
+        amount, unit, _ = await recieve_token(token)
+        if ref:
+            logger.info(
+                "donation received", extra={"ref": ref, "amount": amount, "unit": unit}
+            )
+        return "Thanks!"
+    except Exception:
+        return "Invalid token."
+
+
+@router.api_route(
+    "/{path:path}",
+    methods=["GET", "POST", "PUT", "DELETE"],
+    include_in_schema=False,
+    response_model=None,
+)
+async def wallet_catch_all(path: str) -> NoReturn:
+    raise HTTPException(
+        status_code=404, detail="Not found check /docs for available endpoints"
+    )
+
+
+balance_router.include_router(lightning_router)
+balance_router.include_router(router)
+
+deprecated_wallet_router = APIRouter(prefix="/v1/wallet", include_in_schema=False)
+deprecated_wallet_router.include_router(router)

routstr/core/__init__.py

@@ -0,0 +1,3 @@
+from .logging import get_logger
+
+__all__ = ["get_logger"]

routstr/core/db.py

@@ -0,0 +1,181 @@
+import os
+import time
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from alembic import command
+from alembic.config import Config
+from sqlalchemy.ext.asyncio.engine import create_async_engine
+from sqlmodel import Field, Relationship, SQLModel, func, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite+aiosqlite:///keys.db")
+
+
+engine = create_async_engine(DATABASE_URL, echo=False)  # echo=True for debugging SQL
+
+
+class ApiKey(SQLModel, table=True):  # type: ignore
+    __tablename__ = "api_keys"
+
+    hashed_key: str = Field(primary_key=True)
+    balance: int = Field(default=0, description="Balance in millisatoshis (msats)")
+    reserved_balance: int = Field(
+        default=0, description="Reserved balance in millisatoshis (msats)"
+    )
+    refund_address: str | None = Field(
+        default=None,
+        description="Lightning address to refund remaining balance after key expires",
+    )
+    key_expiry_time: int | None = Field(
+        default=None,
+        description="Unix-timestamp after which the cashu-token's balance gets refunded to the refund_address",
+    )
+    total_spent: int = Field(
+        default=0, description="Total spent in millisatoshis (msats)"
+    )
+    total_requests: int = Field(default=0)
+    refund_mint_url: str | None = Field(
+        default=None,
+        description="URL of the mint used to create the cashu-token",
+    )
+    refund_currency: str | None = Field(
+        default=None,
+        description="Currency of the cashu-token",
+    )
+
+    @property
+    def total_balance(self) -> int:
+        return self.balance - self.reserved_balance
+
+
+class ModelRow(SQLModel, table=True):  # type: ignore
+    __tablename__ = "models"
+    id: str = Field(primary_key=True)
+    upstream_provider_id: int = Field(
+        primary_key=True, foreign_key="upstream_providers.id", ondelete="CASCADE"
+    )
+    name: str = Field()
+    created: int = Field()
+    description: str = Field()
+    context_length: int = Field()
+    architecture: str = Field()
+    pricing: str = Field()
+    sats_pricing: str | None = Field(default=None)
+    per_request_limits: str | None = Field(default=None)
+    top_provider: str | None = Field(default=None)
+    canonical_slug: str | None = Field(default=None, description="Canonical model slug")
+    alias_ids: str | None = Field(
+        default=None, description="JSON array of model alias IDs"
+    )
+    enabled: bool = Field(default=True, description="Whether this model is enabled")
+    upstream_provider: "UpstreamProviderRow" = Relationship(back_populates="models")
+
+
+class LightningInvoice(SQLModel, table=True):  # type: ignore
+    __tablename__ = "lightning_invoices"
+
+    id: str = Field(primary_key=True, description="Unique invoice identifier")
+    bolt11: str = Field(description="BOLT11 invoice string", unique=True)
+    amount_sats: int = Field(description="Amount in satoshis")
+    description: str = Field(description="Invoice description")
+    payment_hash: str = Field(description="Payment hash for tracking", unique=True)
+    status: str = Field(
+        default="pending", description="pending, paid, expired, cancelled"
+    )
+    api_key_hash: str | None = Field(
+        default=None, description="Associated API key hash for topup operations"
+    )
+    purpose: str = Field(description="create or topup")
+    created_at: int = Field(
+        default_factory=lambda: int(time.time()), description="Unix timestamp"
+    )
+    expires_at: int = Field(description="Unix timestamp when invoice expires")
+    paid_at: int | None = Field(default=None, description="Unix timestamp when paid")
+
+
+class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
+    __tablename__ = "upstream_providers"
+    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")
+    api_key: str = Field(description="API key for the upstream provider")
+    api_version: str | None = Field(
+        default=None, description="API version for Azure OpenAI"
+    )
+    enabled: bool = Field(default=True, description="Whether this provider is enabled")
+    provider_fee: float = Field(
+        default=1.01, description="Provider fee multiplier (default 1%)"
+    )
+    models: list["ModelRow"] = Relationship(
+        back_populates="upstream_provider",
+        sa_relationship_kwargs={"cascade": "all, delete-orphan"},
+    )
+
+
+async def balances_for_mint_and_unit(
+    db_session: AsyncSession, mint_url: str, unit: str
+) -> int:
+    query = select(func.sum(ApiKey.balance)).where(
+        ApiKey.refund_mint_url == mint_url, ApiKey.refund_currency == unit
+    )
+    result = await db_session.exec(query)
+    return result.one() or 0
+
+
+async def init_db() -> None:
+    """Initializes the database and creates tables if they don't exist."""
+    async with engine.begin() as conn:
+        if DATABASE_URL.startswith("sqlite"):
+            await conn.exec_driver_sql("PRAGMA journal_mode=WAL")
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with AsyncSession(engine, expire_on_commit=False) as session:
+        yield session
+
+
+@asynccontextmanager
+async def create_session() -> AsyncGenerator[AsyncSession, None]:
+    async with AsyncSession(engine, expire_on_commit=False) as session:
+        yield session
+
+
+def run_migrations() -> None:
+    """Run Alembic migrations programmatically."""
+    import pathlib
+
+    try:
+        # Get the path to the alembic.ini file
+        project_root = pathlib.Path(__file__).resolve().parents[2]
+        alembic_ini_path = project_root / "alembic.ini"
+
+        if not alembic_ini_path.exists():
+            raise FileNotFoundError(
+                f"Alembic configuration file not found at {alembic_ini_path}"
+            )
+
+        # Create Alembic config object
+        alembic_cfg = Config(str(alembic_ini_path))
+
+        # Set the database URL in the config
+        alembic_cfg.set_main_option("sqlalchemy.url", DATABASE_URL)
+
+        # Run migrations to the latest revision
+        command.upgrade(alembic_cfg, "head")
+
+        logger.info("Database migrations completed successfully")
+
+    except Exception as e:
+        logger.error(
+            "Database migration failed",
+            extra={"error": str(e), "error_type": type(e).__name__},
+        )
+        raise

routstr/core/exceptions.py

@@ -0,0 +1,57 @@
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+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")
+
+    # Get status code and detail - works for both FastAPI and Starlette HTTPException
+    status_code = getattr(exc, "status_code", 500)
+    detail = getattr(exc, "detail", str(exc))
+
+    logger.warning(
+        "HTTP exception",
+        extra={
+            "request_id": request_id,
+            "status_code": status_code,
+            "detail": detail,
+            "path": request.url.path,
+        },
+    )
+
+    return JSONResponse(
+        status_code=status_code,
+        content={
+            "detail": detail,
+            "request_id": request_id,
+        },
+    )
+
+
+async def general_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Handle general exceptions and include request ID in response."""
+    request_id = getattr(request.state, "request_id", "unknown")
+
+    logger.error(
+        "Unhandled exception",
+        extra={
+            "request_id": request_id,
+            "error": str(exc),
+            "error_type": type(exc).__name__,
+            "path": request.url.path,
+        },
+        exc_info=True,
+    )
+
+    return JSONResponse(
+        status_code=500,
+        content={
+            "detail": "Internal server error, please contact support with the request ID.",
+            "request_id": request_id,
+        },
+    )

routstr/core/log_manager.py

@@ -0,0 +1,511 @@
+import json
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class LogManager:
+    def __init__(self, logs_dir: Path = Path("logs")):
+        self.logs_dir = logs_dir
+
+    def _yield_log_entries(
+        self,
+        hours_back: int | None = None,
+        specific_date: str | None = None,
+        reverse_files: bool = False,
+        max_files: int | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        """
+        Yields log entries from files.
+
+        Args:
+            hours_back: specific number of hours to look back.
+            specific_date: specific date string (YYYY-MM-DD) to look at.
+            reverse_files: if True, process files in reverse order (newest first).
+            max_files: maximum number of log files to process (most recent if reverse_files is True).
+        """
+        if not self.logs_dir.exists():
+            return
+
+        log_files = []
+        cutoff_date = None
+
+        if specific_date:
+            log_file = self.logs_dir / f"app_{specific_date}.log"
+            if log_file.exists():
+                log_files.append(log_file)
+        else:
+            log_files = sorted(self.logs_dir.glob("app_*.log"))
+            if reverse_files:
+                log_files.reverse()
+
+            # If we only care about hours back, we can optimize file selection
+            if hours_back is not None:
+                cutoff_date = datetime.now(timezone.utc) - timedelta(hours=hours_back)
+                filtered_files = []
+                for log_path in log_files:
+                    try:
+                        file_date_str = log_path.stem.split("_")[1]
+                        file_date = datetime.strptime(
+                            file_date_str, "%Y-%m-%d"
+                        ).replace(tzinfo=timezone.utc)
+                        # Include file if it's from the same day or after the cutoff day
+                        if file_date >= cutoff_date.replace(
+                            hour=0, minute=0, second=0, microsecond=0
+                        ):
+                            filtered_files.append(log_path)
+                    except Exception:
+                        continue
+                log_files = filtered_files
+
+            if max_files is not None and len(log_files) > max_files:
+                log_files = log_files[:max_files]
+
+        for log_file in log_files:
+            try:
+                with open(log_file, "r") as f:
+                    # For reverse search, we might want to read lines in reverse?
+                    # But usually logs are append-only.
+                    # If reverse_files is True, we iterate files newest to oldest.
+                    # But lines within file are still oldest to newest unless we reverse them.
+                    lines = f.readlines()
+                    if reverse_files:
+                        lines.reverse()
+
+                    for line in lines:
+                        try:
+                            entry = json.loads(line.strip())
+
+                            if cutoff_date:
+                                timestamp_str = entry.get("asctime", "")
+                                if not timestamp_str:
+                                    continue
+                                log_time = datetime.strptime(
+                                    timestamp_str, "%Y-%m-%d %H:%M:%S"
+                                )
+                                log_time = log_time.replace(tzinfo=timezone.utc)
+                                if log_time < cutoff_date:
+                                    continue
+
+                            yield entry
+                        except json.JSONDecodeError:
+                            continue
+            except Exception as e:
+                logger.error(f"Error processing log file {log_file}: {e}")
+                continue
+
+    def search_logs(
+        self,
+        date: str | None = None,
+        level: str | None = None,
+        request_id: str | None = None,
+        search_text: str | None = None,
+        status_codes: list[int] | None = None,
+        methods: list[str] | None = None,
+        endpoints: list[str] | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """
+        Search through log files and return matching entries.
+        """
+        log_entries: list[dict[str, Any]] = []
+
+        # Use reverse=True to get newest logs first by default
+        # If date is specified, we only look at that file
+
+        search_text_lower = search_text.lower() if search_text else None
+
+        # We iterate efficiently
+        iterator = self._yield_log_entries(
+            specific_date=date,
+            reverse_files=True if not date else False,
+            max_files=7 if not date else None,
+        )
+
+        # If we are searching globally (no date), we might want to limit how far back we go?
+        # PR 228 did: "glob("app_*.log") sorted by mtime reverse [:7]" (last 7 files)
+        # My _yield_log_entries with reverse_files=True does all files.
+        # Let's rely on limit to stop us.
+
+        # Optimization: if we are not searching by date, maybe limit to last 7 files inside _yield?
+        # For now, let's just iterate.
+
+        for log_data in iterator:
+            if not self._matches_filters(
+                log_data,
+                level,
+                request_id,
+                search_text_lower,
+                status_codes,
+                methods,
+                endpoints,
+            ):
+                continue
+
+            log_entries.append(log_data)
+
+            if len(log_entries) >= limit:
+                break
+
+        # Sort by time descending (newest first)
+        log_entries.sort(key=lambda x: x.get("asctime", ""), reverse=True)
+        return log_entries
+
+    def _matches_filters(
+        self,
+        log_data: dict[str, Any],
+        level: str | None,
+        request_id: str | None,
+        search_text_lower: str | None,
+        status_codes: list[int] | None = None,
+        methods: list[str] | None = None,
+        endpoints: list[str] | None = None,
+    ) -> bool:
+        if level and log_data.get("levelname", "").upper() != level.upper():
+            return False
+
+        if request_id and log_data.get("request_id") != request_id:
+            return False
+
+        if status_codes:
+            entry_status = log_data.get("status_code")
+            if entry_status is not None:
+                try:
+                    if int(entry_status) not in status_codes:
+                        return False
+                except (ValueError, TypeError):
+                    return False
+            else:
+                return False
+
+        if methods:
+            entry_method = log_data.get("method", "").upper()
+            if entry_method not in [m.upper() for m in methods]:
+                return False
+
+        if endpoints:
+            entry_path = log_data.get("path", "")
+            matched = False
+            for endpoint in endpoints:
+                clean_endpoint = endpoint.lstrip("/")
+                if entry_path.startswith(clean_endpoint):
+                    matched = True
+                    break
+                if clean_endpoint in entry_path:
+                    matched = True
+                    break
+            if not matched:
+                return False
+
+        if search_text_lower:
+            message = str(log_data.get("message", "")).lower()
+            name = str(log_data.get("name", "")).lower()
+            pathname = str(log_data.get("pathname", "")).lower()
+
+            if (
+                search_text_lower not in message
+                and search_text_lower not in name
+                and search_text_lower not in pathname
+            ):
+                return False
+
+        return True
+
+    def get_usage_summary(self, hours: int = 24) -> dict:
+        entries = list(self._yield_log_entries(hours_back=hours))
+        return self._calculate_summary_stats(entries)
+
+    def get_usage_metrics(self, interval: int = 15, hours: int = 24) -> dict:
+        entries = list(self._yield_log_entries(hours_back=hours))
+        return self._aggregate_metrics_by_time(entries, interval, hours)
+
+    def get_error_details(self, hours: int = 24, limit: int = 100) -> dict:
+        errors: list[dict] = []
+        # Iterate newest to oldest for errors?
+        # yield_log_entries sorts files by name (date) ascending by default.
+        # usage stats logic usually expects ascending time for aggregation (though dictionaries don't care).
+        # For error details "last N errors", we probably want newest first.
+
+        # Using list() loads everything into memory, which is what PR 229 did.
+        # For optimization, we could use reverse iterator.
+
+        # Let's just stick to PR 229 logic which filters 'ERROR' level.
+
+        entries = self._yield_log_entries(hours_back=hours)  # oldest to newest
+
+        for entry in entries:
+            if entry.get("levelname", "").upper() == "ERROR":
+                timestamp_str = entry.get("asctime", "")
+                errors.append(
+                    {
+                        "timestamp": timestamp_str,
+                        "message": entry.get("message", ""),
+                        "error_type": entry.get("error_type", "unknown"),
+                        "pathname": entry.get("pathname", ""),
+                        "lineno": entry.get("lineno", 0),
+                        "request_id": entry.get("request_id", ""),
+                    }
+                )
+
+        # Sort reverse time
+        errors.sort(key=lambda x: x["timestamp"], reverse=True)
+        return {"errors": errors[:limit], "total_count": len(errors)}
+
+    def get_revenue_by_model(self, hours: int = 24, limit: int = 20) -> dict:
+        entries = list(self._yield_log_entries(hours_back=hours))
+
+        model_stats: dict[str, dict[str, int | float]] = defaultdict(
+            lambda: {
+                "revenue_msats": 0,
+                "refunds_msats": 0,
+                "requests": 0,
+                "successful": 0,
+                "failed": 0,
+            }
+        )
+
+        for entry in entries:
+            try:
+                model = entry.get("model", "unknown")
+                if not isinstance(model, str):
+                    model = "unknown"
+
+                message = entry.get("message", "").lower()
+
+                if "received proxy request" in message:
+                    model_stats[model]["requests"] += 1
+
+                if (
+                    "completed for streaming" in message
+                    or "completed for non-streaming" in message
+                ):
+                    model_stats[model]["successful"] += 1
+                    cost_data = entry.get("cost_data")
+                    if isinstance(cost_data, dict):
+                        actual_cost = cost_data.get("total_msats", 0)
+                        if isinstance(actual_cost, (int, float)) and actual_cost > 0:
+                            model_stats[model]["revenue_msats"] += actual_cost
+
+                if "revert payment" in message or "upstream request failed" in message:
+                    model_stats[model]["failed"] += 1
+                    if "revert payment" in message:
+                        max_cost = entry.get("max_cost_for_model", 0)
+                        if isinstance(max_cost, (int, float)) and max_cost > 0:
+                            model_stats[model]["refunds_msats"] += max_cost
+
+            except Exception:
+                continue
+
+        models: list[dict[str, Any]] = []
+        total_revenue = 0.0
+
+        for model, stats in model_stats.items():
+            revenue_msats = float(stats["revenue_msats"])
+            refunds_msats = float(stats["refunds_msats"])
+
+            revenue_sats = revenue_msats / 1000
+            refunds_sats = refunds_msats / 1000
+            net_revenue_sats = revenue_sats - refunds_sats
+
+            total_revenue += net_revenue_sats
+
+            requests = int(stats["requests"])
+            successful = int(stats["successful"])
+
+            models.append(
+                {
+                    "model": model,
+                    "revenue_sats": revenue_sats,
+                    "refunds_sats": refunds_sats,
+                    "net_revenue_sats": net_revenue_sats,
+                    "requests": requests,
+                    "successful": successful,
+                    "failed": int(stats["failed"]),
+                    "avg_revenue_per_request": (
+                        revenue_sats / successful if successful > 0 else 0
+                    ),
+                }
+            )
+
+        models.sort(key=lambda x: float(x["net_revenue_sats"]), reverse=True)
+
+        return {
+            "models": models[:limit],
+            "total_revenue_sats": total_revenue,
+            "total_models": len(models),
+        }
+
+    def _calculate_summary_stats(self, entries: list[dict]) -> dict:
+        stats: dict[str, Any] = {
+            "total_entries": 0,
+            "total_requests": 0,
+            "successful_chat_completions": 0,
+            "failed_requests": 0,
+            "total_errors": 0,
+            "total_warnings": 0,
+            "payment_processed": 0,
+            "upstream_errors": 0,
+            "unique_models": set(),
+            "error_types": defaultdict(int),
+            "revenue_msats": 0.0,
+            "refunds_msats": 0.0,
+        }
+
+        for entry in entries:
+            try:
+                stats["total_entries"] += 1
+
+                message = entry.get("message", "").lower()
+                level = entry.get("levelname", "").upper()
+
+                if level == "ERROR":
+                    stats["total_errors"] += 1
+                    if "error_type" in entry:
+                        stats["error_types"][str(entry["error_type"])] += 1
+                elif level == "WARNING":
+                    stats["total_warnings"] += 1
+
+                if "received proxy request" in message:
+                    stats["total_requests"] += 1
+
+                if (
+                    "completed for streaming" in message
+                    or "completed for non-streaming" in message
+                ):
+                    stats["successful_chat_completions"] += 1
+
+                if "upstream request failed" in message or "revert payment" in message:
+                    stats["failed_requests"] += 1
+
+                if "payment processed successfully" in message:
+                    stats["payment_processed"] += 1
+
+                if "upstream" in message and level == "ERROR":
+                    stats["upstream_errors"] += 1
+
+                if "model" in entry:
+                    model = entry["model"]
+                    if isinstance(model, str) and model != "unknown":
+                        stats["unique_models"].add(model)
+
+                if (
+                    "completed for streaming" in message
+                    or "completed for non-streaming" in message
+                ):
+                    cost_data = entry.get("cost_data")
+                    if isinstance(cost_data, dict):
+                        actual_cost = cost_data.get("total_msats", 0)
+                        if isinstance(actual_cost, (int, float)) and actual_cost > 0:
+                            stats["revenue_msats"] += float(actual_cost)
+
+                if "revert payment" in message:
+                    max_cost = entry.get("max_cost_for_model", 0)
+                    if isinstance(max_cost, (int, float)) and max_cost > 0:
+                        stats["refunds_msats"] += float(max_cost)
+
+            except Exception:
+                continue
+
+        revenue_sats = stats["revenue_msats"] / 1000
+        refunds_sats = stats["refunds_msats"] / 1000
+        net_revenue_sats = revenue_sats - refunds_sats
+
+        total_requests = stats["total_requests"]
+        successful = stats["successful_chat_completions"]
+
+        return {
+            "total_entries": stats["total_entries"],
+            "total_requests": total_requests,
+            "successful_chat_completions": successful,
+            "failed_requests": stats["failed_requests"],
+            "total_errors": stats["total_errors"],
+            "total_warnings": stats["total_warnings"],
+            "payment_processed": stats["payment_processed"],
+            "upstream_errors": stats["upstream_errors"],
+            "unique_models_count": len(stats["unique_models"]),
+            "unique_models": sorted(list(stats["unique_models"])),
+            "error_types": dict(stats["error_types"]),
+            "success_rate": (successful / total_requests * 100)
+            if total_requests > 0
+            else 0,
+            "revenue_msats": stats["revenue_msats"],
+            "refunds_msats": stats["refunds_msats"],
+            "revenue_sats": revenue_sats,
+            "refunds_sats": refunds_sats,
+            "net_revenue_msats": stats["revenue_msats"] - stats["refunds_msats"],
+            "net_revenue_sats": net_revenue_sats,
+            "avg_revenue_per_request_msats": (
+                stats["revenue_msats"] / successful if successful > 0 else 0
+            ),
+            "refund_rate": (
+                (stats["failed_requests"] / total_requests * 100)
+                if total_requests > 0
+                else 0
+            ),
+        }
+
+    def _aggregate_metrics_by_time(
+        self, entries: list[dict], interval_minutes: int, hours_back: int
+    ) -> dict:
+        time_buckets: dict[str, dict[str, Any]] = defaultdict(
+            lambda: {"requests": 0, "errors": 0, "revenue_msats": 0.0}
+        )
+
+        for entry in entries:
+            try:
+                timestamp_str = entry.get("asctime", "")
+                if not timestamp_str:
+                    continue
+
+                log_time = datetime.strptime(timestamp_str, "%Y-%m-%d %H:%M:%S")
+                log_time = log_time.replace(tzinfo=timezone.utc)
+
+                # Round down to nearest interval
+                minutes = log_time.minute
+                rounded_minutes = (minutes // interval_minutes) * interval_minutes
+                bucket_time = log_time.replace(
+                    minute=rounded_minutes, second=0, microsecond=0
+                )
+                bucket_key = bucket_time.strftime("%Y-%m-%d %H:%M:%S")
+
+                bucket = time_buckets[bucket_key]
+
+                message = entry.get("message", "").lower()
+                level = entry.get("levelname", "").upper()
+
+                if "received proxy request" in message:
+                    bucket["requests"] += 1
+
+                if level == "ERROR":
+                    bucket["errors"] += 1
+
+                if (
+                    "completed for streaming" in message
+                    or "completed for non-streaming" in message
+                ):
+                    cost_data = entry.get("cost_data")
+                    if isinstance(cost_data, dict):
+                        actual_cost = cost_data.get("total_msats", 0)
+                        if isinstance(actual_cost, (int, float)) and actual_cost > 0:
+                            bucket["revenue_msats"] += float(actual_cost)
+            except Exception:
+                continue
+
+        result = []
+        for bucket_key in sorted(time_buckets.keys()):
+            result.append({"timestamp": bucket_key, **time_buckets[bucket_key]})
+
+        return {
+            "metrics": result,
+            "interval_minutes": interval_minutes,
+            "hours_back": hours_back,
+            "total_buckets": len(result),
+        }
+
+
+log_manager = LogManager()

routstr/core/logging.py

@@ -1,3 +1,40 @@
+"""
+Logging configuration for Routstr.
+
+CRITICAL LOG MESSAGES FOR USAGE STATISTICS:
+===========================================
+The following log messages are parsed by the usage tracking system (routstr/core/admin.py).
+DO NOT modify or remove these messages without updating the usage tracking logic:
+
+1. "Received proxy request" (INFO) - routstr/proxy.py
+   - Used to count total incoming requests
+   - Includes model information in context
+
+    2. "Payment adjustment completed for streaming" (INFO) - routstr/upstream/base.py
+       "Payment adjustment completed for non-streaming" (INFO) - routstr/upstream/base.py
+   - Used to track successful completions and revenue
+   - The 'cost_data.total_msats' field is extracted for revenue calculation
+   - Must include 'cost_data' in extra dict
+
+3. "Payment processed successfully" (INFO) - routstr/auth.py
+   - Used to count successful payment processing events
+   - Tracks payment-related metrics
+
+4. "Upstream request failed, revert payment" (WARNING) - routstr/proxy.py
+   - Used to track failed requests and refunds
+   - The 'max_cost_for_model' field is extracted for refund calculation
+   - Must include 'max_cost_for_model' in extra dict
+
+5. Any ERROR level logs with "upstream" in the message
+   - Used to count upstream provider errors
+   - Helps identify service reliability issues
+
+If you need to modify these messages, ensure you also update the parsing logic in:
+- routstr/core/admin.py:_aggregate_metrics_by_time()
+- routstr/core/admin.py:_get_summary_stats()
+- routstr/core/admin.py:get_revenue_by_model()
+"""
+
 import logging.config
 import logging.handlers
 import os
@@ -8,6 +45,21 @@ from pathlib import Path
 from typing import Any
 
 from pythonjsonlogger import jsonlogger
+from rich.logging import RichHandler
+
+# Define custom TRACE level
+TRACE_LEVEL = 5
+logging.addLevelName(TRACE_LEVEL, "TRACE")
+
+
+def trace(self: logging.Logger, message: str, *args: Any, **kwargs: Any) -> None:
+    """Log with TRACE level"""
+    if self.isEnabledFor(TRACE_LEVEL):
+        self._log(TRACE_LEVEL, message, args, **kwargs)
+
+
+# Add the trace method to Logger class
+setattr(logging.Logger, "trace", trace)
 
 
 class DailyRotatingFileHandler(logging.handlers.TimedRotatingFileHandler):
@@ -74,7 +126,7 @@ def get_package_version() -> str:
                 return version
             current_path = current_path.parent
 
-        # Fallback: try the simple path resolution (3 levels up for router/logging/logging_config.py)
+        # Fallback: try the simple path resolution (3 levels up for routstr/logging/logging_config.py)
         pyproject_path = Path(__file__).parent.parent.parent / "pyproject.toml"
         if pyproject_path.exists():
             with open(pyproject_path, "rb") as f:
@@ -100,6 +152,23 @@ class VersionFilter(logging.Filter):
         return True
 
 
+class RequestIdFilter(logging.Filter):
+    """Filter to add request ID to all log records."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Add request ID to the log record if available."""
+        try:
+            # Import here to avoid circular imports
+            from .middleware import request_id_context
+
+            request_id = request_id_context.get(None)
+            record.request_id = request_id if request_id else "no-request-id"
+        except ImportError:
+            # If middleware isn't available yet, just use default
+            record.request_id = "no-request-id"
+        return True
+
+
 class SecurityFilter(logging.Filter):
     """Filter to remove sensitive information from logs."""
 
@@ -123,21 +192,24 @@ class SecurityFilter(logging.Filter):
         """Filter out sensitive information from log records."""
         try:
             message = record.getMessage()
+            standalone_patterns = [
+                r"Bearer\s+([a-zA-Z0-9_\-\.]{10,})",  # Bearer token (must be 10 characters or more to reduce false-positives)
+                r"cashu[A-Z]+([a-zA-Z0-9_\-\.=/+]+)",  # Cashu tokens
+                r"nsec[a-z0-9]+",  # Nostr Public / Private Key
+            ]
+            for pattern in standalone_patterns:
+                message = re.sub(pattern, "[REDACTED]", message, flags=re.IGNORECASE)
 
             for key in self.SENSITIVE_KEYS:
                 if key in message.lower():
-                    patterns = [
-                        rf"{key}[:\s=]+([a-zA-Z0-9_\-\.]+)",  # key: value or key=value
-                        rf'{key}[:\s=]+["\']([^"\']+)["\']',  # key: "value" or key='value'
-                        r"Bearer\s+([a-zA-Z0-9_\-\.]+)",  # Bearer token
-                        r"cashu[A-Z]+([a-zA-Z0-9_\-\.=/+]+)",  # Cashu tokens
+                    key_patterns = [
+                        rf"{key}\s*[:=]\s*([a-zA-Z0-9_\-\.=/+]+)",  # key:value or key=value (including any variant with spaces)
+                        rf'{key}\s*[:=]\s*["\']([^"\']+)["\']',  # key:"value" or key='value' (including any variant with spaces)
                     ]
-
-                    for pattern in patterns:
+                    for pattern in key_patterns:
                         message = re.sub(
                             pattern, f"{key}: [REDACTED]", message, flags=re.IGNORECASE
                         )
-
             record.msg = message
             record.args = ()
 
@@ -149,13 +221,43 @@ class SecurityFilter(logging.Filter):
 
 def get_log_level() -> str:
     """Get log level from environment variable."""
-    return os.environ.get("LOG_LEVEL", "INFO").upper()
+    try:
+        from .settings import settings
+
+        level = settings.log_level.upper()
+    except Exception:
+        level = os.environ.get("LOG_LEVEL", "INFO").upper()
+    # Validate log level - if invalid, default to INFO
+    valid_levels = {"TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+    if level not in valid_levels:
+        level = "INFO"
+    return level
+
+
+def should_enable_console_logging() -> bool:
+    """Check if console logging should be enabled."""
+    try:
+        from .settings import settings
+
+        return bool(settings.enable_console_logging)
+    except Exception:
+        return os.environ.get("ENABLE_CONSOLE_LOGGING", "true").lower() in (
+            "true",
+            "1",
+            "yes",
+        )
 
 
 def setup_logging() -> None:
     """Configure centralized logging for the application."""
 
     log_level = get_log_level()
+    console_enabled = should_enable_console_logging()
+
+    # Determine which handlers to use
+    handlers = ["file"]
+    if console_enabled:
+        handlers.append("console")
 
     LOGGING_CONFIG = {
         "version": 1,
@@ -163,27 +265,24 @@ def setup_logging() -> None:
         "formatters": {
             "json": {
                 "()": jsonlogger.JsonFormatter,
-                "format": "%(asctime)s %(name)s %(levelname)s %(message)s %(pathname)s %(lineno)d %(version)s",
-                "datefmt": "%Y-%m-%d %H:%M:%S",
-            },
-            "standard": {
-                "format": "%(asctime)s [%(levelname)s] %(name)s v%(version)s: %(message)s",
+                "format": "%(asctime)s %(name)s %(levelname)s %(message)s %(pathname)s %(lineno)d %(version)s %(request_id)s",
                 "datefmt": "%Y-%m-%d %H:%M:%S",
             },
         },
         "filters": {
             "version_filter": {"()": VersionFilter},
+            "request_id_filter": {"()": RequestIdFilter},
             "security_filter": {"()": SecurityFilter},
         },
         "handlers": {
             "console": {
-                "class": "logging.StreamHandler",
+                "()": RichHandler,
                 "level": log_level,
-                "formatter": "json"
-                if os.environ.get("LOG_FORMAT", "json").lower() == "json"
-                else "standard",
-                "stream": "ext://sys.stdout",
-                "filters": ["version_filter", "security_filter"],
+                "show_time": False,
+                "show_path": False,
+                "rich_tracebacks": True,
+                "markup": True,
+                "filters": ["request_id_filter", "security_filter"],
             },
             "file": {
                 "()": DailyRotatingFileHandler,
@@ -194,53 +293,88 @@ def setup_logging() -> None:
                 "interval": 1,  # Every 1 day
                 "backupCount": 30,  # Keep 30 days of logs
                 "atTime": None,  # Rotate at midnight (00:00)
-                "filters": ["version_filter", "security_filter"],
+                "filters": ["version_filter", "request_id_filter", "security_filter"],
             },
         },
         "loggers": {
-            "router": {
+            "routstr": {
                 "level": log_level,
-                "handlers": ["console", "file"],
+                "handlers": handlers,
                 "propagate": False,
             },
-            "router.payment": {
+            "routstr.payment": {
                 "level": log_level,
-                "handlers": ["console", "file"],
+                "handlers": handlers,
                 "propagate": False,
             },
-            "router.cashu": {
+            "routstr.proxy": {
                 "level": log_level,
-                "handlers": ["console", "file"],
+                "handlers": handlers,
                 "propagate": False,
             },
-            "router.proxy": {
+            "routstr.auth": {
                 "level": log_level,
-                "handlers": ["console", "file"],
+                "handlers": handlers,
                 "propagate": False,
             },
-            "router.auth": {
+            "routstr.payment.models": {
                 "level": log_level,
-                "handlers": ["console", "file"],
+                "handlers": handlers,
+                "propagate": False,
+            },
+            "routstr.core.exceptions": {
+                "level": log_level,
+                "handlers": handlers,
+                "propagate": False,
+            },
+            "routstr.core.middleware": {
+                "level": log_level,
+                "handlers": ["file"],
                 "propagate": False,
             },
             # Suppress verbose third-party logging
             "httpx": {
                 "level": "WARNING",
-                "handlers": ["console"],
+                "handlers": ["console"] if console_enabled else [],
+                "propagate": False,
+            },
+            "openai": {
+                "level": "WARNING",
+                "handlers": ["console"] if console_enabled else [],
                 "propagate": False,
             },
             "httpcore": {
                 "level": "WARNING",
-                "handlers": ["console"],
+                "handlers": ["console"] if console_enabled else [],
+                "propagate": False,
+            },
+            "websockets": {
+                "level": "WARNING",
+                "handlers": [],
                 "propagate": False,
             },
             "uvicorn.access": {
                 "level": "WARNING",
-                "handlers": ["console"],
+                "handlers": ["file"],
+                "propagate": False,
+            },
+            "uvicorn.error": {
+                "level": log_level,
+                "handlers": handlers,
+                "propagate": False,
+            },
+            "watchfiles.main": {"level": "WARNING", "handlers": [], "propagate": False},
+            "aiosqlite": {"level": "ERROR", "handlers": [], "propagate": False},
+            "alembic": {
+                "level": "WARNING",
+                "handlers": ["console"] if console_enabled else [],
                 "propagate": False,
             },
         },
-        "root": {"level": log_level, "handlers": ["console"]},
+        "root": {
+            "level": log_level,
+            "handlers": ["console"] if console_enabled else [],
+        },
     }
 
     os.makedirs("logs", exist_ok=True)

routstr/core/main.py

@@ -0,0 +1,337 @@
+import asyncio
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import AsyncGenerator
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.exceptions import HTTPException
+
+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.price import update_prices_periodically
+from ..proxy import initialize_upstreams, proxy_router, refresh_model_maps_periodically
+from ..wallet import periodic_payout
+from .admin import admin_router
+from .db import create_session, init_db, run_migrations
+from .exceptions import general_exception_handler, http_exception_handler
+from .logging import get_logger, setup_logging
+from .middleware import LoggingMiddleware
+from .settings import SettingsService
+from .settings import settings as global_settings
+
+# Initialize logging first
+setup_logging()
+logger = get_logger(__name__)
+
+if os.getenv("VERSION_SUFFIX") is not None:
+    __version__ = f"0.2.1-{os.getenv('VERSION_SUFFIX')}"
+else:
+    __version__ = "0.2.1"
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
+    logger.info("Application startup initiated", extra={"version": __version__})
+
+    btc_price_task = None
+    pricing_task = None
+    payout_task = None
+    nip91_task = None
+    providers_task = None
+    models_refresh_task = None
+    model_maps_refresh_task = None
+
+    try:
+        # Run database migrations on startup
+        run_migrations()
+
+        # Initialize database connection pools
+        # This creates any tables that might not be tracked by migrations yet
+        await init_db()
+
+        # Initialize application settings (env -> computed -> DB precedence)
+        async with create_session() as session:
+            s = await SettingsService.initialize(session)
+
+        # Apply app metadata from settings
+        try:
+            app.title = s.name
+            app.description = s.description
+        except Exception:
+            pass
+
+        # await ensure_models_bootstrapped()
+
+        from ..payment.price import _update_prices
+        from ..proxy import get_upstreams
+        from ..upstream.helpers import refresh_upstreams_models_periodically
+
+        _update_prices_task = asyncio.create_task(_update_prices())
+        _initialize_upstreams_task = asyncio.create_task(initialize_upstreams())
+
+        # ensure both setup tasks complete
+        await asyncio.gather(
+            _update_prices_task, _initialize_upstreams_task, return_exceptions=True
+        )
+
+        btc_price_task = asyncio.create_task(update_prices_periodically())
+        pricing_task = asyncio.create_task(update_sats_pricing())
+        if global_settings.models_refresh_interval_seconds > 0:
+            models_refresh_task = asyncio.create_task(
+                refresh_upstreams_models_periodically(get_upstreams())
+            )
+        model_maps_refresh_task = asyncio.create_task(refresh_model_maps_periodically())
+        payout_task = asyncio.create_task(periodic_payout())
+        if global_settings.nsec:
+            nip91_task = asyncio.create_task(announce_provider())
+        if global_settings.providers_refresh_interval_seconds > 0:
+            providers_task = asyncio.create_task(providers_cache_refresher())
+
+        yield
+
+    except asyncio.CancelledError:
+        # Expected during shutdown
+        pass
+    except Exception as e:
+        logger.error(
+            "Application startup failed",
+            extra={"error": str(e), "error_type": type(e).__name__},
+        )
+        raise
+    finally:
+        logger.info("Application shutdown initiated")
+
+        if btc_price_task is not None:
+            btc_price_task.cancel()
+        if pricing_task is not None:
+            pricing_task.cancel()
+        if payout_task is not None:
+            payout_task.cancel()
+        if nip91_task is not None:
+            nip91_task.cancel()
+        if providers_task is not None:
+            providers_task.cancel()
+        if models_refresh_task is not None:
+            models_refresh_task.cancel()
+        if model_maps_refresh_task is not None:
+            model_maps_refresh_task.cancel()
+
+        try:
+            tasks_to_wait = []
+            if btc_price_task is not None:
+                tasks_to_wait.append(btc_price_task)
+            if pricing_task is not None:
+                tasks_to_wait.append(pricing_task)
+            if payout_task is not None:
+                tasks_to_wait.append(payout_task)
+            if nip91_task is not None:
+                tasks_to_wait.append(nip91_task)
+            if providers_task is not None:
+                tasks_to_wait.append(providers_task)
+            if models_refresh_task is not None:
+                tasks_to_wait.append(models_refresh_task)
+            if model_maps_refresh_task is not None:
+                tasks_to_wait.append(model_maps_refresh_task)
+
+            if tasks_to_wait:
+                await asyncio.gather(*tasks_to_wait, return_exceptions=True)
+            logger.info("Background tasks stopped successfully")
+        except Exception as e:
+            logger.error(
+                "Error stopping background tasks",
+                extra={"error": str(e), "error_type": type(e).__name__},
+            )
+
+
+app = FastAPI(version=__version__, lifespan=lifespan)
+
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=global_settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+    expose_headers=["x-routstr-request-id"],
+)
+
+# Add logging middleware
+app.add_middleware(LoggingMiddleware)
+
+# Add exception handlers
+app.add_exception_handler(HTTPException, http_exception_handler)  # type: ignore
+app.add_exception_handler(Exception, general_exception_handler)
+
+
+@app.get("/v1/info")
+async def info() -> dict:
+    return {
+        "name": global_settings.name,
+        "description": global_settings.description,
+        "version": __version__,
+        "npub": global_settings.npub,
+        "mints": global_settings.cashu_mints,
+        "http_url": global_settings.http_url,
+        "onion_url": global_settings.onion_url,
+    }
+
+
+@app.get("/v1/providers")
+async def providers() -> RedirectResponse:
+    return RedirectResponse("/v1/providers/")
+
+
+UI_DIST_PATH = Path(__file__).parent.parent.parent / "ui_out"
+
+if UI_DIST_PATH.exists() and UI_DIST_PATH.is_dir():
+    logger.info(f"Serving static UI from {UI_DIST_PATH}")
+
+    app.mount(
+        "/_next",
+        StaticFiles(directory=UI_DIST_PATH / "_next", check_dir=True),
+        name="next-static",
+    )
+
+    @app.get("/", include_in_schema=False)
+    async def serve_root_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "index.html")
+
+    # Add explicit route for /index.txt to redirect to /
+    @app.get("/index.txt", include_in_schema=False)
+    async def redirect_index_txt() -> RedirectResponse:
+        return RedirectResponse("/")
+
+    @app.get("/admin")
+    async def admin_redirect() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "index.html")
+
+    @app.get("/dashboard", include_in_schema=False)
+    async def serve_dashboard_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "index.html")
+
+    @app.get("/login", include_in_schema=False)
+    async def serve_login_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "login" / "index.html")
+
+    # Add explicit route for /login/index.txt to redirect to /login
+    @app.get("/login/index.txt", include_in_schema=False)
+    async def redirect_login_index_txt() -> RedirectResponse:
+        return RedirectResponse("/login")
+
+    @app.get("/model", include_in_schema=False)
+    async def serve_models_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "model" / "index.html")
+
+    # Add explicit route for /model/index.txt to redirect to /model
+    @app.get("/model/index.txt", include_in_schema=False)
+    async def redirect_model_index_txt() -> RedirectResponse:
+        return RedirectResponse("/model")
+
+    @app.get("/providers", include_in_schema=False)
+    async def serve_providers_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "providers" / "index.html")
+
+    # Add explicit route for /providers/index.txt to redirect to /providers
+    @app.get("/providers/index.txt", include_in_schema=False)
+    async def redirect_providers_index_txt() -> RedirectResponse:
+        return RedirectResponse("/providers")
+
+    @app.get("/settings", include_in_schema=False)
+    async def serve_settings_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "settings" / "index.html")
+
+    # Add explicit route for /settings/index.txt to redirect to /settings
+    @app.get("/settings/index.txt", include_in_schema=False)
+    async def redirect_settings_index_txt() -> RedirectResponse:
+        return RedirectResponse("/settings")
+
+    @app.get("/transactions", include_in_schema=False)
+    async def serve_transactions_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "transactions" / "index.html")
+
+    # Add explicit route for /transactions/index.txt to redirect to /transactions
+    @app.get("/transactions/index.txt", include_in_schema=False)
+    async def redirect_transactions_index_txt() -> RedirectResponse:
+        return RedirectResponse("/transactions")
+
+    @app.get("/balances", include_in_schema=False)
+    async def serve_balances_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "balances" / "index.html")
+
+    # Add explicit route for /balances/index.txt to redirect to /balances
+    @app.get("/balances/index.txt", include_in_schema=False)
+    async def redirect_balances_index_txt() -> RedirectResponse:
+        return RedirectResponse("/balances")
+
+    @app.get("/logs", include_in_schema=False)
+    async def serve_logs_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "logs" / "index.html")
+
+    # Add explicit route for /logs/index.txt to redirect to /logs
+    @app.get("/logs/index.txt", include_in_schema=False)
+    async def redirect_logs_index_txt() -> RedirectResponse:
+        return RedirectResponse("/logs")
+
+    @app.get("/usage", include_in_schema=False)
+    async def serve_usage_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "usage" / "index.html")
+
+    # Add explicit route for /usage/index.txt to redirect to /usage
+    @app.get("/usage/index.txt", include_in_schema=False)
+    async def redirect_usage_index_txt() -> RedirectResponse:
+        return RedirectResponse("/usage")
+
+    @app.get("/unauthorized", include_in_schema=False)
+    async def serve_unauthorized_ui() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "unauthorized" / "index.html")
+
+    # Add explicit route for /unauthorized/index.txt to redirect to /unauthorized
+    @app.get("/unauthorized/index.txt", include_in_schema=False)
+    async def redirect_unauthorized_index_txt() -> RedirectResponse:
+        return RedirectResponse("/unauthorized")
+
+    @app.get("/favicon.ico", include_in_schema=False)
+    async def serve_favicon() -> FileResponse:
+        icon_path = UI_DIST_PATH / "icon.ico"
+        if icon_path.exists():
+            return FileResponse(icon_path)
+        return FileResponse(UI_DIST_PATH / "favicon.ico")
+
+    @app.get("/icon.ico", include_in_schema=False)
+    async def serve_icon() -> FileResponse:
+        return FileResponse(UI_DIST_PATH / "icon.ico")
+
+    app.mount(
+        "/static", StaticFiles(directory=UI_DIST_PATH, check_dir=True), name="ui-static"
+    )
+else:
+    logger.warning(
+        f"UI dist directory not found at {UI_DIST_PATH}, skipping static file serving"
+    )
+
+    @app.get("/", include_in_schema=False)
+    async def root_fallback() -> dict:
+        return {
+            "name": global_settings.name,
+            "description": global_settings.description,
+            "version": __version__,
+            "status": "running",
+            "ui": "not available",
+        }
+
+
+app.include_router(models_router)
+app.include_router(admin_router)
+app.include_router(balance_router)
+app.include_router(deprecated_wallet_router)
+app.include_router(providers_router)
+app.include_router(proxy_router)

routstr/core/middleware.py

@@ -0,0 +1,135 @@
+import time
+import uuid
+from contextvars import ContextVar
+from typing import Callable
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+# Context variable to store request ID across async context
+request_id_context: ContextVar[str | None] = ContextVar("request_id")
+
+
+class LoggingMiddleware(BaseHTTPMiddleware):
+    """Middleware to log detailed request and response information."""
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        # Generate request ID
+        request_id = str(uuid.uuid4())
+        request.state.request_id = request_id
+
+        # Set request ID in context for logging
+        token = request_id_context.set(request_id)
+
+        # Start timing
+        start_time = time.time()
+
+        # Log request details
+        request_body = None
+        if request.method in ["POST", "PUT", "PATCH"]:
+            try:
+                # Only read body for non-streaming requests
+                if hasattr(request, "_body"):
+                    request_body = await request.body()
+            except Exception:
+                pass
+
+        # Extract request info
+        client_host = None
+        if request.client:
+            client_host = request.client.host
+
+        # Log incoming request
+        logger.info(
+            "Incoming request",
+            extra={
+                "request_id": request_id,
+                "method": request.method,
+                "path": request.url.path,
+                "query_params": dict(request.query_params),
+                "client_host": client_host,
+                "headers": {
+                    k: v
+                    for k, v in request.headers.items()
+                    if k.lower()
+                    not in [
+                        "authorization",
+                        "x-cashu",
+                        "cookie",
+                        "cf-connecting-ip",
+                        "cf-ipcountry",
+                        "x-forwarded-for",
+                        "x-real-ip",
+                    ]
+                },
+                "body_size": len(request_body) if request_body else 0,
+            },
+        )
+
+        # Log at TRACE level for full body (security filter will redact sensitive data)
+        if request_body and hasattr(logger, "exception"):
+            logger.exception(
+                "Request body",
+                extra={
+                    "request_id": request_id,
+                    "method": request.method,
+                    "path": request.url.path,
+                    "body": request_body.decode("utf-8", errors="ignore")[
+                        :1000
+                    ],  # Limit size
+                },
+            )
+
+        # Process request
+        try:
+            response = await call_next(request)
+
+            # Calculate duration
+            duration = time.time() - start_time
+
+            # Log response
+            logger.info(
+                "Request completed",
+                extra={
+                    "request_id": request_id,
+                    "method": request.method,
+                    "path": request.url.path,
+                    "status_code": response.status_code,
+                    "duration_ms": round(duration * 1000, 2),
+                    "client_host": client_host,
+                },
+            )
+            if hasattr(response, "headers"):
+                response.headers["x-routstr-request-id"] = request_id
+
+            return response
+
+        except Exception as e:
+            # Calculate duration
+            duration = time.time() - start_time
+
+            # Log error
+            logger.error(
+                "Request failed",
+                extra={
+                    "request_id": request_id,
+                    "method": request.method,
+                    "path": request.url.path,
+                    "duration_ms": round(duration * 1000, 2),
+                    "client_host": client_host,
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                },
+                exc_info=True,
+            )
+            raise
+        finally:
+            # Reset context
+            request_id_context.reset(token)
+
+
+__all__ = ["LoggingMiddleware", "request_id_context"]

routstr/core/settings.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic.v1 import BaseModel, BaseSettings, Field, validator
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+
+class Settings(BaseSettings):
+    class Config:
+        case_sensitive = True
+
+        @classmethod
+        def parse_env_var(cls, field_name: str, raw_value: str) -> Any:  # type: ignore[override]
+            if field_name in {"cashu_mints", "cors_origins", "relays"}:
+                v = str(raw_value).strip()
+                if v == "":
+                    return []
+                return [p.strip() for p in v.split(",") if p.strip()]
+            return raw_value
+
+    # Core
+    upstream_base_url: str = Field(default="", env="UPSTREAM_BASE_URL")
+    upstream_api_key: str = Field(default="", env="UPSTREAM_API_KEY")
+    admin_password: str = Field(default="", env="ADMIN_PASSWORD")
+
+    # Node info
+    name: str = Field(default="ARoutstrNode", env="NAME")
+    description: str = Field(default="A Routstr Node", env="DESCRIPTION")
+    npub: str = Field(default="", env="NPUB")
+    http_url: str = Field(default="", env="HTTP_URL")
+    onion_url: str = Field(default="", env="ONION_URL")
+
+    # Cashu
+    cashu_mints: list[str] = Field(default_factory=list, env="CASHU_MINTS")
+
+    @validator("cashu_mints", pre=True, each_item=True)
+    def normalize_mint_url(cls, v: str) -> str:
+        if isinstance(v, str):
+            return v.rstrip("/")
+        return v
+
+    receive_ln_address: str = Field(default="", env="RECEIVE_LN_ADDRESS")
+    primary_mint: str = Field(default="", env="PRIMARY_MINT_URL")
+    primary_mint_unit: str = Field(default="sat", env="PRIMARY_MINT_UNIT")
+
+    # Pricing
+    # Default behavior: derive pricing from MODELS
+    # If fixed_pricing is True -> use fixed_cost_per_request and ignore tokens
+    # If fixed_per_1k_* are set (non-zero) -> override model token pricing when model-based
+    fixed_pricing: bool = Field(default=False, env="FIXED_PRICING")
+    fixed_cost_per_request: int = Field(default=1, env="FIXED_COST_PER_REQUEST")
+    fixed_per_1k_input_tokens: int = Field(default=0, env="FIXED_PER_1K_INPUT_TOKENS")
+    fixed_per_1k_output_tokens: int = Field(default=0, env="FIXED_PER_1K_OUTPUT_TOKENS")
+    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")
+    # Minimum per-request charge in millisatoshis when model pricing is free/zero
+    min_request_msat: int = Field(default=1, env="MIN_REQUEST_MSAT")
+
+    # Network
+    cors_origins: list[str] = Field(default_factory=lambda: ["*"], env="CORS_ORIGINS")
+    tor_proxy_url: str = Field(default="socks5://127.0.0.1:9050", env="TOR_PROXY_URL")
+    providers_refresh_interval_seconds: int = Field(
+        default=300, env="PROVIDERS_REFRESH_INTERVAL_SECONDS"
+    )
+    pricing_refresh_interval_seconds: int = Field(
+        default=120, env="PRICING_REFRESH_INTERVAL_SECONDS"
+    )
+    models_refresh_interval_seconds: int = Field(
+        default=360, env="MODELS_REFRESH_INTERVAL_SECONDS"
+    )
+    enable_pricing_refresh: bool = Field(default=True, env="ENABLE_PRICING_REFRESH")
+    enable_models_refresh: bool = Field(default=True, env="ENABLE_MODELS_REFRESH")
+    refund_cache_ttl_seconds: int = Field(default=3600, env="REFUND_CACHE_TTL_SECONDS")
+
+    # Logging
+    log_level: str = Field(default="INFO", env="LOG_LEVEL")
+    enable_console_logging: bool = Field(default=True, env="ENABLE_CONSOLE_LOGGING")
+
+    # Other
+    chat_completions_api_version: str = Field(
+        default="", env="CHAT_COMPLETIONS_API_VERSION"
+    )
+    models_path: str = Field(default="models.json", env="MODELS_PATH")
+    source: str = Field(default="", env="SOURCE")
+
+    # Secrets / optional runtime controls
+    provider_id: str = Field(default="", env="PROVIDER_ID")
+    nsec: str = Field(default="", env="NSEC")
+
+    # Discovery
+    relays: list[str] = Field(default_factory=list, env="RELAYS")
+
+
+def _compute_primary_mint(cashu_mints: list[str]) -> str:
+    return cashu_mints[0] if cashu_mints else "https://mint.minibits.cash/Bitcoin"
+
+
+def resolve_bootstrap() -> Settings:
+    base = Settings()  # Reads env with custom parse_env_var
+    # Back-compat env mapping
+    try:
+        # Map MODEL_BASED_PRICING -> fixed_pricing (inverted)
+        if "MODEL_BASED_PRICING" in os.environ and "FIXED_PRICING" not in os.environ:
+            mbp_raw = os.environ.get("MODEL_BASED_PRICING", "").strip().lower()
+            mbp = mbp_raw in {"1", "true", "yes", "on"}
+            base.fixed_pricing = not mbp
+        # Map COST_PER_REQUEST -> fixed_cost_per_request if new not provided
+        if (
+            "COST_PER_REQUEST" in os.environ
+            and "FIXED_COST_PER_REQUEST" not in os.environ
+        ):
+            try:
+                base.fixed_cost_per_request = int(
+                    os.environ["COST_PER_REQUEST"].strip()
+                )
+            except Exception:
+                pass
+        # Map COST_PER_1K_* -> FIXED_PER_1K_*
+        if (
+            "COST_PER_1K_INPUT_TOKENS" in os.environ
+            and "FIXED_PER_1K_INPUT_TOKENS" not in os.environ
+        ):
+            try:
+                base.fixed_per_1k_input_tokens = int(
+                    os.environ["COST_PER_1K_INPUT_TOKENS"].strip()
+                )
+            except Exception:
+                pass
+        if (
+            "COST_PER_1K_OUTPUT_TOKENS" in os.environ
+            and "FIXED_PER_1K_OUTPUT_TOKENS" not in os.environ
+        ):
+            try:
+                base.fixed_per_1k_output_tokens = int(
+                    os.environ["COST_PER_1K_OUTPUT_TOKENS"].strip()
+                )
+            except Exception:
+                pass
+    except Exception:
+        pass
+    if not base.onion_url:
+        try:
+            from ..nip91 import discover_onion_url_from_tor  # type: ignore
+
+            discovered = discover_onion_url_from_tor()
+            if discovered:
+                base.onion_url = discovered
+        except Exception:
+            pass
+    # Derive NPUB from NSEC if not provided
+    if not base.npub and base.nsec:
+        try:
+            from nostr.key import PrivateKey  # type: ignore
+
+            if base.nsec.startswith("nsec"):
+                pk = PrivateKey.from_nsec(base.nsec)
+            elif len(base.nsec) == 64:
+                pk = PrivateKey(bytes.fromhex(base.nsec))
+            else:
+                pk = None
+            if pk is not None:
+                try:
+                    base.npub = pk.public_key.bech32()
+                except Exception:
+                    # Fallback to hex if bech32 not available
+                    base.npub = pk.public_key.hex()
+        except Exception:
+            pass
+    if not base.cors_origins:
+        base.cors_origins = ["*"]
+    if not base.primary_mint:
+        base.primary_mint = _compute_primary_mint(base.cashu_mints)
+    return base
+
+
+class SettingsRow(BaseModel):
+    id: int
+    data: dict[str, Any]
+    updated_at: datetime | None = None
+
+
+# Single, concrete settings instance that callers import directly
+settings: Settings = resolve_bootstrap()
+
+
+class SettingsService:
+    _current: Settings | None = None
+    _lock: asyncio.Lock = asyncio.Lock()
+
+    @classmethod
+    def get(cls) -> Settings:
+        if cls._current is None:
+            raise RuntimeError("SettingsService not initialized")
+        return cls._current
+
+    @classmethod
+    async def initialize(cls, db_session: AsyncSession) -> Settings:
+        async with cls._lock:
+            from sqlmodel import text
+
+            await db_session.exec(  # type: ignore
+                text(
+                    "CREATE TABLE IF NOT EXISTS settings (id INTEGER PRIMARY KEY, data TEXT NOT NULL, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP)"
+                )
+            )
+
+            row = await db_session.exec(  # type: ignore
+                text("SELECT id, data, updated_at FROM settings WHERE id = 1")
+            )
+            row = row.first()
+            env_resolved = resolve_bootstrap()
+
+            if row is None:
+                await db_session.exec(  # type: ignore
+                    text(
+                        "INSERT INTO settings (id, data, updated_at) VALUES (1, :data, :updated_at)"
+                    ).bindparams(
+                        data=json.dumps(env_resolved.dict()),
+                        updated_at=datetime.now(timezone.utc),
+                    )
+                )
+                await db_session.commit()
+                cls._current = settings
+                # Update the existing instance in-place for all live importers
+                for k, v in env_resolved.dict().items():
+                    setattr(settings, k, v)
+                return cls._current
+
+            db_id, db_data, _updated_at = row
+            try:
+                db_json = (
+                    json.loads(db_data) if isinstance(db_data, str) else dict(db_data)
+                )
+            except Exception:
+                db_json = {}
+
+            merged_dict: dict[str, Any] = dict(env_resolved.dict())
+            merged_dict.update(
+                {k: v for k, v in db_json.items() if v not in (None, "", [], {})}
+            )
+
+            # Ensure primary_mint is consistent with cashu_mints if not explicitly set
+            if not merged_dict.get("primary_mint"):
+                merged_dict["primary_mint"] = _compute_primary_mint(
+                    merged_dict.get("cashu_mints", [])
+                )
+
+            if any(k not in db_json for k in merged_dict.keys()):
+                await db_session.exec(  # type: ignore
+                    text(
+                        "UPDATE settings SET data = :data, updated_at = :updated_at WHERE id = 1"
+                    ).bindparams(
+                        data=json.dumps(merged_dict),
+                        updated_at=datetime.now(timezone.utc),
+                    )
+                )
+                await db_session.commit()
+
+            # Update the existing instance in-place for all live importers
+            for k, v in merged_dict.items():
+                setattr(settings, k, v)
+            cls._current = settings
+            return cls._current
+
+    @classmethod
+    async def update(
+        cls, partial: dict[str, Any], db_session: AsyncSession
+    ) -> Settings:
+        async with cls._lock:
+            current = cls.get()
+            candidate_dict = {**current.dict(), **partial}
+            candidate = Settings(**candidate_dict)
+            from sqlmodel import text
+
+            # Ensure primary_mint reflects candidate mints if missing
+            if not candidate.primary_mint:
+                candidate.primary_mint = _compute_primary_mint(candidate.cashu_mints)
+
+            await db_session.exec(  # type: ignore
+                text(
+                    "UPDATE settings SET data = :data, updated_at = :updated_at WHERE id = 1"
+                ).bindparams(
+                    data=json.dumps(candidate.dict()),
+                    updated_at=datetime.now(timezone.utc),
+                )
+            )
+            await db_session.commit()
+            # Update in-place
+            for k, v in candidate.dict().items():
+                setattr(settings, k, v)
+            cls._current = settings
+            return settings
+
+    @classmethod
+    async def reload_from_db(cls, db_session: AsyncSession) -> Settings:
+        async with cls._lock:
+            from sqlmodel import text
+
+            row = await db_session.exec(text("SELECT data FROM settings WHERE id = 1"))  # type: ignore
+            row = row.first()
+            if row is None:
+                raise RuntimeError("Settings row missing")
+            (data_str,) = row
+            data = json.loads(data_str) if isinstance(data_str, str) else dict(data_str)
+            # Update in-place
+            for k, v in data.items():
+                setattr(settings, k, v)
+            cls._current = settings
+            return settings

routstr/discovery.py

@@ -0,0 +1,401 @@
+import asyncio
+import json
+import random
+import string
+from typing import Any
+
+import httpx
+import websockets
+from fastapi import APIRouter
+
+from .core.logging import get_logger
+from .core.settings import settings
+
+logger = get_logger(__name__)
+
+providers_router = APIRouter(prefix="/v1/providers")
+
+# In-memory providers cache and lock
+_PROVIDERS_CACHE: list[dict[str, Any]] = []
+_PROVIDERS_CACHE_LOCK = asyncio.Lock()
+
+
+def generate_subscription_id() -> str:
+    """Generate a random subscription ID."""
+    return "".join(random.choices(string.ascii_lowercase + string.digits, k=10))
+
+
+async def query_nostr_relay_for_providers(
+    relay_url: str,
+    pubkey: str | None = None,
+    limit: int = 1000,
+    timeout: int = 30,
+) -> list[dict[str, Any]]:
+    """
+    Query a Nostr relay for provider announcements.
+    Searches for NIP-91 (kind:38421) events.
+    """
+    events = []
+
+    # Build filter for NIP-91 events
+    filter_obj: dict[str, Any] = {
+        "kinds": [38421],  # NIP-91 Provider Announcements
+        "limit": limit,
+    }
+
+    # If specific pubkey provided, filter by author
+    if pubkey:
+        filter_obj["authors"] = [pubkey]
+
+    sub_id = generate_subscription_id()
+    req_message = json.dumps(["REQ", sub_id, filter_obj])
+
+    try:
+        async with websockets.connect(relay_url, open_timeout=timeout) as websocket:
+            logger.debug("Connected to relay, searching for NIP-91 events (kind 38421)")
+            await websocket.send(req_message)
+
+            while True:
+                try:
+                    message = await asyncio.wait_for(websocket.recv(), timeout=5)
+                    data = json.loads(message)
+
+                    if data[0] == "EVENT" and data[1] == sub_id:
+                        event = data[2]
+                        logger.debug(
+                            f"Found provider announcement: {event['id'][:6]}...{event['id'][-6:]}"
+                        )
+                        events.append(event)
+                    elif data[0] == "EOSE" and data[1] == sub_id:
+                        logger.debug("Received EOSE message")
+                        break
+                    elif data[0] == "NOTICE":
+                        try:
+                            msg = str(data[1])
+                            if len(msg) > 200:
+                                msg = msg[:200] + "..."
+                            logger.debug(f"Relay notice: {msg}")
+                        except Exception:
+                            logger.debug("Relay notice received")
+
+                except asyncio.TimeoutError:
+                    logger.debug("Timeout waiting for message")
+                    break
+                except json.JSONDecodeError:
+                    logger.warning("Failed to decode message as JSON")
+                    continue
+
+            await websocket.send(json.dumps(["CLOSE", sub_id]))
+
+    except Exception as e:
+        logger.debug(f"Query failed: {type(e).__name__}")
+
+    logger.info(f"Query complete. Found {len(events)} provider announcements")
+    return events
+
+
+def parse_provider_announcement(event: dict[str, Any]) -> dict[str, Any] | None:
+    """
+    Parse provider announcement events.
+    Handles NIP-91 (kind:38421) format.
+    Returns structured provider data or None if invalid.
+    """
+    try:
+        tags = event.get("tags", [])
+        kind = event.get("kind")
+
+        # Common fields
+        d_tag = None
+        endpoint_urls = []
+        provider_name = None
+        endpoint_url = None
+
+        for tag in tags:
+            if len(tag) >= 2:
+                if tag[0] == "endpoint":
+                    endpoint_url = tag[1]
+                elif tag[0] == "name":
+                    provider_name = tag[1]
+                elif tag[0] == "d":
+                    d_tag = tag[1]
+
+        # Early validation only applies to legacy/other kinds, not NIP-91
+        if kind != 38421 and (not endpoint_url or not provider_name or not d_tag):
+            logger.warning(
+                f"Invalid provider announcement - missing required tags: {event['id']}"
+            )
+            return None
+
+        # Extract optional tags
+        description = None
+        mint_urls = []
+        version = None
+
+        # Parse NIP-91 format
+        if kind == 38421:  # NIP-91 format
+            for tag in tags:
+                if len(tag) >= 2:
+                    if tag[0] == "d":
+                        d_tag = tag[1]
+                    elif tag[0] == "u":
+                        endpoint_urls.append(tag[1])
+                    elif tag[0] == "mint":
+                        mint_urls.append(tag[1])
+                    elif tag[0] == "version":
+                        version = tag[1]
+
+            # Parse metadata from content for NIP-91
+            content = event.get("content", "")
+            if content:
+                try:
+                    metadata = json.loads(content)
+                    provider_name = metadata.get("name", "Unknown Provider")
+                    description = metadata.get("about")
+                except (json.JSONDecodeError, TypeError):
+                    provider_name = "Unknown Provider"
+            else:
+                provider_name = "Unknown Provider"
+
+            # Use first URL as primary endpoint
+            endpoint_url = endpoint_urls[0] if endpoint_urls else None
+
+            # Validate NIP-91 required fields
+            if not endpoint_url or not d_tag:
+                logger.warning(
+                    f"Invalid NIP-91 announcement - missing required fields: {event['id']}"
+                )
+                return None
+        else:
+            logger.warning(
+                f"Unknown event kind when parsing provider announcement: {kind}"
+            )
+            return None
+
+        return {
+            "id": d_tag,
+            "pubkey": event["pubkey"],
+            "created_at": event["created_at"],
+            "kind": kind,
+            "endpoint_url": endpoint_url,
+            "endpoint_urls": endpoint_urls,  # All URLs for NIP-91
+            "name": provider_name,
+            "description": description,
+            "mint_urls": mint_urls,
+            "version": version,
+            "content": event.get("content", ""),
+        }
+
+    except Exception as e:
+        logger.error(
+            f"Error parsing provider announcement {event.get('id', 'unknown')}: {e}"
+        )
+        return None
+
+
+async def get_cache() -> list[dict[str, Any]]:
+    async with _PROVIDERS_CACHE_LOCK:
+        return list(_PROVIDERS_CACHE)
+
+
+def _get_discovery_relays() -> list[str]:
+    try:
+        relays = settings.relays
+    except Exception:
+        relays = []
+    if not relays:
+        relays = [
+            "wss://relay.nostr.band",
+            "wss://relay.damus.io",
+            "wss://relay.routstr.com",
+            "wss://nos.lol",
+        ]
+    return relays
+
+
+async def _discover_providers(pubkey: str | None = None) -> list[dict[str, Any]]:
+    discovery_relays = _get_discovery_relays()
+
+    tasks = [
+        query_nostr_relay_for_providers(relay_url=r, pubkey=pubkey, limit=100)
+        for r in discovery_relays
+    ]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    all_events: list[dict[str, Any]] = []
+    event_ids: set[str] = set()
+    for res in results:
+        if isinstance(res, BaseException):
+            logger.error(f"Relay query failed: {res}")
+            continue
+        if isinstance(res, list):
+            for event in res:
+                # Filter out localhost announcements
+                try:
+                    tags = event.get("tags", [])
+                    is_localhost = any(
+                        isinstance(tag, list)
+                        and len(tag) >= 2
+                        and tag[0] == "u"
+                        and tag[1] == "http://localhost:8000"
+                        for tag in tags
+                    )
+                    if is_localhost:
+                        logger.debug(
+                            f"Skipping localhost provider event: {event.get('id', 'unknown')}"
+                        )
+                        continue
+                except Exception:
+                    # If tags are malformed, fall through to normal handling
+                    pass
+
+                if (eid := event.get("id")) and eid not in event_ids:
+                    event_ids.add(eid)
+                    all_events.append(event)
+        else:
+            logger.error(f"Unexpected relay result type: {type(res)}")
+
+    providers: list[dict[str, Any]] = []
+    seen_endpoints: set[str] = set()
+    for event in all_events:
+        parsed = parse_provider_announcement(event)
+        if parsed and (eu := parsed.get("endpoint_url")) and eu not in seen_endpoints:
+            seen_endpoints.add(eu)
+            providers.append(parsed)
+
+    random.shuffle(providers)
+    return providers[:42]
+
+
+async def refresh_providers_cache(pubkey: str | None = None) -> None:
+    try:
+        providers = await _discover_providers(pubkey=pubkey)
+
+        health_tasks = [
+            fetch_provider_health(provider["endpoint_url"]) for provider in providers
+        ]
+        health_results = await asyncio.gather(*health_tasks, return_exceptions=True)
+
+        new_cache: list[dict[str, Any]] = []
+        for provider, hr in zip(providers, health_results):
+            if isinstance(hr, Exception):
+                health: dict[str, Any] = {
+                    "status_code": 500,
+                    "endpoint": "error",
+                    "json": {"error": str(hr)},
+                }
+            else:
+                health = hr  # type: ignore[assignment]
+            new_cache.append({"provider": provider, "health": health})
+
+        async with _PROVIDERS_CACHE_LOCK:
+            _PROVIDERS_CACHE.clear()
+            _PROVIDERS_CACHE.extend(new_cache)
+        logger.info(
+            f"Providers cache refreshed with {len(new_cache)} entries (limit 42)"
+        )
+    except Exception as e:
+        logger.error(f"Failed to refresh providers cache: {e}")
+
+
+async def providers_cache_refresher(
+    interval_seconds: int | None = None, pubkey: str | None = None
+) -> None:
+    if interval_seconds is None:
+        try:
+            interval_seconds = settings.providers_refresh_interval_seconds
+        except Exception:
+            interval_seconds = 300
+
+    await refresh_providers_cache(pubkey=pubkey)
+    while True:
+        try:
+            await asyncio.sleep(interval_seconds)
+        except asyncio.CancelledError:
+            break
+        await refresh_providers_cache(pubkey=pubkey)
+
+
+async def fetch_provider_health(endpoint_url: str) -> dict[str, Any]:
+    """Fetch provider health and info, preferring /v1/info for models and pricing."""
+    try:
+        # Determine if we need Tor proxy based on .onion domain
+        is_onion = ".onion" in endpoint_url
+
+        # Set up client arguments conditionally
+        proxies = None
+        if is_onion:
+            try:
+                tor_proxy = settings.tor_proxy_url
+            except Exception:
+                tor_proxy = "socks5://127.0.0.1:9050"
+            proxies = {"http://": tor_proxy, "https://": tor_proxy}  # type: ignore[assignment]
+
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(30.0),
+            follow_redirects=True,
+            proxies=proxies,  # type: ignore[arg-type]
+        ) as client:
+            # Prefer provider's /v1/info for full details
+            info_url = f"{endpoint_url.rstrip('/')}/v1/info"
+            try:
+                response = await client.get(info_url)
+                if response.status_code == 200:
+                    return {
+                        "status_code": response.status_code,
+                        "endpoint": "info",
+                        "json": response.json(),
+                    }
+            except Exception:
+                pass
+
+            # Fallback to /v1/models
+            models_url = f"{endpoint_url.rstrip('/')}/v1/models"
+            try:
+                response = await client.get(models_url)
+                if response.status_code == 200:
+                    return {
+                        "status_code": response.status_code,
+                        "endpoint": "models",
+                        "json": response.json(),
+                    }
+            except Exception:
+                pass
+
+            # Fallback to root endpoint
+            response = await client.get(endpoint_url)
+            return {
+                "status_code": response.status_code,
+                "endpoint": "root",
+                "json": response.json()
+                if response.headers.get("content-type", "").startswith(
+                    "application/json"
+                )
+                else {"message": "OK"},
+            }
+
+    except Exception as e:
+        return {
+            "status_code": 500,
+            "endpoint": "error",
+            "json": {"error": f"Failed to fetch provider: {str(e)}"},
+        }
+
+
+@providers_router.get("/")
+async def get_providers(
+    include_json: bool = False, pubkey: str | None = None
+) -> dict[str, list[dict[str, Any]]]:
+    """
+    Return cached providers. If include_json, return provider+health; otherwise provider only.
+    Optional filter by pubkey.
+    """
+    cache = await get_cache()
+    if not cache:
+        await refresh_providers_cache(pubkey=pubkey)
+        cache = await get_cache()
+    if pubkey:
+        cache = [c for c in cache if c.get("provider", {}).get("pubkey") == pubkey]
+    if include_json:
+        return {"providers": cache}
+    providers_only = [c["provider"] for c in cache]
+    return {"providers": providers_only}

routstr/lightning.py

@@ -0,0 +1,270 @@
+import hashlib
+import secrets
+import time
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from .core.db import ApiKey, LightningInvoice, get_session
+from .core.logging import get_logger
+from .core.settings import settings
+from .wallet import get_wallet
+
+logger = get_logger(__name__)
+
+lightning_router = APIRouter(prefix="/lightning")
+
+
+class InvoiceCreateRequest(BaseModel):
+    amount_sats: int = Field(gt=0, le=1_000_000, description="Amount in satoshis")
+    purpose: str = Field(description="create or topup", pattern="^(create|topup)$")
+    api_key: str | None = Field(
+        default=None, description="Required for topup operations"
+    )
+
+
+class InvoiceCreateResponse(BaseModel):
+    invoice_id: str
+    bolt11: str
+    amount_sats: int
+    expires_at: int
+    payment_hash: str
+
+
+class InvoiceStatusResponse(BaseModel):
+    status: str
+    api_key: str | None = None
+    amount_sats: int
+    paid_at: int | None = None
+    created_at: int
+    expires_at: int
+
+
+class InvoiceRecoverRequest(BaseModel):
+    bolt11: str = Field(description="BOLT11 invoice string")
+
+
+async def generate_lightning_invoice(
+    amount_sats: int, description: str
+) -> tuple[str, str]:
+    wallet = await get_wallet(settings.primary_mint, "sat")
+    quote = await wallet.request_mint(amount_sats)
+    return quote.request, quote.quote
+
+
+def generate_invoice_id() -> str:
+    return secrets.token_urlsafe(16)
+
+
+@lightning_router.post("/invoice", response_model=InvoiceCreateResponse)
+async def create_invoice(
+    request: InvoiceCreateRequest,
+    session: AsyncSession = Depends(get_session),
+) -> InvoiceCreateResponse:
+    if request.purpose == "topup" and not request.api_key:
+        raise HTTPException(
+            status_code=400, detail="api_key is required for topup operations"
+        )
+
+    if request.purpose == "topup" and request.api_key:
+        if not request.api_key.startswith("sk-"):
+            raise HTTPException(status_code=400, detail="Invalid API key format")
+
+        api_key = await session.get(ApiKey, request.api_key[3:])
+        if not api_key:
+            raise HTTPException(status_code=404, detail="API key not found")
+
+    try:
+        description = f"Routstr {request.purpose} {request.amount_sats} sats"
+        bolt11, payment_hash = await generate_lightning_invoice(
+            request.amount_sats, description
+        )
+
+        invoice_id = generate_invoice_id()
+        expires_at = int(time.time()) + 3600  # 1 hour expiry
+
+        invoice = LightningInvoice(
+            id=invoice_id,
+            bolt11=bolt11,
+            amount_sats=request.amount_sats,
+            description=description,
+            payment_hash=payment_hash,
+            status="pending",
+            api_key_hash=request.api_key[3:] if request.api_key else None,
+            purpose=request.purpose,
+            expires_at=expires_at,
+        )
+
+        session.add(invoice)
+        await session.commit()
+
+        logger.info(
+            "Lightning invoice created",
+            extra={
+                "invoice_id": invoice_id,
+                "amount_sats": request.amount_sats,
+                "purpose": request.purpose,
+                "expires_at": expires_at,
+            },
+        )
+
+        return InvoiceCreateResponse(
+            invoice_id=invoice_id,
+            bolt11=bolt11,
+            amount_sats=request.amount_sats,
+            expires_at=expires_at,
+            payment_hash=payment_hash,
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to create Lightning invoice: {e}")
+        raise HTTPException(
+            status_code=500, detail="Failed to create Lightning invoice"
+        )
+
+
+@lightning_router.get(
+    "/invoice/{invoice_id}/status", response_model=InvoiceStatusResponse
+)
+async def get_invoice_status(
+    invoice_id: str,
+    session: AsyncSession = Depends(get_session),
+) -> InvoiceStatusResponse:
+    invoice = await session.get(LightningInvoice, invoice_id)
+    if not invoice:
+        raise HTTPException(status_code=404, detail="Invoice not found")
+
+    if invoice.status == "pending" and int(time.time()) > invoice.expires_at:
+        invoice.status = "expired"
+        await session.commit()
+
+    if invoice.status == "pending":
+        await check_invoice_payment(invoice, session)
+
+    api_key = None
+    if invoice.status == "paid" and invoice.purpose == "create":
+        if invoice.api_key_hash:
+            api_key = f"sk-{invoice.api_key_hash}"
+    elif (
+        invoice.status == "paid" and invoice.purpose == "topup" and invoice.api_key_hash
+    ):
+        api_key = f"sk-{invoice.api_key_hash}"
+
+    return InvoiceStatusResponse(
+        status=invoice.status,
+        api_key=api_key,
+        amount_sats=invoice.amount_sats,
+        paid_at=invoice.paid_at,
+        created_at=invoice.created_at,
+        expires_at=invoice.expires_at,
+    )
+
+
+@lightning_router.post("/recover", response_model=InvoiceStatusResponse)
+async def recover_invoice(
+    request: InvoiceRecoverRequest,
+    session: AsyncSession = Depends(get_session),
+) -> InvoiceStatusResponse:
+    result = await session.exec(
+        select(LightningInvoice).where(LightningInvoice.bolt11 == request.bolt11)
+    )
+    invoice = result.first()
+
+    if not invoice:
+        raise HTTPException(status_code=404, detail="Invoice not found")
+
+    if invoice.status == "pending":
+        await check_invoice_payment(invoice, session)
+
+    api_key = None
+    if invoice.status == "paid":
+        if invoice.purpose == "create" and invoice.api_key_hash:
+            api_key = f"sk-{invoice.api_key_hash}"
+        elif invoice.purpose == "topup" and invoice.api_key_hash:
+            api_key = f"sk-{invoice.api_key_hash}"
+
+    return InvoiceStatusResponse(
+        status=invoice.status,
+        api_key=api_key,
+        amount_sats=invoice.amount_sats,
+        paid_at=invoice.paid_at,
+        created_at=invoice.created_at,
+        expires_at=invoice.expires_at,
+    )
+
+
+async def check_invoice_payment(
+    invoice: LightningInvoice, session: AsyncSession
+) -> None:
+    try:
+        wallet = await get_wallet(settings.primary_mint, "sat")
+
+        mint_status = await wallet.get_mint_quote(invoice.payment_hash)
+
+        if mint_status.paid:
+            invoice.status = "paid"
+            invoice.paid_at = int(time.time())
+
+            if invoice.purpose == "create":
+                api_key = await create_api_key_from_invoice(invoice, session)
+                invoice.api_key_hash = api_key.hashed_key
+            elif invoice.purpose == "topup" and invoice.api_key_hash:
+                await topup_api_key_from_invoice(invoice, session)
+
+            await session.commit()
+
+            logger.info(
+                "Lightning invoice paid",
+                extra={
+                    "invoice_id": invoice.id,
+                    "amount_sats": invoice.amount_sats,
+                    "purpose": invoice.purpose,
+                    "api_key_hash": invoice.api_key_hash[:8] + "..."
+                    if invoice.api_key_hash
+                    else None,
+                },
+            )
+
+    except Exception as e:
+        logger.error(f"Failed to check invoice payment: {e}")
+
+
+async def create_api_key_from_invoice(
+    invoice: LightningInvoice, session: AsyncSession
+) -> ApiKey:
+    wallet = await get_wallet(settings.primary_mint, "sat")
+    await wallet.mint(invoice.amount_sats, quote_id=invoice.payment_hash)
+
+    dummy_token = f"invoice-{invoice.id}-{invoice.payment_hash}"
+    hashed_key = hashlib.sha256(dummy_token.encode()).hexdigest()
+
+    api_key = ApiKey(
+        hashed_key=hashed_key,
+        balance=invoice.amount_sats * 1000,  # Convert to msats
+        refund_currency="sat",
+        refund_mint_url=settings.primary_mint,
+    )
+
+    session.add(api_key)
+    await session.flush()
+
+    return api_key
+
+
+async def topup_api_key_from_invoice(
+    invoice: LightningInvoice, session: AsyncSession
+) -> None:
+    wallet = await get_wallet(settings.primary_mint, "sat")
+    await wallet.mint(invoice.amount_sats, quote_id=invoice.payment_hash)
+
+    if not invoice.api_key_hash:
+        raise ValueError("No API key associated with topup invoice")
+
+    api_key = await session.get(ApiKey, invoice.api_key_hash)
+    if not api_key:
+        raise ValueError("Associated API key not found")
+
+    api_key.balance += invoice.amount_sats * 1000  # Convert to msats
+    await session.flush()

routstr/nip91.py

@@ -0,0 +1,574 @@
+#!/usr/bin/env python3
+"""
+NIP-91: Routstr Provider Discoverability Implementation
+Automatically announces this Routstr proxy instance to Nostr relays.
+"""
+
+import asyncio
+import json
+import os
+import random
+import ssl
+import time
+from typing import Any, cast
+
+from nostr.event import Event
+from nostr.filter import Filter, Filters
+from nostr.key import PrivateKey
+from nostr.message_type import ClientMessageType
+from nostr.relay_manager import RelayManager
+
+from .core import get_logger
+from .core.settings import settings
+
+logger = get_logger(__name__)
+
+
+def get_app_version() -> str | None:
+    try:
+        from .core.main import __version__ as imported_version
+
+        return imported_version
+    except Exception:
+        return None
+
+
+def _event_to_dict(ev: Event) -> dict[str, Any]:
+    return {
+        "id": ev.id,
+        "pubkey": ev.public_key,
+        "created_at": ev.created_at,
+        "kind": int(ev.kind) if not isinstance(ev.kind, int) else ev.kind,
+        "tags": ev.tags,
+        "content": ev.content,
+        "sig": ev.signature,
+    }
+
+
+def nsec_to_keypair(nsec: str) -> tuple[str, str] | None:
+    """
+    Convert a Nostr private key (nsec) to a keypair (privkey_hex, pubkey_hex).
+
+    Args:
+        nsec: Nostr private key in nsec format or hex format
+
+    Returns:
+        Tuple of (private_key_hex, public_key_hex) or None if invalid
+    """
+    try:
+        if nsec.startswith("nsec"):
+            pk = PrivateKey.from_nsec(nsec)
+            return (pk.hex(), pk.public_key.hex())
+
+        if len(nsec) == 64:
+            pk = PrivateKey(bytes.fromhex(nsec))
+            return (pk.hex(), pk.public_key.hex())
+
+        logger.error(f"Invalid private key format/length: {len(nsec)}")
+        return None
+    except Exception as e:
+        logger.error(f"Failed to convert nsec to keypair: {e}")
+        return None
+
+
+def create_nip91_event(
+    private_key_hex: str,
+    provider_id: str,
+    endpoint_urls: list[str],
+    mint_urls: list[str] | None = None,
+    version: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Create a NIP-91 compliant provider announcement event (kind:38421).
+
+    Args:
+        private_key_hex: 32-byte hex private key for signing
+        provider_id: Unique identifier for this provider (d tag)
+        endpoint_urls: List of URLs to connect to the provider
+        mint_urls: Optional list of ecash mint URLs for payments
+        version: Provider software version
+        metadata: Optional metadata dictionary (name, picture, about, etc.)
+
+    Returns:
+        Complete signed nostr event as a dict ready for publishing
+    """
+    pk = PrivateKey(bytes.fromhex(private_key_hex))
+
+    tags = [["d", provider_id]]
+    for url in endpoint_urls:
+        tags.append(["u", url])
+    if mint_urls:
+        for m in mint_urls:
+            if m:
+                tags.append(["mint", m])
+    if version:
+        tags.append(["version", version])
+
+    content = json.dumps(metadata, separators=(",", ":")) if metadata else ""
+
+    ev = Event(pk.public_key.hex(), content, kind=38421, tags=tags)
+    pk.sign_event(ev)
+    return _event_to_dict(ev)
+
+
+def _get_tag_values(event: dict[str, Any], key: str) -> list[str]:
+    tags = event.get("tags", [])
+    values: list[str] = []
+    for tag in tags:
+        if isinstance(tag, list) and tag and tag[0] == key and len(tag) >= 2:
+            values.append(tag[1])
+    return values
+
+
+def _get_single_tag_value(event: dict[str, Any], key: str) -> str | None:
+    values = _get_tag_values(event, key)
+    return values[0] if values else None
+
+
+def _parse_content_json(content: str) -> dict[str, Any]:
+    if not content:
+        return {}
+    try:
+        parsed = json.loads(content)
+        return parsed if isinstance(parsed, dict) else {}
+    except Exception:
+        return {}
+
+
+def events_semantically_equal(a: dict[str, Any], b: dict[str, Any]) -> bool:
+    if a.get("kind") != b.get("kind"):
+        return False
+
+    if _get_single_tag_value(a, "d") != _get_single_tag_value(b, "d"):
+        return False
+
+    urls_a = set(_get_tag_values(a, "u"))
+    urls_b = set(_get_tag_values(b, "u"))
+    if urls_a != urls_b:
+        return False
+
+    mints_a = set(_get_tag_values(a, "mint"))
+    mints_b = set(_get_tag_values(b, "mint"))
+    if mints_a != mints_b:
+        return False
+
+    if _get_single_tag_value(a, "version") != _get_single_tag_value(b, "version"):
+        return False
+
+    content_a = _parse_content_json(cast(str, a.get("content", "")))
+    content_b = _parse_content_json(cast(str, b.get("content", "")))
+    if content_a != content_b:
+        return False
+
+    return True
+
+
+async def query_nip91_events(
+    relay_url: str,
+    pubkey: str,
+    provider_id: str | None = None,
+    timeout: int = 30,
+) -> tuple[list[dict[str, Any]], bool]:
+    """
+    Query a Nostr relay for NIP-91 provider announcements (kind:38421) via nostr library.
+
+    Returns a tuple of (events, ok) where ok indicates whether the relay interaction
+    succeeded without transport-level errors.
+    """
+
+    def _sync_query() -> tuple[list[dict[str, Any]], bool]:
+        rm = RelayManager()
+        rm.add_relay(relay_url)
+        events_out: list[dict[str, Any]] = []
+        ok = True
+        try:
+            rm.open_connections({"cert_reqs": ssl.CERT_NONE})
+            time.sleep(1.0)
+
+            flt = Filter(kinds=[38421], authors=[pubkey], limit=10)
+            filters = Filters([flt])
+            sub_id = f"nip91_{int(time.time())}"
+            rm.add_subscription(sub_id, filters)
+            req: list[Any] = [ClientMessageType.REQUEST, sub_id]
+            req.extend(filters.to_json_array())
+            rm.publish_message(json.dumps(req))
+
+            start = time.time()
+            last_event_ts = start
+            while time.time() - start < timeout:
+                drained = False
+                while rm.message_pool.has_events():
+                    drained = True
+                    ev_msg = rm.message_pool.get_event()
+                    ev = ev_msg.event
+                    ev_dict = _event_to_dict(ev)
+                    if provider_id is not None:
+                        tags = ev_dict.get("tags", [])
+                        if not any(
+                            isinstance(t, list)
+                            and len(t) >= 2
+                            and t[0] == "d"
+                            and t[1] == provider_id
+                            for t in tags
+                        ):
+                            continue
+                    events_out.append(ev_dict)
+                    logger.debug(
+                        f"Found listing event: {ev_dict.get('id', '')[:6]}...{ev_dict.get('id', '')[-6:]}"
+                    )
+                if drained:
+                    last_event_ts = time.time()
+
+                while rm.message_pool.has_notices():
+                    notice = rm.message_pool.get_notice()
+                    try:
+                        content = getattr(notice, "content", notice)
+                        s = str(content)
+                        if len(s) > 200:
+                            s = s[:200] + "..."
+                        logger.debug(f"Relay notice: {s}")
+                    except Exception:
+                        pass
+
+                if time.time() - last_event_ts > 2.5:
+                    break
+
+                time.sleep(0.1)
+        except Exception as e:
+            ok = False
+            logger.debug(f"Failed to query relay {relay_url}: {type(e).__name__}")
+        finally:
+            try:
+                rm.close_connections()
+            except Exception:
+                pass
+        return events_out, ok
+
+    return await asyncio.to_thread(_sync_query)
+
+
+def discover_onion_url_from_tor(base_dir: str = "/var/lib/tor") -> str | None:
+    """Discover onion URL by reading Tor hidden service hostname files.
+
+    Tries common paths first, then scans recursively for any 'hostname' file.
+    Returns an http URL like 'http://<host>.onion' if found.
+    """
+    common_candidates = [
+        os.path.join(base_dir, "hs", "router", "hostname"),
+        os.path.join(base_dir, "hs", "ROUTER", "hostname"),
+        os.path.join(base_dir, "hidden_service", "hostname"),
+    ]
+
+    for candidate in common_candidates:
+        try:
+            with open(candidate, "r", encoding="utf-8") as f:
+                host = f.readline().strip()
+            if host and host.endswith(".onion"):
+                return f"http://{host}"
+        except Exception:
+            pass
+
+    try:
+        for root, _dirs, files in os.walk(base_dir):
+            if "hostname" in files:
+                path = os.path.join(root, "hostname")
+                try:
+                    with open(path, "r", encoding="utf-8") as f:
+                        host = f.readline().strip()
+                    if host and host.endswith(".onion"):
+                        return f"http://{host}"
+                except Exception:
+                    continue
+    except Exception:
+        pass
+
+    return None
+
+
+async def _determine_provider_id(public_key_hex: str, relay_urls: list[str]) -> str:
+    explicit = settings.provider_id
+    if explicit:
+        logger.info(f"Using configured provider_id from env: {explicit}")
+        return explicit
+
+    async def query_single_relay(relay_url: str) -> list[dict[str, Any]]:
+        try:
+            events, _ok = await query_nip91_events(relay_url, public_key_hex, None)
+            return events
+        except Exception:
+            return []
+
+    # Query all relays concurrently
+    all_events_lists = await asyncio.gather(
+        *[query_single_relay(relay_url) for relay_url in relay_urls]
+    )
+
+    latest_event: dict[str, Any] | None = None
+    latest_ts = -1
+
+    for events_list in all_events_lists:
+        for ev in events_list:
+            ts = int(ev.get("created_at", 0))
+            if ts > latest_ts:
+                latest_event = ev
+                latest_ts = ts
+
+    existing_d = _get_single_tag_value(latest_event, "d") if latest_event else None
+    if existing_d:
+        logger.info(f"Reusing existing provider_id from relay: {existing_d}")
+        return existing_d
+
+    fallback = public_key_hex[:12]
+    logger.info(f"No existing provider_id found; using fallback: {fallback}")
+    return fallback
+
+
+async def publish_to_relay(
+    relay_url: str,
+    event: dict[str, Any],
+    timeout: int = 30,
+) -> bool:
+    """
+    Publish a NIP-91 event to a nostr relay via nostr library.
+    """
+
+    def _sync_publish() -> bool:
+        rm = RelayManager()
+        rm.add_relay(relay_url)
+        try:
+            rm.open_connections({"cert_reqs": ssl.CERT_NONE})
+            time.sleep(1.0)
+            # Publish the event as-is via publish_message to preserve signature
+            rm.publish_message(json.dumps(["EVENT", event]))
+            logger.debug(f"Sent NIP-91 event {event.get('id', '')} to {relay_url}")
+            time.sleep(1.0)
+            return True
+        except Exception as e:
+            logger.debug(f"Failed to publish to {relay_url}: {type(e).__name__}")
+            return False
+        finally:
+            try:
+                rm.close_connections()
+            except Exception:
+                pass
+
+    return await asyncio.to_thread(_sync_publish)
+
+
+async def announce_provider() -> None:
+    """
+    Background task to announce this Routstr provider to Nostr relays.
+    Checks for existing announcements and creates new ones if needed.
+    """
+    # Check for NSEC in environment (use NSEC only)
+    nsec = settings.nsec
+    if not nsec:
+        logger.info("Nostr private key not found (NSEC), skipping NIP-91 announcement")
+        return
+
+    # Convert NSEC to keypair
+    keypair = nsec_to_keypair(nsec)
+    if not keypair:
+        logger.error("Failed to parse NSEC, skipping NIP-91 announcement")
+        return
+
+    private_key_hex, public_key_hex = keypair
+    logger.info(f"Using Nostr pubkey: {public_key_hex}")
+
+    # Resolve settings and determine if we can publish BEFORE touching relays
+    try:
+        base_url: str | None = settings.http_url
+        onion_url: str | None = settings.onion_url
+        provider_name = settings.name or "Routstr Proxy"
+        provider_about = settings.description or "Privacy-preserving AI proxy via Nostr"
+        cashu_mints = [m.strip() for m in settings.cashu_mints if m.strip()]
+    except Exception:
+        base_url = settings.http_url or None
+        onion_url = settings.onion_url or None
+        provider_name = settings.name or "Routstr Proxy"
+        provider_about = settings.description or "Privacy-preserving AI proxy via Nostr"
+        cashu_mints = [m.strip() for m in settings.cashu_mints if m.strip()]
+    if not onion_url:
+        discovered = discover_onion_url_from_tor()
+        if discovered:
+            onion_url = discovered
+            logger.info(f"Discovered onion URL via Tor volume: {onion_url}")
+    mint_urls = cashu_mints if cashu_mints else None
+
+    endpoint_urls: list[str] = []
+    if base_url and base_url.strip() and base_url.strip() != "http://localhost:8000":
+        endpoint_urls.append(base_url.strip())
+    if onion_url and onion_url.strip():
+        ou = onion_url.strip()
+        if ou.endswith(".onion") and not (
+            ou.startswith("http://") or ou.startswith("https://")
+        ):
+            ou = f"http://{ou}"
+        endpoint_urls.append(ou)
+
+    if not endpoint_urls:
+        logger.warning(
+            "No valid endpoints configured (HTTP_URL/ONION_URL). Skipping NIP-91 publish."
+        )
+        return
+
+    # Only now configure relays and determine provider_id (may query relays)
+    relay_urls = [u.strip() for u in getattr(settings, "relays", []) if u.strip()]
+    if not relay_urls:
+        relay_urls = [
+            "wss://relay.nostr.band",
+            "wss://relay.damus.io",
+            "wss://relay.routstr.com",
+            "wss://nos.lol",
+        ]
+
+    provider_id = await _determine_provider_id(public_key_hex, relay_urls)
+    logger.info(f"Using provider_id: {provider_id}")
+
+    # Build metadata
+    metadata = {
+        "name": provider_name,
+        "about": provider_about,
+    }
+
+    # Create the candidate event that we would publish
+    version_str = get_app_version()
+    candidate_event = create_nip91_event(
+        private_key_hex=private_key_hex,
+        provider_id=provider_id,
+        endpoint_urls=endpoint_urls,
+        mint_urls=mint_urls,
+        version=version_str,
+        metadata=metadata,
+    )
+
+    # Backoff configuration and state (sensible defaults)
+    backoff_base = 5.0
+    backoff_max = 900.0
+    backoff_jitter_ratio = 0.2
+    relay_next_allowed: dict[str, float] = {}
+    relay_current_delay: dict[str, float] = {}
+
+    def _should_skip(relay: str) -> bool:
+        return time.time() < relay_next_allowed.get(relay, 0.0)
+
+    def _register_success(relay: str) -> None:
+        relay_current_delay[relay] = 0.0
+        relay_next_allowed[relay] = time.time()
+
+    def _register_failure(relay: str) -> None:
+        previous = relay_current_delay.get(relay, 0.0)
+        delay = backoff_base if previous <= 0.0 else min(backoff_max, previous * 2.0)
+        jitter = delay * backoff_jitter_ratio * (2.0 * random.random() - 1.0)
+        scheduled = time.time() + max(0.0, delay + jitter)
+        relay_current_delay[relay] = delay
+        relay_next_allowed[relay] = scheduled
+        logger.debug(
+            f"Backoff: {relay} delay={delay:.1f}s jitter={jitter:.1f}s next={int(scheduled)}"
+        )
+
+    # Fetch existing events for this provider_id
+    existing_events: list[dict[str, Any]] = []
+    for relay_url in relay_urls:
+        if _should_skip(relay_url):
+            logger.debug(f"Skipping {relay_url} due to backoff")
+            continue
+        events, ok = await query_nip91_events(relay_url, public_key_hex, provider_id)
+        if ok:
+            _register_success(relay_url)
+            existing_events.extend(events)
+        else:
+            _register_failure(relay_url)
+
+    # Decide whether to publish: publish if none exist or any differ from candidate
+    found_any = len(existing_events) > 0
+    all_match = found_any and all(
+        events_semantically_equal(ev, candidate_event) for ev in existing_events
+    )
+
+    if not all_match:
+        logger.debug(
+            "No matching NIP-91 announcement found or differences detected; publishing update"
+        )
+        success_count = 0
+        for relay_url in relay_urls:
+            if _should_skip(relay_url):
+                logger.debug(f"Skipping publish to {relay_url} due to backoff")
+                continue
+            if await publish_to_relay(relay_url, candidate_event):
+                _register_success(relay_url)
+                success_count += 1
+            else:
+                _register_failure(relay_url)
+        logger.info(
+            f"Published NIP-91 announcement to {success_count}/{len(relay_urls)} relays"
+        )
+    else:
+        logger.debug(
+            "Matching NIP-91 announcement already present; skipping publish on startup"
+        )
+
+    # Re-announce periodically (every 24 hours)
+    announcement_interval = 24 * 60 * 60
+
+    while True:
+        try:
+            await asyncio.sleep(announcement_interval)
+
+            # Build fresh candidate event for comparison
+            version_str = get_app_version()
+            candidate_event = create_nip91_event(
+                private_key_hex=private_key_hex,
+                provider_id=provider_id,
+                endpoint_urls=endpoint_urls,
+                mint_urls=mint_urls,
+                version=version_str,
+                metadata=metadata,
+            )
+
+            # Fetch existing events for this provider_id
+            existing_events = []
+            for relay_url in relay_urls:
+                if _should_skip(relay_url):
+                    logger.debug(f"Skipping {relay_url} due to backoff")
+                    continue
+                events, ok = await query_nip91_events(
+                    relay_url, public_key_hex, provider_id
+                )
+                if ok:
+                    _register_success(relay_url)
+                    existing_events.extend(events)
+                else:
+                    _register_failure(relay_url)
+
+            found_any = len(existing_events) > 0
+            all_match = found_any and all(
+                events_semantically_equal(ev, candidate_event) for ev in existing_events
+            )
+
+            if all_match:
+                logger.debug(
+                    "Matching NIP-91 announcement already present; skipping periodic re-announce"
+                )
+                continue
+
+            logger.debug(
+                f"Re-announcing provider due to differences or absence: {candidate_event['id']}"
+            )
+            for relay_url in relay_urls:
+                if _should_skip(relay_url):
+                    logger.debug(f"Skipping publish to {relay_url} due to backoff")
+                    continue
+                ok = await publish_to_relay(relay_url, candidate_event)
+                if ok:
+                    _register_success(relay_url)
+                else:
+                    _register_failure(relay_url)
+
+        except asyncio.CancelledError:
+            logger.info("NIP-91 announcement task cancelled")
+            break
+        except Exception as e:
+            logger.debug(f"Error in NIP-91 announcement loop: {type(e).__name__}")
+            # Continue running despite errors

routstr/payment/__init__.py

@@ -0,0 +1,8 @@
+from .cost_calculation import CostData, CostDataError, MaxCostData, calculate_cost
+
+__all__ = [
+    "CostData",
+    "CostDataError",
+    "MaxCostData",
+    "calculate_cost",
+]