> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openxswitch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling Wallet Balances

> When integrating OpenXSwitch/Blockchain webhooks to manage internal database records or user account balances, avoid updating local records by manually adding or subtracting incoming transaction amounts.

Due to rare on-chain edge cases, such as blockchain re-organizations, dynamic fee deductions, or execution adjustments, calculating local balances incrementally using transfer/deposit amounts can lead to ledger drift over time.

### Recommended Sync Strategy

Instead of calculating state changes incrementally, set your local ledger records directly using the verified snapshot provided in `params.wallet.token.balance`:

* `value`: The human-readable string representation of the verified balance, pre-formatted to match token decimals.
* `rawValue`: The raw integer string representation in minimal base units (atomic units/wei/lamport/satoshi/sun).

## Samples

`wallets` are always synchronized with `onchain` state. `Balance` values returned in webhook events reflect the latest blockchain state for the wallet and token.

```json highlight={23-24} theme={null}
{
 "requestId": "....",
 "method": "wallets:''.''",
 "params": {
   "...",
   "wallet":{
	  "id":"69eba664a8d8bc8c594d17fd",
	  "address":"0x7A750D8D6e12cce09A7c15482077a8A4d4c37de4",
	  "type":"settlement",
	  "protocol":"EVM",
	  "name":"Default Wallet(EVM)",
	  "refId":"b2be0f63-f73e-49f5-bc52-93dae008b1d7",
	  "custodyType":"DEVELOPER",
	  "token":{
	    "name":"Euro Coin",
		"symbol":"EURC",
		"blockchain":"BASE",
		"tokenAddress":"0x808456652fdb597867f38412077a9182bf77359f",
		"isNative":false,
		"decimals":6,
		"standard":"ERC20",
		"balance":{
			"value":"20",
			"rawValue":"20000000"
		    }
		 }
	   }
	}
  }
}
```

### Why Use `params.wallet.token.balance`?

1. **State Overwriting:** Replacing local database values with the payload state guarantees absolute alignment with the on-chain ledger at transaction execution time.
2. **Re-org Protection:** In the event of a chain re-organization, subsequent state updates automatically correct local records without requiring manual database reconciliation.
3. **Multi-Source Consistency:** Overwriting state avoids race conditions when multiple transactions occur in close succession across automated wallet workflows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.