Skip to main content
Behind every credit balance is a wallet — a credit account — and an append-only ledger of everything that ever happened to it. The balance you show a customer isn’t a number you store and mutate; it’s the sum of the wallet’s open grants, derived from the ledger.

​
Credit accounts are wallets

A customer holds one credit account per denomination they transact in — a unit wallet for “AI Credits”, a usd wallet for prepaid dollars, and so on. Each wallet is its own bucket; balances are never combined across wallets. A wallet accumulates grants (deposits) and deductions (usage), and its balance at any moment is: 
balance = Σ (remaining of every open grant in the wallet)
Because the balance is derived, it’s always internally consistent — there’s no separate counter to drift out of sync with the grants.

​
Wallet lifecycle

A credit account moves through three states:
StatusMeaningCan deduct?Can grant?
ACTIVENormal operationYesYes
FROZENTemporarily suspended — usage is blocked but the balance is preservedNo—
CLOSEDRetired — the wallet is doneNoNo
FROZEN is a pause, not a loss — grants stay on the books and become spendable again when the wallet returns to ACTIVE. CLOSED is terminal.
The ACTIVE / FROZEN / CLOSED lifecycle is part of v2 credit accounts. Reach for FROZEN when you need to halt consumption without wiping a customer’s balance — for example while a billing dispute is resolved.

​
The ledger

The ledger is the append-only record of every grant and every deduction against a wallet. Nothing is edited in place and nothing is deleted — a correction is a new entry, never a rewrite. That gives you:
  • A complete audit trail — every credit’s origin and every unit’s consumption is traceable.
  • A derivable balance — replay the open grants and you get the current balance, at any point in time.
  • Explainable deductions — you can show exactly which grant a unit of usage was drawn from and why (via the priority convention).
Each ledger entry ties back to its source: a grant entry to its rule (plan, drip, rollover, promotional, package), a deduction entry to the usage event that caused it.

​
Reserving before you spend

For operations whose final cost you don’t know upfront — an AI completion, a long-running job — you can hold balance on a wallet before the work starts, then confirm, adjust, or release the hold when it finishes. This reserve → work → finalize flow keeps concurrent requests from double-spending the same credits.

​
Reading a wallet

Read a customer’s live per-wallet balance from GET /v1/credit-accounts?customerId=…, the grants behind it from GET /v1/credit-grants?customerId=…, and the full history from GET /v1/credit-ledger?customerId=…. In the app, the React hooks render wallets, ledger, and burn directly.

​
See also

Grants & priority

What a grant is and the order deductions draw from.

Top-ups

How a top-up lands as a grant on the wallet.

Credit accounts (React)

Render a customer’s wallets and ledger in your UI.

Quickstart

Grant, spend, and read the ledger end to end.