Wondering what’s next for npm?Check out our public roadmap! »


    2.0.14 • Public • Published


    dependencies npm CI Testing install size Code Scan Alerts Build Status Coverage Status

    A small, 'zero dependency' fast node.js package that delivers the latest forex rates for a given currency pair.

    Using npm:

    $ npm i --save forexy

    Usage and Examples

    To retrieve the latest forex rates for USD/GBP (US dollar to Great British Pound) we pass the two currency codes to the get() method. The get() method returns the current rate, in the first currency denomination (in this example in USD $).

    The currency pair are case insensitive and can be split using: a space, kept together, a forward slash /, or a dash -

    See Demo on runkit

    const Forexy = require("forexy");
    const currencyCheck = new Forexy();
      .get("USD/GBP") //case insensitive and in formats: "usdgbp", "usb gbp", "usd-gbp", "usd/gbp"
      .then((result) => {
        \tpair: console.log(`${currencyCheck.pair} rate is ${result}`);
      .catch((err) => {
        console.error(`Error: ${err}`);


    USDGBP rate is 1.72342


    Forexy returns a Promise, which allows you to use an async/await function, or then().catch().

    const currency = async (pair) => {
      try {
        let result = await currencyCheck.get(pair).then((rate) => rate);
        console.log(`USD/GBP rate is ${result}`);
      } catch (err) {
        console.error(`Error: ${err}`);
    currency("USD GBP");

    ...which is the same as

      .then((result) => {
        console.log(`USD-GBP rate is ${result}`);
      .catch((err) => {
        console.error(`Error: ${err}`);


    Forexy also has a host of Events that you can use through the lifecycle process.


    Get a JSON object with all data.

    currencyCheck.on("fulldata", (data) => {
      //returned JSON of all data.
      console.log("on fulldata:" + JSON.stringify(data));
      //eg. {"rates":{"USDLSL":{"rate":15.140088,"timestamp":1607414291}},"code":200}


    This returns a Date object, which can be further manipulated, this will be approximately the current timestamp.

    currencyCheck.on("timestamp", (data) => {
      //This returns a Date object.
      console.log("on timestamp:" + data); //Tues Dec 08 2021 20:51:10 GMT


    Returns the currency pair values, in uppercase.

    currencyCheck.on("pair", (data) => {
      console.log("on pair:" + data); //USDGBP


    currencyCheck.on("statusCode", (data) => {
      //If no errors then returns '200'
      console.log("on statusCode:" + data);


    rate is the same as the default value returned from the get() method.

    currencyCheck.on("rate", (data) => {
      console.log("on rate:" + data);
      //eg. 1.2234


    Triggered before the request is made. Returns the currency pair value.

    currencyCheck.on("request", (data) => {
      //called before the request is made, returns the currency pair
      console.log("on request:" + data);


    The same returned data as 'fulldata' but streamed.

    currencyCheck.on("stream", (data) => {
      //streamed data
      console.log("on stream: " + data);


    Forexy has constructor properties (prototypes), which get set during the last successful calling of the get() method.


    This is an epoch timestamp. Convert it to a Date(obj.timestamp) object type to manipulate it as a Date.


    Six characters of the two currency codes. For example, USDAUD (US Dollar against Australian Dollar).


    A numeric float indicating the last returned rate for the given currency pair, for example, 1.7453


    An object of all values returned from the last get().

    A Properties Example:

    const forex = new Forexy();
    const currency = async (pair) => {
      try {
        let result = await forex.get(pair).then((rate) => rate);
          `\nCurrency ${pair} rate is ${result}
      } catch (err) {
        console.error(`Error: ${err}`);
    currency("USD NZD");


    Currency USD NZD rate is 1.410037
            timestamp:timestamp:Sun Dec 13 2021 11:39:21 GMT

    Error Handling

    Forexy has built in Error Handling, which will catch any issues in development.

    Unsupported Forex Pairs

    Forexy currently only offers the most popular currency pairs. I plan to add more as the demand grows.

    If you enter an invalid currency pair, the promise will reject with a list of supported currency pairs available.

    If you use Forexy with async / await then wrap the call into a Try {} catch {}. Otherwise use the Promise then().catch(). Any Errors will be directed to the catch()

    const currency = async (pair) => {
      try {
        // code that we will 'try' to run
        let result = await currencyCheck.get("MONOPOLYMONEY");
      } catch (error) {
        // code to run if there are any problems
        console.error(`Error: ${err}`); //display Error message

    or using promise then().catch():

      .then((result) => {
        // code to run if the promise returns a resolve()
      .catch((err) => {
        // code to run if there are any problems
        console.error(`Error: ${err}`);

    Supported Currency Pairs

    Since the introduction of version 1.1 I haven't found a currency that is not covered. Drop me a line if your currency pair isn't there, and I will look at getting it added. You can also raise a Github Issue.

    Version Changes

    • 1.0.x - Using an public free API, JSON returned is fixed.

    • 1.1.x - Setting up a Custom API, with the JSON customised for Forexy. Caching including to allow more traffic. Backwards compatible with v.1.0.x. A larger number of currency pair values available. New functionality to be added - coming very soon !

    • 2.0.x - Using the new Custom API under the hood, which is faster, allows for more hits and also returns better JSON data. Everything has remained backwards compatible. To Add new Properties and Events shortly. Note: To use version 1.0.x API, call the contructor with the following object: v:2. for example:

    const forex = new Forexy({ v: 1 }); //use version 1.0 API.


    npm i forexy

    DownloadsWeekly Downloads






    Unpacked Size

    12.7 kB

    Total Files


    Last publish


    • avatar