Reconcile wallet funds by comparing the recorded wallet, its ledger and any reserved holds. A hold is a reservation associated with work, so it should not automatically be counted as a completed debit or as freely available funds.
IN THIS ARTICLE
01 Read the evidence
| Method | Resource | Scope | Idempotency-Key |
|---|---|---|---|
GET |
/v2/wallets |
wallet:read |
Not required by this route |
GET |
/v2/wallets/{walletId} |
wallet:read |
Not required by this route |
GET |
/v2/wallets/{walletId}/ledger |
wallet:read |
Not required by this route |
GET |
/v2/wallets/{walletId}/holds |
wallet:read |
Not required by this route |
- List the wallets visible to the authenticated account and select the returned public wallet ID and currency.
- Read that wallet's current recorded balances.
- Fetch its ledger and match relevant entries to the order, settlement or funding reference in your own reconciliation record.
- Read the holds and distinguish active reservations from completed or released states as represented by the response.
- Compare the related order and payment evidence before deciding whether the discrepancy is a pending operation, unpaid funding invoice or a completed settlement.
Do these collections all paginate the same way?
No. The wallet list uses its collection pagination. The current wallet-ledger helper returns a server-driven result and does not consume page or page_size controls. The holds helper requests up to 250 holds and also ignores those page controls. Do not assume a second page request proves you have retrieved older holds beyond that bound.
Should I subtract every hold from every balance field?
Use the meaning of the balance fields returned by the installed contract. A balance already representing spendable funds must not have reservations subtracted a second time. Keep decimal currency values exact and avoid merging wallets in different currencies into one unlabeled total.
How should I repair a discrepancy?
First reconcile the original order, invoice and settlement. Do not edit ledger rows directly or create another top-up because a paid invoice has not yet appeared as credit. Provide the wallet, order and payment references to authorised billing support if the records disagree.
A custom dashboard should distinguish recorded balance, reserved work and completed charges clearly. It should also show its data freshness so a delayed job is not misrepresented as lost money or a duplicate charge.