Routstr is a FastAPI-based reverse proxy that sits in front of any OpenAI-compatible API. It handles pay-per-request billing using the Cashu eCash protocol on Bitcoin and tracks usage in a local SQL database.
The server exposes the same endpoints as the upstream API and deducts sats from user accounts for each call. Pricing can be static or model-specific by loading models.json (falls back to models.example.json).
The proxy implements a seamless eCash payment flow that maintains compatibility with existing OpenAI clients while enabling Bitcoin micropayments:
sequenceDiagram
participant Client
participant Proxy as Routstr Proxy
participant DB as Database
participant Upstream as OpenAI API
participant Wallet as Cashu Wallet
Client->>Proxy: API Request + eCash Token
Proxy->>Wallet: Validate & Redeem Token
Wallet-->>Proxy: Token Value (sats)
Proxy->>DB: Store/Update Balance
Proxy->>Upstream: Forward API Request
Upstream-->>Proxy: API Response + Usage Data
Proxy->>DB: Deduct Actual Request Cost
Proxy->>DB: Update Final Balance
Proxy-->>Client: API Response
- 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.jsonto 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 using NIP-91 protocol
- NIP-91 Auto-Announcement – Automatically announce this provider to Nostr relays when NSEC is provided
- Docker Support – Provided
Dockerfileandcompose.ymlfor running with an optional Tor hidden service
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- Python 3.11+
- uv package manager (used in development)
uv sync # install dependenciesCreate a .env file based on .env.example and fill in the required values:
cp .env.example .envfastapi run routstr --host 0.0.0.0 --port 8000The service forwards requests to UPSTREAM_BASE_URL. Supply the upstream API key via the UPSTREAM_API_KEY environment variable if required.
docker compose up --buildThis builds the image and also starts a Tor container exposing the API as a hidden service.
The most common settings are shown below. See .env.example for the full list.
UPSTREAM_BASE_URL– URL of the OpenAI-compatible serviceUPSTREAM_API_KEY– API key for the upstream service (optional)FIXED_PRICING– Set totrueto use a fixed per-request price;false(default) uses model pricing frommodels.jsonADMIN_PASSWORD– Password for the/admin/dashboardCASHU_MINTS– Comma-separated list of Cashu mint URLsNAME– Name of the proxyDESCRIPTION– Description of the proxyNPUB– Nostr public key of the proxyHTTP_URL– Public-facing URL of the proxyONION_URL– Tor hidden service URL of the proxyNEXT_PUBLIC_API_URL- UI Configuration for Next.js frontend (proxy URL, default: 'http://127.0.0.1:8000' )
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.
When the FastAPI application starts, it automatically:
- Runs all pending database migrations
- Updates the schema to the latest version
- 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.
For development or troubleshooting, you can use these Makefile commands:
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 filesWhen you modify SQLModel models:
# 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-upgradeRoutstr includes a modern Next.js admin dashboard that's served directly from the Python backend as static files - no separate Node.js server required.
make ui-buildThis compiles the Next.js application into static HTML, CSS, and JavaScript files in ui/out/.
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.
Go to the admin dashboard at http://localhost:8000/ and login with your ADMIN_PASSWORD to withdraw your balance as a Cashu token.
example.py shows how to use the proxy with the official OpenAI client:
CASHU_TOKEN=<redeemable token> python example.pyThe script sends streaming chat completions and pays for each request using the provided token.
uv run pytestThe tests create a temporary SQLite database and mock the Cashu wallet. See tests/README.md for more details.
We're implementing support for the Cashu Nut-24 specification, which will enable per-request token exchange with automatic change handling:
graph TD
A["Client Request<br/>x-cashu: token"] --> B[Proxy Validates Token]
B --> C{Token ≥ Minimum Amount?}
C -->|No| F[Return 402 Payment Required]
C -->|Yes| D[Calculate Request Cost]
D --> E[Process Request]
E --> G[Forward to Upstream API]
G --> H[Receive API Response]
H --> I[Calculate Change]
I --> J["Return Response<br/>x-cashu: change_token"]
F --> K[End]
J --> K
Key Benefits:
- Per-Request Payments – Send exact tokens for each API call
- 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 (must meet minimum amount) - Response:
x-cashu: <change_token>– Change token if payment exceeds cost
Implementation Note:
The proxy should implement either a dedicated endpoint to communicate minimum eCash requirements per request, or extend the existing models.json to include minimum token amounts per model. This allows clients to autonomously determine the appropriate token amount to send with each request.
Compatible Clients:
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:
- routstr-chat – chat app for the routstr network
- otrta-client – rust web app for the routstr network
clients automatically:
- Handle eCash Headers – Add
x-cashutokens to requests and process change tokens - Manage Wallets – Maintain your Cashu wallet
- Configure Proxy – Set Routstr proxy endpoints
- Top-up Balances – Automatically request ecash when tokens run low and redeem ecash tokens
This approach eliminates the need for account management while maintaining the security and privacy benefits of eCash payments.
This project is licensed under the terms of the GPLv3. See the LICENSE file for the full license text.