# How the OmniRoute Free Tier Budget System Calculates Free Tokens

> Discover how OmniRoute's free tier budget system calculates free tokens. Learn about per-model quotas, deduplication, and allotment categorization for recurring, credit-based, and signup grants.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-24

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/freeModelCatalog.ts) performs the heavy lifting of calculating final token counts. It categorizes tokens into distinct buckets based on their `freeType`:

```ts
// 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

```ts
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):

```ts
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.