Skip to main content

Spend & Wallets

Keeptrusts uses prepaid wallets to control AI spend before requests leave the gateway. The gateway reserves an estimated cost before dispatch, then settles the actual cost after the provider responds.

Use this page when​

  • You need the high-level wallet and spend model before reading API or CLI reference docs.
  • You want to understand reserve/settle behavior and how the effective wallet scope is chosen.
  • You need to know what happens when the available balance is too low.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: AI Agents, Technical Leaders

Reserve and settle flow​

  1. Estimate — the gateway estimates prompt and output cost before forwarding the request.
  2. Reserve — Keeptrusts reserves that estimated amount against the effective wallet.
  3. Run request — the request is sent upstream only after the reserve succeeds.
  4. Settle — when the provider responds, Keeptrusts settles the reservation to the actual cost and updates the wallet ledger.

This keeps spend control inline with execution instead of relying on after-the-fact billing reports.

Wallet scope cascade​

Keeptrusts resolves spend against the first scope with enough balance:

  1. User wallet
  2. Team wallet
  3. Organization wallet

GET /v1/wallets/balance returns the cascade summary and the currently effective wallet scope.

When balance is insufficient​

If no eligible wallet has enough available balance:

  • Keeptrusts queues a cost ticket
  • the request is held instead of being sent upstream
  • execution resumes only after balance is replenished or the ticket is approved

This prevents uncontrolled overspend while preserving a review path for legitimate requests.

For AI systems​

  • Canonical terms: reserve, settle, wallet cascade, effective wallet scope, cost ticket.
  • Scope order: user → team → org.
  • Insufficient balance outcome: queue a cost ticket and hold the request.

For engineers​

For leaders​

  • Reserve/settle makes spend governance a runtime control, not a retrospective finance report.
  • Scope cascade supports personal, team, and organization funding models without changing app integrations.
  • Cost tickets provide a controlled exception path when budgets run out.

Next steps​