diff --git a/docs/api/authentication.md b/docs/api/authentication.md index 9448802a..9b83ba9d 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -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 \ No newline at end of file +- [Using the API](../user-guide/using-api.md) - Integration examples diff --git a/docs/api/endpoints.md b/docs/api/endpoints.md index 89c4e94a..b7d2589d 100644 --- a/docs/api/endpoints.md +++ b/docs/api/endpoints.md @@ -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 \ No newline at end of file +- [Examples](../user-guide/using-api.md) - Code examples diff --git a/docs/api/overview.md b/docs/api/overview.md index 24dfb2d2..0b81318d 100644 --- a/docs/api/overview.md +++ b/docs/api/overview.md @@ -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 diff --git a/docs/user-guide/admin-dashboard.md b/docs/user-guide/admin-dashboard.md index 7c9b1e58..26c88391 100644 --- a/docs/user-guide/admin-dashboard.md +++ b/docs/user-guide/admin-dashboard.md @@ -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. diff --git a/docs/user-guide/introduction.md b/docs/user-guide/introduction.md index 1e40a797..4b1344ef 100644 --- a/docs/user-guide/introduction.md +++ b/docs/user-guide/introduction.md @@ -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 \ No newline at end of file +3. [Admin Dashboard](admin-dashboard.md) - Managing your account diff --git a/docs/user-guide/payment-flow.md b/docs/user-guide/payment-flow.md index a73163c0..03841a83 100644 --- a/docs/user-guide/payment-flow.md +++ b/docs/user-guide/payment-flow.md @@ -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 \ No newline at end of file +- [Models & Pricing](models-pricing.md) - Cost details diff --git a/docs/user-guide/using-api.md b/docs/user-guide/using-api.md index e409887e..4a1ced1e 100644 --- a/docs/user-guide/using-api.md +++ b/docs/user-guide/using-api.md @@ -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 '{