> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Amount

> Immutable token amount class with safe BigInt arithmetic, parsing, and formatting.

<Warning>
  `@chipi-stack/core` is in development (v0.1.0). APIs may change before stable release.
</Warning>

## 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

```typescript theme={null}
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.

```typescript theme={null}
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).

```typescript theme={null}
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`.

```typescript theme={null}
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

| Method     | Signature                          | Description                                   |
| ---------- | ---------------------------------- | --------------------------------------------- |
| `add`      | `add(other: Amount): Amount`       | Add two amounts                               |
| `subtract` | `subtract(other: Amount): Amount`  | Subtract (throws if result would be negative) |
| `multiply` | `multiply(scalar: bigint): Amount` | Multiply by a scalar                          |
| `divide`   | `divide(divisor: bigint): Amount`  | Divide by a scalar (truncates)                |

## Comparisons

```typescript theme={null}
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

| Method   | Signature                     | Description             |
| -------- | ----------------------------- | ----------------------- |
| `eq`     | `eq(other: Amount): boolean`  | Equal                   |
| `gt`     | `gt(other: Amount): boolean`  | Greater than            |
| `gte`    | `gte(other: Amount): boolean` | Greater than or equal   |
| `lt`     | `lt(other: Amount): boolean`  | Less than               |
| `lte`    | `lte(other: Amount): boolean` | Less than or equal      |
| `isZero` | `isZero(): boolean`           | Check if amount is zero |

## Formatting

```typescript theme={null}
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

| Method        | Signature                                   | Description                                       |
| ------------- | ------------------------------------------- | ------------------------------------------------- |
| `toBase`      | `toBase(): bigint`                          | Raw value in base units                           |
| `toUnit`      | `toUnit(): string`                          | Human-readable string (e.g., `"1.5"`)             |
| `toFormatted` | `toFormatted(compressed?: boolean): string` | Formatted with symbol, optional compression (K/M) |

## Properties

| Property   | Type     | Description                        |
| ---------- | -------- | ---------------------------------- |
| `raw`      | `bigint` | Raw value in base units (readonly) |
| `decimals` | `number` | Token decimal places (readonly)    |
| `symbol`   | `string` | Token symbol (readonly)            |

## Example

```typescript theme={null}
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"
}
```

## Related

* [TxBuilder](/sdk/core/tx-builder): Use Amount with TxBuilder for typed transfers
* [Erc20](/sdk/core/erc20): Returns Amount objects from `balanceOf()` and `allowance()`
* [TokenRegistry](/sdk/core/token-registry): Look up TokenInfo for Amount.parse()