From 8a924c377b18b5c614ab76e6e52ffb72ef8b4625 Mon Sep 17 00:00:00 2001 From: Georgios Konstantopoulos Date: Thu, 29 Jan 2026 16:55:40 +0000 Subject: [PATCH] docs: update eth_getBalance behavior to reflect JSON-RPC error Update documentation to reflect that eth_getBalance now returns a JSON-RPC error instead of a placeholder value. Co-authored-by: Dan Robinson Co-authored-by: Josh Co-authored-by: Liam Amp-Thread-ID: https://ampcode.com/threads/T-019c0aa6-161b-72ee-8a84-507056e17f65 Co-authored-by: Amp --- src/pages/quickstart/evm-compatibility.mdx | 11 ++++++++++- src/pages/quickstart/wallet-developers.mdx | 2 +- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/src/pages/quickstart/evm-compatibility.mdx b/src/pages/quickstart/evm-compatibility.mdx index 24749e3e..6ad44d0d 100644 --- a/src/pages/quickstart/evm-compatibility.mdx +++ b/src/pages/quickstart/evm-compatibility.mdx @@ -53,7 +53,16 @@ Many wallets and applications check a user's "native account balance" before let This stems from the return value of the `eth_getBalance` RPC method. When a wallet calls this method, it expects a hex string representing the "native token balance", hard-coded to be represented as an 18-decimal place number. -On Tempo, the `eth_getBalance` method returns a hex string representing an extremely large number. Specifically it returns: `0x9612084f0316e0ebd5182f398e5195a51b5ca47667d4c9b26c9b26c9b26c9b2` which is represented in decimals as 4.242424242424242e+75. +On Tempo, the `eth_getBalance` method returns a JSON-RPC error with a helpful message pointing to documentation: + +```json +{ + "error": { + "code": -32000, + "message": "Native balance not used. See docs.tempo.xyz/quickstart/wallet-developers for balance queries." + } +} +``` Our recommendation to wallets and to applications using this method is to remove this balance check, and to not represent any "native balance" in your user's UI. This will allow users to complete actions without being blocked by balance checks. diff --git a/src/pages/quickstart/wallet-developers.mdx b/src/pages/quickstart/wallet-developers.mdx index a1b28964..32d1705b 100644 --- a/src/pages/quickstart/wallet-developers.mdx +++ b/src/pages/quickstart/wallet-developers.mdx @@ -20,7 +20,7 @@ As part of supporting Tempo in your wallet, you can also deliver an enhanced exp If you use `eth_getBalance` to validate a user's balance, you should instead check the user's account fee token balance on Tempo. Additionally, you should not display any "native balance" in your UI for Tempo users. :::info -In testnet, `eth_getBalance` [returns a large placeholder value](/quickstart/evm-compatibility#handling-eth-native-token-balance-checks) for the native token balance to unblock existing assumptions wallets have about the native token balance. +On Tempo, `eth_getBalance` [returns a JSON-RPC error](/quickstart/evm-compatibility#handling-eth-native-token-balance-checks) with code `-32000` and a message linking to this documentation, since there is no native token balance. ::: :::code-group