Routstr Core v0.2.0

Release Date: November 2025

Version 0.2.0 introduces multi-provider support, intelligent cost-based routing, and a modern Next.js admin dashboard. This major release transforms routstr-core into a comprehensive multi-provider routing node.

🚀 New Features

Multi-Provider Architecture

• Multiple upstream provider support (OpenRouter, Ollama, Anthropic, generic OpenAI endpoints)
• Provider-specific implementations with extensible base class
• Configurable provider fees
• Dynamic provider selection based on cost

Modern Admin Dashboard

• Complete Next.js UI rewrite with TypeScript and TailwindCSS
• Real-time wallet balance with msat/sat/USD unit toggle
• Model management: add, edit, disable, bulk collection from providers
• Provider management: add, configure, enable/disable providers
• Static export served from FastAPI (no separate Node.js server)

🐛 Bug Fixes

Fixes

• Fixed wallet concurrency issues in top-up operations
• Fixed model alias precedence (e.g., glm-4.6 mapping)
• Fixed disabled models filtering in API responses
• Fixed max_tokens integer type enforcement
• Fixed Ollama request formatting
• Fixed x-cashu header forwarding

Full Changelog: v0.1.4...v0.2.0

Routstr Core v0.1.4

Routstr Core v0.1.4 Release Notes

Release Date: October 2025

Version 0.1.4 delivers critical bug fixes for payment processing, enhanced admin functionality with models management, and performance optimizations.

---

🐛 Bug Fixes

Payment & Pricing

