Package org.bitcoinj.core

Class Coin

java.lang.Object
org.bitcoinj.core.Coin
All Implemented Interfaces:
Serializable, Comparable<Coin>, Monetary
public final class Coin extends Object implements Monetary, Comparable<Coin>, Serializable
Represents a monetary Bitcoin value. This class is immutable.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    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 BigDecimal
    satoshiToBtc(long satoshis)
    Convert an amount in satoshis to an amount in BTC.
    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.

    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.

    • 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

    • 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)
      Convert a decimal amount of BTC into satoshis.
      Parameters:
      coins - number of coins
      Returns:
      number of satoshis

    • 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)
      Create a Coin from a decimal amount of BTC.
      Parameters:
      coins - number of coins (in BTC)
      Returns:
      Coin object containing value in satoshis

    • 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)

    • 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>