@stellarshift/token-units

BigInt-first unit conversion for EVM token amounts — parseUnits / formatUnits with arbitrary decimals, plus ETH / gwei shortcuts.

Designed for backend scripts, indexers, and take-home tasks that should not depend on full ethers or viem.

Install

npm install @stellarshift/token-units

Examples

const {
  parseUnits,
  formatUnits,
  parseEther,
  formatEther,
  parseGwei,
  formatGwei,
} = require('@stellarshift/token-units');

// ERC-20 with 6 decimals (USDC-style)
parseUnits('12.34', 6);   // 12340000n
formatUnits(12340000n, 6); // '12.34'

// Native ETH
parseEther('0.05');        // 50000000000000000n
formatEther('50000000000000000n'); // '0.05'

// Gas price
parseGwei('25.5');         // 25500000000n
formatGwei(25500000000n);  // '25.5'

API

| Export | Description | |--------|-------------| | parseUnits(value, decimals) | Human → base units (bigint) | | formatUnits(value, decimals, precision?) | Base → human string | | parseEther / formatEther | 18-decimal shortcuts | | parseGwei / formatGwei | 9-decimal shortcuts | | WEI_PER_GWEI, WEI_PER_ETHER | Constants |

Behaviour

• Uses native BigInt — no floating-point rounding on wei
• Rejects fractional strings longer than decimals
• Negative values supported for accounting use-cases

License

MIT © StellarShift Labs