Token Management

LibreChat includes a token/credit system for controlling user access to AI features. This allows you to implement usage limits, quotas, or paid tiers.

Overview

The token management system enables:

User balance tracking
Usage quotas and limits
Credit-based access control
Transaction history
Automated balance deduction

Add Balance

Add tokens/credits to user accounts

Set Balance

Set specific balance amounts

List Balances

View all user balances

Balance Configuration

Configure the balance system

Enabling Balance System

Enable the balance system in librechat.yaml:

librechat.yaml

balance:
  enabled: true
  
  # Initial balance for new users
  initialBalance: 1000
  
  # Minimum balance required
  minimumBalance: 0
  
  # Allow negative balances
  allowNegative: false
  
  # Token costs per model
  tokenCosts:
    openai:
      gpt-4: 0.03
      gpt-3.5-turbo: 0.002
    anthropic:
      claude-3-opus: 0.015
      claude-3-sonnet: 0.003

The balance system must be enabled in librechat.yaml before using token management commands.

Add Balance

Add tokens/credits to a user’s account.

Usage

npm run add-balance <email> <amount>

Interactive Mode

npm run add-balance

You’ll be prompted for:

Email: User’s email address
Amount: Number of tokens to add (default: 1000)

Examples

npm run add-balance [email protected] 1000

Transaction Record

Each balance addition creates a transaction record with:

User ID
Amount added
Context: “admin”
Timestamp
New balance

Balance additions are tracked in the transaction history, which can be useful for billing, auditing, and user support.

Set Balance

Set a user’s balance to a specific amount (overwriting the current balance).

Usage

npm run set-balance <email> <amount>

Interactive Mode

npm run set-balance

Examples

npm run set-balance [email protected] 1000

This overwrites the current balance!Unlike add-balance, this command sets the balance to the exact amount specified, regardless of the current balance. Use add-balance to increment the existing balance.

List Balances

View token balances for all users.

Usage

npm run list-balances

Output Format

Displays:

Email address
Current balance
Last transaction date
Total tokens used

Example Output

┌──────────────────────────┬──────────┬────────────────┬──────────────┐
│ Email                    │ Balance  │ Last Updated   │ Tokens Used  │
├──────────────────────────┼──────────┼────────────────┼──────────────┤
│ [email protected]        │ 2,450    │ 2024-03-01     │ 5,550        │
│ [email protected]        │ 10,000   │ 2024-03-02     │ 1,200        │
│ [email protected]        │ 0        │ 2024-02-28     │ 1,000        │
└──────────────────────────┴──────────┴────────────────┴──────────────┘

Configuration

Configure the balance system in librechat.yaml:

Basic Settings

balance.enabled

boolean

required

Enable or disable the balance system

balance.initialBalance

number

default:"1000"

Starting balance for new users

balance.minimumBalance

number

default:"0"

Minimum balance required to use features

balance.allowNegative

boolean

default:"false"

Allow users to have negative balances

Token Costs

Define costs per model:

librechat.yaml

balance:
  enabled: true
  
  # Cost per 1000 tokens
  tokenCosts:
    # OpenAI models
    openai:
      gpt-4: 0.03          # $0.03 per 1k tokens
      gpt-4-32k: 0.06      # $0.06 per 1k tokens
      gpt-3.5-turbo: 0.002 # $0.002 per 1k tokens
    
    # Anthropic models
    anthropic:
      claude-3-opus: 0.015
      claude-3-sonnet: 0.003
      claude-3-haiku: 0.00025
    
    # Google models
    google:
      gemini-pro: 0.0005
      gemini-ultra: 0.01
    
    # Custom endpoints
    custom:
      default: 0.001  # Default for custom models

Usage Limits

Implement daily or monthly limits:

librechat.yaml

balance:
  enabled: true
  
  # Usage limits
  limits:
    # Daily token limit per user
    daily: 10000
    
    # Monthly token limit per user
    monthly: 100000
    
    # Maximum tokens per request
    perRequest: 4000

Balance Tiers

Create different user tiers:

librechat.yaml

balance:
  enabled: true
  
  tiers:
    free:
      initialBalance: 1000
      monthlyRefill: 1000
      models:
        - gpt-3.5-turbo
    
    pro:
      initialBalance: 10000
      monthlyRefill: 10000
      models:
        - gpt-3.5-turbo
        - gpt-4
        - claude-3-sonnet
    
    enterprise:
      initialBalance: 100000
      monthlyRefill: 100000
      models: all

