How the OmniRoute Free Tier Budget System Calculates Free Tokens

The OmniRoute free tier budget system calculates free tokens by aggregating per-model quotas from a hand-seeded catalog, deduplicating shared pools using dedupedSum, and categorizing allotments into steady recurring, credit-based, and one-time signup grants via the computeFreeModelTotals function in open-sse/config/freeModelCatalog.ts.

The OmniRoute project (diegosouzapw/OmniRoute) provides a unified interface for multiple AI providers, with a sophisticated system for tracking available free-tier capacity. Understanding how the OmniRoute free tier budget system calculates free tokens requires examining its three-stage aggregation pipeline, which transforms raw provider limits into accurate, deduplicated budget totals.

The Three-Stage Calculation Pipeline

The calculation proceeds through distinct stages, from raw data ingestion to final summation, ensuring accurate representation of complex provider policies including shared pools and one-time credits.

Stage 1: Source Data from Generated Catalogs

The system maintains two primary data sources in the open-sse/config directory that define the upper bounds of each provider’s free tokens:

• FREE_TIER_BUDGETS – A legacy per-provider map found in open-sse/config/freeTierCatalog.ts that records simple monthly token caps.
• FREE_MODEL_BUDGETS – A canonical, flat array of objects stored in open-sse/config/freeModelCatalog.data.ts that serves as the source of truth for every free-tier model.

The FREE_MODEL_BUDGETS array contains detailed objects recording the provider, model ID, monthly token cap, any one-time credit, the free-type (such as recurring-daily, recurring-monthly, or one-time-initial), an optional pool key for deduplication, and the provider’s ToS verdict. Both files are auto-generated by the free-tier research script (scripts/research/...) and refreshed on every release.

Stage 2: Deduplication and Pool Handling

Many providers offer several models that share a single free quota (for example, a "requests-per-day" pool that applies across multiple model variants). The helper function dedupedSum groups models by their poolKey and takes the maximum value for each pool, ensuring that a single pool is not double-counted in the final total.

Models without a pool key are counted individually. This logic prevents inflation of the free tier budget when multiple models draw from the same underlying quota.

Stage 3: Aggregation via computeFreeModelTotals

The computeFreeModelTotals function in open-sse/config/freeModelCatalog.ts performs the heavy lifting of calculating final token counts. It categorizes tokens into distinct buckets based on their freeType:

// Total recurring tokens (steady headline)
const steadyRecurringTokens = dedupedSum(models, m => m.monthlyTokens,
                                         m => RECURRING.has(m.freeType));

// Recurring credit grants (e.g., monthly $-credit plans)
const recurringCredits = dedupedSum(models, m => m.creditTokens,
                                    m => m.freeType === "recurring-credit");

// One-time signup credits (first-month only)
const oneTimeCredits = dedupedSum(models, m => m.creditTokens,
                                  m => m.freeType === "one-time-initial");

// Boost from deposit-unlock pools (e.g., OpenRouter $10 top-up)
const boostMonthlyTokens = … // Sum of FREE_TIER_BOOSTS whose pool is still live

The function returns a FreeModelTotals object containing:

• steadyRecurringTokens – The conservative headline used throughout the UI (e.g., ~X M/B tokens/month).
• steadyWithRecurringCreditsTokens – Steady tokens plus any recurring credit grants.
• firstMonthRealisticTokens – The maximum a user can expect in the first month, including one-time signup credits.
• boostMonthlyTokens – Extra tokens unlocked by a one-time deposit, shown separately to keep the headline conservative.
• uncappedProviders – Providers that are permanently free but have no published token cap (rate-limited only), listed but not summed into the headline.
• Metadata including modelCount, poolCount, per-model details, and a human-readable headline.

Practical Implementation

Developers can consume the free tier budget calculation directly in their applications using the exported functions from the configuration module.

Basic Usage

import { computeFreeModelTotals } from "@/open-sse/config/freeModelCatalog";

// Full totals (including providers flagged as "avoid")
const allTotals = computeFreeModelTotals();

// Exclude providers whose terms forbid proxy use
const usableTotals = computeFreeModelTotals({ excludeTosAvoid: true });

console.log("Steady free tokens/month:", allTotals.steadyRecurringTokens);
console.log("First-month realistic tokens:", allTotals.firstMonthRealisticTokens);
console.log("Extra boost from deposits:", allTotals.boostMonthlyTokens);

API Route Integration

The totals surface to the UI via the /api/free-tier/summary endpoint, which formats results using the helper fmt() (B for billions, M for millions):

// Example implementation in src/app/api/v1/free-tier/summary/route.ts
export async function GET() {
  const totals = computeFreeModelTotals({ excludeTosAvoid: true });
  return new Response(JSON.stringify({
    headline: totals.headline,
    steadyTokens: totals.steadyRecurringTokens,
    firstMonthTokens: totals.firstMonthRealisticTokens,
    boostTokens: totals.boostMonthlyTokens,
    uncappedProviders: totals.uncappedProviders,
  }));
}

The headline generated here powers the free-tier card displayed in the dashboard documentation (docs/screenshots/free-tier-budget-card.svg).

Summary

• Source of truth lives in open-sse/config/freeModelCatalog.data.ts as the auto-generated FREE_MODEL_BUDGETS array.
• Pool deduplication uses the dedupedSum function to take maximum values for shared quota pools, preventing budget inflation.
• Token categorization separates steady recurring allotments, recurring credits, one-time signup bonuses, and deposit-unlocked boosts via computeFreeModelTotals.
• ToS filtering allows optional exclusion of providers marked "avoid" using the excludeTosAvoid parameter.
• UI integration occurs through the /api/free-tier/summary endpoint, which formats totals for display.

Frequently Asked Questions

What is the difference between steady recurring tokens and first-month realistic tokens?

Steady recurring tokens represent the sustainable, ongoing monthly capacity available every month without additional actions, calculated from recurring-daily, recurring-monthly, and similar free types. First-month realistic tokens include these recurring amounts plus any one-time-initial signup credits, representing the maximum headroom a new user experiences during their initial month before those one-time grants expire.

How does OmniRoute handle providers that share a single free quota pool?

When multiple models share a quota pool, they are assigned the same poolKey in FREE_MODEL_BUDGETS. The dedupedSum helper groups these models and takes the maximum monthly token value for that pool rather than summing them, ensuring the budget calculation reflects the actual shared limit rather than artificially inflated totals.

Can I exclude providers with restrictive Terms of Service from the budget calculation?

Yes. Pass excludeTosAvoid: true to computeFreeModelTotals() to filter out any provider whose ToS verdict is "avoid" (such as opencode-zen or duckduckgo-web). This returns the usable free-tier headroom while the raw catalog in open-sse/config/freeTierCatalog.ts preserves the complete data for documentation purposes.

Where does the free tier budget data originate?

The data is hand-seeded through research and stored in FREE_MODEL_BUDGETS within open-sse/config/freeModelCatalog.data.ts. This file is auto-generated by scripts in scripts/research/... and refreshed on every release, ensuring the OmniRoute free tier budget system reflects current provider policies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}