Currency Exchange Package

A comprehensive real-time currency exchange package with support for latest rates, historical data, and currency conversion using the FreeCurrencyAPI service.

Features

• 🌍 Real-time currency exchange rates
• 💱 Currency conversion with accurate calculations
• 📊 Support for 33+ international currencies
• 📅 Historical exchange rate data
• 🔍 API status monitoring
• 🛡️ Comprehensive error handling
• 📦 Both ES modules and direct function exports
• ⚡ Built on FreeCurrencyAPI for reliable data

Installation

npm install currency_exchange

Quick Start

ES Module Import (Recommended)

import CurrencyExchange from 'currency_exchange';

// Create an instance
const currencyExchange = new CurrencyExchange();

// Convert currency
const result = await currencyExchange.convertCurrency(100, 'USD', 'EUR');
console.log(`100 USD = ${result.convertedAmount} EUR`);

Direct Function Import

import { convertCurrency, getLatestRates } from 'currency_exchange';

// Direct function usage
const conversion = await convertCurrency(50, 'USD', 'GBP');
const rates = await getLatestRates('EUR', 'USD,GBP');

API Reference

Class: CurrencyExchange

Constructor

new CurrencyExchange(apiKey?)

• apiKey (optional): FreeCurrencyAPI key. Uses default if not provided.

Methods

getLatestRates(baseCurrency, currencies)

Get the latest exchange rates.

const rates = await currencyExchange.getLatestRates('USD', 'EUR,GBP,JPY');
console.log(rates.data.EUR); // Current USD to EUR rate

Parameters:

• baseCurrency (string): Base currency code (default: 'USD')
• currencies (string|Array): Target currencies (comma-separated or array)

Returns: Promise resolving to API response with latest rates

convertCurrency(amount, fromCurrency, toCurrency)

Convert amount between currencies.

const result = await currencyExchange.convertCurrency(100, 'USD', 'EUR');
console.log(result);
// Output: {
//   amount: 100,
//   fromCurrency: 'USD',
//   toCurrency: 'EUR',
//   rate: 0.864600096,
//   convertedAmount: 86.46,
//   timestamp: '2025-11-09T18:20:00.000Z'
// }

Parameters:

• amount (number): Amount to convert (must be positive)
• fromCurrency (string): Source currency code
• toCurrency (string): Target currency code

Returns: Promise resolving to conversion result object

convertToMultipleCurrencies(amount, fromCurrency, toCurrencies)

Convert amount to multiple currencies at once.

const results = await currencyExchange.convertToMultipleCurrencies(
    50, 'USD', ['EUR', 'GBP', 'JPY']
);

Parameters:

• amount (number): Amount to convert
• fromCurrency (string): Source currency code
• toCurrencies (Array): Array of target currency codes

Returns: Promise resolving to object with conversions array

getHistoricalRates(date, baseCurrency, currencies)

Get historical exchange rates for a specific date.

const historical = await currencyExchange.getHistoricalRates(
    '2024-01-01', 'USD', 'EUR,GBP'
);

Parameters:

• date (string): Date in YYYY-MM-DD format
• baseCurrency (string): Base currency (default: 'USD')
• currencies (string|Array): Target currencies

Returns: Promise resolving to historical rates

getCurrencies()

Get list of all available currencies.

const currencies = await currencyExchange.getCurrencies();
console.log(Object.keys(currencies.data)); // ['EUR', 'USD', 'JPY', ...]

Returns: Promise resolving to currencies list

getStatus()

Check API status and quota information.

const status = await currencyExchange.getStatus();
console.log(status.quotas.month.remaining); // Remaining API calls

Returns: Promise resolving to API status

Direct Function Exports

For convenience, all methods are also available as direct function exports:

import { 
    getLatestRates, 
    convertCurrency, 
    getHistoricalRates, 
    getCurrencies, 
    getStatus 
} from 'currency_exchange';

// Use directly without creating instance
const rates = await getLatestRates('USD', 'EUR');
const conversion = await convertCurrency(100, 'EUR', 'USD');

Error Handling

The package includes comprehensive error handling:

try {
    const result = await currencyExchange.convertCurrency(-10, 'USD', 'EUR');
} catch (error) {
    console.error(error.message); // "Amount must be a positive number"
}

try {
    const result = await currencyExchange.convertCurrency(100, 'INVALID', 'EUR');
} catch (error) {
    console.error(error.message); // API-specific error message
}

Examples

Basic Currency Conversion

import CurrencyExchange from 'currency_exchange';

const exchange = new CurrencyExchange();

// Convert 1000 USD to multiple currencies
const results = await exchange.convertToMultipleCurrencies(
    1000, 'USD', ['EUR', 'GBP', 'JPY', 'CAD', 'AUD']
);

results.conversions.forEach(conv => {
    console.log(`${conv.amount} ${conv.fromCurrency} = ${conv.convertedAmount} ${conv.toCurrency}`);
});

Historical Rate Analysis

// Compare rates from different dates
const dates = ['2024-01-01', '2024-06-01', '2024-12-01'];
for (const date of dates) {
    const rates = await exchange.getHistoricalRates(date, 'USD', 'EUR');
    console.log(`${date}: 1 USD = ${rates.data.EUR} EUR`);
}

API Quota Monitoring

const status = await exchange.getStatus();
console.log(`API Calls Remaining: ${status.quotas.month.remaining}/${status.quotas.month.total}`);

Supported Currencies

The package supports 33+ international currencies including:

• EUR - Euro
• USD - US Dollar
• GBP - British Pound
• JPY - Japanese Yen
• CAD - Canadian Dollar
• AUD - Australian Dollar
• CHF - Swiss Franc
• And many more...

Get the complete list:

const currencies = await exchange.getCurrencies();
console.log(Object.keys(currencies.data));

Requirements

• Node.js >= 12.0.0
• Internet connection for API access
• FreeCurrencyAPI key (default provided for testing)

Testing

Run the comprehensive test suite:

npm test

The tests verify:

• API connectivity and status
• Currency conversion accuracy
• Error handling
• All export methods
• Historical data access

License

ISC License

Contributing

Issues and pull requests are welcome at the GitHub repository.

API Service

This package uses FreeCurrencyAPI for real-time exchange rates. The service provides:

• Real-time currency exchange rates
• Historical data access
• 1000 free API calls per month
• High accuracy and reliability

Built with ❤️ by Saurabh Verma