Forex
View SourceForex
is a simple Elixir library that serves as a wrapper to the
foreign exchange reference rates provided by the European Central Bank.
[!NOTE]
From the European Central Bank
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.
## 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 is5
.:symbols
- A list of currency codes (atoms or strings) to filter the rates by. The default isnil
, 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 istrue
.:feed_fn
- Anmfa
tuple that can be used to fetch the exchange rates from a custom feed. This option is mostly used for testing purposes. The default isnil
, 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 change the base currency by passing the base
option to the relevant functions.
To fetch the latest exchange rates, you can use the current_rates/1
function:
iex> Forex.current_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 https://hexdocs.pm/forex.
Installation
The package can be installed by adding forex
to your list of dependencies in mix.exs
:
def deps do
[
{:forex, "~> 0.1.1"}
]
end
License
This project is licensed under the MIT License - see the LICENSE file for details.