Convert between BTC, mBTC, μBTC and satoshi in your Javascript application
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
src
test
.babelrc
.editorconfig
.eslintrc
.gitignore
.npmignore
.travis.yml
LICENSE.md
README.md
package.json
rollup.config.js

README.md

bitcoin-units

Build Status codecov npm version

Convert between any bitcoin unit - BTC, mBTC, μBTC, satoshi and even your own custom units! Available for ES6 and Node.js.

bitcoin(1, 'mBTC').to('BTC').value()
0.001

bitcoin(100000, 'satoshi').to('BTC').format()
'0.001 BTC'

👉 Try the demo

Installation

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

yarn add bitcoin-units

Or NPM:

npm install bitcoin-units --save

Usage

Importing

Import using ES6:

import bitcoin from 'bitcoin-units';

Or AMD:

var bitcoin = require('bitcoin-units');

Converting bitcoin

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

bitcoin(1, 'mBTC').to('BTC').value()
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: bitcoin or bitcoins

  • mbtc: millibtc

  • bit: μbtc or microbtc

  • satoshi: sat, sats, satoshi, satoshis

Available getters

value() returns a Number:

bitcoin(1, 'mBTC').to('BTC').value()
0.001

toString() returns a string:

bitcoin(100000, 'satoshi').to('BTC').toString()
'0.001'

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

bitcoin(100000, 'satoshi').to('BTC').format()
'0.001 BTC'

Customization

Custom Format

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

bitcoin.setDisplay('satoshi', {
  format: '{amount} sats'
});

bitcoin(1, 'BTC').to('satoshi').format();

'100,000,000 sats'

Custom Unit

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

bitcoin.setUnit('custom', 1 / 1E2);

bitcoin(1, 'btc').to('custom').value();

100

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

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

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

bitcoin(1, 'satoshi').to('usd').value();

0.00008

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

bitcoin.setFiat('usd', 8000);

bitcoin(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.