From a7d5f394722f5f045f8ddeeea3b196cbd2d44320 Mon Sep 17 00:00:00 2001
From: DJP <DJP>
Date: Wed, 11 Mar 2026 19:41:36 -0400
Subject: [PATCH] docs: Add detailed cost calculation explanation and verified
 pricing tables

Explains how LibreChat calculates tokenValue, how the dashboard reads it,
and includes verified pricing tables for Claude, OpenAI, and Gemini models.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 34bfb83..500f14f 100644
--- a/README.md
+++ b/README.md
@@ -132,7 +132,74 @@ To reset the key in your browser: open DevTools (F12) > Application > Local Stor
 
 ## Cost Calculation
 
-Costs come directly from LibreChat's `transactions` collection. LibreChat stores `tokenValue = rawAmount x rate` where rate is USD per 1M tokens. The dashboard reads these pre-calculated values — it does not independently calculate pricing.
+### How it works
+
+The dashboard does **not** calculate costs itself. Costs come directly from LibreChat's MongoDB `transactions` collection, which records every API call.
+
+When a user sends a message, LibreChat:
+1. Records the token usage in the `transactions` collection with fields like `rawAmount` (token count, stored as negative), `tokenType` (prompt or completion), and `model`
+2. Looks up the model's pricing from its internal pricing table (`api/models/tx.js`)
+3. Calculates `tokenValue = rawAmount × rate` where rate is USD per 1M tokens
+4. Stores `tokenValue` alongside the transaction
+
+The dashboard reads `tokenValue` and converts to USD: **`cost = Math.abs(tokenValue) / 1,000,000`**
+
+This means costs reflect the rate that was active *at the time of the API call*. If pricing changes, old transactions keep their original cost (which is correct — they were billed at the old rate).
+
+### Where pricing lives
+
+The pricing table is in LibreChat's codebase at `api/models/tx.js`. It uses a longest-match pattern strategy — e.g. `claude-sonnet-4-6` matches before the generic `claude-` fallback.
+
+### Agent transactions
+
+When a user interacts with an Agent, LibreChat records `model` as `agent_XYZ` (the agent's ID). The dashboard resolves these to the underlying LLM model via the `agents` collection (cached, refreshed every 5 minutes).
+
+### Verified pricing (March 2026)
+
+The following rates from LibreChat's `tx.js` have been validated against official provider pricing pages:
+
+**Anthropic Claude** (source: platform.claude.com/docs/en/about-claude/pricing)
+
+| Model | Input ($/1M tokens) | Output ($/1M tokens) | Verified |
+|-------|--------------------:|---------------------:|----------|
+| claude-opus-4-6 | 5.00 | 25.00 | Yes |
+| claude-sonnet-4-6 | 3.00 | 15.00 | Yes |
+| claude-sonnet-4 | 3.00 | 15.00 | Yes |
+| claude-opus-4-5 | 5.00 | 25.00 | Yes |
+| claude-opus-4 | 15.00 | 75.00 | Yes |
+| claude-haiku-4-5 | 1.00 | 5.00 | Yes |
+| claude-3-5-haiku | 0.80 | 4.00 | Yes |
+| claude-3-opus | 15.00 | 75.00 | Yes |
+| claude-3-haiku | 0.25 | 1.25 | Yes |
+
+**OpenAI** (source: openai.com/api/pricing)
+
+| Model | Input ($/1M tokens) | Output ($/1M tokens) | Verified |
+|-------|--------------------:|---------------------:|----------|
+| gpt-4o | 2.50 | 10.00 | Yes |
+| gpt-4o-mini | 0.15 | 0.60 | Yes |
+| gpt-4.1 | 2.00 | 8.00 | Yes |
+| gpt-4.1-mini | 0.40 | 1.60 | Yes |
+| gpt-4.1-nano | 0.10 | 0.40 | Yes |
+| o1 | 15.00 | 60.00 | Yes |
+| o1-mini | 1.10 | 4.40 | Mismatch* |
+| o3 | 2.00 | 8.00 | Yes |
+| o3-mini | 1.10 | 4.40 | Yes |
+| o4-mini | 1.10 | 4.40 | Yes |
+
+*o1-mini: tx.js has $1.10/$4.40, current OpenAI pricing shows $3/$12. May reflect an older rate. Only affects you if using o1-mini.
+
+**Google Gemini** (source: ai.google.dev/gemini-api/docs/pricing)
+
+| Model | Input ($/1M tokens) | Output ($/1M tokens) | Verified |
+|-------|--------------------:|---------------------:|----------|
+| gemini-2.5-pro | 1.25 | 10.00 | Yes |
+| gemini-2.5-flash | 0.30 | 2.50 | Yes |
+| gemini-2.0-flash | 0.10 | 0.40 | Yes |
+| gemini-2.0-flash-lite | 0.075 | 0.30 | Yes |
+| gemini-1.5-flash | 0.15 | 0.60 | Deprecated |
+
+Note: Gemini 2.5 Pro has tiered pricing — prompts over 200K tokens cost $2.50/$15.00. tx.js uses the base tier which applies to most usage.
 
 ## API Endpoints