Wallets

A wallet is a high-frequency balance account. It accepts writes at high throughput and periodically posts an aggregated journal entry to the ledger.

Why wallets exist

The core ledger is GAAP-compliant and immutable — every write is a permanent, auditable record. This makes it ideal for billing events, invoices, and settlements, but not for thousands of small writes per second. Typical use cases that need wallets:

• Token grants and burns — every API call or event debits a balance
• Usage metering — credits accumulate per request, per second
• Real-time point systems — micro-credits on user actions

For these patterns, use wallets. For low-frequency writes (billing events, invoices, refunds) use the Journal Entries API directly.

Balance consistency

The wallet’s balance is always current — it reflects all accepted writes immediately, including any that have not yet been posted to the ledger. Callers never see a stale balance.

Writes accepted by the wallet are batched and posted to the ledger periodically. There is a short delay (typically a few seconds) between a write being accepted and the corresponding journal entry appearing in the ledger.

Wallet identity

Wallets are identified by a caller-defined key (callerKey) — any opaque string meaningful to your system (e.g. user_abc123, subscription_xyz, device_001).

The full wallet key sent to the API is:

{ledgerId}:{callerKey}

Where ledgerId is the UUID shown on the ledger detail page in the dashboard.

Wallets are auto-created on first write. There is no provisioning step — the first credit or debit call creates the wallet if it does not already exist.

Reservations

Wallets support a reserve → commit/release flow for scenarios where you need to hold balance before confirming a spend (e.g. authorising a payment before settlement).

1. Reserve — temporarily holds an amount, reducing available but not balance
2. Commit — settles the hold; deducts from balance and closes the reservation
3. Release — cancels the hold; restores the held amount to available

Reservations expire automatically if neither committed nor released within their TTL.

Wallets vs. direct ledger writes