• Fixed upstream provider fee not applied to USD pricing (#189) - @kwsantiago
• Fixed refund amount below 1 sat for sat mint (#180) - @sh1ftred
• Fixed 503 mint service unavailable error (#179) - @sh1ftred
• Fixed periodic payouts processing

Input Validation

• Fixed max_tokens parameter incorrectly accepting strings (#172)
• Fixed MINTS environment variable initialization

---

✨ New Features

Admin Dashboard - @shroominic

• Models management dashboard with visual configuration interface
• Models.json batch paste for bulk configuration imports
• Donations endpoint for Cashu-based donation processing
• Removed ADMIN_PASSWORD requirement - credentials configured in setup wizard

API Improvements

• Auto-redirect from v1/providers to v1/providers/
• Enhanced upstream error message handling

---

🚀 Improvements

Performance

• Enabled SQLite WAL mode for better concurrency and reduced locking
• Configurable model refresh interval to reduce unnecessary API calls

Model Management

• Filter out OpenRouter spam models automatically
• Custom version suffix support for deployments

Technical

• Pinned Python version to 3.11
• Added comprehensive fee consistency test suite (781 lines) - @kwsantiago
• Code formatting with Ruff

---

📊 Statistics

• 26 files changed: +1,936 insertions, -146 deletions
• 45+ commits, 5 merged pull requests
• Key changes: routstr/core/admin.py (+808), tests/unit/test_fee_consistency.py (+781)

---

🙏 Contributors

@shroominic, @kwsantiago, @sh1ftred

---

🔄 Migration Notes

Requirements:

• Python 3.11+ required
• File system must support SQLite WAL mode

Breaking Changes:

• max_tokens now strictly enforces integer type
• New installations use setup wizard for admin credentials

---

Full Changelog: v0.1.3...v0.1.4

⬆️v0.1.3

Routstr v0.1.3 — 2025-09-16

Highlights

• DB-backed settings with live updates: Env vars seed on first run; DB is the source of truth (except DATABASE_URL). Manage via Admin UI or PATCH /admin/api/settings.
• Models moved to database with background sats-pricing computation and optional periodic refresh.
• Smarter max-cost reservation: Discount based on prompt tokens and max_tokens using TOLERANCE_PERCENTAGE, with a MIN_REQUEST_MSAT floor.
• Faster startup and provider discovery; .onion endpoints use Tor proxy by default.

Breaking changes

• Configuration is DB-first after bootstrap. Env changes won’t auto-apply (besides DATABASE_URL).
• Models endpoint: Use /v1/models for canonical model info; /v1/info keeps an empty models field for back-compat.
• Legacy pricing envs are auto-mapped but deprecated:
  • MODEL_BASED_PRICING → !FIXED_PRICING
  • COST_PER_REQUEST → FIXED_COST_PER_REQUEST
  • COST_PER_1K_* → FIXED_PER_1K_*

Added

• SettingsService with env→computed→DB merge; runtime edits; app metadata (name/description) applied to OpenAPI.
• Automatic migrations on startup; new tables: settings, models.
• Per-model sats pricing and per-request maximums computed in the background.
• Pricing controls: FIXED_PRICING, FIXED_COST_PER_REQUEST, optional per-1k token overrides, MIN_REQUEST_MSAT.
• Azure chat support: Optional CHAT_COMPLETIONS_API_VERSION adds api-version to /chat/completions.
• Derive NPUB from NSEC during bootstrap if not provided.

Changed / Improvements

• Proxy header hardening: Strip sensitive headers; replace Authorization with upstream key when configured.
• Discovery: Read RELAYS from settings; Tor proxy defaults for .onion via TOR_PROXY_URL; faster announcement fetching.
• Admin: Improved auth/log UX; fixed log search; show mint balances in dashboard.
• Performance: Optimized startup; lazy DB info loading.

Fixed

• Refunds: Correct msat→sat conversion; configurable refund cache TTL via REFUND_CACHE_TTL_SECONDS; better error mapping for mint outages.
• Balances: Reserved balance reporting and negative-reserved edge cases.
• Tests: Updated to patch settings and use fixed-pricing flags.

Upgrade notes (from v0.1.2)

1. Ensure DATABASE_URL, UPSTREAM_BASE_URL, and ADMIN_PASSWORD are set. Optionally set UPSTREAM_API_KEY, RELAYS, CASHU_MINTS, TOR_PROXY_URL.
2. Start the service; automatic Alembic migrations will run (settings, models tables).
3. Configure settings via Admin UI (/admin) or PATCH /admin/api/settings. Env changes after first run won’t apply automatically.
4. Prefer new pricing envs or a models.json at MODELS_PATH. Legacy envs are mapped but will be removed in a future release.
5. Optional tuning: TOLERANCE_PERCENTAGE, MIN_REQUEST_MSAT, PRICING_REFRESH_INTERVAL_SECONDS, MODELS_REFRESH_INTERVAL_SECONDS, ENABLE_*_REFRESH.
6. For Azure, set CHAT_COMPLETIONS_API_VERSION.

References

• Configuration: docs/getting-started/configuration.md
• API: docs/api/endpoints.md
• Custom pricing: docs/advanced/custom-pricing.md

Stats and credits

• 42 files changed, +1819/−832 lines.
• Merges: #170 token-discount-max-cost, #171 move-models-to-db.
• Contributors: Shroominic.

⬆️ v0.1.2

Routstr Core v0.1.2 Release Notes

🚀 What's New

Major Features

Provider Discovery Revolution 🎯

• Complete migration to RIP-02 protocol for decentralized provider discovery
• Automatic provider announcement on Nostr network
• Tor integration for enhanced privacy and accessibility
• Robust rate limiting and error handling

Balance Management Overhaul 💰

• Robust streaming finalization without interruptions
• Cached refund operations for improved performance
• Enhanced balance handling reliability

Documentation & Developer Experience

Comprehensive Documentation Suite 📚

• 10,000+ lines of new documentation added
• Complete API reference with examples
• User guides for setup, configuration, and usage
• Developer documentation for architecture and testing
• Advanced topics: custom pricing, migrations, Tor setup

Technical Improvements

Core Infrastructure 🔧

• Nostr library integration for better protocol support
• Optimized timeouts and performance improvements
• Enhanced logging and error tracking
• Dev version indicators for better debugging

Quality Assurance ✅

• Improved test suite with better coverage
• Bug fixes across provider management and balance systems
• Code formatting and quality improvements

📈 Key Metrics

• 48 commits merged since v0.1.1
• 30+ documentation files created/updated
• Major protocol improvements: Full RIP-02 implementation
• New integrations: Azure OpenAI, fixes

📦 Installation & Upgrade

From Source

git clone https://github.com/routstr/routstr-core.git
cd routstr-proxy
uv sync

Using Docker

docker-compose up -d

📚 Documentation

We've added extensive documentation covering:

• Getting Started: Quickstart, Docker setup, configuration
• User Guide: API usage, payment flows, admin dashboard
• API Reference: Complete endpoint documentation
• Developer Docs: Architecture, testing, code structure
• Advanced Topics: Custom pricing, migrations, Tor, Nostr

---

Previous Release: v0.1.1

v0.1.1

• automatic payouts to set LNURL (env vars)
• x-cashu latency speedup
• general token claim speedup
• msat fixes
• multi-mint fixes
• codebase cleanup
• better logging
• simpler node setup
• improved dashboard
• automatic database migrations
• fixed refund issues

🔀 v0.1

Summary

• Added multi mint support
• Multi currency (sat/msat)
• Payment Method: X-Cashu Headers
• Improved pricing and usage tracking
• Improved admin dashboard with payouts
• Temporary anonymous api keys

💰 X-Cashu Header Support (Nut-24)

• Per-Request Payments – Send exact tokens for each API call using x-cashu headers
• Automatic Change – Receive change tokens in response headers
• No Pre-funding – No need to maintain account balances
• Precise Billing – Pay only for actual usage with msat-level precision
• Minimum Amount Protection – Proxy enforces minimum token value to prevent dust attacks

Header Format:

• Request: x-cashu: <ecash_token> – Token to spend for this request

• Response: x-cashu: <change_token> – Change token if payment exceeds cost

• Cashu Wallet Integration – Accept Lightning payments and redeem eCash tokens

• API Key Management – Hashed keys stored in SQLite with balance tracking

• Model-Based Pricing – Convert USD prices to sats using live BTC/USD rates

• Admin Dashboard – Simple HTML interface at /admin/

Compatible Clients:

• routstr-chat - Web Chat App to interact with any routstr proxy
• otrta-client – Rust client with automatic wallet management
• goose/roo-code/others - Goose, Roo Code or any client that supports the OpenAI API standard