Tokentoll
🐾 TokenToll: is a self-hostable billing infrastructure for LLM APIs and SaaS products. Drop-in SDKs for Node.js and Python, YAML-defined pricing plans, Stripe adapter, and a real-time usage dashboard | The open-source alternative to Lago and Orb.
Install / Use
/learn @AlameerAshraf/TokentollREADME
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT" /></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python" /></a> <a href="https://fastapi.tiangolo.com/"><img src="https://img.shields.io/badge/FastAPI-0.109+-009688?style=flat-square&logo=fastapi&logoColor=white" alt="FastAPI" /></a> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a> <a href="https://www.mongodb.com/"><img src="https://img.shields.io/badge/MongoDB-7-47A248?style=flat-square&logo=mongodb&logoColor=white" alt="MongoDB" /></a> <a href="https://redis.io/"><img src="https://img.shields.io/badge/Redis-7-DC382D?style=flat-square&logo=redis&logoColor=white" alt="Redis" /></a> <a href="https://www.docker.com/"><img src="https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker" /></a> <a href="https://stripe.com/"><img src="https://img.shields.io/badge/Stripe-Integrated-635BFF?style=flat-square&logo=stripe&logoColor=white" alt="Stripe" /></a> <a href="http://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-Welcome-brightgreen?style=flat-square" alt="PRs Welcome" /></a>
<br /> <br />Star History
<a href="https://www.star-history.com/?repos=AlameerAshraf%2Ftokentoll&type=timeline&logscale=&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=AlameerAshraf/tokentoll&type=timeline&theme=dark&logscale&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=AlameerAshraf/tokentoll&type=timeline&logscale&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=AlameerAshraf/tokentoll&type=timeline&logscale&legend=top-left" /> </picture> </a>12 AI Providers · 5 Pricing Models · 30+ API Endpoints · Python & Node SDKs
🚀 Quick Start · 🎯 Features · 📦 SDKs · 📖 API Reference · ⚙️ Configuration · 🐳 Deployment · 🤝 Contributing
<br /></div> <br />
🐾 What is TokenToll?
The problem: You're building a SaaS on top of LLMs. You need to track usage per customer, enforce quotas, support free tiers and prepaid credits, and generate invoices. Building all that from scratch takes weeks.
The solution: TokenToll gives you a single API to handle all of it. Ingest usage events, define pricing in YAML, and let TokenToll compute costs, enforce limits, generate invoices, and sync to Stripe — or run fully self-hosted.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ │ report │ │ invoice │ │
│ Your App │────────▶ │ TokenToll │────────▶ │ Customer │
│ calls LLM │ tokens │ API │ auto │ gets bill │
│ │ │ │ │ │
└──────────────┘ └──────────────┘ └──────────────┘
🎯 Features
<table> <tr> <td width="33%" valign="top">📊 Usage Metering
✅ Event ingestion via REST or SDK<br/> ✅ Idempotent (duplicate IDs ignored)<br/> ✅ Batch ingestion<br/> ✅ Multi-meter (tokens, calls, compute)<br/>
💰 Flexible Pricing
✅ Per-unit — qty × rate<br/>
✅ Tiered — bracket-based rates<br/>
✅ Volume — total determines rate<br/>
✅ Flat — fixed monthly fee<br/>
✅ Prepaid — credit deduction<br/>
✅ Free tiers — free allowance<br/>
🔒 Quotas & Entitlements
✅ Hard limits — block at cap<br/> ✅ Soft limits — alert via webhook<br/> ✅ Budget caps — dollar spending limits<br/> ✅ Alert thresholds — 80%, 100%, etc.<br/>
🧾 Invoicing & Payments
✅ Auto monthly invoice generation<br/> ✅ Per-meter line items<br/> ✅ Stripe sync or self-hosted<br/> ✅ Prepaid credit auto-apply<br/> ✅ Invoice status tracking<br/> ✅ Retry with exponential backoff<br/>
</td> <td width="33%" valign="top">🏢 Multi-Tenancy
✅ Full tenant isolation<br/> ✅ Operator super-admin API<br/> ✅ Per-tenant API key rotation<br/> ✅ SHA-256 hashed key storage<br/>
🔔 Webhooks & Observability
✅ HMAC-SHA256 signed delivery<br/> ✅ 3 event types with auto-retry<br/> ✅ Full audit logging<br/> ✅ Event replay / reconciliation<br/> ✅ Platform analytics endpoint<br/> ✅ Rate limiting per tenant<br/>
</td> </tr> </table> <br />🤖 Built-in AI Provider Pricing
TokenToll ships with pre-configured cost tables for 12 providers and 100+ models. Pass provider and model with your events — costs are calculated automatically.
<br />[!TIP] Rates are YAML files in
config/provider_pricing/— update them anytime and hot-reload without restart.
🏗️ Architecture
┌─────────────────┐ ┌──────────────────┐ ┌───────────────┐
│ │ │ │ │ │
│ Your App │────────▶│ TokenToll API │────────▶│ MongoDB │
│ (SDK / HTTP) │ │ (FastAPI) │ │ │
│ │ │ │ └───────────────┘
└─────────────────┘ └────────┬─────────┘
│
┌────────▼─────────┐
│ Redis Streams │
└────────┬─────────┘
│
┌────────────────┼────────────────-┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ Ingestion │ │ Invoice │ │ Webhook │
│ Worker │ │ Worker │ │ Worker │
└─────────────┘ └──────┬──────┘ └─────────────┘
│
┌───────▼────────┐
│ Stripe │
│ (optional) │
└────────────────┘
| Component | Role | |:---|:---| | 🌐 API Server | FastAPI REST API — auth, rate limiting, multi-tenant routing | | ⚡ Ingestion Worker | Processes usage events, updates wallets, checks entitlements | | 💵 Invoice Worker | Monthly invoice generation, Stripe sync, credit application | | 📨 Webhook Worker | HMAC-signed delivery with retries to your endpoints | | 🍃 MongoDB | Persistent storage — tenants, customers, events, invoices, audit logs | | 🔴 Redis | Stream-based queue + per-tenant rate limiting |
<br />🚀 Quick Start
[!NOTE] You need Docker & Docker Compose. Stripe is optional — without it, TokenToll runs in manual invoicing mode.
Step 1 — Start the stack
git clone https://github.com/AlameerAshraf/tokentoll.git
cd tokentoll
docker compose -f docker/docker-compose.yml up -d
Step 2 — Verify it's running
curl http://localhost:8000/health | jq
# ✅ {"status": "ok", "database": "ok"}
Step 3 — Create a tenant (your SaaS company)
curl -s -X POST http://localhost:8000/v1/tenants \
-H "Content-Type: application/json" \
-d '{"name": "My SaaS", "slug": "my-saas"}' | jq
Step 4 — Generate an API key
curl -s -X POST http://localhost:8000/v1/tenan
