bitcoin-convert

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

Usage no npm install needed!

<script type="module">
  import bitcoinConvert from 'https://cdn.skypack.dev/bitcoin-convert';
</script>

README

bitcoin-convert

Travis build status Coverage Status npm version

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.