GitHub - AlameerAshraf/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.

The open-source billing engine for AI & SaaS products

Meter tokens. Enforce quotas. Invoice automatically.

Star History

12 AI Providers · 5 Pricing Models · 30+ API Endpoints · Python & Node SDKs

🚀 Quick Start · 🎯 Features · 📦 SDKs · 📖 API Reference · ⚙️ Configuration · 🐳 Deployment · 🤝 Contributing

🐾 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

📊 Usage Metering

✅ Event ingestion via REST or SDK
✅ Idempotent (duplicate IDs ignored)
✅ Batch ingestion
✅ Multi-meter (tokens, calls, compute)

💰 Flexible Pricing

✅ Per-unit — qty × rate
✅ Tiered — bracket-based rates
✅ Volume — total determines rate
✅ Flat — fixed monthly fee
✅ Prepaid — credit deduction
✅ Free tiers — free allowance

🔒 Quotas & Entitlements

✅ Hard limits — block at cap
✅ Soft limits — alert via webhook
✅ Budget caps — dollar spending limits
✅ Alert thresholds — 80%, 100%, etc.

🧾 Invoicing & Payments

✅ Auto monthly invoice generation
✅ Per-meter line items
✅ Stripe sync or self-hosted
✅ Prepaid credit auto-apply
✅ Invoice status tracking
✅ Retry with exponential backoff

🏢 Multi-Tenancy

✅ Full tenant isolation
✅ Operator super-admin API
✅ Per-tenant API key rotation
✅ SHA-256 hashed key storage

🔔 Webhooks & Observability

✅ HMAC-SHA256 signed delivery
✅ 3 event types with auto-retry
✅ Full audit logging
✅ Event replay / reconciliation
✅ Platform analytics endpoint
✅ Rate limiting per tenant

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

_{GPT-4o · o1 · o3}	_{Claude 4 · 3.5 · Haiku}	_{Gemini 2.5 · Flash}	_{Large · Codestral}
_{V3 · R1}	_{Llama 3 · Llama 4}	_{Command R+}	_{LPU Inference}
_Grok	_{Sonar Pro}	_{Open Models}	_{Hosted OpenAI}

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

🚀 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/tenants/{tenant_id}/api-keys \
  -d '{"name": "production"}' | jq

# ⚠️ Save the "key" field — shown only once!

Step 5 — Create a customer & send usage

# Create customer on the "default" plan
curl -s -X POST http://localhost:8000/v1/tenants/{tenant_id}/customers \
  -H "Authorization: Bearer tt_your_key" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_123", "plan_id": "default", "name": "Alice"}' | jq

# Report usage
curl -s -X POST http://localhost:8000/v1/events \
  -H "Authorization: Bearer tt_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_001",
    "customer_id": "user_123",
    "meter_name": "token_count",
    "quantity": 1500,
    "provider": "openai",
    "model": "gpt-4o"
  }' | jq
# ✅ {"accepted": 1, "rejected": 0, "errors": []}

Step 6 — Check the balance

curl -s http://localhost:8000/v1/tenants/{tenant_id}/customers/{customer_id}/balance \
  -H "Authorization: Bearer tt_your_key" | jq

Tip

For the full 14-phase walkthrough covering every feature with curl, see docs/full-scenario-guide.md.

📦 SDKs

The SDKs are not published to package registries. Build and use them locally from your macine or PUBLISH THEM IF YOU WANT 👍🏻 🐾.

Build & install locally

Python SDK

# From repo root — editable install (changes apply immediately)
pip install -e ./packages/sdk-python
# or with uv:
uv pip install -e ./packages/sdk-python

Node.js SDK

# 1. Build the package (from repo root)
cd packages/sdk-node && npm run build

# 2. In your app, install from the local path
# If your app is inside tokentoll (e.g. apps/dashboard):
npm install ../../packages/sdk-node

# If your app is elsewhere, use an absolute or relative path:
npm install /path/to/tokentoll/packages/sdk-node

# Or add to your package.json dependencies:
# "@tokentoll/sdk-node": "file:../path/to/tokentoll/packages/sdk-node"

