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
2. Either your own deployment or access to a public node

3. The base URL (e.g., https://api.routstr.com/v1)

4. A Cashu Wallet (optional but recommended)

5. Nutstash - Web wallet
6. Minibits - Mobile wallet

7. Cashu.me - Simple web wallet

8. An API Client

9. OpenAI Python/JavaScript SDK
10. Any HTTP client (curl, Postman, etc.)
11. 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 (sk-...) 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="sk-...",
    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
2. Simple flat fee per API call

3. Good for uniform usage

4. Token-Based Pricing

5. Pay per input/output token

6. More accurate for varied usage

7. Model-Based Pricing

8. Different rates per model
9. 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