> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useunitpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets & the ledger

> Credit accounts as wallets, their lifecycle, and the append-only ledger behind every balance.

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](/documentation/credits/denominations) 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](/documentation/credits/grants-and-priority) (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:

| Status   | Meaning                                                               | Can deduct? | Can grant? |
| -------- | --------------------------------------------------------------------- | :---------: | :--------: |
| `ACTIVE` | Normal operation                                                      |     Yes     |     Yes    |
| `FROZEN` | Temporarily suspended — usage is blocked but the balance is preserved |      No     |      —     |
| `CLOSED` | Retired — the wallet is done                                          |      No     |     No     |

```mermaid actions={false} theme={null}
stateDiagram-v2
    [*] --> ACTIVE
    ACTIVE --> FROZEN: freeze
    FROZEN --> ACTIVE: unfreeze
    ACTIVE --> CLOSED: close
    FROZEN --> CLOSED: close
```

`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.

<Note>
  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.
</Note>

## 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](/documentation/credits/grants-and-priority)).

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](/react/introduction) render wallets, ledger, and burn directly.

## See also

<CardGroup cols={2}>
  <Card title="Grants & priority" icon="layer-group" href="/documentation/credits/grants-and-priority">
    What a grant is and the order deductions draw from.
  </Card>

  <Card title="Top-ups" icon="arrow-up-from-bracket" href="/documentation/credits/top-ups">
    How a top-up lands as a grant on the wallet.
  </Card>

  <Card title="Credit accounts (React)" icon="react" href="/react/introduction">
    Render a customer's wallets and ledger in your UI.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/documentation/getting-started/setup">
    Grant, spend, and read the ledger end to end.
  </Card>
</CardGroup>