Stablecoin Reconciliation & Ledger Integrity Guide

Ensure your internal balances, Bitnob wallet balances, and on-chain transactions stay perfectly in sync—always.

Why This Matters

In a multi-chain stablecoin system:

On-chain transactions are probabilistic until confirmed

Webhook delivery may fail or delay

Transfers may succeed on Bitnob but fail on-chain

Deposits may arrive without a known customer mapping

Even one unnoticed mismatch breaks trust

Your business must track and reconcile:

What you think the balance is (your internal ledger)

What Bitnob says the balance is (wallet API)

What the blockchain actually shows (confirmed txs to/from deposit addresses)

This guide shows how.

Reconciliation Strategy

Your Reconciliation System Should Answer:

question	example
Did we credit a deposit before it had enough confirmations?	Deposit shown, but only 4/15 confirmations
Did Bitnob emit a webhook but our system missed it?	Webhook succeeded but our job failed to process it
Did we mark a transfer as completed that actually failed?	txHash reverted — user was shown success
Did a wallet balance change without a matching ledger event?	Bitnob wallet says +$100 but no known deposit or webhook

Core Ledger Rules

Your internal ledger should:

Record every deposit and withdrawal with a reference, txHash, chain, token, wallet_id, timestamp, and source (Bitnob or internal)

Only allow a deposit credit once the deposit.success webhook is received

Only allow a withdrawal debit once Bitnob returns a 200 OK AND emits transfer.success

Log every webhook in a separate webhook_event_log table for traceability

Support reconciliation diffs, i.e.,

Reconciliation Diff Example

Daily Reconciliation Job

Inputs:

Bitnob wallet balances per chain/token (GET /wallets)

Your internal ledger balance per wallet/chain/token

Known incoming deposits (confirmed txs)

Known outgoing transfers with final status

What to Compare:

check	what to do if mismatch
Wallet balances Bitnob vs internal ledger	Log discrepancy, investigate missing tx
Deposit webhooks missing in ledger	Backfill ledger fromwebhook_event_log
Transfers marked successful but failed	Reverse ledger entry and notify support
Transfers initiated but not confirmed	Wait or mark as stuck and escalate
Orphaned on-chain tx (no wallet mapping)	Create holding wallet + assign manually

All mismatches should be grouped into “Pending Investigation”, “Resolved”, or “False Positive” buckets.

Reconciliation Alerts (for Ops/Finance)

Trigger alerts for:

Discrepancy ≥ threshold ($1 or 0.5%)

Stuck transfer in pending > 30 mins

Webhook not processed after 3 retries

Daily ledger delta ≠ expected net movement

Dashboard suggestion:

wallet id	token	bitnob balance	internal ledger	diff	status
X123	USDT	$10,000.00	$9,800.00	-200	Underinvestigation

Handling Missed Webhooks

Bitnob guarantees at-least-once delivery. But your app must:

Deduplicate based on event + txHash

Log every received event and its process result

Provide a retry mechanism (manual or automated) for:

deposit.success

transfer.success

transfer.failed

Missed webhooks are often the root cause of ledger mismatch.

Handling Partial Confirmations

Don’t credit a customer unless:

deposit.success webhook was received OR: You poll a txHash and see it has ≥ required confirmations for the chain

chain	minimum confirmations
Ethereum	15
BSC	15
Polygon	15
Tron	19
Solana	1
TON	3+ (chain-specific)

Internal Recovery Tools

Replay webhook by reference or txHash

Ledger explorer: filter by wallet, token, chain, date, discrepancy

Manual credit/debit override UI (restricted access)

Webhook ingestion log with status (success, retrying, dead-letter)

Export CSV for finance audits

Weekly Ops Checklist

task	status
Ledger balances reconcile with Bitnob	✅/❌
All deposit.success events processed	✅/❌
All transfer.success match ledger	✅/❌
No stuck pending transfers	✅/❌
Alert review + false positives tagged	✅/❌

Golden Rules for Integrity

Webhook-driven, not API-poll-driven . Only use polling as a failsafe.

Ledger is your truth, not the UI . Don’t show a transaction as completed unless it is reconciled.

Every Bitnob event must map to one and only one ledger action.

Your system should fail loudly . Never silently skip a webhook or write to ledger without audit.