# token-amount

> [](https://www.npmjs.com/package/token-amount) [](https://bundlephobia.com/result?p=token-amount)

Latest version **0.3.0** (published 2020-12-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install token-amount
pnpm add token-amount
yarn add token-amount
bun add token-amount
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2020-12-10 |
| First published | 2020-06-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=10 |
| Dependencies | 1 |
| Unpacked size | 66.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Aragon Association |
| Maintainers | delfipolito, promaty, andy-hook, evalir, gabrielg, facuspagnuolo, aragon-ci, izqui, luisivan, bpierre, sohkai |

## Links

- npm: https://www.npmjs.com/package/token-amount
- npm.io page: https://npm.io/package/token-amount

## Dependencies (1)

- [jsbi](https://npm.io/package/jsbi.md) ^3.1.4

## Recent versions

- 0.3.0 (latest) — 2020-12-10
- 0.2.0 — 2020-09-04
- 0.1.0 — 2020-06-18

## README

# 💸 TokenAmount

[<img src="https://img.shields.io/npm/v/token-amount" alt="" />](https://www.npmjs.com/package/token-amount) [<img src="https://img.shields.io/bundlephobia/minzip/token-amount" alt="" />](https://bundlephobia.com/result?p=token-amount)

A transportable object for token amounts with formatting.

## Usage

Add it to your project:

```console
yarn add token-amount
```

Use it:

```js
import TokenAmount from 'token-amount'

const amount = new TokenAmount('9388295879707883945', 18, { symbol: 'ANT' })

console.log(amount.format()) // '9.39 ANT'
```

## API

### Constructor

#### new TokenAmount(value, decimals, { symbol })

Instantiates a new `TokenAmount` with the given `value` and `decimals`. The options are optional, and can take a `symbol` (e.g. `"ANT"`).

##### Parameters

- `value`: the amount value, as a `BigInt`, `String`, `Number` or `BigInt`-like (e.g. BN.js).
- `decimals`: the amount of decimals, as a `BigInt`, `String`, `Number` or `BigInt`-like (e.g. BN.js).
- `symbol`: the token symbol, as a `String`.

### Formatting

#### TokenAmount#format(options)

Formats the token amount.

##### Parameters

- `options.symbol`: the token symbol, as a `String`. Overrides the value set in the constructor.
- `options.commify`: whether the formatted amount should include comma separators
- `options.digits`: the number of digits to display. Defaults to `2`.
- `options.displaySign`: whether the sign (`-` or `+`) should be displayed for the amount.

#### TokenAmount#toString(options)

Alias to TokenAmount#format().

#### TokenAmount.format(amount, decimals, options)

Static equivalent of `TokenAmount#format()`, with the `TokenAmount` instance passed as a first parameter.

### Converting

#### TokenAmount#convert(rate, targetDecimals, options)

Converts from a rate, returning a new `TokenAmount` instance with the desired decimals and set options. The conversion rate is expressed as the amount of the output token obtained per unit of the input token. An example would be:

- Input token: ANT
- Output token: ETH
- Amount of ANT: 10
- Conversion rate: 0.5 ETH per ANT. (1 ANT = 0.5 ETH)
- Converted Amount = 10 \* 0.50 = 5 ETH.

##### Parameters

- `rate`: the rate to convert from, as a `String` or a `Number`.
- `targetDecimals`: the target amount of decimals for the output, as a `BigInt`, `String`, `Number` or `BigInt`-like (e.g. BN.js).
- `options.symbol`: the token symbol, as a `String`.

#### TokenAmount.convert(amount, rate, targetDecimals, options)

Static equivalent of `TokenAmount#convert()`, with the `TokenAmount` instance passed as a first parameter.

### Transporting

#### TokenAmount#export()

Exports the object into a string that can get stored or transported.

#### TokenAmount.import()

Instantiates a new instance by importing a string generated by `TokenAmount#export()`.

---
_Source: https://npm.io/package/token-amount · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._