routstr-core/docs/user-guide/introduction.md

User Guide Introduction

Welcome to the Routstr Core User Guide. This guide will help you understand how to use Routstr to access AI APIs with Bitcoin micropayments.

What You'll Learn

• How the payment system works
• Creating and managing API keys
• Making API calls through Routstr
• Using the admin dashboard
• Managing your balance

Prerequisites

Before starting, you'll need:

1. A Running Routstr Instance

   • Either your own deployment or access to a public node
   • The base URL (e.g., https://api.yournode.com)

2. A Cashu Wallet (optional but recommended)

   • Nutstash - Web wallet
   • Minibits - Mobile wallet
   • Cashu.me - Simple web wallet

3. An API Client

   • OpenAI Python/JavaScript SDK
   • Any HTTP client (curl, Postman, etc.)
   • Your application code

How Routstr Works

Traditional API Access

graph LR
    A[Your App] --> B[OpenAI API]
    B --> A

• Direct connection to provider
• Monthly billing
• Credit card required
• Usage limits

With Routstr

graph LR
    A[Your App] --> B[Routstr Proxy]
    B --> C[OpenAI API]
    C --> B
    B --> A
    D[Bitcoin/eCash] --> B

• Pay per request with Bitcoin
• No credit card needed
• Anonymous payments
• Instant settlement

Key Concepts

eCash Tokens

• Digital bearer tokens backed by Bitcoin
• Can be sent like cash - whoever has the token owns it
• Redeemable at Cashu mints for Bitcoin
• Perfect for micropayments

API Keys

• Created by depositing eCash tokens
• Track your balance and usage
• Can be topped up anytime
• Optional expiry and refund address

Balance Management

• Measured in millisatoshis (msats)
• 1 Bitcoin = 100,000,000 sats = 100,000,000,000 msats
• Deducted based on actual usage
• Withdrawable as eCash tokens

Typical Workflow

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. 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:

POST /v1/wallet/create
{
  "cashu_token": "cashuAeyJ0..."
}

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:

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

With either method:

# Using persistent wallet API key
client = OpenAI(
    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"
)

4. Monitor Usage

• Check balance: GET /v1/wallet/balance
• View admin dashboard
• Track costs per request

5. Withdraw Funds

When done, withdraw remaining balance as eCash through the admin interface.

Supported Endpoints

Routstr supports all standard OpenAI endpoints:

• ✅ /v1/chat/completions - Chat models
• 🚧 /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

Cost Structure

Pricing Models

1. Fixed Cost Per Request

   • Simple flat fee per API call
   • Good for uniform usage

2. Token-Based Pricing

   • Pay per input/output token
   • More accurate for varied usage

3. Model-Based Pricing

   • Different rates per model
   • Reflects actual provider costs

Cost Calculation

Total Cost = Base Fee + (Input Tokens * Input Rate) + (Output Tokens * Output Rate)

Fees may include:

• Exchange rate markup (BTC/USD conversion)
• Provider margin
• Node operator fee

Getting Support

Documentation

• This user guide for general usage
• API Reference for technical details
• Contributing Guide for developers

Community

• GitHub Issues for bugs and features
• Nostr for decentralized discussion
• Node operator contact info

Troubleshooting

Common issues and solutions:

• Payment Flow - Understanding the payment process
• Using the API - API integration guide
• Admin Dashboard - Managing your node

Security Considerations

API Key Security

• Treat API keys like passwords
• Never share or commit them
• Rotate keys regularly
• Use environment variables

Payment Security

• eCash tokens are bearer instruments
• Verify mint trustworthiness
• Keep backups of tokens
• Use small amounts for testing

Network Security

• Always use HTTPS connections
• Verify SSL certificates
• Consider using Tor for privacy
• Monitor for unusual activity

Next Steps

Ready to start? Continue with:

1. Payment Flow - Detailed payment process
2. Using the API - Making your first calls
3. Admin Dashboard - Managing your account