🐍 Python

from tokentoll import TokenToll

client = TokenToll(
    api_key="tt_your_key",
    base_url="http://localhost:8000",
    tenant_id="your_tenant_id"
)

# 🐾 Emit usage — one line
client.emit("user_123", "token_count", 1500)

# Check balance
balance = client.get_balance("user_123")

# Gate requests on quota
result = client.check_entitlement(
    "user_123", "token_count", 1000
)
if result["allowed"]:
    # serve the request
    ...

💚 Node.js

import { TokenToll } from '@tokentoll/sdk-node';

const client = new TokenToll({
  apiKey: 'tt_your_key',
  baseUrl: 'http://localhost:8000',
  tenantId: 'your_tenant_id',
});

// 🐾 Emit usage — one line
await client.emit('user_123', 'token_count', 1500);

// Check balance
const balance = await client.getBalance('user_123');

// Gate requests on quota
const { allowed, remaining } =
  await client.checkEntitlement(
    'user_123', 'token_count', 1000
  );

Environment variables (both SDKs): TOKENTOLL_API_KEY · TOKENTOLL_BASE_URL · TOKENTOLL_TENANT_ID

📖 API Reference

Note

🐾 Interactive Swagger UI is available at http://localhost:8000/docs when running locally.

Core Endpoints

	Method	Path	Auth	Description
📤	`POST`	`/v1/events`	Tenant	Ingest usage events (single or batch)
🏢	`POST`	`/v1/tenants`	Operator	Create a tenant
🏢	`GET`	`/v1/tenants`	Any	List tenants
🏢	`PATCH`	`/v1/tenants/{id}`	Any	Update tenant
🏢	`DELETE`	`/v1/tenants/{id}`	Any	Delete tenant (cascade)
👤	`POST`	`/v1/tenants/{id}/customers`	Tenant	Create a customer
👤	`GET`	`/v1/tenants/{id}/customers`	Tenant	List customers
👤	`PATCH`	`/v1/tenants/{id}/customers/{id}`	Tenant	Update customer / change plan
👤	`DELETE`	`/v1/tenants/{id}/customers/{id}`	Tenant	Delete customer
💰	`GET`	`.../customers/{id}/balance`	Tenant	Get usage & credit balance
💰	`POST`	`.../customers/{id}/credits`	Operator	Add prepaid credits
🔒	`POST`	`.../customers/{id}/check-entitlement`	Tenant	Check quota before serving
📊	`PUT`	`.../customers/{id}/budget`	Tenant	Set budget cap & alert thresholds
📊	`GET`	`.../customers/{id}/budget`	Tenant	Get budget
📊	`DELETE`	`.../customers/{id}/budget`	Tenant	Remove budget
🧾	`GET`	`.../customers/{id}/invoices`	Tenant	List invoices
🧾	`GET`	`/v1/tenants/{id}/invoices/{id}`	Tenant	Get single invoice
🔑	`POST`	`/v1/tenants/{id}/api-keys`	Any	Create API key
🔑	`GET`	`/v1/tenants/{id}/api-keys`	Any	List API keys
🔑	`DELETE`	`/v1/tenants/{id}/api-keys/{id}`	Any	Revoke API key
🔔	`POST`	`/v1/tenants/{id}/webhooks`	Tenant	Register webhook
🔔	`GET`	`/v1/tenants/{id}/webhooks`	Tenant	List webhooks
🔔	`PATCH`	`/v1/tenants/{id}/webhooks/{id}`	Tenant	Update webhook
🔔	`DELETE`	`/v1/tenants/{id}/webhooks/{id}`	Tenant	Delete webhook
📋	`GET`	`/v1/tenants/{id}/plans`	Tenant	List plans for tenant

Operator Endpoints

	Method	Path	Description
