Documentation / @cashconnect-js/core / primitives/satoshis

BCHUnits

type BCHUnits = "sats" | "bits" | "mBCH" | "BCH";

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:1

---

Satoshis

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:22

Satoshis Primitive

Example

// Import our primitives
import { Satoshis } from '@xocash/primitives';

// Create an amount from BCH.
const sats = Satoshis.fromBCH(0.54321);

// Output as a satoshi number.
console.log(satoshis.toSats());

// Output as a satoshis bigint.
console.log(satoshis.toBigInt());

Methods

fromSats()

static fromSats(satoshis): Satoshis;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:44

Instantiates from a Satoshi Amount.

Parameters

Parameter	Type	Description
satoshis	number | bigint	{number} The Satoshi amount.

Returns

Satoshis

New instance of Satoshis.

fromSatoshis()

static fromSatoshis(satoshis): Satoshis;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:57

Instantiates from a Satoshi Amount.

Parameters

Parameter	Type	Description
satoshis	number | bigint	{number} The Satoshi amount.

Returns

Satoshis

New instance of Satoshis.

Deprecated

Use fromSats() instead.

fromBits()

static fromBits(bits): Satoshis;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:68

Instantiates from a Bits Amount (100 satoshis = 1 bit).

Parameters

Parameter	Type	Description
bits	number	{number} The Bits amount.

Returns

Satoshis

New instance of Satoshis.

fromMBCH()

static fromMBCH(mBCH): Satoshis;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:81

Instantiates from a mBCH Amount (100,000 satoshis = 1 mBCH).

Parameters

Parameter	Type	Description
mBCH	number	{number} The mBCH amount.

Returns

Satoshis

New instance of Satoshis.

fromBCH()

static fromBCH(bch): Satoshis;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:94

Instantiates from a BCH Amount (100,000,000 satoshis = 1 BCH).

Parameters

Parameter	Type	Description
bch	number	{number} The BCH amount.

Returns

Satoshis

New instance of Satoshis.

fromRaw()

static fromRaw(sats): Satoshis;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:109

Creates an instance from serialized data.

Parameters

Parameter	Type
sats	bigint

Returns

Satoshis

A new instance of this primitive.

Remarks

This method is UNSAFE and MUST only be used where input is already verified or trusted.

toBigInt()

toBigInt(): bigint;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:150

Converts the amount to Satoshis (as a BigInt).

Returns

bigint

The satoshi amount.

toSats()

toSats(): number;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:159

Converts the amount to Satoshis.

Returns

number

The satoshi amount.

toSatoshis()

toSatoshis(): number;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:170

Converts the amount to Satoshis.

Returns

number

The satoshi amount.

Deprecated

Use toSats() instead.

toBits()

toBits(): number;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:179

Converts the amount to Bits (100 satoshis = 1 bit).

Returns

number

The bit amount.

toMBCH()

toMBCH(): number;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:188

Converts the amount to mBCH (100,000 satoshis = 1 mBCH).

Returns

number

The mBCH amount.

toBCH()

toBCH(): number;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:197

Converts the amount to BCH (100,000,000 satoshis = 1 BCH).

Returns

number

The BCH amount.

toRaw()

toRaw(): bigint;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:206

Converts this primitive to a serializable raw object representation.

Returns

bigint

Serialzied primitive data.

format()

format(units, opts): string;

Defined in: cashconnect-js/packages/core/src/primitives/satoshis.ts:227

Formats the amount in the specified unit with formatting options.

Parameters

Parameter	Type	Description
units	BCHUnits	The unit to format as ('sats', 'bits', 'mBCH', 'BCH')
opts	{ roundToDigits?: number; appendSuffix?: boolean; showApproximationSymbol?: boolean; }	Formatting options
opts.roundToDigits?	number	Number of decimals to round to
opts.appendSuffix?	boolean	Whether to append the unit suffix
opts.showApproximationSymbol?	boolean	-

Returns

string

Formatted amount as string

Examples

// Format as BCH with 2 decimal places and suffix
satoshis.format('BCH', { roundToDigits: 2, appendSuffix: true }) // "0.12 BCH"

// Format as satoshis without suffix
satoshis.format('sats', { roundToDigits: 0, appendSuffix: false }) // "12345678"