9qeklajc
c1b7f78a02
Routstr-to-Routstr auto top-up had no spend bound. Admin settings were accepted without range or type validation, and every low-balance cycle independently minted a Cashu token and handed it to the configured peer. A malicious, buggy, or persistently non-crediting peer therefore received a fresh bearer token every sixty seconds; nothing in the worker noticed that the previous one had never been credited, and nothing survived a restart, so the bleed was limited only by the owner's mint balance. Auto top-up now mirrors the PPQ claim machinery that already guards the Lightning path. Each provider gets one durable claim row keyed by its id, so a second worker (or the same worker after a restart) loses the insert or the ownership-fenced update instead of paying twice. The claim moves to "sent" before the network call, and only a peer balance that reaches the pre-topup balance plus the top-up amount clears it: an uncredited token holds the slot rather than being retried. Repeated non-credit walks the claim through exponential backoff to a halt that needs an admin release, and a rolling 24h cap bounds the total even when every attempt looks successful. Settings validation now rejects non-positive, non-finite, boolean, huge, and non-integer amounts, amounts outside the per-transaction range, and a missing mint URL, at the admin API as well as in the worker. The claim row is a CashuTransaction like the PPQ one, so no migration is needed; provider delete and type change refuse to orphan it.
Routstr Payment Proxy
Routstr is a decentralized protocol for permissionless, private, and censorship-resistant AI inference. It combines Nostr for discovery and Cashu for private Bitcoin micropayments.
This repo contains Routstr Core: a FastAPI-based reverse proxy that sits in front of OpenAI-compatible APIs and handles pay-per-request billing.
Start Here
- Overview: https://docs.routstr.com/overview/
- Provider Guide: https://docs.routstr.com/provider/quickstart/
- User Guide: https://docs.routstr.com/user-guide/introduction/
Basic Usage
If you are a user/developer, you just point an OpenAI-compatible SDK at a Routstr node and pay with a Cashu token.
OpenAI SDK
from openai import OpenAI
client = OpenAI(
base_url="https://api.routstr.com/v1",
api_key="cashuBo2FteCJodHRwczovL21...",
)
response = client.chat.completions.create(
model="gpt-5-nano",
messages=[{"role": "user", "content": "hello"}],
)
print(response.choices[0].message.content)
cURL
curl https://api.routstr.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "x-cashu: cashuBo2FteCJodHRwczovL21..." \
-d '{
"model": "gpt-5-nano",
"messages": [{"role": "user", "content": "hello"}]
}'
Quick Start (Docker)
If you are a node runner, start a Routstr Core instance using Docker Compose:
-
Prepare your
.env:# Optional: encrypts node secrets at rest. If unset, the node generates a key # on first start, writes it to routstr_secret.key, and prints it once — back # up that file. Set it explicitly to manage the key yourself (recommended in # production). ROUTSTR_SECRET_KEY=<generated-key> NAME="My AI Node" DESCRIPTION="Fast access to models" RECEIVE_LN_ADDRESS=yourname@wallet.comYour Nostr identity (
nsec) is not set in.env— configure it from the admin UI after first start, where it's stored encrypted in the database. (NSECin.envis still read once as a legacy seed for existing deployments.)If you don't set one, a key is generated and printed on first start — save it somewhere safe (losing it makes previously encrypted secrets unreadable). To supply your own, generate it once and keep it stable:
uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" -
Start the services:
docker compose up -d -
Get your admin password: On first start the node generates an admin password and logs it once with the
/adminURL. Read it from the logs:docker compose logs routstr | grep -i admin(Lost it? Reset with
docker compose exec routstr /.venv/bin/python scripts/reset_admin_password.py --regenerate.) -
Configure: Open http://localhost:8000/admin/ to connect your AI providers and set pricing.
For full instructions, see the Provider Quick Start Guide.
Development
make setup
cp .env.example .env
fastapi run routstr