Freebucks Quota Protection
Relevant source files
The following files were used as context for generating this wiki page:
Freebucks Quota Protection manages the consumption and preservation of upstream credits (Freebucks) within the account pool. This system prevents unnecessary credit loss by controlling session releases and enforcing scheduling logic based on real-time pricing and balance data returned from the Freebuff official endpoints.
The service handles Freebuff credentials via a multi-account pool, manages free-session admission, and performs request shaping to ensure compatibility with OpenAI-compatible API agents.
Sources: README_EN.md:12-16, README.md:16-20
Architecture and Billing Logic
The upstream bills in Freebucks (FB), where each model has an hourly price. An "admit" operation buys a full hour for a specific model; subsequent requests within that hour incur no marginal cost. The proxy utilizes this by maintaining active sessions until they expire naturally, as early releases via the DELETE method do not issue refunds.
Sources: README_EN.md:79-84, src/AGENTS.md:52-56
Quota Gates
The system enforces two independent quota gates that must both be satisfied for a request to proceed:
- Session Units: Tracked as
rateLimitsByModel.recentCount. The standard limit is 6 sessions per model per day. - Freebucks: The actual currency. Even if units are available, a request fails if there is a
freebucksShortfall.
Sources: src/AGENTS.md:46-51, README_EN.md:104-106
Billing Flow Diagram
This diagram illustrates the lifecycle of a Freebucks-billed session from admission to expiration.
Sources: src/AGENTS.md:46-56, README_EN.md:79-84
Account Scheduling and Failover
The scheduler prioritizes session reuse to maximize the value of purchased hours. It follows a "Sticky-first" (drain, not rotate) strategy to avoid triggering anti-farming measures and to minimize unnecessary admission costs.
Sources: src/AGENTS.md:61-65, dashboard/views/proxy/index.ts:161-165
Scheduling Priority
| Priority | Category | Behavior |
|---|---|---|
| 1 | Hot Session | Reuses existing active session for the requested model. |
| 2 | Used Account | Picks an account that has already purchased a session window. |
| 3 | Fresh Account | Picks an unused account from the pool (Clean account). |
Sources: src/AGENTS.md:61-64, dashboard/locale/dict/accounts.ts:98-100
Cooldown and Failover Logic
When a request fails, the system applies specific cooldown rules based on the error type:
- Account-level failure: Triggers a full account cooldown (e.g.,
banned,rate_limited,403). - Model-level failure: Triggers a cooldown only for the specific model (e.g.,
model_unavailable). - Transient errors: Errors like
503orpurchase_capacity(slot contention) cause the scheduler to skip the account without applying a cooldown.
Sources: src/AGENTS.md:57-60, README_EN.md:118-120
Configuration and Management
Quota protection settings are managed via the web console and stored in the /data directory.
Sources: README_EN.md:57-61, dashboard/views/proxy/index.ts:208-220
Key Protection Parameters
| Parameter | Description | Default / Range |
|---|---|---|
idleReleaseSec | Seconds to wait before releasing an idle session. | 600s (Default) |
maxNewSessionsPerRequest | Limit on new session admissions allowed per single request. | 2 (Default) |
lowBalanceThreshold | FB balance level that triggers a warning in the console. | 15 FB (Default) |
accountMaxConcurrency | Maximum concurrent requests allowed per account. | 2 (Standard) |
Sources: dashboard/views/proxy/index.ts:50-57, src/AGENTS.md:66-67
Session Management Interaction
The following sequence shows how the proxy manages session state between the user and the upstream.
Implementation Details
The system retrieves real-time pricing from the freebucks.prices field in session responses. It does not hardcode prices, ensuring accuracy as upstream rates change.
Sources: README_EN.md:85-88, test/suites/entries/smoke/parts/money/refund/fixture.ts:50-55
// Example of Freebucks metadata structure used in scheduling
const freebucksMetadata = {
balance: 25,
daily: {
limit: 25,
spent: 0,
remaining: 25,
resetAt: "2026-10-07T07:00:00Z"
},
prices: {
'deepseek/deepseek-v4-flash': 2
}
};
Sources: test/suites/entries/smoke/parts/money/refund/fixture.ts:50-55
Conclusion
Freebucks Quota Protection ensures cost-efficient operation by treating session admissions as one-hour buyouts and maximizing reuse. By enforcing dual gates (units and credits) and utilizing a sticky-first scheduling algorithm, the proxy maintains high availability while protecting the account pool from unnecessary resource depletion.