Skip to main content
@chipi-stack/core is in development (v0.1.0). APIs may change before stable release.

​
Overview

Amount is an immutable value type that represents a token amount using BigInt internally. All arithmetic is exact with zero floating-point precision loss.

​
Usage

import { Amount } from "@chipi-stack/core";

const usdc = { symbol: "USDC", decimals: 6, address: "0x..." };

// Parse human-readable string
const amount = Amount.parse("1.5", usdc);
amount.toBase();      // 1_500_000n
amount.toUnit();      // "1.5"
amount.toFormatted(); // "1.5 USDC"

​
Factory Methods

​
Amount.parse(value, token)

Parse a human-readable string into an Amount. 
const amount = Amount.parse("100.50", { symbol: "USDC", decimals: 6, address: "0x..." });

​
Parameters

  • value (string): Human-readable value (e.g., "1.5", "100")
  • token (TokenInfo): Object with symbol, decimals, and address

​
Throws

  • If value is negative or non-numeric
  • If value has more decimal places than the token supports

​
Amount.fromRaw(raw, decimals, symbol?)

Create an Amount from a raw bigint value (base units). 
const amount = Amount.fromRaw(1_500_000n, 6, "USDC");
amount.toUnit(); // "1.5"

​
Parameters

  • raw (bigint): Raw value in base units (e.g., wei)
  • decimals (number): Token decimal places
  • symbol (string, optional): Token symbol, defaults to ""

​
Throws

  • If raw is negative

​
Arithmetic

All arithmetic methods return a new Amount (immutable). Both operands must have the same decimals. 
const a = Amount.parse("10.0", usdc);
const b = Amount.parse("3.5", usdc);

a.add(b);           // 13.5 USDC
a.subtract(b);      // 6.5 USDC
a.multiply(2n);     // 20.0 USDC
a.divide(4n);       // 2.5 USDC (truncates, no rounding)

​
Methods

MethodSignatureDescription
addadd(other: Amount): AmountAdd two amounts
subtractsubtract(other: Amount): AmountSubtract (throws if result would be negative)
multiplymultiply(scalar: bigint): AmountMultiply by a scalar
dividedivide(divisor: bigint): AmountDivide by a scalar (truncates)

​
Comparisons

const a = Amount.parse("10.0", usdc);
const b = Amount.parse("3.5", usdc);

a.gt(b);    // true
a.lt(b);    // false
a.eq(b);    // false
a.gte(b);   // true
a.lte(b);   // false
a.isZero(); // false

​
Methods

MethodSignatureDescription
eqeq(other: Amount): booleanEqual
gtgt(other: Amount): booleanGreater than
gtegte(other: Amount): booleanGreater than or equal
ltlt(other: Amount): booleanLess than
ltelte(other: Amount): booleanLess than or equal
isZeroisZero(): booleanCheck if amount is zero

​
Formatting

const amount = Amount.parse("1500000.0", usdc);

amount.toBase();                // 1_500_000_000_000n (raw bigint)
amount.toUnit();                // "1500000.0"
amount.toFormatted();           // "1500000.0 USDC"
amount.toFormatted(true);       // "1.5M USDC" (compressed)

​
Methods

MethodSignatureDescription
toBasetoBase(): bigintRaw value in base units
toUnittoUnit(): stringHuman-readable string (e.g., "1.5")
toFormattedtoFormatted(compressed?: boolean): stringFormatted with symbol, optional compression (K/M)

​
Properties

PropertyTypeDescription
rawbigintRaw value in base units (readonly)
decimalsnumberToken decimal places (readonly)
symbolstringToken symbol (readonly)

​
Example

import { Amount, TokenRegistry } from "@chipi-stack/core";

const registry = new TokenRegistry("mainnet");
const usdcInfo = registry.bySymbol("USDC")!;

// Parse user input
const sendAmount = Amount.parse("25.50", usdcInfo);

// Get balance (returned by Erc20.balanceOf())
const balance = Amount.fromRaw(50_000_000n, 6, "USDC");

// Compare
if (balance.lt(sendAmount)) {
  console.log(`Insufficient: have ${balance.toFormatted()}, need ${sendAmount.toFormatted()}`);
} else {
  const remaining = balance.subtract(sendAmount);
  console.log(`After transfer: ${remaining.toFormatted()}`); // "24.5 USDC"
}
  • TxBuilder: Use Amount with TxBuilder for typed transfers
  • Erc20: Returns Amount objects from balanceOf() and allowance()
  • TokenRegistry: Look up TokenInfo for Amount.parse()