Managing token decimals is critical when working with HBAR, HTS tokens, and ERC tokens on Hedera, as each system has distinct precision standards. These differences impact how token balances are calculated, displayed, and transferred across various tools and environments.
The table below compares the decimal handling of HBAR, HTS tokens, and ERC tokens on Hedera, incorporating details about their representation across APIs and services. This overview highlights differences in precision and context.
| API/Service | Decimals | Explanation |
|---|---|---|
| Hedera API (HAPI) | 8 decimals | HBAR is represented with 8 decimal places, aligning with its native smallest unit tinybar. |
| Hedera Smart Contract Service | 8 decimals | Within the EVM environment, HBAR maintains 8 decimal places, consistent with its native representation. |
| JSON-RPC Relay (Arguments) | 8 decimals | When HBAR values are passed as arguments in JSON-RPC calls, they are represented with 8 decimal places. |
JSON-RPC Relay (msg.value) | 18 decimals | For compatibility with EVM tooling, msg.value in JSON-RPC Relay represents HBAR with 18 decimal places. Consequently, gasPrice also uses 18 decimal places in this context. |
| HTS Tokens | Configurable (up to 8 decimals) | HTS tokens allow token creators to define precision at token creation, offering flexibility for various use cases. |
| ERC Tokens | Default 18 decimals | ERC tokens on Hedera follow Ethereum token standards, with 18 decimals as the default unless specified otherwise. |
Key Impacts:
- Account for scaling differences when converting HBAR between APIs, especially when using JSON-RPC.
- HBAR fees are always calculated in tinybars, regardless of the API or service used.
- JSON-RPC’s use of 18 decimals ensures smooth integration with EVM tools and libraries.
Utility functions are essential for managing discrepancies between HBAR (measured in tinybars, 8 decimals), HTS tokens (which can have configurable decimal places), and ERC tokens (measured in wei, 18 decimals). These conversions ensure consistency across your smart contracts, front-end applications, and APIs.
Code Example: Decimal Conversion Helpers
{% code overflow="wrap" %}
// Convert from 18 decimals (weibar/wei) to 8 decimals (tinybar)
function convertToTinybar(uint256 weiAmount) public pure returns (uint256) {
// 1 tinybar = 10^10 weibar
return weiAmount / (10 ** 10);
}
// Convert from 8 decimals (tinybar) to 18 decimals (weibar/wei)
function convertToWei(uint256 tinybarAmount) public pure returns (uint256) {
return tinybarAmount * (10 ** 10);
}{% endcode %}
Reference: Smart Contracts Gas and Fees