hex.pm badge Documentation badge CI

Forex is a simple Elixir library that serves as a wrapper to the foreign exchange reference rates provided by the European Central Bank.

Usage Information

The reference rates are usually updated at around 16:00 CET every working day, except on TARGET closing days.

They are based on the daily concertation procedure between central banks across Europe, which normally takes place around 14:10 CET. The reference rates are published for information purposes only. Using the rates for transaction purposes is strongly discouraged.

Source: European Central Bank

Motivation

Even though there are other libraries in the Elixir ecosystem that provide similar functionality (example: ex_money), Forex was created with the intent of providing access to currency exchange rates for projects that want to self-host the data and not rely on third-party paid services in a simple and straightforward manner. No API keys, no authentication, no rate limits, just a simple Elixir library that fetches the data from the European Central Bank and caches it for later use.

Options

  • :base - The base currency to convert the rates to. The default currency base is :eur.

  • :format - The format of the rate value. Supported values are :decimal and :string. The default is :decimal.

  • :round - The number of decimal places to round the rate value to. The default is 5.

  • :symbols - A list of currency codes (atoms or strings) to filter the rates by. The default is nil, which means all available currencies will be returned.

  • :keys - The format of the keys in the rate map. Supported values are :strings and :atoms. The default is :atoms.

  • :use_cache - A boolean value to enable or disable the cache. To enable the cache check the usage section docs for detailed instructions. The default is true.

  • :feed_fn - An mfa tuple that can be used to fetch the exchange rates from a custom feed. This option is mostly used for testing purposes. The default is nil, which means the default feed will be used.

Usage

By default the base currency is the Euro (EUR), the same as the European Central Bank, but you can change the base currency by passing the base option to the relevant functions.

To fetch the latest exchange rates, you can use the latest_rates/1 function:

iex> Forex.latest_rates()
{:ok,
  %{
    base: :eur,
    date: ~D[2025-03-12],
    rates: %{
      usd: Decimal.new("1.1234"),
      jpy: Decimal.new("120.1234"),
      ...
      zar: Decimal.new("24.1442")
    }}
  }

To fetch the exchange rates for the last ninety days, you can use the last_ninety_days_rates/1 function:

iex> Forex.last_ninety_days_rates()
{:ok,
  [
    %{
      date: ~D[2025-03-12],
      base: :eur,
      rates: %{
        usd: Decimal.new("1.1234"),
        jpy: Decimal.new("120.1234"),
        ...
        zar: Decimal.new("24.1442")
      }
    },
    ...
  ]}

To fetch the historic exchange rates (for any working day since 4 January 1999), you can use the historic_rates/1 function:

iex> Forex.historic_rates()
{:ok,
  [
    %{
      date: ~D[2025-03-12],
      base: :eur,
      rates: %{
        usd: Decimal.new("1.1234"),
        jpy: Decimal.new("120.1234"),
        ...
        zar: Decimal.new("24.1442")
      }
    },
    ...
  ]}

To fetch the exchange rates for a specific date, you can use the get_historic_rate/2 function:

iex> Forex.get_historic_rate(~D[2025-02-25])
{:ok,
  [
    %{
      date: ~D[2025-03-12],
      base: :eur,
      rates: %{
        usd: Decimal.new("1.1234"),
        jpy: Decimal.new("120.1234"),
        ...
        zar: Decimal.new("24.1442")
      }
    },
    ...
  ]}

To fetch the exchange rates between two dates, you can use the get_historic_rates_between/3 function:

iex> Forex.get_historic_rates_between(~D[2025-02-25], ~D[2025-02-28])

{:ok,
  [
    %{
      date: ~D[2025-03-12],
      base: :eur,
      rates: %{
        usd: Decimal.new("1.1234"),
        jpy: Decimal.new("120.1234"),
        ...
        zar: Decimal.new("24.1442")
      }
    },
    ...
  ]}

To convert an amount from one currency to another, you can use the exchange/4 function:

iex> Forex.exchange(100, "USD", "EUR")
{:ok, Decimal.new("91.86100")}

iex>  Forex.exchange(420, :eur, :gbp)
{:ok, Decimal.new("353.12760")}

To list all available currencies from the European Central Bank, you can use the available_currencies/1 function:

iex> Forex.available_currencies()
[:try, :eur, :aud, :bgn, :brl, ...]

Full documentation can be found at docs.

Installation

The package can be installed by adding forex to your list of dependencies in mix.exs:

def deps do
  [
    {:forex, "~> 0.2.1"}
  ]
end

License

This project is licensed under the MIT License - see the LICENSE file for details.