⚙️	`GET`	`/v1/config/plans`	List all plan configs
⚙️	`GET`	`/v1/config/plans/{id}`	Get plan config detail
⚙️	`PUT`	`/v1/config/plans/{id}`	Create or update plan
⚙️	`DELETE`	`/v1/config/plans/{id}`	Delete plan
🔄	`POST`	`/v1/config/reload`	Hot-reload config from YAML
📈	`GET`	`/v1/analytics`	Platform-wide aggregate stats
⏪	`POST`	`/v1/tenants/{id}/replay`	Replay events to rebuild usage
🤖	`GET`	`/v1/providers`	List available provider pricing

Authentication

Authorization: Bearer tt_...       ← Recommended
X-API-Key: tt_...                  ← Alternative header
?api_key=tt_...                    ← Query parameter

⚙️ Configuration

📋 Plans — `config/plans/*.yaml`

# config/plans/pro.yaml
name: pro
pricing_model: tiered
provider: openai                    # Use built-in provider rates

meters:
  token_count:
    tiers:
      - up_to: 1_000_000           # First 1M tokens
        rate: 0.0001
      - up_to: 10_000_000          # 1M – 10M tokens
        rate: 0.00008
      - up_to: null                 # 10M+ tokens
        rate: 0.00005

entitlements:
  token_count:
    hard_limit: 50_000_000          # 🛑 Block at 50M
    soft_limit: 40_000_000          # ⚠️ Alert at 40M

free_tier:
  token_count: 100_000              # 🎁 First 100K free

💲 Pricing Models

Model	Formula	Use Case
`per_unit`	`quantity × rate`	Simple token billing — $0.001/token
`tiered`	Rate changes per bracket	Volume discounts — cheaper at scale
`volume`	Total volume picks the rate	Enterprise pricing — all units at best rate
`flat`	Fixed fee	SaaS subscriptions — $99/month
`prepaid`	Deduct from credit balance	Buy $100 in credits, use until gone

📏 Meters — `config/meters/*.yaml`

name: token_count
type: token_count         # token_count | request_count | compute_time | custom
unit: tokens

🤖 Provider Pricing — `config/provider_pricing/*.yaml`

provider: openai
currency: USD
updated_at: "2025-03-01"
models:
  gpt-4o:
    input_per_million: 2.50
    output_per_million: 10.00
  gpt-4o-mini:
    input_per_million: 0.15
    output_per_million: 0.60

🔄 Hot Reload

curl -X POST http://localhost:8000/v1/config/reload \
  -H "Authorization: Bearer $OPERATOR_KEY"

# ✅ {"reloaded": true, "plans_synced": 4, "meters_synced": 1}

🧪 Testing

TokenToll includes integration tests covering critical billing guarantees:

tests/
├── integration/
│   ├── test_ingestion_idempotency.py   ← Duplicate events never double-counted
│   └── test_tenant_isolation.py        ← Cross-tenant access blocked (403)
└── conftest.py                         ← Shared fixtures

Test	What It Proves
✅ Idempotency	Same `event_id` sent twice → usage counted only once
✅ Tenant Isolation	Tenant A cannot read Tenant B's data → returns `403`
✅ Cross-Tenant Events	Events for another tenant's customer → rejected as `unknown_customer`

Run Tests

# Start dependencies
docker compose -f docker/docker-compose.yml up -d mongodb redis

# API integration tests
cd apps/api && uv run pytest -v

# Node SDK tests
cd packages/sdk-node && npm test

# Lint
cd apps/api && ruff check .

🐳 Deployment

Docker Compose (Recommended)

STRIPE_SECRET_KEY=sk_live_... \
OPERATOR_API_KEY=your-secret \
docker compose -f docker/docker-compose.yml up -d

Services

Service	Port	Description
🌐 `api`	`8000`	FastAPI REST API
⚡ `workers`	—	Ingestion event processor
💵 `invoice-worker`	—	Monthly invoice generator
📨 `webhook-worker`	—	Webhook delivery with retries
🖥️ `dashboard`	`5174`	React operator & customer UI
🍃 `mongodb`	`27018`	Persistent storage
🔴 `redis`	`6379`	Queue + rate limiting

Environment Variables

