bitcoin-units


Convert between any bitcoin unit - BTC, mBTC, μBTC, satoshi and even your own custom units.

``ts
new BitcoinUnit(10000, 'sats').to('BTC').getValue();
// 0.001;

new BitcoinUnit(21000, 'sats').to('BTC').format();
// '0.00021000 BTC';
`

👉 Try the demo

Installation

Add bitcoin-units to your Javascript project dependencies using Yarn:

`bash
yarn add bitcoin-units
`

Or NPM:

`bash
npm install bitcoin-units --save
`

Usage

$3

Import using ESM:

`js
import BitcoinUnit from 'bitcoin-units';
`

Or CJS:

`js
const BitcoinUnit = require('bitcoin-units');
`

$3

Basic unit conversions are done using the to(unit) function:

`js
new BitcoinUnit(1, 'mBTC').to('BTC').getValue();
// 0.001;
`

#### Available units

There are 4 available units by default:
btc, mbtc, bit and satoshi.

You can also use any of the following aliases:

- btc: bitcoinor bitcoins

- mbtc: millibtc

- bit: microbtc

- sats: sat, satoshi, satoshis

#### Available getters

getValue() returns a Number:

`js
new BitcoinUnit(1, 'mBTC').to('BTC').value();
// 0.001;
`

toString() returns a string:

`js
new BitcoinUnit(100000, 'satoshi').to('BTC').toString();
// '0.001';
`

format() returns a string with the value and unit:

`js
new BitcoinUnit(100000, 'satoshi').to('BTC').format();
// '0.00100000 BTC';
`

$3

#### Custom Format

You can set your own custom formats using the BitcoinUnit.setDisplay(unit, options):

`js
BitcoinUnit.setDisplay('sats', {
format: '{amount} something',
});

new BitcoinUnit(1, 'BTC').to('satoshi').format();

// '100,000,000 something';
`

#### Custom Unit

If you want to create your own custom units, you can use the bitcoin.setUnit(unit, value):

`js
BitcoinUnit.setUnit('custom', 1 / 1e2);

new BitcoinUnit(1, 'btc').to('custom').value();

// 100;
`

You can use this to create your own conversion to fiat currencies:

`js
// Let's suppose a rate of 1 BTC = $8000.00

BitcoinUnit.setUnit('usd', 1 / 8000);

new BitcoinUnit(1, 'satoshi').to('usd').value();

// 0.00008;
`

There's a shorthand to this function named bitcoin.setFiat(unit, rate):

`js
BitcoinUnit.setFiat('usd', 8000);

new BitcoinUnit(1, 'satoshi').to('usd').value();

// 0.00008;
``

Author

Rui Gomes
https://ruigomes.me

License

The MIT License (MIT). Please see LICENSE file for more information.