Ether is denominated in units of wei, the smallest unit of ether. This allows a wide range of values to be represented and transferred on the network while maintaining precision.

Common units of Ether include:

  • wei — 1 wei — 1
  • kwei — 1e3 wei — 1,000
  • mwei — 1e6 wei — 1,000,000
  • gwei — 1e9 wei — 1,000,000,000
  • microether — 1e12 wei — 1,000,000,000,000
  • milliether — 1e15 wei — 1,000,000,000,000,000
  • ether (ETH) — 1e18 wei — 1,000,000,000,000,000,000

When working with ether, it’s more user-friendly to use larger denominations like ether or gwei. But it’s essential to know the underlying representation in wei when performing calculations or working with smart contracts. A simple miscalculation can be costly.

Luckily, Ethers.js provides utility methods for easy conversion between units, making it easier and safer to work with ether.

  • formatUnits() — returns a string representation of a value formatted in the chosen denomination or with the given number of digits.
  • parseUnits() — returns a BigNumber representation of a value, parsed with the chosen denomination or the given number of digits.
import { utils } from 'ethers';
const { formatUnits, parseUnits } = utils;

// format methods convert and return a string
const twoEther = parseUnits('2', 'ether');

formatUnits(twoEther); // 2.0
formatUnits(twoEther, 'gwei'); // 2000000000.0
formatUnits(twoEther, 'wei'); // 2000000000000000000

// parse methods convert and return a BigNumber
const twoEtherString = '2';

parseUnits(twoEtherString); // { BigNumber: "2000000000000000000" }
parseUnits(twoEtherString, 'gwei'); // { BigNumber: "2000000000" }
parseUnits(twoEtherString, 'wei'); // { BigNumber: "2" }