bitcoin-convert

Conversion between the bitcoin base unit (BTC) and other units (Satoshi, μBTC, ...)

The change log is automatically produced with the help of semantic-release.

Features

• Avoids rounding errors by using a big number package
• Converts from/to a Number, Big or String
• Units can be added or removed

Getting started

bitcoin-convert is available for Node.js and most modern browsers. If you want to know if your currrent browser is compatible, run the online test suite.

Install with npm

> npm install bitcoin-convert --save

Node usage

var btcConvert = require('bitcoin-convert');    
var coins = btcConvert(4.6, 'Satoshi', 'BTC');  

Browser usage

Include the package from your project

<script src="./node_modules/bitcoin-convert/dist/bitcoin-convert.min.js" type="text/javascript"></script>

or from the unpkg CDN

<script src="https://unpkg.com/bitcoin-convert/dist/bitcoin-convert.min.js"></script>

The script creates the btcConvert global object or defines it if you are using AMD.

var coins = btcConvert(4.6, 'Satoshi', 'BTC');  

API

btcConvert (from, fromUnit, toUnit, [representation])

Converts an amount from one unit to another unit.

• from (number | string | Big) - the amount to convert
• fromUnit (string) - the unit of the amount
• toUnit (string) - the unit to convert to
• representation (string) - the type of value to return, defaults to 'Number'.
  • 'Number' - returns a standard javascript Number
  • 'Big' - returns a Big number
  • 'String' - returns a string

Examples

btcConvert(2, 'BTC', 'bit') // returns 2000000
btcConvert(2, 'BTC', 'bit', 'String') // returns '2000000'

btcConvert.units()

Returns an Array of unit symbols that can be used for conversion.

Example

console.log(btcConvert.units())
// produces
// ['BTC', 'mBTC', 'μBTC', 'bit', 'Satoshi', 'sat']

btcConvert.addUnit (unit, factor)

Adds a new unit for conversion. Throws when unit already exists and the factors are different.

• unit (string) - the new unit symbol
• factor (number | string | Big) - conversion factor to yield a BTC.

Example

convert.addUnit('finney', 0.0000001);
convert(30, 'finney', 'BTC') // produces 0.000003

// 10 satoshis can be expressed as 1 finney
convert(20, 'Satoshi', 'finney') // produces 2

btcConvert.removeUnit (unit)

Removes the unit from conversion. Throws when unit is pre-defined. Removing a non-existing symbol is allowed.

• unit (string) - the unit symbol to remove.