mirror of
https://github.com/Routstr/protocol.git
synced 2026-08-10 16:13:12 +00:00
77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# RIP-01: OpenAI-API Proxy with Cashu Payments
|
||
|
||
[x] - Implement HTTP proxy interface for OpenAI-compatible API requests
|
||
|
||
- [x] Integrate per-request micropayment handling via Cashu tokens
|
||
- [x] Support endpoints:
|
||
- [x] POST /v1/{path:path} (proxy to upstream AI service)
|
||
- [x] GET /v1/wallet (get Cashu token balance and API key)
|
||
- [x] POST /v1/wallet/topup (top up wallet with Cashu token)
|
||
- [x] POST /v1/wallet/refund (refund remaining balance as Cashu token)
|
||
- [x] Authorization via Bearer API key or Cashu token
|
||
- [x] API key and Cashu token validation and redemption
|
||
- [x] Token-based pricing for chat/completions with MODEL_BASED_PRICING
|
||
- [x] SSE and JSON cost reporting in responses
|
||
- [ ] Tor hidden service deployment support
|
||
- [ ] Admin dashboard for monitoring and settings
|
||
|
||
Defines the HTTP proxy interface forwarding OpenAI-compatible API requests, with per-request micropayment handling via Cashu tokens.
|
||
|
||
## Endpoints
|
||
|
||
### POST /v1/{path:path} e.g. /v1/chat/completions
|
||
|
||
Forward proxied requests to the upstream AI service at `UPSTREAM_BASE_URL`.
|
||
This is usually your llamacpp or vllm server.
|
||
|
||
### GET /v1/wallet
|
||
|
||
Get the balance of the Cashu token and the associated API key.
|
||
|
||
### POST /v1/wallet/topup
|
||
|
||
Top up the balance of that temporary wallet with another Cashu token.
|
||
|
||
### POST /v1/wallet/refund
|
||
|
||
Recieve the full amount of the remaining balance as a Cashu token.
|
||
|
||
#### Authorization
|
||
|
||
- Header: `Authorization: Bearer <api-key>` or `Bearer <cashu-token>`
|
||
- API keys: prefixed `sk-`, validated against stored hashed keys.
|
||
- Cashu tokens: prefixed `cashu`, redeemed via Cashu mint.
|
||
|
||
#### Payment Flow
|
||
|
||
1. **Balance**: The cashu token is redeemed and the balance is credited internally (allows reuse of the same token for multiple requests).
|
||
2. **Api-Key**: Each balance has an associated API key that allowes for top-ups.
|
||
3. **Token based pricing**: For chat/completions when `MODEL_BASED_PRICING`=true:
|
||
- Parse upstream `usage.prompt_tokens` and `usage.completion_tokens`.
|
||
- Compute `input_msats` = prompt_tokens/1000 × model.prompt_price.
|
||
- Compute `output_msats` = completion_tokens/1000 × model.completion_price.
|
||
- Charge or refund the difference via balance adjustment.
|
||
- Emit SSE event `data: {"cost": {...}}` appended to stream.
|
||
|
||
#### Responses
|
||
|
||
- **Streaming** (`text/event-stream`): Proxy SSE chunks and inject a final cost event.
|
||
- **Non-Streaming** (`application/json`): Embed a top-level `"cost": {...}` field in JSON.
|
||
|
||
#### Error Codes
|
||
|
||
- `401 Unauthorized`: Missing or invalid API key/Cashu token.
|
||
- `402 Payment Required`: Insufficient balance.
|
||
- `502 Bad Gateway`: Upstream service unavailable.
|
||
- `500 Internal Server Error`: Unexpected errors.
|
||
|
||
## Tor Routing
|
||
|
||
Every node can be deployed as a Tor hidden service.
|
||
|
||
## Multi model support
|
||
|
||
Each node can serve multiple models.
|
||
These models are defined in the root `/` endpoint.
|
||
Including node information and pricing.
|