Transaction History

View a user’s transaction history:

Using MongoDB

db.transactions.find({ user: ObjectId("user_id") }).sort({ createdAt: -1 })

Transaction Fields

user - User ID
tokenType - Type of tokens (credits, tokens, etc.)
rawAmount - Amount of transaction
rate - Exchange rate (if applicable)
context - Context (admin, usage, refund, etc.)
model - AI model used (for usage transactions)
conversationId - Related conversation
balance - Balance after transaction
createdAt - Transaction timestamp

Automated Balance Deduction

LibreChat automatically deducts tokens based on usage:

User Sends Message

User submits a message to an AI model

Token Count

System counts input and output tokens

Calculate Cost

Cost is calculated based on model rates

Deduct Balance

Tokens are deducted from user’s balance

Update Transaction Log

Transaction is recorded with details

Insufficient Balance

When a user has insufficient balance:

Block Request
Allow Negative
Use Free Model

balance:
  enabled: true
  onInsufficientBalance: block

User receives an error message and the request is blocked.

balance:
  enabled: true
  allowNegative: true

User can go into negative balance (pay later model).

balance:
  enabled: true
  onInsufficientBalance: fallback
  fallbackModel: gpt-3.5-turbo

Automatically switch to a free or cheaper model.

Environment Variables

Optional environment variables for balance system:

CHECK_BALANCE

boolean

default:"false"

Enable balance checking before processing requests

FORCE_BALANCE_CHECK

boolean

default:"false"

Force balance check even for admin users

Best Practices

Set Reasonable Initial Balances

Give new users enough tokens to meaningfully try the service without excessive free usage.

Monitor Usage Patterns

Track which models are used most and adjust pricing accordingly.

Implement Refill Policies

Consider monthly refills for subscription users or balance expiration for free tiers.

Communicate Costs Clearly

Show users their balance and cost per request in the UI.

Audit Transactions Regularly

Review transaction logs for unusual patterns or potential issues.

Troubleshooting

Error: Balance is not enabled

Enable the balance system in librechat.yaml:

balance:
  enabled: true

Balances not deducting

Verify CHECK_BALANCE is set to true in .env
Check librechat.yaml has token costs defined
Ensure database transactions are working
Review server logs for errors

Transaction not created

Verify MongoDB connection
Check user ID is valid
Ensure balance configuration is correct
Review database permissions

Incorrect token costs

Verify model names match exactly in librechat.yaml
Check for typos in model names
Ensure costs are per 1000 tokens (standard format)
Update configuration and restart server

User Management - Create and manage users
Configuration - YAML configuration reference
Monitoring - Track usage and costs

Get Started

Core Features

Configuration

Deployment

User Guide

Administration

Overview

Add Balance

Set Balance

List Balances

Balance Configuration

Enabling Balance System

Add Balance

Usage

Interactive Mode

Examples

Transaction Record

Set Balance

Usage

Interactive Mode

Examples

List Balances

Usage

Output Format

Example Output

Configuration

Basic Settings

Token Costs

Usage Limits

Balance Tiers

Transaction History

Using MongoDB

Transaction Fields

Automated Balance Deduction

Insufficient Balance

Environment Variables

Best Practices

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Deployment

User Guide

Administration

​Overview

Add Balance

Set Balance

List Balances

Balance Configuration

​Enabling Balance System

​Add Balance

​Usage

​Interactive Mode

​Examples

​Transaction Record

​Set Balance

​Usage

​Interactive Mode

​Examples

​List Balances

​Usage

​Output Format

​Example Output

​Configuration

​Basic Settings

​Token Costs

​Usage Limits

​Balance Tiers

​Transaction History

​Using MongoDB

​Transaction Fields

​Automated Balance Deduction

​Insufficient Balance

​Environment Variables

​Best Practices

​Troubleshooting

​Related Documentation

Build docs developers (and LLMs) love

Overview

Enabling Balance System

Add Balance

Usage

Interactive Mode

Examples

Transaction Record

Set Balance

Usage

Interactive Mode

Examples

List Balances

Usage

Output Format

Example Output

Configuration

Basic Settings

Token Costs

Usage Limits

Balance Tiers

Transaction History

Using MongoDB

Transaction Fields

Automated Balance Deduction

Insufficient Balance

Environment Variables

Best Practices

Troubleshooting

Related Documentation