Variable	Default	Description
`MONGODB_URI`	`mongodb://localhost:27017/tokentoll`	MongoDB connection
`REDIS_URL`	`redis://localhost:6379/0`	Redis connection
`STRIPE_SECRET_KEY`	(none)	Stripe key — omit for manual invoicing
`OPERATOR_API_KEY`	(none)	Super-admin key — omit for open bootstrap
`RATE_LIMIT_REQUESTS_PER_MINUTE`	`1000`	Per-tenant rate limit
`LOG_LEVEL`	`INFO`	Logging verbosity
`CONFIG_PATH`	(auto)	Path to `config/` directory
`INVOICE_INTERVAL_MIN`	`60`	Invoice worker interval (minutes)

📂 Project Structure

tokentoll/
│
├── 🐾 apps/
│   ├── api/                          ← FastAPI REST API
│   │   └── src/
│   │       ├── main.py               ← App entry point & lifespan
│   │       ├── api/
│   │       │   ├── routes/           ← 15 route modules
│   │       │   ├── middleware/       ← Auth (API key) + Rate limiting
│   │       │   └── errors.py        ← Standardized error responses
│   │       ├── models/               ← 12 Beanie ODM document classes
│   │       ├── services/             ← 7 business logic modules
│   │       ├── adapters/             ← MongoDB, Redis, Stripe, Manual
│   │       └── config/               ← YAML loaders + JSON schemas
│   │
│   ├── workers/                      ← Background processors
│   │   └── src/workers/
│   │       ├── ingestion_worker.py   ← Usage event processing
│   │       ├── invoice_worker.py     ← Monthly billing
│   │       └── webhook_worker.py     ← Webhook delivery
│   │
│   └── dashboard/                    ← React + Vite + TypeScript
│       └── src/pages/                ← Operator & customer views
│
├── 📦 packages/
│   ├── sdk-python/                   ← Python SDK (httpx)
│   └── sdk-node/                     ← Node.js SDK (TypeScript)
│
├── ⚙️ config/
│   ├── plans/                        ← Pricing plan definitions
│   ├── meters/                       ← Meter definitions
│   └── provider_pricing/             ← 12 AI provider cost tables
│
├── 🐳 docker/
│   ├── docker-compose.yml            ← Full stack (7 services)
│   ├── Dockerfile.api
│   ├── Dockerfile.workers
│   └── Dockerfile.dashboard
│
└── 📚 docs/
    ├── full-scenario-guide.md        ← Complete HTTP walkthrough (14 phases)
    ├── video-script.md               ← Demo video script
    ├── deployment.md                 ← Production deployment
    └── testing-scenario.md           ← Test scenarios

🤝 Contributing

We welcome contributions! TokenToll is open source and community-driven.

Dev Setup

# 1. Fork & clone
git clone https://github.com/your-username/tokentoll.git && cd tokentoll

# 2. Start dependencies
docker compose -f docker/docker-compose.yml up -d mongodb redis

# 3. Install & run API
cd apps/api && uv sync && uvicorn src.main:app --reload --port 8000

# 4. Run workers (separate terminals)
cd apps/workers && uv sync
python -m src.workers.main ingestion
python -m src.workers.main invoice
python -m src.workers.main webhook

# 5. Build SDKs (for local use in your projects — see [SDKs](#-sdks))
cd packages/sdk-python && uv sync && pip install -e .   # or: uv pip install -e .
cd packages/sdk-node && npm install && npm run build

Contribution Flow

Step	Action
1	🍴 Fork the repo
2	🌿 Branch — `git checkout -b feat/my-feature`
3	✅ Test — `cd apps/api && uv run pytest -v`
4	🧹 Lint — `ruff check .`
5	📬 PR — open with a clear description

📄 License

MIT — use it however you want. See LICENSE for details.

🚀 Get Started · 📚 Read the Docs · 🔗 View API

Built with ❤️ for the AI developer community in Egypt 🇪🇬

Name		Name	Last commit message	Last commit date
.claude		.claude
apps		apps
config		config
docker		docker
example		example
packages		packages
.dockerignore		.dockerignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LLM-AGENT.md		LLM-AGENT.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation