Package org.bitcoinj.base

Class Coin

java.lang.Object
org.bitcoinj.base.Coin
All Implemented Interfaces:
Comparable<Coin>, Monetary
public final class Coin extends Object implements Monetary, Comparable<Coin>
Represents a monetary Bitcoin value. This class is immutable and should be treated as a Java Value-based class. We recommend using the Coin class wherever possible to represent Bitcoin monetary values. If you have existing code that uses other numeric types and need to convert there are conversion methods.

Internally Coin is implemented as a long (see value) that represents a number of satoshis. It can also be considered a fixed-point number of bitcoins.

To create a Coin from an integer number of satoshis, use ofSat(long). To convert to a long number of satoshis use toSat(). (You can also use valueOf(long), getValue() or value.)

To create a Coin from a decimal number of bitcoins, use ofBtc(BigDecimal). To convert to a BigDecimal of bitcoins use toBtc(). (Performing fixed-point conversion, these methods essentially multiply or divide by Coin.COIN.toSat().)

Never ever use float or double to represent monetary values.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    BYTES
    Number of bytes to store this amount.
    static final Coin
    CENT
    0.01 Bitcoins.
    static final Coin
    COIN
    One Bitcoin.
    static final Coin
    FIFTY_COINS
     
    static final Coin
    MICROCOIN
    0.000001 Bitcoins, also known as 1 µBTC or 1 uBTC.
    static final Coin
    MILLICOIN
    0.001 Bitcoins, also known as 1 mBTC.
    static final Coin
    NEGATIVE_SATOSHI
    Represents a monetary value of minus one satoshi.
    static final Coin
    SATOSHI
    A satoshi is the smallest unit that can be transferred.
    static final int
    SMALLEST_UNIT_EXPONENT
    Number of decimals for one Bitcoin.
    final long
    value
    The number of satoshis of this monetary value.
    static final Coin
    ZERO
    Zero Bitcoins.

  • Method Summary

    Modifier and Type
    Method
    Description
    Coin
    add(Coin value)
     
    static long
    btcToSatoshi(BigDecimal coins)
    Convert a decimal amount of BTC into satoshis.
    int
    compareTo(Coin other)
     
    Coin
    div(int divisor)
    Alias for divide
    Coin
    div(long divisor)
    Alias for divide
    Coin
    divide(long divisor)
     
    long
    divide(Coin divisor)
     
    Coin[]
    divideAndRemainder(long divisor)
     
    boolean
    equals(Object o)
     
    long
    getValue()
    Returns the number of satoshis of this monetary value.
    int
    hashCode()
     
    boolean
    isGreaterThan(Coin other)
    Returns true if the monetary value represented by this instance is greater than that of the given other Coin, otherwise false.
    boolean
    isLessThan(Coin other)
    Returns true if the monetary value represented by this instance is less than that of the given other Coin, otherwise false.
    boolean
    isNegative()
    Returns true if and only if this instance represents a monetary value less than zero, otherwise false.
    boolean
    isPositive()
    Returns true if and only if this instance represents a monetary value greater than zero, otherwise false.
    boolean
    isZero()
    Returns true if and only if this instance represents zero monetary value, otherwise false.
    long
    longValue()
    Returns the number of satoshis of this monetary value.
    Coin
    minus(Coin value)
    Alias for subtract
    Coin
    multiply(long factor)
     
    Coin
    negate()
     
    static Coin
    ofBtc(BigDecimal coins)
    Create a Coin from a decimal amount of BTC.
    static Coin
    ofSat(long satoshis)
    Create a Coin from a long integer number of satoshis.
    static Coin
    parseCoin(String str)
    Create a Coin by parsing a String amount expressed in "the way humans are used to".
    static Coin
    parseCoinInexact(String str)
    Create a Coin by parsing a String amount expressed in "the way humans are used to".
    Coin
    plus(Coin value)
    Alias for add
    static Coin
    read(ByteBuffer buf)
    Read a Coin amount from the given buffer as 8 bytes in little-endian order.
    static BigDecimal
    satoshiToBtc(long satoshis)
    Convert an amount in satoshis to an amount in BTC.
    byte[]
    serialize()
    Allocates a byte array and serializes the amount.
    Coin
    shiftLeft(int n)
     
    Coin
    shiftRight(int n)
     
    int
    signum()
     
    int
    smallestUnitExponent()
    Returns the absolute value of exponent of the value of a "smallest unit" in scientific notation.
    Coin
    subtract(Coin value)
     
    Coin
    times(int factor)
    Alias for multiply
    Coin
    times(long factor)
    Alias for multiply
    BigDecimal
    toBtc()
    Convert to number of bitcoin (in BTC)
    String
    toFriendlyString()
    Returns the value as a 0.12 type string.
    String
    toPlainString()
    Returns the value as a plain string denominated in BTC.
    long
    toSat()
    Convert to number of satoshis
    String
    toString()
     
    static Coin
    valueOf(int coins, int cents)
    Create a Coin from an amount expressed in "the way humans are used to".
    static Coin
    valueOf(long satoshis)
    Create a Coin from a long integer number of satoshis.
    ByteBuffer
    write(ByteBuffer buf)
    Write the amount into the given buffer as 8 bytes in little-endian order.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • SMALLEST_UNIT_EXPONENT

      public static final int SMALLEST_UNIT_EXPONENT
      Number of decimals for one Bitcoin. This constant is useful for quick adapting to other coins because a lot of constants derive from it.
      See Also:

    • ZERO

      public static final Coin ZERO
      Zero Bitcoins.

    • COIN

      public static final Coin COIN
      One Bitcoin.

    • CENT

      public static final Coin CENT
      0.01 Bitcoins. This unit is not really used much.

    • MILLICOIN

      public static final Coin MILLICOIN
      0.001 Bitcoins, also known as 1 mBTC.

    • MICROCOIN

      public static final Coin MICROCOIN
      0.000001 Bitcoins, also known as 1 µBTC or 1 uBTC.

    • SATOSHI

      public static final Coin SATOSHI
      A satoshi is the smallest unit that can be transferred. 100 million of them fit into a Bitcoin.

    • FIFTY_COINS

      public static final Coin FIFTY_COINS

    • NEGATIVE_SATOSHI

      public static final Coin NEGATIVE_SATOSHI
      Represents a monetary value of minus one satoshi.

    • BYTES

      public static final int BYTES
      Number of bytes to store this amount.
      See Also:

    • value

      public final long value
      The number of satoshis of this monetary value.

  • Method Details

    • valueOf

      public static Coin valueOf(long satoshis)
      Create a Coin from a long integer number of satoshis.
      Parameters:
      satoshis - number of satoshis
      Returns:
      Coin object containing value in satoshis

    • read

      public static Coin read(ByteBuffer buf) throws BufferUnderflowException
      Read a Coin amount from the given buffer as 8 bytes in little-endian order.
      Parameters:
      buf - buffer to read from
      Returns:
      read amount
      Throws:
      BufferUnderflowException - if the read value extends beyond the remaining bytes of the buffer

    • smallestUnitExponent

      public int smallestUnitExponent()
      Description copied from interface: Monetary
      Returns the absolute value of exponent of the value of a "smallest unit" in scientific notation. For Bitcoin, a satoshi is worth 1E-8 so this would be 8.
      Specified by:
      smallestUnitExponent in interface Monetary

    • getValue

      public long getValue()
      Returns the number of satoshis of this monetary value.
      Specified by:
      getValue in interface Monetary

    • valueOf

      public static Coin valueOf(int coins, int cents)
      Create a Coin from an amount expressed in "the way humans are used to".
      Parameters:
      coins - Number of bitcoins
      cents - Number of bitcents (0.01 bitcoin)
      Returns:
      Coin object containing value in satoshis

    • btcToSatoshi

      public static long btcToSatoshi(BigDecimal coins) throws ArithmeticException
      Convert a decimal amount of BTC into satoshis.
      Parameters:
      coins - number of coins
      Returns:
      number of satoshis
      Throws:
      ArithmeticException - if value has too much precision or will not fit in a long

    • satoshiToBtc

      public static BigDecimal satoshiToBtc(long satoshis)
      Convert an amount in satoshis to an amount in BTC.
      Parameters:
      satoshis - number of satoshis
      Returns:
      number of bitcoins (in BTC)

    • ofBtc

      public static Coin ofBtc(BigDecimal coins) throws ArithmeticException
      Create a Coin from a decimal amount of BTC.
      Parameters:
      coins - number of coins (in BTC)
      Returns:
      Coin object containing value in satoshis
      Throws:
      ArithmeticException - if value has too much precision or will not fit in a long

    • ofSat

      public static Coin ofSat(long satoshis)
      Create a Coin from a long integer number of satoshis.
      Parameters:
      satoshis - number of satoshis
      Returns:
      Coin object containing value in satoshis

    • parseCoin

      public static Coin parseCoin(String str)
      Create a Coin by parsing a String amount expressed in "the way humans are used to".
      Parameters:
      str - string in a format understood by BigDecimal(String), for example "0", "1", "0.10", * "1.23E3", "1234.5E-5".
      Returns:
      Coin object containing value in satoshis
      Throws:
      IllegalArgumentException - if you try to specify fractional satoshis, or a value out of range.

    • parseCoinInexact

      public static Coin parseCoinInexact(String str)
      Create a Coin by parsing a String amount expressed in "the way humans are used to". The amount is cut to satoshi precision.
      Parameters:
      str - string in a format understood by BigDecimal(String), for example "0", "1", "0.10", * "1.23E3", "1234.5E-5".
      Returns:
      Coin object containing value in satoshis
      Throws:
      IllegalArgumentException - if you try to specify a value out of range.

    • add

      public Coin add(Coin value)

    • plus

      public Coin plus(Coin value)
      Alias for add

    • subtract

      public Coin subtract(Coin value)

    • minus

      public Coin minus(Coin value)
      Alias for subtract

    • multiply

      public Coin multiply(long factor)

    • times

      public Coin times(long factor)
      Alias for multiply

    • times

      public Coin times(int factor)
      Alias for multiply

    • divide

      public Coin divide(long divisor)

    • div

      public Coin div(long divisor)
      Alias for divide

    • div

      public Coin div(int divisor)
      Alias for divide

    • divideAndRemainder

      public Coin[] divideAndRemainder(long divisor)

    • divide

      public long divide(Coin divisor)

    • isPositive

      public boolean isPositive()
      Returns true if and only if this instance represents a monetary value greater than zero, otherwise false.

    • isNegative

      public boolean isNegative()
      Returns true if and only if this instance represents a monetary value less than zero, otherwise false.

    • isZero

      public boolean isZero()
      Returns true if and only if this instance represents zero monetary value, otherwise false.

    • isGreaterThan

      public boolean isGreaterThan(Coin other)
      Returns true if the monetary value represented by this instance is greater than that of the given other Coin, otherwise false.

    • isLessThan

      public boolean isLessThan(Coin other)
      Returns true if the monetary value represented by this instance is less than that of the given other Coin, otherwise false.

    • shiftLeft

      public Coin shiftLeft(int n)

    • shiftRight

      public Coin shiftRight(int n)

    • signum

      public int signum()
      Specified by:
      signum in interface Monetary

    • negate

      public Coin negate()

    • longValue

      public long longValue()
      Returns the number of satoshis of this monetary value. It's deprecated in favour of accessing value directly.

    • toSat

      public long toSat()
      Convert to number of satoshis
      Returns:
      decimal number of satoshis

    • toBtc

      public BigDecimal toBtc()
      Convert to number of bitcoin (in BTC)
      Returns:
      decimal number of bitcoin (in BTC)

    • write

      public ByteBuffer write(ByteBuffer buf) throws BufferOverflowException
      Write the amount into the given buffer as 8 bytes in little-endian order.
      Parameters:
      buf - buffer to write into
      Returns:
      the buffer
      Throws:
      BufferOverflowException - if the value doesn't fit the remaining buffer

    • serialize

      public byte[] serialize()
      Allocates a byte array and serializes the amount.
      Returns:
      serialized amount

    • toFriendlyString

      public String toFriendlyString()
      Returns the value as a 0.12 type string. More digits after the decimal place will be used if necessary, but two will always be present.

    • toPlainString

      public String toPlainString()

      Returns the value as a plain string denominated in BTC. The result is unformatted with no trailing zeroes. For instance, a value of 150000 satoshis gives an output string of "0.0015" BTC

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • compareTo

      public int compareTo(Coin other)
      Specified by:
      compareTo in interface Comparable<Coin>