Balance Model via Webhooks

Recommended Update Strategy

It is recommended not to implement balance updates using increment/decrement logic from webhook amounts. Instead, always overwrite balances using the latest balance values returned in webhook payloads to prevent drift, duplicate accounting, or inconsistent wallet state.

Product	Balance Source	Recommended Handling
Wallet Infrastructure	`wallet.token.balance.value` or `wallet.tokens[].balance.value`	Replace the token balance directly using the latest `balance.value` returned for the token in the webhook payload.

Samples

wallets are always synchronized with onchain state. Balance values returned in webhook events reflect the latest blockchain state for the wallet and token. Use the balance from: wallet → token or tokens → balance → value

{
   "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"
			}
		 }
	   }
	}
}

In this example:

Human-readable balance: balance.value = "20"
Raw blockchain balance: balance.rawValue = "20000000"

Platform

Swaps

Stock Tokens

Gas Fees

Webhook

Recommended Update Strategy

Samples

​Recommended Update Strategy

​Samples

Recommended Update Strategy

Samples