Decimal Handling (8 vs. 18 Decimals)

Overview

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.

---

Token Decimal Comparison and API Context

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.

---

Conversion Helpers

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

// 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);
}

Reference: Smart Contracts Gas and Fees

---

Additional Resources

• ERC-20 Token Standard

• Hedera Token Service Documentation

• HBAR Decimal Places Documentation

• Token Managed by Smart Contracts