xrate

Get exchange rates and convert currencies using third-party services.

Disclaimer

I am not affiliated with any of the third-party services mentioned in this or other related documents.

Installation

Requirements:

• Java 11+
• a free API key to the The Free Currency Converter API. (not mandatory, see PLUGINS.md)

Steps:

1. Download the prebuilt distribution from the project's Releases page, or build it yourself. (see Build)
2. Extract the xrate-<version>.zip file where you want.
3. Add the bin directory inside the extracted xrate directory to your PATH.
4. Confirm that you are able to run the program with xrate --version.
5. Specify your API key in xrate/config/xrate.properties as xrate.core.auth=YOUR-API-KEY.

Usage

To confirm that your installation works, you can display the help message by issuing:

xrate --help

The output should be similar to this:

Usage: xrate [-hlV] [-c=<configFilePath>] FROM TO AMOUNT
Get exchange rates and convert currencies using third-party services.

      FROM        The currency to convert from. Defaults to USD.
      TO          The currency to convert to. Defaults to GBP.
      AMOUNT      The amount to convert. Defaults to 1.
  -c, --config=<configFilePath>
                  Path to the config file to use.
  -h, --help      Show this help message and exit.
  -l, --list      Print the available currencies and exit.
  -V, --version   Print version information and exit.

The three main parameters are FROM, TO and AMOUNT. Each of them have a default value:

• FROM defaults to USD (United States dollar)
• TO defaults to GBP (Pound sterling)
• AMOUNT defaults to 1

Because of the default values you may run xrate without any parameters, e.g.:

xrate
1 USD = 0.7438 GBP
1 USD = 0.7438 GBP
1 GBP = 1.3445 USD

In this case the first two output lines are identical because xrate derives the conversion rates from the amount and the result. If the amount is 1, then the first two lines will be the same.

You may run xrate with two ISO 4217 currency codes of your choice, e.g.:

xrate EUR HUF
1 EUR = 367.6017 HUF
1 EUR = 367.6017 HUF
1 HUF = 0.0027 EUR

To see all available currency codes use the -l / --list option, e.g.:

xrate --list
ADP, AED, AFA, AFN, ALL, AMD, ANG, AOA, ARS, ATS, AUD, AWG, AYM, AZM, AZN, BAM...

This will print the available currency codes separated by a comma and a space. Note, that a third-party service may not support all the listed currencies.

Finally, you may run xrate with a specified custom amount, e.g.:

xrate EUR GBP 5.43
5.43 EUR = 4.5557 GBP
1 EUR = 0.839 GBP
1 GBP = 1.1919 EUR

Build

Requirements: JDK 11+

To run the unit tests and build the ZIP file, execute:

./mvnw package

(on Windows you do not need the leading ./)

To do all the above and also run the integration tests, execute:

./mvnw verify

The built ZIP file will be in the target directory of the xrate-core module.

Plugins

xrate's functionality can be extended with plugins. See PLUGINS.md for details.

Contact

Gábor Némethi - nemethi

Project - https://github.com/nemethi/xrate

License

This project is licensed under the MIT License. See the LICENSE file for more information.