Utils

@symmio/utils is a framework-agnostic helper layer for SYMMIO SDK consumers. No React, no wagmi, no domain logic. Helpers work in Node scripts, browser bundles, and any framework; browser-specific behavior belongs in the consuming app.

Every export is a pure function or constant. No side effects (except the explicit configureSymmDecimal opt-in), no I/O, no state. Safe to call in render loops.

Install

pnpm add @symmio/utils viem

viem is a peer dependency. decimal.js is a direct dependency the package brings with it.

Sections

• Amounts (bigint) — viem-backed bigint ↔ string token amount helpers + a Decimal.js bridge. formatTokenAmount, parseTokenAmount, rawToDecimal, decimalToRaw, WEI_DECIMALS.
• Decimal helpers — chainable Decimal-based math (toDecimal, safeDivide, formatUnits returning Decimal, RoundingMode, configureSymmDecimal, ZERO_DECIMAL).
• Display formatters — thousand separators, compact (K/M/B/T/Q), currency, percentage, dynamic precision, relative timestamps.
• Address & hash — shortenAddress (checksummed), minifyHash (any hex).

Sub-entry imports

The root barrel (@symmio/utils) re-exports every helper for convenience. Deep imports through each sub-entry tree-shake more cleanly and dodge naming collisions with viem:

import { formatTokenAmount } from "@symmio/utils/amounts";
import { formatUnits, toDecimal } from "@symmio/utils/decimal";
import { formatCompact, formatCurrency } from "@symmio/utils/format";
import { shortenAddress } from "@symmio/utils/address";

Naming overlap with viem

@symmio/utils/decimal exposes formatUnits / parseUnits / formatEther / parseEther that return / accept Decimal, not strings — that’s the key difference from viem’s same-named functions. To avoid ambiguity, the root barrel does not re-export them. Always deep-import:

import { formatUnits, parseUnits } from "@symmio/utils/decimal"; // Decimal-based
import { formatUnits, parseUnits } from "viem"; // string/bigint-based

Already using @symmio/trading-react?

react re-exports the most-used helpers (formatTokenAmount, parseTokenAmount, rawToDecimal, decimalToRaw, shortenAddress) so simple apps don’t need a second dependency for basic amount / address rendering.

Add @symmio/utils directly when you want the full surface — Decimal chainables, compact-currency, dynamic decimals, percentage, relative timestamps.

What’s NOT in utils

• Contract calls, ABI fragments, address registries. Those live in @symmio/trading-core.
• React hooks. Those live in @symmio/trading-react.
• DOM globals. Utils runs in Node scripts and workers too — no window / document at module scope.