eth-format

Zero-dependency TypeScript utilities for formatting Ethereum values — ETH, Gwei, addresses and USD.

npm install @xdkoc/eth-format

Why

Formatting wei to ETH, shortening addresses for display, converting gas prices — every Ethereum app needs this. This library handles it without pulling in ethers.js or viem for just a few helper functions.

Functions

formatEther(wei)

Converts wei to a human-readable ETH string.

import { formatEther } from "@xdkoc/eth-format";

formatEther(1_000_000_000_000_000_000n)  // "1 ETH"
formatEther(1_500_000_000_000_000_000n)  // "1.5 ETH"
formatEther(1_100_000_000_000_000_000n)  // "1.1 ETH"
formatEther(0n)                          // "0 ETH"

// Control decimal places (default: 4)
formatEther(1_123_456_789_000_000_000n, 2)  // "1.12 ETH"

parseEther(eth)

Converts an ETH string to wei as BigInt.

import { parseEther } from "@xdkoc/eth-format";

parseEther("1")    // 1000000000000000000n
parseEther("1.5")  // 1500000000000000000n
parseEther("0.01") // 10000000000000000n

formatGwei(wei)

Converts wei to a human-readable Gwei string. Useful for displaying gas prices.

import { formatGwei } from "@xdkoc/eth-format";

formatGwei(21_000_000_000n)   // "21 Gwei"
formatGwei(1_500_000_000n)    // "1.5 Gwei"
formatGwei(100_000_000_000n)  // "100 Gwei"

weiToGwei(wei)

Converts wei to Gwei as BigInt.

import { weiToGwei } from "@xdkoc/eth-format";

weiToGwei(21_000_000_000n)  // 21n

shortenAddress(address, chars?)

Shortens an Ethereum address for display. Default: 4 characters on each side.

import { shortenAddress } from "@xdkoc/eth-format";

shortenAddress("0x742d35cc6634c0532925a3b8d4c9b7b5a9c1d2e3")     // "0x742d...d2e3"
shortenAddress("0x742d35cc6634c0532925a3b8d4c9b7b5a9c1d2e3", 6)  // "0x742d35...c1d2e3"

isValidAddress(address)

Checks whether a string is a valid Ethereum address (0x prefix + 40 hex characters).

import { isValidAddress } from "@xdkoc/eth-format";

isValidAddress("0x742d35cc6634c0532925a3b8d4c9b7b5a9c1d2e3")  // true
isValidAddress("0x742d35cc")                                   // false
isValidAddress("742d35cc6634c0532925a3b8d4c9b7b5a9c1d2e3")    // false (no 0x)

normalizeAddress(address)

Lowercases an Ethereum address for consistent storage and comparison.

import { normalizeAddress } from "@xdkoc/eth-format";

normalizeAddress("0x742D35CC6634C0532925A3B8D4C9B7B5A9C1D2E3")
// "0x742d35cc6634c0532925a3b8d4c9b7b5a9c1d2e3"

formatUsd(wei, ethPriceUsd)

Converts a wei amount to USD based on the current ETH price.

import { formatUsd } from "@xdkoc/eth-format";

const oneEth = 1_000_000_000_000_000_000n;
formatUsd(oneEth, 3000)  // "$3,000.00"
formatUsd(oneEth, 3241)  // "$3,241.00"

const halfEth = 500_000_000_000_000_000n;
formatUsd(halfEth, 2000) // "$1,000.00"

Full example

import { formatEther, formatGwei, formatUsd, shortenAddress } from "@xdkoc/eth-format";

const tx = {
  from: "0x742d35cc6634c0532925a3b8d4c9b7b5a9c1d2e3",
  value: 2_500_000_000_000_000_000n,  // 2.5 ETH in wei
  gasPrice: 21_000_000_000n,           // 21 Gwei in wei
};

console.log(`From:      ${shortenAddress(tx.from)}`);
// From:      0x742d...d2e3

console.log(`Value:     ${formatEther(tx.value)}`);
// Value:     2.5 ETH

console.log(`Value:     ${formatUsd(tx.value, 3000)}`);
// Value:     $7,500.00

console.log(`Gas price: ${formatGwei(tx.gasPrice)}`);
// Gas price: 21 Gwei

API

| Function | Signature | Returns | |---|---|---| | formatEther | (wei: bigint, decimals?: number) | string | | parseEther | (eth: string) | bigint | | formatGwei | (wei: bigint) | string | | weiToGwei | (wei: bigint) | bigint | | shortenAddress | (address: string, chars?: number) | string | | isValidAddress | (address: string) | boolean | | normalizeAddress | (address: string) | string | | formatUsd | (wei: bigint, ethPriceUsd: number) | string |

Zero dependencies

No ethers.js, no viem, no web3.js. Pure TypeScript with no runtime dependencies.

License

MIT