Unit

Unit is a utility for handling and converting bitcoin units. We strongly recommend to always use satoshis to represent amount inside your application and only convert them to other units in the front-end.

To understand the need of using the Unit class when dealing with unit conversions, see this example:

> 81.99 * 100000 // wrong
8198999.999999999
> var bitcore = require('bitcore');
> var Unit = bitcore.Unit;
> Unit.fromMilis(81.99).toSatoshis() // correct
8199000

Supported units

The supported units are BTC, mBTC, bits (micro BTCs, uBTC) and satoshis. The codes for each unit can be found as members of the Unit class.

var btcCode = Unit.BTC;
var mbtcCode = Unit.mBTC;
var ubtcCode = Unit.uBTC;
var bitsCode = Unit.bits;
var satsCode = Unit.satoshis;

Creating units

There are two ways for creating a unit instance. You can instantiate the class using a value and a unit code; alternatively if the unit it's fixed you could you some of the static methods. Check some examples below:

var unit;
var amount = 100;

// using a unit code
var unitPreference = Unit.BTC;
unit = new Unit(amount, unitPreference);

// using a known unit
unit = Unit.fromBTC(amount);
unit = Unit.fromMilis(amount);
unit = Unit.fromBits(amount);
unit = Unit.fromSatoshis(amount);

Conversion

Once you have a unit instance, you can check its representation in all the available units. For your convenience the classes expose three ways to accomplish this. Using the .to(unitCode) method, using a fixed unit like .toSatoshis() or by using the accessors.

var unit;

// using a unit code
var unitPreference = Unit.BTC;
value = Unit.fromSatoshis(amount).to(unitPreference);

// using a known unit
value = Unit.fromBTC(amount).toBTC();
value = Unit.fromBTC(amount).toMilis();
value = Unit.fromBTC(amount).toBits();
value = Unit.fromBTC(amount).toSatoshis();

// using accessors
value = Unit.fromBTC(amount).BTC;
value = Unit.fromBTC(amount).mBTC;
value = Unit.fromBTC(amount).bits;
value = Unit.fromBTC(amount).satoshis;

Using a fiat currency

The unit class also provides a convenient alternative to create an instance from a fiat amount and the corresponding BTC/fiat exchange rate. Any unit instance can be converted to a fiat amount by providing the current exchange rate. Check the example below:

var unit, fiat;
var amount = 100;
var exchangeRate = 350;

unit = new Unit(amount, exchangeRate);
unit = Unit.fromFiat(amount, exchangeRate);

fiat = Unit.fromBits(amount).atRate(exchangeRate);
fiat = Unit.fromBits(amount).to(exchangeRate);

Unit

Kind: global class

new Unit(amount, code)

Utility for handling and converting bitcoins units. The supported units are BTC, mBTC, bits (also named uBTC) and satoshis. A unit instance can be created with an amount and a unit code, or alternatively using static methods like {fromBTC}. It also allows to be created from a fiat amount and the exchange rate, or alternatively using the {fromFiat} static method. You can consult for different representation of a unit instance using it's {to} method, the fixed unit methods like {toSatoshis} or alternatively using the unit accessors. It also can be converted to a fiat amount by providing the corresponding BTC/fiat exchange rate.

Returns: Unit - A new instance of an Unit

Param Type Description
amount Number The amount to be represented
code String | Number The unit of the amount or the exchange rate

Example

var sats = Unit.fromBTC(1.3).toSatoshis();
var mili = Unit.fromBits(1.3).to(Unit.mBTC);
var bits = Unit.fromFiat(1.3, 350).bits;
var btc = new Unit(1.3, Unit.bits).BTC;

unit.toMillis ⇒ Number

Returns the value represented in mBTC

Kind: instance property of Unit
Returns: Number - The value converted to mBTC

unit.toMicros ⇒ Number

Returns the value represented in bits

Kind: instance property of Unit
Returns: Number - The value converted to bits

unit.toObject ⇒ Object

Returns a plain object representation of the Unit

Kind: instance property of Unit
Returns: Object - An object with the keys: amount and code

unit.to(code) ⇒ Number

Returns the value represented in the specified unit

Kind: instance method of Unit
Returns: Number - The converted value

Param Type Description
code String | Number The unit code or exchange rate

unit.toBTC() ⇒ Number

Returns the value represented in BTC

Kind: instance method of Unit
Returns: Number - The value converted to BTC

unit.toSatoshis() ⇒ Number

Returns the value represented in satoshis

Kind: instance method of Unit
Returns: Number - The value converted to satoshis

unit.atRate(rate) ⇒ Number

Returns the value represented in fiat

Kind: instance method of Unit
Returns: Number - The value converted to satoshis

Param Type Description
rate string The exchange rate between BTC/currency

unit.toString() ⇒ string

Returns a the string representation of the value in satoshis

Kind: instance method of Unit
Returns: string - the value in satoshis

unit.inspect() ⇒ string

Returns a string formatted for the console

Kind: instance method of Unit
Returns: string - the value in satoshis

Unit.fromMillis ⇒ Unit

Returns a Unit instance created from an amount in mBTC

Kind: static property of Unit
Returns: Unit - A Unit instance

Param Type Description
amount Number The amount in mBTC

Unit.fromMicros ⇒ Unit

Returns a Unit instance created from an amount in bits

Kind: static property of Unit
Returns: Unit - A Unit instance

Param Type Description
amount Number The amount in bits

Unit.fromObject(json) ⇒ Unit

Returns a Unit instance created from JSON string or object

Kind: static method of Unit
Returns: Unit - A Unit instance

Param Type Description
json String | Object JSON with keys: amount and code

Unit.fromBTC(amount) ⇒ Unit

Returns a Unit instance created from an amount in BTC

Kind: static method of Unit
Returns: Unit - A Unit instance

Param Type Description
amount Number The amount in BTC

Unit.fromSatoshis(amount) ⇒ Unit

Returns a Unit instance created from an amount in satoshis

Kind: static method of Unit
Returns: Unit - A Unit instance

Param Type Description
amount Number The amount in satoshis

Unit.fromFiat(amount, rate) ⇒ Unit

Returns a Unit instance created from a fiat amount and exchange rate.

Kind: static method of Unit
Returns: Unit - A Unit instance

Param Type Description
amount Number The amount in fiat
rate Number The exchange rate BTC/fiat