mirror of
https://github.com/Routstr/routstr-core.git
synced 2026-08-09 19:04:47 +00:00
routstr core docs
This commit is contained in:
Shroominic
@@ -8,15 +8,14 @@ Routstr uses API key authentication for all protected endpoints. This guide cove
|
||||
|
||||
Create an API key by depositing an eCash token:
|
||||
|
||||
**Note: The POST /v1/wallet/create endpoint is coming soon. Currently, you can use Cashu tokens directly as API keys in the Authorization header.**
|
||||
|
||||
```bash
|
||||
POST /v1/wallet/create
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"cashu_token": "cashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vbWlu...",
|
||||
"name": "Production Key",
|
||||
"expires_at": "2024-12-31T23:59:59Z",
|
||||
"refund_npub": "npub1abcdef..."
|
||||
"cashu_token": "cashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vbWlu..."
|
||||
}
|
||||
```
|
||||
|
||||
@@ -25,9 +24,6 @@ Content-Type: application/json
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `cashu_token` | string | Yes | Base64-encoded Cashu token |
|
||||
| `name` | string | No | Friendly name for the key |
|
||||
| `expires_at` | string | No | ISO 8601 expiration timestamp |
|
||||
| `refund_npub` | string | No | Nostr pubkey for refunds |
|
||||
|
||||
**Response:**
|
||||
|
||||
@@ -36,7 +32,6 @@ Content-Type: application/json
|
||||
"api_key": "rstr_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
|
||||
"balance": 10000,
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"expires_at": "2024-12-31T23:59:59Z",
|
||||
"key_id": "key_123456"
|
||||
}
|
||||
```
|
||||
@@ -163,12 +158,14 @@ Response:
|
||||
### API Key Storage
|
||||
|
||||
**Do:**
|
||||
|
||||
- Store keys in environment variables
|
||||
- Use secret management systems
|
||||
- Encrypt keys at rest
|
||||
- Implement key rotation
|
||||
|
||||
**Don't:**
|
||||
|
||||
- Commit keys to version control
|
||||
- Share keys between environments
|
||||
- Log keys in plain text
|
||||
@@ -221,6 +218,7 @@ withdraw_balance(old_key)
|
||||
**Status Code:** 401
|
||||
|
||||
**Common Causes:**
|
||||
|
||||
- Typo in API key
|
||||
- Key doesn't exist
|
||||
- Key has been deleted
|
||||
@@ -243,6 +241,7 @@ withdraw_balance(old_key)
|
||||
**Status Code:** 401
|
||||
|
||||
**Resolution:**
|
||||
|
||||
- Create a new API key
|
||||
- Contact admin if refund address was set
|
||||
|
||||
@@ -266,6 +265,7 @@ withdraw_balance(old_key)
|
||||
**Status Code:** 402
|
||||
|
||||
**Resolution:**
|
||||
|
||||
- Top up the API key balance
|
||||
- Use a more economical model
|
||||
- Optimize request parameters
|
||||
@@ -284,6 +284,7 @@ curl https://your-node.com/v1/chat/completions \
|
||||
```
|
||||
|
||||
Response includes change:
|
||||
|
||||
```
|
||||
X-Cashu: cashuAeyJjaGFuZ2UiOlt7...
|
||||
```
|
||||
@@ -424,4 +425,4 @@ All API key usage is logged:
|
||||
|
||||
- [Endpoints](endpoints.md) - Complete endpoint reference
|
||||
- [Errors](errors.md) - Error handling guide
|
||||
- [Using the API](../user-guide/using-api.md) - Integration examples
|
||||
- [Using the API](../user-guide/using-api.md) - Integration examples
|
||||
|
||||
+114
-227
@@ -1,12 +1,33 @@
|
||||
# API Endpoints
|
||||
|
||||
Complete reference for all available endpoints in Routstr Core.
|
||||
Complete reference for all Routstr API endpoints.
|
||||
|
||||
## Chat Completions
|
||||
## Overview
|
||||
|
||||
Routstr provides OpenAI-compatible endpoints with Bitcoin/eCash payment integration.
|
||||
|
||||
### Base URL
|
||||
|
||||
All endpoints use the base URL:
|
||||
|
||||
```text
|
||||
https://api.routstr.com/v1
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
All endpoints require authentication via:
|
||||
|
||||
- **Bearer Token**: `Authorization: Bearer rstr_your_api_key`
|
||||
- **X-Cashu Header**: `X-Cashu: cashuAeyJ0...` (for direct eCash payments)
|
||||
|
||||
See [Authentication](authentication.md) for details.
|
||||
|
||||
## Chat
|
||||
|
||||
### Create Chat Completion
|
||||
|
||||
Generate a model response for a conversation.
|
||||
Send messages to generate model responses.
|
||||
|
||||
```http
|
||||
POST /v1/chat/completions
|
||||
@@ -16,7 +37,7 @@ POST /v1/chat/completions
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "gpt-3.5-turbo",
|
||||
"model": "gpt-4",
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
@@ -28,7 +49,6 @@ POST /v1/chat/completions
|
||||
}
|
||||
],
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 150,
|
||||
"stream": false
|
||||
}
|
||||
```
|
||||
@@ -38,17 +58,15 @@ POST /v1/chat/completions
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `model` | string | Yes | - | Model ID to use |
|
||||
| `messages` | array | Yes | - | Conversation messages |
|
||||
| `messages` | array | Yes | - | Array of message objects |
|
||||
| `temperature` | number | No | 1.0 | Sampling temperature (0-2) |
|
||||
| `max_tokens` | integer | No | Unlimited | Maximum tokens to generate |
|
||||
| `stream` | boolean | No | false | Stream response |
|
||||
| `max_tokens` | integer | No | Model default | Maximum tokens to generate |
|
||||
| `stream` | boolean | No | false | Stream partial responses |
|
||||
| `top_p` | number | No | 1.0 | Nucleus sampling |
|
||||
| `n` | integer | No | 1 | Number of completions |
|
||||
| `stop` | string/array | No | null | Stop sequences |
|
||||
| `presence_penalty` | number | No | 0 | Presence penalty (-2 to 2) |
|
||||
| `frequency_penalty` | number | No | 0 | Frequency penalty (-2 to 2) |
|
||||
| `logit_bias` | object | No | null | Token bias |
|
||||
| `user` | string | No | null | End-user identifier |
|
||||
|
||||
**Response:**
|
||||
|
||||
@@ -57,19 +75,19 @@ POST /v1/chat/completions
|
||||
"id": "chatcmpl-123",
|
||||
"object": "chat.completion",
|
||||
"created": 1677652288,
|
||||
"model": "gpt-3.5-turbo",
|
||||
"model": "gpt-4",
|
||||
"choices": [{
|
||||
"index": 0,
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "Hello! How can I assist you today?"
|
||||
"content": "Hello! How can I help you today?"
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}],
|
||||
"usage": {
|
||||
"prompt_tokens": 9,
|
||||
"completion_tokens": 10,
|
||||
"total_tokens": 19
|
||||
"prompt_tokens": 13,
|
||||
"completion_tokens": 9,
|
||||
"total_tokens": 22
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -78,7 +96,7 @@ POST /v1/chat/completions
|
||||
|
||||
When `stream: true`:
|
||||
|
||||
```
|
||||
```text
|
||||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
|
||||
|
||||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
|
||||
@@ -88,10 +106,12 @@ data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
## Completions
|
||||
## Completions (Coming Soon)
|
||||
|
||||
### Create Completion
|
||||
|
||||
**Note: This endpoint is coming soon and not yet available.**
|
||||
|
||||
Generate text completion (legacy endpoint).
|
||||
|
||||
```http
|
||||
@@ -133,7 +153,9 @@ POST /v1/completions
|
||||
|
||||
## Embeddings
|
||||
|
||||
### Create Embeddings
|
||||
### Create Embeddings (Coming Soon)
|
||||
|
||||
**Note: This endpoint is coming soon and not yet available.**
|
||||
|
||||
Generate vector representations of text.
|
||||
|
||||
@@ -178,10 +200,12 @@ POST /v1/embeddings
|
||||
}
|
||||
```
|
||||
|
||||
## Images
|
||||
## Images (Coming Soon)
|
||||
|
||||
### Create Image
|
||||
|
||||
**Note: This endpoint is coming soon and not yet available.**
|
||||
|
||||
Generate images from text prompts.
|
||||
|
||||
```http
|
||||
@@ -224,10 +248,12 @@ POST /v1/images/generations
|
||||
}
|
||||
```
|
||||
|
||||
## Audio
|
||||
## Audio (Coming Soon)
|
||||
|
||||
### Create Transcription
|
||||
|
||||
**Note: This endpoint is coming soon and not yet available.**
|
||||
|
||||
Convert audio to text.
|
||||
|
||||
```http
|
||||
@@ -256,6 +282,8 @@ Content-Type: multipart/form-data
|
||||
|
||||
### Create Translation
|
||||
|
||||
**Note: This endpoint is coming soon and not yet available.**
|
||||
|
||||
Translate audio to English.
|
||||
|
||||
```http
|
||||
@@ -284,71 +312,28 @@ GET /v1/models
|
||||
{
|
||||
"id": "gpt-3.5-turbo",
|
||||
"object": "model",
|
||||
"created": 1677652288,
|
||||
"created": 1677610602,
|
||||
"owned_by": "openai",
|
||||
"permission": [...],
|
||||
"root": "gpt-3.5-turbo",
|
||||
"parent": null,
|
||||
"pricing": {
|
||||
"prompt": 0.0015,
|
||||
"prompt": 0.001,
|
||||
"completion": 0.002,
|
||||
"prompt_sats_per_1k": 3,
|
||||
"completion_sats_per_1k": 4
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "gpt-4",
|
||||
"object": "model",
|
||||
"created": 1677652288,
|
||||
"owned_by": "openai",
|
||||
"pricing": {
|
||||
"prompt": 0.03,
|
||||
"completion": 0.06,
|
||||
"prompt_sats_per_1k": 60,
|
||||
"completion_sats_per_1k": 120
|
||||
"unit": "1k tokens"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Get Model
|
||||
|
||||
Get details for a specific model.
|
||||
|
||||
```http
|
||||
GET /v1/models/{model_id}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "gpt-3.5-turbo",
|
||||
"object": "model",
|
||||
"created": 1677652288,
|
||||
"owned_by": "openai",
|
||||
"permission": [{
|
||||
"allow_create_engine": false,
|
||||
"allow_sampling": true,
|
||||
"allow_logprobs": true,
|
||||
"allow_search_indices": false,
|
||||
"allow_view": true,
|
||||
"allow_fine_tuning": false
|
||||
}],
|
||||
"root": "gpt-3.5-turbo",
|
||||
"parent": null,
|
||||
"pricing": {
|
||||
"prompt": 0.0015,
|
||||
"completion": 0.002,
|
||||
"image": 0,
|
||||
"request": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Wallet Management
|
||||
|
||||
### Create API Key
|
||||
### Create Wallet (Coming Soon)
|
||||
|
||||
Create a new API key with eCash deposit.
|
||||
**Note: This endpoint is coming soon. Currently, you can use Cashu tokens directly as API keys.**
|
||||
|
||||
Create a new wallet with eCash deposit.
|
||||
|
||||
```http
|
||||
POST /v1/wallet/create
|
||||
@@ -358,10 +343,8 @@ POST /v1/wallet/create
|
||||
|
||||
```json
|
||||
{
|
||||
"cashu_token": "cashuAeyJ0b2tlbiI6W3...",
|
||||
"name": "My API Key",
|
||||
"expires_at": "2024-12-31T23:59:59Z",
|
||||
"refund_npub": "npub1..."
|
||||
"cashu_token": "cashuAeyJ0...",
|
||||
"admin_key": "optional-admin-key"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -369,48 +352,47 @@ POST /v1/wallet/create
|
||||
|
||||
```json
|
||||
{
|
||||
"api_key": "rstr_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
|
||||
"api_key": "rstr_1234567890abcdef",
|
||||
"admin_key": "radmin_fedcba0987654321",
|
||||
"balance": 10000,
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"expires_at": "2024-12-31T23:59:59Z"
|
||||
"mint": "https://mint.example.com",
|
||||
"unit": "sat"
|
||||
}
|
||||
```
|
||||
|
||||
### Check Balance
|
||||
|
||||
Get current balance and usage stats.
|
||||
Get current wallet balance.
|
||||
|
||||
```http
|
||||
GET /v1/wallet/balance
|
||||
Authorization: Bearer {api_key}
|
||||
Authorization: Bearer rstr_your_api_key
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"balance": 8546,
|
||||
"total_deposited": 10000,
|
||||
"total_spent": 1454,
|
||||
"last_used": "2024-01-01T12:34:56Z",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
"balance": 8500,
|
||||
"currency": "sat",
|
||||
"reserved": 0
|
||||
}
|
||||
```
|
||||
|
||||
### Top Up Balance
|
||||
### Top Up Wallet
|
||||
|
||||
Add funds to existing API key.
|
||||
Add funds to existing wallet.
|
||||
|
||||
```http
|
||||
POST /v1/wallet/topup
|
||||
Authorization: Bearer {api_key}
|
||||
Authorization: Bearer rstr_your_api_key
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"cashu_token": "cashuAeyJ0b2tlbiI6W3..."
|
||||
"cashu_token": "cashuAeyJ0..."
|
||||
}
|
||||
```
|
||||
|
||||
@@ -418,19 +400,19 @@ Authorization: Bearer {api_key}
|
||||
|
||||
```json
|
||||
{
|
||||
"old_balance": 8546,
|
||||
"added_amount": 5000,
|
||||
"new_balance": 13546
|
||||
"balance": 18500,
|
||||
"amount_added": 10000,
|
||||
"currency": "sat"
|
||||
}
|
||||
```
|
||||
|
||||
### Withdraw Balance
|
||||
### Withdraw Funds
|
||||
|
||||
Generate eCash token from balance.
|
||||
Withdraw balance as eCash.
|
||||
|
||||
```http
|
||||
POST /v1/wallet/withdraw
|
||||
Authorization: Bearer {api_key}
|
||||
Authorization: Bearer rstr_your_api_key
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
@@ -438,7 +420,7 @@ Authorization: Bearer {api_key}
|
||||
```json
|
||||
{
|
||||
"amount": 5000,
|
||||
"mint_url": "https://mint.minibits.cash/Bitcoin"
|
||||
"mint": "https://mint.example.com"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -446,172 +428,77 @@ Authorization: Bearer {api_key}
|
||||
|
||||
```json
|
||||
{
|
||||
"cashu_token": "cashuAeyJ0b2tlbiI6W3...",
|
||||
"cashu_token": "cashuAeyJ0...",
|
||||
"amount": 5000,
|
||||
"mint_url": "https://mint.minibits.cash/Bitcoin"
|
||||
"mint": "https://mint.example.com"
|
||||
}
|
||||
```
|
||||
|
||||
## Node Information
|
||||
|
||||
### Get Node Info
|
||||
|
||||
Get public information about the Routstr node.
|
||||
|
||||
```http
|
||||
GET /v1/info
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Lightning AI Gateway",
|
||||
"description": "Fast AI API access with Bitcoin payments",
|
||||
"version": "0.1.1b",
|
||||
"npub": "npub1abc...",
|
||||
"mints": [
|
||||
"https://mint.minibits.cash/Bitcoin",
|
||||
"https://testnut.cashu.space"
|
||||
],
|
||||
"http_url": "https://api.lightning-ai.com",
|
||||
"onion_url": "http://lightningai.onion",
|
||||
"models": {
|
||||
"gpt-3.5-turbo": {
|
||||
"name": "GPT-3.5 Turbo",
|
||||
"pricing": {
|
||||
"prompt": 0.0015,
|
||||
"completion": 0.002
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Discovery
|
||||
## Provider Discovery
|
||||
|
||||
### List Providers
|
||||
|
||||
Discover Routstr providers from Nostr relays.
|
||||
Get available upstream providers.
|
||||
|
||||
```http
|
||||
GET /v1/providers
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `relay` | string | Specific relay URL |
|
||||
| `limit` | integer | Maximum results |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": [
|
||||
{
|
||||
"name": "Fast AI Node",
|
||||
"npub": "npub1xyz...",
|
||||
"url": "https://fast-ai.com",
|
||||
"description": "Low latency AI API access",
|
||||
"models": ["gpt-3.5-turbo", "gpt-4"],
|
||||
"pricing": {
|
||||
"gpt-3.5-turbo": {
|
||||
"prompt_sats_per_1k": 3,
|
||||
"completion_sats_per_1k": 4
|
||||
}
|
||||
}
|
||||
"name": "openai",
|
||||
"models": ["gpt-4", "gpt-3.5-turbo"],
|
||||
"endpoints": ["chat/completions", "completions"],
|
||||
"status": "active"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Admin Endpoints
|
||||
### Provider Info
|
||||
|
||||
### Admin Dashboard
|
||||
|
||||
Access the web-based admin interface.
|
||||
Get specific provider details.
|
||||
|
||||
```http
|
||||
GET /admin/
|
||||
```
|
||||
|
||||
Requires password authentication via web form.
|
||||
|
||||
### Admin API
|
||||
|
||||
Protected endpoints for node management.
|
||||
|
||||
```http
|
||||
POST /admin/api/withdraw
|
||||
X-Admin-Password: {admin_password}
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"api_key": "rstr_123...",
|
||||
"amount": 5000
|
||||
}
|
||||
```
|
||||
|
||||
## Health & Status
|
||||
|
||||
### Health Check
|
||||
|
||||
Monitor service health.
|
||||
|
||||
```http
|
||||
GET /health
|
||||
GET /v1/providers/{provider_name}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"version": "0.1.1b",
|
||||
"timestamp": "2024-01-01T00:00:00Z",
|
||||
"checks": {
|
||||
"database": "ok",
|
||||
"upstream": "ok",
|
||||
"mint": "ok"
|
||||
}
|
||||
"name": "openai",
|
||||
"display_name": "OpenAI",
|
||||
"description": "Official OpenAI API",
|
||||
"models": [
|
||||
{
|
||||
"id": "gpt-4",
|
||||
"name": "GPT-4",
|
||||
"context_window": 8192,
|
||||
"pricing": {
|
||||
"prompt": 0.03,
|
||||
"completion": 0.06,
|
||||
"unit": "1k tokens"
|
||||
}
|
||||
}
|
||||
],
|
||||
"endpoints": ["chat/completions", "completions", "embeddings"],
|
||||
"features": ["streaming", "function_calling"],
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
### Metrics
|
||||
|
||||
Get service metrics.
|
||||
|
||||
```http
|
||||
GET /metrics
|
||||
```
|
||||
|
||||
Returns Prometheus-compatible metrics.
|
||||
|
||||
## Deprecated Endpoints
|
||||
|
||||
### Legacy Balance Check
|
||||
|
||||
```http
|
||||
GET /v1/balance
|
||||
Authorization: Bearer {api_key}
|
||||
```
|
||||
|
||||
⚠️ **Deprecated**: Use `/v1/wallet/balance` instead.
|
||||
|
||||
## Rate Limits
|
||||
## Rate Limiting
|
||||
|
||||
All endpoints are subject to rate limiting:
|
||||
|
||||
| Endpoint Type | Limit | Window |
|
||||
|---------------|-------|--------|
|
||||
| AI Generation | 100/min | 1 minute |
|
||||
| Wallet Operations | 10/min | 1 minute |
|
||||
| Info/Discovery | 60/min | 1 minute |
|
||||
- **Per minute**: 60 requests
|
||||
- **Per hour**: 1000 requests
|
||||
- **Per day**: 10000 requests
|
||||
|
||||
Rate limit information is included in response headers.
|
||||
|
||||
@@ -619,4 +506,4 @@ Rate limit information is included in response headers.
|
||||
|
||||
- [Errors](errors.md) - Error handling reference
|
||||
- [Authentication](authentication.md) - Auth details
|
||||
- [Examples](../user-guide/using-api.md) - Code examples
|
||||
- [Examples](../user-guide/using-api.md) - Code examples
|
||||
|
||||
@@ -5,7 +5,7 @@ Routstr Core provides a complete OpenAI-compatible API with additional endpoints
|
||||
## Base URL
|
||||
|
||||
```
|
||||
https://your-routstr-node.com/v1
|
||||
https://api.routstr.com/v1
|
||||
```
|
||||
|
||||
All API endpoints are prefixed with `/v1` for versioning.
|
||||
@@ -91,10 +91,10 @@ All errors follow a consistent format:
|
||||
Standard OpenAI-compatible endpoints:
|
||||
|
||||
- **Chat Completions**: `/v1/chat/completions`
|
||||
- **Completions**: `/v1/completions`
|
||||
- **Embeddings**: `/v1/embeddings`
|
||||
- **Images**: `/v1/images/generations`
|
||||
- **Audio**: `/v1/audio/transcriptions`
|
||||
- **Completions**: `/v1/completions` *(Coming soon)*
|
||||
- **Embeddings**: `/v1/embeddings` *(Coming soon)*
|
||||
- **Images**: `/v1/images/generations` *(Coming soon)*
|
||||
- **Audio**: `/v1/audio/transcriptions` *(Coming soon)*
|
||||
- **Models**: `/v1/models`
|
||||
|
||||
### Payment Endpoints
|
||||
|
||||
@@ -8,7 +8,7 @@ The Routstr admin dashboard provides a web interface for managing your node, vie
|
||||
|
||||
The admin dashboard is available at:
|
||||
```
|
||||
https://your-routstr-node.com/admin/
|
||||
https://api.routstr.com/admin/
|
||||
```
|
||||
|
||||
> **Important**: Always include the trailing slash (`/`) in the URL.
|
||||
|
||||
@@ -87,13 +87,19 @@ graph LR
|
||||
### 1. Get Bitcoin/eCash
|
||||
|
||||
Options:
|
||||
|
||||
- Buy Bitcoin and deposit to a Cashu mint
|
||||
- Receive eCash tokens from someone else
|
||||
- Use a testnet mint for testing
|
||||
|
||||
### 2. Create API Key
|
||||
### 2. Use Your eCash
|
||||
|
||||
You have two options for using your eCash tokens with Routstr:
|
||||
|
||||
#### Option A: Create a Persistent Wallet
|
||||
|
||||
Create a wallet with an API key for multiple requests:
|
||||
|
||||
Send your eCash token to Routstr:
|
||||
```bash
|
||||
POST /v1/wallet/create
|
||||
{
|
||||
@@ -101,15 +107,36 @@ POST /v1/wallet/create
|
||||
}
|
||||
```
|
||||
|
||||
Receive your API key and balance.
|
||||
This returns an API key (`rstr_...`) and your balance. The wallet persists between requests.
|
||||
|
||||
#### Option B: Direct Token Usage
|
||||
|
||||
Use your Cashu token directly as the API key:
|
||||
|
||||
```python
|
||||
client = OpenAI(
|
||||
api_key="cashuAeyJ0...", # Your Cashu token directly
|
||||
base_url="https://api.routstr.com/v1"
|
||||
)
|
||||
```
|
||||
|
||||
Routstr automatically converts the token to access the associated wallet. Each request consumes from the token's balance.
|
||||
|
||||
### 3. Make API Calls
|
||||
|
||||
Use your API key like any OpenAI key:
|
||||
With either method:
|
||||
|
||||
```python
|
||||
# Using persistent wallet API key
|
||||
client = OpenAI(
|
||||
api_key="your-routstr-key",
|
||||
base_url="https://your-routstr-node/v1"
|
||||
api_key="rstr_your_api_key",
|
||||
base_url="https://api.routstr.com/v1"
|
||||
)
|
||||
|
||||
# Or using Cashu token directly
|
||||
client = OpenAI(
|
||||
api_key="cashuAeyJ0...",
|
||||
base_url="https://api.routstr.com/v1"
|
||||
)
|
||||
```
|
||||
|
||||
@@ -128,11 +155,11 @@ When done, withdraw remaining balance as eCash through the admin interface.
|
||||
Routstr supports all standard OpenAI endpoints:
|
||||
|
||||
- ✅ `/v1/chat/completions` - Chat models
|
||||
- ✅ `/v1/completions` - Text completion
|
||||
- ✅ `/v1/embeddings` - Text embeddings
|
||||
- ✅ `/v1/images/generations` - Image generation
|
||||
- ✅ `/v1/audio/transcriptions` - Audio to text
|
||||
- ✅ `/v1/audio/translations` - Audio translation
|
||||
- 🚧 `/v1/completions` - Text completion (Coming soon)
|
||||
- 🚧 `/v1/embeddings` - Text embeddings (Coming soon)
|
||||
- 🚧 `/v1/images/generations` - Image generation (Coming soon)
|
||||
- 🚧 `/v1/audio/transcriptions` - Audio to text (Coming soon)
|
||||
- 🚧 `/v1/audio/translations` - Audio translation (Coming soon)
|
||||
- ✅ `/v1/models` - List available models
|
||||
- ✅ Custom provider endpoints
|
||||
|
||||
@@ -159,6 +186,7 @@ Total Cost = Base Fee + (Input Tokens * Input Rate) + (Output Tokens * Output Ra
|
||||
```
|
||||
|
||||
Fees may include:
|
||||
|
||||
- Exchange rate markup (BTC/USD conversion)
|
||||
- Provider margin
|
||||
- Node operator fee
|
||||
@@ -180,6 +208,7 @@ Fees may include:
|
||||
### Troubleshooting
|
||||
|
||||
Common issues and solutions:
|
||||
|
||||
- [Payment Flow](payment-flow.md) - Understanding the payment process
|
||||
- [Using the API](using-api.md) - API integration guide
|
||||
- [Admin Dashboard](admin-dashboard.md) - Managing your node
|
||||
@@ -213,4 +242,4 @@ Ready to start? Continue with:
|
||||
|
||||
1. [Payment Flow](payment-flow.md) - Detailed payment process
|
||||
2. [Using the API](using-api.md) - Making your first calls
|
||||
3. [Admin Dashboard](admin-dashboard.md) - Managing your account
|
||||
3. [Admin Dashboard](admin-dashboard.md) - Managing your account
|
||||
|
||||
@@ -5,6 +5,7 @@ Understanding how payments work in Routstr is key to using the system effectivel
|
||||
## Overview
|
||||
|
||||
Routstr uses a pre-funded account model where:
|
||||
|
||||
1. Users deposit eCash tokens to create an API key
|
||||
2. Each API request deducts from the balance
|
||||
3. Users can withdraw remaining balance as eCash
|
||||
@@ -16,12 +17,14 @@ Routstr uses a pre-funded account model where:
|
||||
Get a Cashu token from any compatible source:
|
||||
|
||||
**Option A: From a Cashu Wallet**
|
||||
|
||||
```bash
|
||||
# Example: Creating a 10,000 sat token
|
||||
cashu send 10000
|
||||
```
|
||||
|
||||
**Option B: Lightning Invoice**
|
||||
|
||||
```bash
|
||||
# Some mints support direct Lightning deposits
|
||||
curl -X POST https://mint.example.com/v1/mint/quote/bolt11 \
|
||||
@@ -29,6 +32,7 @@ curl -X POST https://mint.example.com/v1/mint/quote/bolt11 \
|
||||
```
|
||||
|
||||
**Option C: Test Tokens**
|
||||
|
||||
```bash
|
||||
# Get test tokens from testnet mints
|
||||
# Check mint documentation for faucets
|
||||
@@ -36,31 +40,28 @@ curl -X POST https://mint.example.com/v1/mint/quote/bolt11 \
|
||||
|
||||
### Step 2: Create API Key
|
||||
|
||||
**Note: The POST /v1/wallet/create endpoint is coming soon. Currently, you can use Cashu tokens directly as API keys in the Authorization header.**
|
||||
|
||||
Send your token to Routstr:
|
||||
|
||||
```bash
|
||||
curl -X POST https://your-routstr-node/v1/wallet/create \
|
||||
curl -X POST https://api.routstr.com/v1/wallet/create \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"cashu_token": "cashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vbWlu...",
|
||||
"name": "My Project Key",
|
||||
"expires_at": "2024-12-31T23:59:59Z",
|
||||
"refund_npub": "npub1abc..."
|
||||
"cashu_token": "cashuAeyJ0b2tlbiI6W3sibWludCI6Imh0dHBzOi8vbWlu..."
|
||||
}'
|
||||
```
|
||||
|
||||
**Request Parameters:**
|
||||
|
||||
- `cashu_token` (required): The eCash token to deposit
|
||||
- `name` (optional): Friendly name for the key
|
||||
- `expires_at` (optional): ISO timestamp for key expiration
|
||||
- `refund_npub` (optional): Nostr pubkey for refunds
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"api_key": "rstr_1234567890abcdef",
|
||||
"balance": 10000000,
|
||||
"expires_at": "2024-12-31T23:59:59Z",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
@@ -70,11 +71,12 @@ curl -X POST https://your-routstr-node/v1/wallet/create \
|
||||
Check your key's balance:
|
||||
|
||||
```bash
|
||||
curl -X GET https://your-routstr-node/v1/wallet/balance \
|
||||
curl -X GET https://api.routstr.com/v1/wallet/balance \
|
||||
-H "Authorization: Bearer rstr_1234567890abcdef"
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"balance": 10000000,
|
||||
@@ -113,7 +115,7 @@ import openai
|
||||
|
||||
client = openai.OpenAI(
|
||||
api_key="rstr_1234567890abcdef",
|
||||
base_url="https://your-routstr-node/v1"
|
||||
base_url="https://api.routstr.com/v1"
|
||||
)
|
||||
|
||||
# Make request
|
||||
@@ -133,6 +135,7 @@ print(f"Total tokens: {response.usage.total_tokens}")
|
||||
### Cost Breakdown
|
||||
|
||||
For the above request:
|
||||
|
||||
```
|
||||
Model: gpt-3.5-turbo
|
||||
Input tokens: 13
|
||||
@@ -155,16 +158,17 @@ Track your usage in real-time:
|
||||
|
||||
```bash
|
||||
# Get current balance
|
||||
curl -X GET https://your-routstr-node/v1/wallet/balance \
|
||||
curl -X GET https://api.routstr.com/v1/wallet/balance \
|
||||
-H "Authorization: Bearer your-api-key"
|
||||
|
||||
# View recent transactions (through admin dashboard)
|
||||
# Access at https://your-routstr-node/admin/
|
||||
# Access at https://api.routstr.com/admin/
|
||||
```
|
||||
|
||||
### Low Balance Handling
|
||||
|
||||
When balance is insufficient:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
@@ -180,7 +184,7 @@ When balance is insufficient:
|
||||
Add funds to existing key:
|
||||
|
||||
```bash
|
||||
curl -X POST https://your-routstr-node/v1/wallet/topup \
|
||||
curl -X POST https://api.routstr.com/v1/wallet/topup \
|
||||
-H "Authorization: Bearer your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
@@ -201,7 +205,7 @@ curl -X POST https://your-routstr-node/v1/wallet/topup \
|
||||
### Via API (if enabled)
|
||||
|
||||
```bash
|
||||
curl -X POST https://your-routstr-node/v1/wallet/withdraw \
|
||||
curl -X POST https://api.routstr.com/v1/wallet/withdraw \
|
||||
-H "Authorization: Bearer your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
@@ -215,6 +219,7 @@ curl -X POST https://your-routstr-node/v1/wallet/withdraw \
|
||||
### Token Validation
|
||||
|
||||
Routstr validates tokens by:
|
||||
|
||||
1. Checking signature validity
|
||||
2. Verifying with the issuing mint
|
||||
3. Ensuring no double-spending
|
||||
@@ -223,6 +228,7 @@ Routstr validates tokens by:
|
||||
### Failed Payments
|
||||
|
||||
Common failure reasons:
|
||||
|
||||
- Invalid token signature
|
||||
- Already spent token
|
||||
- Untrusted mint
|
||||
@@ -231,7 +237,7 @@ Common failure reasons:
|
||||
### Refund Policy
|
||||
|
||||
- Unused balance can be withdrawn anytime
|
||||
- Expired keys with balance can be refunded to `refund_npub`
|
||||
- Expired keys with balance can be refunded
|
||||
- Node operators may have additional policies
|
||||
|
||||
## Advanced Features
|
||||
@@ -239,11 +245,13 @@ Common failure reasons:
|
||||
### Multi-Mint Support
|
||||
|
||||
Routstr accepts tokens from multiple mints:
|
||||
|
||||
```bash
|
||||
CASHU_MINTS=https://mint1.com,https://mint2.com,https://mint3.com
|
||||
```
|
||||
|
||||
Benefits:
|
||||
|
||||
- Redundancy if one mint is down
|
||||
- User choice of mints
|
||||
- Geographic distribution
|
||||
@@ -251,11 +259,13 @@ Benefits:
|
||||
### Automatic Payouts
|
||||
|
||||
Configure automatic Lightning payouts:
|
||||
|
||||
```bash
|
||||
RECEIVE_LN_ADDRESS=satoshi@getalby.com
|
||||
```
|
||||
|
||||
When enabled:
|
||||
|
||||
- Balances above threshold are swept
|
||||
- Converted to Lightning payments
|
||||
- Sent to configured address
|
||||
@@ -263,14 +273,16 @@ When enabled:
|
||||
### Per-Request Payments (Coming Soon)
|
||||
|
||||
Future support for Nut-24 headers:
|
||||
|
||||
```bash
|
||||
curl -X POST https://your-routstr-node/v1/chat/completions \
|
||||
curl -X POST https://api.routstr.com/v1/chat/completions \
|
||||
-H "x-cashu: cashuAeyJ0..." \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{...}'
|
||||
```
|
||||
|
||||
Response includes change:
|
||||
|
||||
```
|
||||
HTTP/1.1 200 OK
|
||||
x-cashu: cashuAeyJjaGFuZ2Ui...
|
||||
@@ -331,11 +343,13 @@ x-cashu: cashuAeyJjaGFuZ2Ui...
|
||||
### Payment Rejected
|
||||
|
||||
**Error:** "Invalid token"
|
||||
|
||||
- Check token format
|
||||
- Verify mint is trusted
|
||||
- Ensure not already spent
|
||||
|
||||
**Error:** "Insufficient value"
|
||||
|
||||
- Token value too low
|
||||
- Check current pricing
|
||||
- Add larger token
|
||||
@@ -356,4 +370,4 @@ x-cashu: cashuAeyJjaGFuZ2Ui...
|
||||
|
||||
- [Using the API](using-api.md) - Integration guide
|
||||
- [Admin Dashboard](admin-dashboard.md) - Account management
|
||||
- [Models & Pricing](models-pricing.md) - Cost details
|
||||
- [Models & Pricing](models-pricing.md) - Cost details
|
||||
|
||||
@@ -21,7 +21,7 @@ from openai import OpenAI
|
||||
# Initialize client with Routstr endpoint
|
||||
client = OpenAI(
|
||||
api_key="rstr_your_api_key_here",
|
||||
base_url="https://your-routstr-node.com/v1"
|
||||
base_url="https://api.routstr.com/v1"
|
||||
)
|
||||
|
||||
# Use exactly like OpenAI
|
||||
@@ -46,7 +46,7 @@ import OpenAI from 'openai';
|
||||
// Initialize client
|
||||
const openai = new OpenAI({
|
||||
apiKey: 'rstr_your_api_key_here',
|
||||
baseURL: 'https://your-routstr-node.com/v1'
|
||||
baseURL: 'https://api.routstr.com/v1'
|
||||
});
|
||||
|
||||
// Make a request
|
||||
@@ -70,7 +70,7 @@ main();
|
||||
Direct HTTP requests:
|
||||
|
||||
```bash
|
||||
curl https://your-routstr-node.com/v1/chat/completions \
|
||||
curl https://api.routstr.com/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer rstr_your_api_key_here" \
|
||||
-d '{
|
||||
|
||||
Reference in New Issue
Block a user