Skip to content

Overview

Routstr Core is a powerful payment proxy that brings Bitcoin micropayments to AI APIs. This overview will help you understand the core concepts and architecture.

Core Concepts

Payment Proxy

Routstr acts as a transparent proxy between your application and OpenAI-compatible APIs. It:

  • Intercepts API requests
  • Validates payment tokens
  • Forwards requests to the upstream provider
  • Tracks usage and deducts costs
  • Returns responses to the client

Cashu eCash Protocol

Cashu is a Bitcoin eCash protocol that enables:

  • Privacy: Payments are unlinkable and untraceable
  • Instant Settlement: No waiting for blockchain confirmations
  • Micropayments: Send fractions of a satoshi
  • Offline Capability: Tokens can be transferred without internet

Lightning Network Integration

Routstr connects to the Lightning Network through Cashu mints, enabling:

  • Fast Bitcoin deposits and withdrawals
  • Global payment reach
  • Low transaction fees
  • No minimum payment amounts

Architecture

System Components

graph TB
    subgraph "Client Side"
        A[AI Application]
        B[OpenAI SDK]
        C[eCash Wallet]
    end

    subgraph "Routstr Core"
        D[FastAPI Server]
        E[Auth Module]
        F[Payment Module]
        G[Proxy Module]
        H[SQLite Database]
    end

    subgraph "External Services"
        I[Upstream AI Provider]
        J[Cashu Mint]
        K[Bitcoin/Lightning]
    end

    A --> B
    B --> D
    C --> D
    D --> E
    E --> F
    F --> J
    D --> G
    G --> I
    D --> H
    J --> K

Key Modules

  1. Authentication (auth.py)
  2. API key validation
  3. Balance checking

  4. Request authorization

  5. Payment Processing (payment/)

  6. Token validation
  7. Cost calculation
  8. Balance updates

  9. Pricing models

  10. Proxy Handler (proxy.py)

  11. Request forwarding
  12. Response streaming
  13. Usage tracking

  14. Error handling

  15. Wallet Management (wallet.py)

  16. Cashu wallet integration
  17. Token redemption
  18. Balance management

  19. Automatic payouts

  20. Admin Interface (core/admin.py)

  21. Web dashboard
  22. Balance viewing
  23. Key management
  24. Withdrawal interface

Payment Flow

Standard Flow (API Key)

  1. User deposits eCash tokens to create an API key
  2. Client sends requests with the API key
  3. Routstr checks balance and forwards request
  4. Cost is deducted based on actual usage
  5. Response is returned to client

Per-Request Flow (Coming Soon)

  1. Client includes eCash token in request header
  2. Routstr validates token meets minimum amount
  3. Request is processed
  4. Change is returned in response header
  5. No account or balance needed

Supported Features

API Compatibility

  • ✅ Chat completions (streaming and non-streaming)
  • ✅ Text completions
  • ✅ Embeddings
  • ✅ Image generation
  • ✅ Audio transcription/translation
  • ✅ Model listing
  • ✅ Custom endpoints

Payment Features

  • ✅ Multiple Cashu mint support
  • ✅ Automatic balance tracking
  • ✅ Model-based pricing
  • ✅ USD to BTC conversion
  • ✅ Configurable fees
  • ✅ Balance withdrawals

Operational Features

  • ✅ Docker deployment
  • ✅ Tor hidden service support
  • ✅ Nostr relay discovery
  • ✅ Database migrations
  • ✅ Comprehensive logging
  • ✅ Admin dashboard

Next Steps