Skip to main content

Wallet Management: Allocating AI Credits to Teams

Keeptrusts allocates AI credits to teams by combining wallet visibility in /usage with the real wallet movement endpoints such as /v1/wallets/allocate and /v1/wallets/reclaim: the console shows you balance, effective available funds, and the ledger, while the transfer itself can be driven through a controlled admin workflow instead of guessing at who should pay for current usage.

Use this page when​

  • You want each team to have a clear AI spending envelope.
  • You need to stop one team from consuming the entire organization wallet.
  • You want a wallet flow that stays tied to real runtime usage and ledger records.

Primary audience​

  • Primary: Technical Engineers and platform operators managing cost controls
  • Secondary: Technical Leaders assigning team-level AI budgets

The problem​

Organization-wide funding is simple until it stops being simple. As soon as several teams share the same governed AI platform, one of them usually consumes more budget, experiments more aggressively, or needs stronger controls than the rest.

If all spend lands on one undifferentiated balance, you lose several important things at once:

  • no clear per-team accountability
  • no straightforward way to protect critical teams from lower-priority overuse
  • no clean way to connect runtime usage to budget decisions
  • no durable ledger that explains why funds moved

AI cost governance is harder than ordinary SaaS budgeting because charges do not arrive in neat fixed monthly blocks. Spend is created request by request. That means your funding model needs to map to the same request flow. Otherwise wallet allocation becomes a spreadsheet exercise that drifts away from the runtime.

Keeptrusts solves this with a wallet cascade and a real ledger. The important part is using the console and API together instead of expecting one surface to do everything.

The solution​

The current product already exposes the key pieces you need.

On /usage, the wallet view shows organization wallet balance, effective available balance, and transaction history. The ledger distinguishes credit, allocation in, allocation out, reservation, settlement, refund, and expiry-style movements. That means the console can answer what happened to the money.

The wallet system also resolves spend through a cascade: user wallet first, then team wallet, then organization wallet. That matters because team allocation is not an abstract budget label. It becomes part of the actual request funding decision.

Allocation itself is performed through the wallet APIs and BFF routes:

  • /v1/wallets/allocate to move funds into a team wallet
  • /v1/wallets/reclaim to return unused funds
  • /api/wallets/allocate and /api/wallets/reclaim for same-origin console-admin flows

This split is useful. The console is where you decide whether the allocation makes sense. The API is where the controlled transfer happens.

Implementation​

The safest workflow starts with evidence, not a funding guess.

  1. Open /usage and group current spend by team so you know who is actually using the platform.
  2. Review the wallet summary and transaction ledger to see whether recent spend is reserve-heavy, settlement-heavy, or already triggering funding pressure.
  3. Open /settings/teams if you need to confirm the exact team identities and names you will fund.
  4. Apply the allocation or reclaim action through the wallet API or your internal admin workflow.
  5. Return to /usage and confirm the ledger shows the movement you expected.
  6. Watch for downstream effects such as cost-ticket creation, wallet exhaustion, or an obvious mismatch between allocation and actual team demand.

If your teams map cleanly to consumer groups at the gateway layer, keep that linkage explicit in configuration as well:

consumer_groups:
  - id: engineering
    wallet_team_id: team_engineering
  - id: support
    wallet_team_id: team_support

cost_tracking:
  wallet_enforcement: true

That is what turns a financial policy into runtime behavior. Requests from the engineering group resolve against the engineering wallet, support traffic resolves against support, and the organization wallet remains the fallback rather than the only funding source.

A practical monthly allocation workflow looks like this:

  1. Review the previous month in /usage and identify the teams with stable, high-volume demand.
  2. Allocate baseline credits to those teams.
  3. Leave organization-level headroom for shared or unexpected traffic.
  4. During the month, watch /usage for which team is approaching its envelope.
  5. Reclaim unused funds from clearly over-allocated teams and reassign them deliberately instead of topping up the organization wallet blindly.

This also makes wallet exhaustion easier to reason about. If a request runs out of funds and falls through the cascade, the question is no longer "Why is the whole platform expensive?" It becomes "Which scope is exhausted, and was that expected?"

That is a much more actionable question. It tells you whether you need more credits, a policy change, a routing change, or a conversation with one team about how it is using the system.

Results and impact​

Team wallet allocation gives cost governance a real operating model. Instead of discovering overuse after the fact, you assign funding deliberately, monitor it in the same console where spend appears, and keep an auditable ledger of every adjustment.

This improves both fairness and resilience. High-priority teams do not get crowded out by unrelated experimentation. Platform teams can reassign budget based on evidence instead of guesswork. Leaders can ask why a team received more credits and get an answer grounded in usage and ledger history.

It also makes funding changes safer. Because the wallet movement is recorded and visible in /usage, you do not need to reconstruct the history from email or chat messages later.

Key takeaways​

  • Use /usage to decide allocations from real spend patterns before moving funds.
  • The console shows wallet state and ledger history; the API performs the allocation or reclaim action.
  • Team wallet allocation becomes meaningful only when it matches actual consumer-group or runtime identity boundaries.
  • The wallet cascade keeps organization funding as a fallback, not a substitute for team accountability.
  • Reclaiming and reassigning funds is often better than repeatedly increasing the organization pool.

Next steps​