From a42fdfc8f7352ab0694d633e82b8ad8f8875a1d6 Mon Sep 17 00:00:00 2001
From: shroominic <34897716+shroominic@users.noreply.github.com>
Date: Fri, 13 Jun 2025 16:19:02 +0200
Subject: [PATCH] Improve README with usage and setup instructions

---
 README.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 97 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index be4b7bf0..41e1286a 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,99 @@
-# proxy
+# Routstr Payment Proxy
 
-a reverse proxy that you can plug in front of any OpenAI compatible API
-endpoint to handle payments using the Cashu protocol (Bitcoin L3).
+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](https://cashu.space/) protocol on Bitcoin and tracks usage in a local
+SQL database.
 
-Model pricing information is loaded from ``models.json`` by default. If that
-file is not present, the bundled ``models.example.json`` will be used. You can
-specify a custom path with the ``MODELS_PATH`` environment variable.
+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`).
+
+## Features
+
+- **Cashu Wallet integration** – accept Lightning payments and redeem 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.
+- **Docker support** – provided `Dockerfile` and `compose.yml` for running with
+  an optional Tor hidden service.
+
+## Getting started
+
+### 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
+```
+
+Create a `.env` file based on `.env.example` and fill in the required values:
+
+```bash
+cp .env.example .env
+```
+
+### Running locally
+
+```bash
+fastapi run router --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.
+
+### Docker
+
+```bash
+docker compose up --build
+```
+
+This builds the image and also starts a Tor container exposing the API as a
+hidden service.
+
+## Environment variables
+
+The most common settings are shown below. See `.env.example` for the full list.
+
+- `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
+
+## Example client
+
+`example.py` shows how to use the proxy with the official OpenAI client:
+
+```bash
+CASHU_TOKEN=<redeemable token> python example.py
+```
+
+The script sends streaming chat completions and pays for each request using the
+provided token.
+
+## Running tests
+
+```bash
+uv run pytest
+```
+
+The tests create a temporary SQLite database and mock the Cashu wallet. See
+`tests/README.md` for more details.
+
+## License
+
+This project is licensed under the terms of the GPLv3. See the `LICENSE` file
+for the full license text.