Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Library for dealing with money and currency conversion

This branch is 32 commits ahead, 87 commits behind alup:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

RubyMoney - Money

Build Status Dependency Status


When contributing, please make sure to update the CHANGELOG and AUTHORS files when you submit your pull request. Upon merging of your first pull request, you will be given commit access to the repository.


This library aids one in handling money and different currencies.


  • Provides a Money class which encapsulates all information about an certain amount of money, such as its value and its currency.
  • Provides a Money::Currency class which encapsulates all information about a monetary unit.
  • Represents monetary values as integers, in cents. This avoids floating point rounding errors.
  • Represents currency as Money::Currency instances providing an high level of flexibility.
  • Provides APIs for exchanging money from one currency to another.
  • Has the ability to parse a money and currency strings into the corresponding Money/Currency object.



  • Your app must use UTF-8 to function with this library. There are a number of non-ASCII currency attributes.
  • This app requires Ruby 1.9 and JSON. If you're using JRuby < 1.7.0 you'll need to add gem "json" to your Gemfile or similar.


Install stable releases with the following command:

gem install money

The development version (hosted on Github) can be installed with:

git clone git://
cd money
rake install


require 'money'

# 10.00 USD
money =, "USD")
money.cents     #=> 1000
money.currency  #=>"USD")

# Comparisons, "USD") ==, "USD")   #=> true, "USD") ==, "USD")    #=> false, "USD") ==, "EUR")   #=> false, "USD") !=, "EUR")   #=> true

# Arithmetic, "USD") +, "USD") ==, "USD"), "USD") -, "USD") ==, "USD"), "USD") / 5                     ==, "USD"), "USD") * 5                     ==, "USD")

# Assumptive Currencies
Money.assume_from_symbol = true
Money.parse("$100") ==, "USD")
Money.parse("€100") ==, "EUR")
Money.parse("£100") ==, "GBP")

# Currency conversions
some_code_to_setup_exchange_rates, "USD").exchange_to("EUR") ==, "EUR")


Currencies are consistently represented as instances of Money::Currency. The most part of Money APIs allows you to supply either a String or a Money::Currency., "USD") ==,"USD")), "EUR").currency =="EUR")

A Money::Currency instance holds all the information about the currency, including the currency symbol, name and much more.

currency =, "USD").currency
currency.iso_code #=> "USD"     #=> "United States Dollar"

To define a new Money::Currency use Money::Currency.register as shown below.

curr = {
  :priority        => 1,
  :iso_code        => "USD",
  :iso_numeric     => "840",
  :name            => "United States Dollar",
  :symbol          => "$",
  :subunit         => "Cent"
  :subunit_to_unit => 100,
  :separator       => ".",
  :delimiter       => ","


The pre-defined set of attributes includes:

  • :priority a numerical value you can use to sort/group the currency list
  • :iso_code the international 3-letter code as defined by the ISO 4217 standard
  • :iso_numeric the international 3-digit code as defined by the ISO 4217 standard
  • :name the currency name
  • :symbol the currency symbol (UTF-8 encoded)
  • :subunit the name of the fractional monetary unit
  • :subunit_to_unit the proportion between the unit and the subunit
  • :separator character between the whole and fraction amounts
  • :delimiter character between each thousands place

All attributes are optional. Some attributes, such as :symbol, are used by the Money class to print out a representation of the object. Other attributes, such as :name or :priority, exist to provide a basic API you can take advantage of to build your application.


The priority attribute is an arbitrary numerical value you can assign to the Money::Currency and use in sorting/grouping operation.

For instance, let's assume your Rails application needs to render a currency selector like the one available here. You can create a couple of custom methods to return the list of major currencies and all currencies as follows:

# Returns an array of currency id where
# priority < 10
def major_currencies(hash)
  hash.inject([]) do |array, (id, attributes)|
    priority = attributes[:priority]
    if priority && priority < 10
      array[priority] ||= []
      array[priority] << id

# Returns an array of all currency id
def all_currencies(hash)

# => [ :usd, :eur, :bgp, :cad ]

# => [ :aed, :afn, all, ... ]

Default Currency

By default Money defaults to USD as its currency. This can be overwritten using:

Money.default_currency ="CAD")

If you use Rails, then environment.rb is a very good place to put this.

Currency Exchange

Exchanging money is performed through an exchange bank object. The default exchange bank object requires one to manually specify the exchange rate. Here's an example of how it works:

Money.add_rate("USD", "CAD", 1.24515)
Money.add_rate("CAD", "USD", 0.803115)

Money.us_dollar(100).exchange_to("CAD")  # =>, "CAD")
Money.ca_dollar(100).exchange_to("USD")  # =>, "USD")

Comparison and arithmetic operations work as expected:, "USD") <=>, "USD")   # => 1; 9.00 USD is smaller, "EUR") +, "EUR") ==, "EUR")

Money.add_rate("USD", "EUR", 0.5), "EUR") +, "USD") ==, "EUR")

There is nothing stopping you from creating bank objects which scrapes XE for the current rates or just returns rand(2):

Money.default_bank =

Configuring use of a bank


gem 'money' # or 'money-rails'
gem 'google_currency'
Money.use_bank :google_currency

Use other Currency services in a similar fashion if the bank follows the following conventions:

  • class name Money::Bank::[name]
  • require 'money/bank/[name]'

You can also explicitly set the class name for the service if it doesn't follow the convention:

Money.use_bank :forex, Forex::CurrencyService

You can always opt to directly use require and the #default_bank method in case the #use_bank convenience helper doesn't work for your particular bank service.


The following is a list of Money.gem compatible currency exchange rate implementations.


Optionally Money can be set up to use an Exchange to perform the currency exchange. Currently a SingleBank and a MultipleBanks exchange are provided. An Exchange class must implement the #exchange_with(from, to_currency, &block) method.

You can assign a default exchange to be used:

Money.default_exchange = primary_bank, secondary_bank

The multi-bank exchange is useful if you want to provide fall-back exchange services in case one (or more) of the exchange services fail.

By default a Money::Exchange::SingleBank exchange (which uses the default bank) will be used if no exchange is explicitly set.

# use default exchange wrapping the bank
money = 100, "EUR", primary_bank

# define custom exchange and use it
my_exchange = my_bank
money = 100, "EUR", primary_bank, my_exchange

# perform the currency exchange

# change the exchange being used = primary_bank, secondary_bank

Ruby on Rails

To integrate money in a Rails application use money-rails gem or follow the instructions below.

Define accessor methods to let Active Record deal with embedding the money object in your models. The following example requires 2 columns:

:price_cents, :integer, :default => 0, :null => false
:price_currency, :string

Then in your model file:

def price price_cents || 0, price_currency || Money.default_currency

def price=(value)
  Money.parse(value).tap do |price|
    write_attribute :price_cents,    price.cents
    write_attribute :price_currency, price.currency_as_string
Something went wrong with that request. Please try again.