The wallet balance ledger

Every time the wallet service changes a balance, it writes a row to wallet_audit_log recording the balance before and after, the amount that caused the change, and the idempotency key the operation ran under.

This is the correct answer to "my balance is wrong" and to any disputed withdrawal. It is the only record in the platform that can distinguish a customer who was credited once from one who was credited twice, and it is the strongest compliance story the product has.

It is also easy to miss: it is surfaced as an unlabelled panel on the Audit Trail tab of four detail screens, and nowhere else.

The endpoint

Nothing in the product writes to this table through an API. The wallet service is the only producer, the table is timestamps: false with a manual createdAt and no updatedAt, and there is no soft-delete column. Append-only is a property of the schema, not a convention.

Querying it

The route takes the standard CRUD parameters: page, perPage, sortField, sortOrder and a JSON-encoded filter.

GET /api/admin/finance/wallet/audit?filter={"walletId":"<uuid>"}
GET /api/admin/finance/wallet/audit?filter={"userId":"<uuid>"}

• walletId — one wallet's history: one currency, one type, one customer.
• userId — that customer's entire trail across every wallet they hold.

Default sort is createdAt. The wallet is joined in, so each row carries the currency and type of the wallet it moved — which is what makes a userId query readable when the customer holds six currencies.

The five money columns are declared numeric on the route so they sort and filter as numbers. Without that they would sort lexicographically and "9" would come after "10".

The columns

All the money columns are DECIMAL(30,18) and arrive from the driver as strings. The panel coerces every one before formatting; so must anything you write against the API.

The eight operations

HOLD and RELEASE are deliberately shown as neutral rather than as a credit or a debit. They move money between two columns of the same wallet and change nothing about what the customer owns. Reading a HOLD as a debit is the most common misread of this table.

The idempotency key is the proof

Every wallet operation runs under a key, and the table carries a unique index on it. That is what makes this ledger able to answer the question a transaction list cannot:

The customer says they were charged twice. Were they?

If two operations shared a key, only the first is here — the second was rejected as a duplicate. Two rows with different keys and identical amounts is a genuine double-movement. One row is one movement, always.

The keys are readable and name their origin: admin_deposit_approve_<txId>, platform_fee_<TYPE>_<referenceId>, admin_transfer_approve_<txId>, transfer_reject_<txId>, admin_wallet_adjust_<walletId>_<type>_<amount>_nonce_<nonce>. The panel shows both the key and the transaction id in the tooltip on the When column.

Where it appears in the admin panel

The panel is composed once and mounted on five detail pages, on the tab labelled Audit Trail:

The wallet screen is the one to reach for when you already know which wallet is in question: it puts the Adjust balance control and the ledger that control writes to on the same page, so you can make a correction and read back what it did without leaving for the customer's record.

On every screen except the customer record the tab shows two panels stacked: the administrative actions taken against that record, and beneath it the balance ledger for the wallet it moved. The first tells you who decided; the second tells you what the decision did to the balance. That pairing is the point of the tab.

The panel loads ten rows at a time and accumulates them behind a Load more button rather than paging, because an audit trail is read as a continuous history. The count in the footer reads Showing n of <total>.

It renders as a plain table rather than the platform's data table, because the value is in the arithmetic lining up: previous → new beside the amount that caused it. Wide content scrolls inside the panel; the page does not scroll sideways.

How it differs from the admin audit trail

The platform has two append-only audit tables and they answer different questions. Mixing them up costs an investigation an hour.

A customer's own trading, deposits and withdrawals produce no admin audit rows — nobody administrative acted. They produce balance-ledger rows for every movement. Conversely, an admin action that changed no balance (editing a gateway, approving a KYC application) appears only in the admin trail.

One semantic that is easy to get backwards on the admin trail: userId is the admin who acted and targetId is the record acted upon. Filtering a customer's page by userId shows what that customer did as an admin, which for a customer is nothing at all — the panel looks empty rather than wrong.

Using it on a dispute

Related: Customer wallets and balance adjustments for what a hand adjustment writes here, and Transaction types and statuses for the row on the other end of transactionId.