bitcoinlib.values module

class bitcoinlib.values.Value(value, denominator=None, network='bitcoin')[source]

Bases: object

Class to represent and convert cryptocurrency values

Create a new Value class. Specify value as integer, float or string. If a string is provided the amount, denominator and currency will be extracted if provided

Examples: Initialize value class >>> Value(10) Value(value=10.00000000000000, denominator=1.00000000, network=’bitcoin’)

>>> Value('15 mBTC')
Value(value=0.01500000000000, denominator=0.00100000, network='bitcoin')
>>> Value('10 sat')
Value(value=0.00000010000000, denominator=0.00000001, network='bitcoin')
>>> Value('1 doge')
Value(value=1.00000000000000, denominator=1.00000000, network='dogecoin')
>>> Value(500, 'm')
Value(value=0.50000000000000, denominator=0.00100000, network='bitcoin')
>>> Value(500, 0.001)
Value(value=0.50000000000000, denominator=0.00100000, network='bitcoin')

All frequently used arithmetic, comparision and logical operators can be used on the Value object. So you can compare Value object, add them together, divide or multiply them, etc.

Values need to use the same network / currency if you work with multiple Value objects. I.e. Value(‘1 BTC’) + Value(‘1 LTC’) raises an error.

# Examples: Value operators >>> Value(‘50000 sat’) == Value(‘5000 fin’) # 1 Satoshi equals 10 Finney, see https://en.bitcoin.it/wiki/Units True

>>> Value('1 btc') > Value('2 btc')
False
>>> Value('1000 LTC') / 5
Value(value=200.00000000000000, denominator=1.00000000, network='litecoin')
>>> Value('0.002 BTC') + 0.02
Value(value=0.02200000000000, denominator=1.00000000, network='bitcoin')

The Value class can be represented in several formats.

# Examples: Format Value class >>> int(Value(“10.1 BTC”)) 10

>>> float(Value("10.1 BTC"))
10.1
>>> round(Value("10.123 BTC"), 2).str()
'10.12000000 BTC'
>>> hex(Value("10.1 BTC"))
'0x3c336080'
Parameters:
  • value (int, float, str) – Value as integer, float or string. Numeric values must be supllied in smallest denominator such as Satoshi’s. String values must be in the format: <value> [<denominator>][<currency_symbol>]

  • denominator (int, float, str) – Denominator as integer or string. Such as 0.001 or m for milli, 1000 or k for kilo, etc. See NETWORK_DENOMINATORS for list of available denominator symbols.

  • network (str, Network) – Specify network if not supplied already in the value string

classmethod from_satoshi(value, denominator=None, network='bitcoin')[source]

Initialize Value class with the smallest denominator as input. Such as represented in script and transactions cryptocurrency values.

Parameters:
  • value (int) – Amount of Satoshi’s / smallest denominator for this network

  • denominator (int, float, str) – Denominator as integer or string. Such as 0.001 or m for milli, 1000 or k for kilo, etc. See NETWORK_DENOMINATORS for list of available denominator symbols.

  • network (str, Network) – Specify network if not supplied already in the value string

Return Value:

str(denominator=None, decimals=None, currency_repr='code')[source]

Get string representation of Value with requested denominator and number of decimals.

>>> Value(1200000, 'sat').str('m')  # milli Bitcoin
'12.00000 mBTC'
>>> Value(12000.3, 'sat').str(1)  # Use denominator = 1 for Bitcoin
'0.00012000 BTC'
>>> Value(12000, 'sat').str('auto')
'120.00 µBTC'
>>> Value(0.005).str('m')
'5.00000 mBTC'
>>> Value(12000, 'sat').str('auto', decimals=0)
'120 µBTC'
>>> Value('13000000 Doge').str('auto')  # Yeah, mega Dogecoins...
'13.00000000 MDOGE'
>>> Value('2100000000').str('auto')
'2.10000000 GBTC'
>>> Value('1.5 BTC').str(currency_repr='symbol')
'1.50000000 ₿'
>>> Value('1.5 BTC').str(currency_repr='name')
'1.50000000 bitcoins'
Parameters:
  • denominator (int, float, str) – Denominator as integer or string. Such as 0.001 or m for milli, 1000 or k for kilo, etc. See NETWORK_DENOMINATORS for list of available denominator symbols. If not provided the default self.denominator value is used. Use value ‘auto’ to automatically determine the best denominator for human readability.

  • decimals (float) – Number of decimals to use

  • currency_repr (str) – Representation of currency. I.e. code: BTC, name: bitcoins, symbol: ₿

Return str:

str_auto(decimals=None, currency_repr='code')[source]

String representation of this Value. Wrapper for the str() method, but automatically determines the denominator depending on the value.

>>> Value('0.0000012 BTC').str_auto()
'120 sat'
>>> Value('0.0005 BTC').str_auto()
'500.00 µBTC'
Parameters:
  • decimals (float) – Number of decimals to use

  • currency_repr (str) – Representation of currency. I.e. code: BTC, name: Bitcoin, symbol: ₿

Return str:

str_unit(decimals=None, currency_repr='code')[source]

String representation of this Value. Wrapper for the str() method, but always uses 1 as denominator, meaning main denominator such as BTC, LTC.

>>> Value('12000 sat').str_unit()
'0.00012000 BTC'
Parameters:
  • decimals (float) – Number of decimals to use

  • currency_repr (str) – Representation of currency. I.e. code: BTC, name: Bitcoin, symbol: ₿

Return str:

to_bytes(length=8, byteorder='little')[source]

Representation of value_sat (value in the smallest denominator: satoshi’s) as bytes string. Used for script or transaction serialization.

>>> Value('1 sat').to_bytes()
b'\x01\x00\x00\x00\x00\x00\x00\x00'
Parameters:
  • length (int) – Length of bytes string to return, default is 8 bytes

  • byteorder (str) – Order of bytes: little or big endian. Default is ‘little’

Return bytes:

to_hex(length=16, byteorder='little')[source]

Representation of value_sat (value in the smallest denominator: satoshi’s) as hexadecimal string.

>>> Value('15 sat').to_hex()
'0f00000000000000'
Parameters:
  • length (int) – Length of hexadecimal string to return, default is 16 characters

  • byteorder (str) – Order of bytes: little or big endian. Default is ‘little’

Returns:

property value_sat

Value in the smallest denominator, i.e. Satoshi for the Bitcoin network

Return int:

bitcoinlib.values.value_to_satoshi(value, network=None)[source]

Convert Value object or value string to the smallest denominator amount as integer

Parameters:
  • value (str, int, float, Value) – Value object, value string as accepted by Value class or numeric value amount

  • network (str, Network) – Specify network to validate value string

Return int: