Skip to content

Knowledgebase

Reconcile wallet balances, ledger entries and reserved holds

domain-nexus, development

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.

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
  1. List the wallets visible to the authenticated account and select the returned public wallet ID and currency.
  2. Read that wallet's current recorded balances.
  3. Fetch its ledger and match relevant entries to the order, settlement or funding reference in your own reconciliation record.
  4. Read the holds and distinguish active reservations from completed or released states as represented by the response.
  5. 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.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support