A zero balance does not explain a missing transfer
Documentation-based guide · Updated
Check the network, account, native asset and token contract before interpreting a zero. Preserve raw units when token metadata is unavailable.
Before you start
- Use an existing public address and the exact network from the original record.
- For a token, have its full contract address on that network. Never enter a recovery phrase or private key.
1. Fix the account and network
Compare the full public address with the original receive record. Select Ethereum, BSC or Base as appropriate. Do not infer the network from the address prefix or a token ticker.
This is a current-state query, not a portfolio scan or historical balance report. The result can reflect a different block from a previous explorer or wallet view, and it may be cached for up to 30 seconds.
Check: Record the full address, network and check time before interpreting the number.
2. Choose native asset or a specific token
With the token field empty, the checker returns the native asset: ETH on Ethereum or Base, BNB on BSC. That number does not include ERC-20 holdings.
For a token balance, supply the contract verified against the issuer’s official network-specific documentation. Matching names and symbols do not establish matching assets. The checker reads that contract’s balanceOf for the supplied address; it does not enumerate every asset or protocol position.
Check: Describe the result as native-asset balance or this specific contract’s token balance.
3. Verify units before reading the displayed amount
Token balances are raw integers. A verified decimals value determines how to display the units. The ERC-20 metadata methods are optional; a failed metadata call does not turn a balance into zero.
If decimals cannot be read, the existing service uses 18 for a provisional display. The English result flags that fallback and retains the raw number. Use the raw value until precision is independently established. A displayed balance is not a test of transferability or token safety.
Check: Keep the raw balance and verified decimals, or mark the human-readable amount provisional.
4. Return to the original transaction
A zero now cannot establish whether an earlier transfer arrived: the address may have received and later spent the asset. A positive balance also cannot identify which transaction supplied it.
Use the original hash to match actual movement. If a wallet and this query disagree, compare network, contract, account and observation time before treating either as a complete history. An RPC or contract-read error is unavailable data, not a numeric zero.
Check: Separate current balance from the historical transfer and from any platform account credit.
Worked example: zero ETH and a nonzero token balance
- Illustrative inputs: the same account on Base returns 0 from the native-asset query.
- A separately identified token contract returns raw balance 1234500 and verified decimals 6, producing 1.2345 token units.
Conclusion: These results can both be correct. Zero native ETH does not imply zero tokens. Neither result alone proves that a particular historical transfer arrived or that the token can be transferred.
Decision & failure branches
| Observation | What it means | Next check |
|---|---|---|
| Native balance is zero | No native units were returned for this account and network at the queried state. | If investigating a token, query its verified contract separately. |
| Token balance is zero | This contract returned zero for this account at the queried state. | Recheck chain, contract and account, then inspect the original transfer and subsequent history. |
| Decimals unavailable | The raw balance may be available while display precision is unverified. | Keep the raw integer; verify precision before interpreting the displayed amount. |
| Contract read or RPC failed | The balance is unknown. | Preserve the error and compare the same chain and contract in its explorer. Do not record zero. |
Completion checklist
- Identify the exact network, account and native asset or token contract.
- Retain raw units, precision status and observation time; keep historical arrival and current balance separate.