Architecture patterns for shared credits, usage allowances, quotas, reward points, and reservation-based accounting—without double-spend or mystery balances.
What this pool coordinates
Credit pools coordinate a finite allowance across people, projects, API keys, agents, or services. They can represent model tokens, compute time, prepaid API usage, internal points, or promotional grants. The core system is an append-only ledger plus policy: accounts hold distinct units, reservations make concurrent use safe, quotas protect infrastructure, and reconciliation turns measured work into final entries.
Architecture priorities
A balance records value or entitlement. A quota limits activity during a window. A point may record participation or rewards. They can appear in one dashboard, but they need separate data models and rules. Clear boundaries keep a rate limit from looking like money and keep a promotional point from being treated as a refundable credit.
When the final cost is unknown, atomically reserve a conservative amount, run the work, commit measured usage, and release the remainder. Every mutation uses an idempotency key. Lease expiry and reconciliation policies handle timeouts, retries, and delayed provider callbacks.
Record grants, purchases, reservations, commits, releases, expirations, refunds, and adjustments as immutable entries. Materialize balances for speed, but preserve the event history that explains every unit. Corrections become compensating entries instead of silent edits.
Organizations often need parent budgets, project subaccounts, provider-specific buckets, expiring grants, and environment limits. Make inheritance and fallback explicit. Deterministic spend order and per-entry funding detail keep reports and disputes understandable.
Reference modules
Use these modules as separate services or bounded components. Their contracts matter more than how many repositories contain them.
Append-only entries, fixed precision, compensating corrections.
Atomic reserve, commit, release, renew, and expire paths.
Requests, units, concurrency, and period-based limits.
Compare observed usage with committed ledger entries.
Project, provider, key, model, and cost-center views.
Separate consumer, operator, finance, support, and auditor access.
Conceptual request
This example is an architecture pattern, not a live PoolAPI.com endpoint. It shows explicit identifiers, units, limits, and idempotency rather than hidden defaults.
POST /credit-reservations
{
"account_id": "acct_project_alpha",
"unit": "model_credit_milli",
"maximum": 25000,
"expires_in_seconds": 120,
"idempotency_key": "req_01J..."
}Frequently asked questions
No. A rate limiter controls activity over time, while a credit pool accounts for a finite allowance or value. A system can enforce both on the same request.
No. Use integers in the smallest unit or fixed-precision decimals with a declared scale.
Yes, but expiration should be a ledger event governed by a visible policy, not an unexplained balance overwrite.
Require idempotency keys and make balance checks plus reservation creation atomic.
Field notes
How to model pooled API credits without double-spend, ambiguous balances, or retry bugs—and how to separate limits from accounting.
A field guide to the resource model, lifecycle, control plane, allocation rules, and reliability patterns behind APIs that coordinate shared pools.
A practical blueprint for routing across LLMs without hiding capability differences, cost controls, reliability signals, or evaluation evidence.