Model Billing and Wallets

ResearchX supports per-model token-based billing combined with a user wallet system for cost management.

Architecture

Model billing config → Token usage generates charges → Deducted from user wallet → Admin can recharge / adjust balance

• Billing can be enabled or disabled independently for each model
• Each user has a dedicated wallet tracking balance, credit limit, and ledger history
• Admins can recharge wallets, adjust credit limits, and disable wallets
• Users with insufficient balance cannot initiate new model calls

Model Billing Configuration

In the model edit form at /workspace/admin/models (system models) or /workspace/models (personal models), find the Billing section at the bottom.

Configuration Fields

Billing Formula

Charge (micro-units) = ⌈(input_tokens × input_price + output_tokens × output_price) / 1000⌉
Actual charge = max(charge, minimum_charge)

⌈...⌉ denotes ceiling (round up).

Price Conversion Reference

Conversion between micro-units and yuan: 1 CNY = 1,000,000 micro-units

Example

Model configuration:

• Input price: 50,000 micro-units/1k tokens (¥0.05/1k tokens)
• Output price: 150,000 micro-units/1k tokens (¥0.15/1k tokens)
• Minimum charge: 1,000 micro-units (¥0.001)

A call consuming 2,000 input tokens + 500 output tokens:

Charge = ⌈(2000 × 50000 + 500 × 150000) / 1000⌉ = ⌈(100000000 + 75000000) / 1000⌉ = 175000 micro-units = ¥0.175

User Wallets

A wallet is automatically created for each user when they first use a billing-enabled model. Wallet properties:

Insufficient Balance Protection

When a user's wallet balance falls below -credit_limit, the system returns a 402 Payment Required error. The user cannot initiate model calls until an admin recharges the wallet or adjusts the balance within the allowed range.

Viewing Personal Wallet and Spending

Visit /workspace/token-usage to see:

• Wallet overview: balance, credit limit, total spent, charge count
• Token usage statistics: last 30 days of token consumption, grouped by day/month/project/model/provider/source
• Usage trend chart: bar chart showing input/output token distribution
• Recent charges: time, amount, post-charge balance, and description for each charge

Admin Operations

Platform-Level Spending Summary

Visit /workspace/admin/token-usage to see:

• Platform-wide token usage totals
• Cumulative spending and charge count
• User spending breakdown: per-user token usage, spending, and current balance
• Model spending breakdown: per-model spending and charge count

Managing User Wallets

Via the /api/admin/users/{userId}/wallet endpoint, admins can:

View Wallet

GET /api/admin/users/{userId}/wallet

Returns wallet information and the 50 most recent ledger entries.

Adjust Credit Limit and Status

PATCH /api/admin/users/{userId}/wallet

{
  "credit_limit_micros": "5000000",
  "status": "active"
}

• credit_limit_micros: new credit limit (micro-units); omit to keep current value
• status: active or disabled; omit to keep current value

Recharge / Adjust / Refund

POST /api/admin/users/{userId}/wallet

{
  "amount_micros": "15000000",
  "entry_type": "recharge",
  "description": "Monthly top-up"
}

Recharges and refunds increase the user balance; charges decrease it. All operations are recorded in the ledger.

Automatic Charge Flow

1. User initiates a chat or Agent call
2. System checks wallet status and balance (assertUserWalletCanStartUsage)
   • Wallet disabled → 402 error
   • Balance < -credit_limit → 402 error
3. After model call completes, the system calculates the charge based on token usage
4. If billing is enabled for the model and the charge > 0, a charge record is created and the wallet balance is updated
5. The charge record includes a pricing snapshot (pricing_snapshot_json) for historical traceability

Common Operations

Recharging a User

1. Go to /workspace/admin/users and find the target user
2. Copy the user ID
3. Recharge the wallet via API or admin UI

Enabling Billing for a Model

1. Go to /workspace/admin/models (system models) or /workspace/models (personal models)
2. Edit the target model
3. In the billing section, check "Enable billing"
4. Fill in input price, output price, and minimum charge
5. Save the model configuration

Disabling a User Wallet

Use PATCH /api/admin/users/{userId}/wallet to set status to disabled. The user will not be able to use any billing-enabled models.

Notes

• Currently only CNY billing currency is supported
• Models without billing enabled do not generate charges or check wallet balance
• Charges are calculated using micro-unit precision to avoid floating-point errors
• Admins can view each user's wallet status on the user management page
• Token usage statistics and billing are separate but related systems: usage is always recorded, while billing only triggers when enabled on the model