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/
Client Guide: https://docs.routstr.com/client/introduction/
Browse providers and models: https://routstr.com/providers

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)

Start a provider node with the guided setup. The default assumes you already have a subdomain with HTTPS and a reverse proxy forwarding to 127.0.0.1:8000, so the node publishes itself on Nostr as soon as it starts. Without a public URL yet, use --private and publish later. Agents: read llms.txt first, and rotate the bootstrap admin password before publishing.

git clone https://github.com/Routstr/routstr-core.git
cd routstr-core
# production: check out a reviewed release tag

# Phase 0: DNS + TLS + reverse proxy -> 127.0.0.1:8000

# Phase 1: start (public is the default)
python3 scripts/node_setup.py start \
  --public-url https://node.example \
  --ln-address you@wallet.com

# Phase 2: back up before configuring
#   routstr_secret.key, keys.db (+ -wal/-shm), .wallet/ and .env
docker compose -f compose.node.yml exec routstr \
  /.venv/bin/python scripts/reveal_nsec.py

# Phase 3: dashboard - rotate the admin password, add an upstream, set pricing
docker compose -f compose.node.yml logs routstr | grep -i admin

# Phase 4: verify
python3 scripts/node_setup.py check --public-url https://node.example

compose.node.yml binds the API to 127.0.0.1 only, starts no Tor service, and starts with analytics off. Your reverse proxy fronts it.
Private mode (python3 scripts/node_setup.py start --private) keeps the node loopback-only and publishes nothing until you set a public URL later.
Port 8000 taken? Pass --port 18080 and point the proxy at it.
Use docker compose -f compose.node.yml ... for every later Compose command. Plain docker compose up selects the different public/Tor stack.
start also mints a long-lived CLI token and writes ~/.routstr/config.json (mode 0600; an existing config for another node is left untouched) so the Routstr CLI can operate the node (routstr instruct, routstr providers list, ...). The token is full node admin; revoke it in Settings → CLI Tokens when done (--no-cli-token skips creation).

See the provider quickstart and the deployment guide for publishing, backups and updates.

Development

make setup
cp .env.example .env
fastapi run routstr

4.1 KiB Raw Permalink Blame History