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 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 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 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 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 smallest denominator, i.e. Satoshi for the Bitcoin network
- Return int