Real-Time Currency Converter
A powerful TypeScript library supporting dual currency providers for maximum coverage and flexibility
✨ Dual Provider Support •
🌍 195+ Currencies •
⚡ Real-time Rates
---
## Features
| ✅ |
Dual Provider Support |
FreeCurrencyAPI (33 currencies) + ExchangeRate-API (163+ currencies) |
| 🌍 |
Global Coverage |
195+ currencies including exotic ones (KES, AFN, etc.) |
| 📈 |
6,500+ Monthly Requests |
5k from FreeCurrencyAPI + 1.5k from ExchangeRate-API |
| ⚡ |
Real-time + Daily Updates |
Real-time rates + timestamped daily updates |
| ✅ |
TypeScript First |
Full type definitions and IntelliSense |
| 🛡️ |
Smart Fallback |
Choose the best provider for each currency pair |
---
## Installation
**npm**
```npm install real-time-currency-converter```
**yarn**
```yarn add real-time-currency-converter```
**pnpm**
```pnpm add real-time-currency-converter```
---
## 🎯 Choose Your Provider
### FreeCurrencyConverter (High Volume)
- ✅ **5,000 free requests/month**
- ✅ **33 major currencies**
- ✅ **Real-time rates**
- ✅ **Account status tracking**
```
import { FreeCurrencyConverter } from 'real-time-currency-converter';
const converter = new FreeCurrencyConverter('fca_live_xxx');
const result = await converter.convert(100, 'USD', 'EUR');
```
### ExchangeRateConverter (Global Coverage)
- ✅ **163+ currencies worldwide**
- ✅ **Daily updates with timestamps**
- ✅ **Historical data support**
- ✅ **Exotic currency support (KES, AFN, etc.)**
```
import { ExchangeRateConverter } from 'real-time-currency-converter';
const converter = new ExchangeRateConverter('your_exchangerate_key');
const result = await converter.convert(100, 'USD', 'KES');
```
---
## Quick Start
### API Key Setup
Choose your provider(s):
Both offer free tiers • No credit card required
### FreeCurrencyAPI (Recommended for Major Currencies)
```
import { FreeCurrencyConverter } from 'real-time-currency-converter';
const converter = new FreeCurrencyConverter('fca_live_xxx');
const result = await converter.convert(100, 'USD', 'EUR');
console.log(${result.convertedAmount} EUR);
```
### ExchangeRate-API (Recommended for Global Coverage)
```
import { ExchangeRateConverter } from 'real-time-currency-converter';
const converter = new ExchangeRateConverter('your_exchangerate_key');
const result = await converter.convert(100, 'USD', 'KES'); // Kenyan Shilling
console.log(${result.convertedAmount} KES);
```
---
## API Reference
### FreeCurrencyConverter
`new FreeCurrencyConverter(apiKey?: string)`
| Parameter |
Type |
Description |
apiKey |
string |
Your FreeCurrencyAPI key (optional, can be set later) |
### ExchangeRateConverter
`new ExchangeRateConverter(apiKey?: string)`
| Parameter |
Type |
Description |
apiKey |
string |
Your ExchangeRate-API key (optional, can be set later) |
### FreeCurrencyConverter Methods
init(apiKey: string)
Initialize or update the API key.
```converter.init('your-freecurrencyapi-key');```
convert(amount, from, to, base?)
Convert currency with real-time rates.
```
const result = await converter.convert(100, 'USD', 'EUR');
// Returns: ConversionResult
```
**Parameters:**
- `amount` (number): Amount to convert
- `fromCurrency` (string): Source currency code
- `toCurrency` (string): Target currency code
- `baseCurrency` (string, optional): Base currency (default: USD)
getLatestRates(base?, currencies?)
Get latest exchange rates.
```
const rates = await converter.getLatestRates('USD', ['EUR', 'GBP']);
// Returns: ExchangeRates
```
getCurrencies(currencies?)
Get ALL supported currencies (33 total)
```
const allCurrencies = await converter.getCurrencies();
// Returns: Record - All 33 currencies
const specificCurrencies = await converter.getCurrencies(['USD', 'EUR', 'GBP']);
// Returns: Record - Only requested currencies
const singleCurrency = await converter.getCurrencies('USD');
// Returns: Record - Only USD
```
getStatus()
Get account status and quota information.
```
const status = await converter.getStatus();
// Returns: AccountStatus
```
convertMultiple(amount, from, toCurrencies, base?)
Convert to multiple currencies at once.
```
const results = await converter.convertMultiple(100, 'USD', ['EUR', 'GBP', 'JPY']);
// Returns: ConversionResults[]
```
### ExchangeRateConverter Methods
init(apiKey: string)
Initialize or update the API key.
```exchangeConverter.init('your-exchangerate-api-key');```
getSupportedCurrencies()
Get all 163+ supported currencies.
```
const currencies = await exchangeConverter.getSupportedCurrencies();
console.log(Supports ${currencies.length} currencies);
// Returns: string[] - Array of currency codes
```
convert(amount, from, to)
Convert currency with timestamps.
```
const result = await exchangeConverter.convert(100, 'USD', 'KES');
console.log(Rate updated: ${result.lastUpdated});
// Returns: ConversionResult with lastUpdated timestamp
```
**Parameters:**
- `amount` (number): Amount to convert
- `fromCurrency` (string): Source currency code
- `toCurrency` (string): Target currency code
getLatestRates(base?, currencies?)
Get latest exchange rates with timestamps.
```
/ Get all rates for USD base
const allRates = await exchangeConverter.getLatestRates('USD');
// Get specific rates
const rates = await exchangeConverter.getLatestRates('EUR', ['USD', 'GBP', 'KES']);
// Returns: ExchangeRates with lastUpdated
```
convertMultiple(amount, from, toCurrencies)
Convert to multiple currencies at once.
```
const results = await exchangeConverter.convertMultiple(100, 'USD', ['EUR', 'KES', 'AFN']);
// Returns: ConversionResults[] with timestamps
```
getHistoricalRates(date, base?, currencies?)
Get historical exchange rates (requires paid plan).
```
const historical = await exchangeConverter.getHistoricalRates('2025-01-01', 'USD', ['EUR', 'GBP']);
// Returns: HistoricalRates
```
isCurrencySupported(currencyCode)
Check if a currency is supported.
```
const isSupported = await exchangeConverter.isCurrencySupported('KES');
console.log(isSupported); // true
// Returns: boolean
```
---
## Usage Examples
### FreeCurrencyConverter Examples
#### Basic Currency Conversion
```
import { FreeCurrencyConverter } from "real-time-currency-converter";
const converter = new FreeCurrencyConverter("fca_live_xxx");
try {
const result = await converter.convert(100, "USD", "EUR");
console.log({
amount: result.amount, // 100
from: result.fromCurrency, // "USD"
to: result.toCurrency, // "EUR"
converted: result.convertedAmount, // 84.23
rate: result.rate, // 0.8423
provider: result.provider, // "freecurrencyapi"
});
} catch (error) {
console.error("Conversion failed:", error.message);
}
```
#### Account Status Monitoring
```
const status = await converter.getStatus();
console.log(`Account ID: ${status.accountId}`);
console.log(`Monthly Usage: ${status.monthlyUsage.used}/${status.monthlyUsage.total}`);
console.log(`Remaining Requests: ${status.monthlyUsage.remaining}`);
console.log(`Usage Percentage: ${status.monthlyUsage.percentage}%`);
```
#### Get Currency Information
```
// Get all supported currencies
const allCurrencies = await converter.getCurrencies();
console.log(`Supports ${Object.keys(allCurrencies).length} currencies`);
// Get specific currency details
const majors = await converter.getCurrencies(["USD", "EUR", "GBP", "JPY"]);
Object.entries(majors).forEach(([code, info]) => {
console.log(`${code}: ${info.name} (${info.symbol})`);
});
```
#### Multiple Currency Conversion
```
const results = await converter.convertMultiple(1000, "USD", [
"EUR",
"GBP",
"JPY",
"CAD",
"AUD",
]);
results.forEach((result) => {
if ("convertedAmount" in result) {
console.log(`$1000 USD = ${result.convertedAmount} ${result.toCurrency}`);
} else {
console.error(`Failed to convert to ${result.toCurrency}: ${result.error}`);
}
});
```
### ExchangeRateConverter Examples
#### Basic Currency Conversion with Timestamps
```
import { ExchangeRateConverter } from "real-time-currency-converter";
const converter = new ExchangeRateConverter("your_exchangerate_key");
try {
const result = await converter.convert(100, "USD", "KES");
console.log({
amount: result.amount, // 100
from: result.fromCurrency, // "USD"
to: result.toCurrency, // "KES"
converted: result.convertedAmount, // 12914.44
rate: result.rate, // 129.1444
provider: result.provider, // "exchangerateapi"
lastUpdated: result.lastUpdated, // "Thu, 18 Sep 2025 00:00:01 +0000"
});
} catch (error) {
console.error("Conversion failed:", error.message);
}
```
#### Exotic Currency Conversions
```
// African currencies
const kesResult = await converter.convert(1000, "USD", "KES"); // Kenyan Shilling
console.log(`$1000 = ${kesResult.convertedAmount} KES`);
// Asian currencies
const afnResult = await converter.convert(500, "EUR", "AFN"); // Afghan Afghani
console.log(`€500 = ${afnResult.convertedAmount} AFN`);
// European currencies
const allResult = await converter.convert(100, "GBP", "ALL"); // Albanian Lek
console.log(`£100 = ${allResult.convertedAmount} ALL`);
```
#### Get All Supported Currencies
```
const currencies = await converter.getSupportedCurrencies();
console.log(`Total currencies: ${currencies.length}`);
console.log("Sample exotic currencies:",currencies.filter((c) => !["USD", "EUR", "GBP"].includes(c)).slice(0, 10));
```
#### Latest Rates with Filtering
```
// Get rates for specific currencies
const rates = await converter.getLatestRates("USD", [
"EUR",
"KES",
"AFN",
"ALL",
]);
console.log("Rates from USD:", rates.rates);
console.log("Last updated:", rates.lastUpdated);
```
### Dual Provider Strategy Examples
#### Smart Provider Selection
```
import {
FreeCurrencyConverter,
ExchangeRateConverter,
} from "real-time-currency-converter";
const freeConverter = new FreeCurrencyConverter("fca_key");
const exchangeConverter = new ExchangeRateConverter("er_key");
async function smartConvert(amount: number, from: string, to: string) {
const majorCurrencies = ["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF"];
// Use FreeCurrency for major currency pairs (higher quota)
if (majorCurrencies.includes(from) && majorCurrencies.includes(to)) {
try {
console.log("Using FreeCurrencyAPI for major pair...");
return await freeConverter.convert(amount, from, to);
} catch (error) {
console.log("FreeCurrency failed, falling back to ExchangeRate-API...");
}
}
// Use ExchangeRate-API for exotic currencies or fallback
console.log("Using ExchangeRate-API for broader coverage...");
return await exchangeConverter.convert(amount, from, to);
}
// Usage
const majorResult = await smartConvert(100, "USD", "EUR"); // Uses FreeCurrency
const exoticResult = await smartConvert(100, "USD", "KES"); // Uses ExchangeRate
```
#### Compare Rates Between Providers
```
async function compareRates(amount: number, from: string, to: string) {
try {
const [freeResult, exchangeResult] = await Promise.allSettled([
freeConverter.convert(amount, from, to),
exchangeConverter.convert(amount, from, to),
]);
if (
freeResult.status === "fulfilled" &&
exchangeResult.status === "fulfilled"
) {
console.log(`FreeCurrency: ${freeResult.value.convertedAmount} ${to}`);
console.log(
`ExchangeRate: ${exchangeResult.value.convertedAmount} ${to}`
);
const difference = Math.abs(
freeResult.value.convertedAmount - exchangeResult.value.convertedAmount
);
console.log(`Difference: ${difference.toFixed(4)} ${to}`);
}
} catch (error) {
console.error("Comparison failed:", error);
}
}
await compareRates(1000, "USD", "EUR");
```
---
## Integration Examples
### React Hook for Dual Providers
```
import { useState } from "react";
import {
FreeCurrencyConverter,
ExchangeRateConverter,
} from "real-time-currency-converter";
function useDualCurrencyConverter(freeApiKey: string, exchangeApiKey: string) {
const [freeConverter] = useState(() => new FreeCurrencyConverter(freeApiKey));
const [exchangeConverter] = useState(
() => new ExchangeRateConverter(exchangeApiKey)
);
const smartConvert = async (
amount: number,
from: string,
to: string,
preferredProvider?: "free" | "exchange"
) => {
if (preferredProvider === "exchange") {
return await exchangeConverter.convert(amount, from, to);
}
// Try FreeCurrency first for major pairs
const majorCurrencies = ["USD", "EUR", "GBP", "JPY"];
if (majorCurrencies.includes(from) && majorCurrencies.includes(to)) {
try {
return await freeConverter.convert(amount, from, to);
} catch (error) {
console.log("Falling back to ExchangeRate-API...");
}
}
return await exchangeConverter.convert(amount, from, to);
};
return { smartConvert, freeConverter, exchangeConverter };
}
export default useDualCurrencyConverter;
```
### Next.js API Route for Both Providers
```
// api/currency/convert.ts
import {
FreeCurrencyConverter,
ExchangeRateConverter,
} from "real-time-currency-converter";
const freeConverter = new FreeCurrencyConverter(
process.env.FREE_CURRENCY_API_KEY
);
const exchangeConverter = new ExchangeRateConverter(
process.env.EXCHANGE_RATE_API_KEY
);
export default async function handler(req: any, res: any) {
if (req.method !== "POST") {
return res.status(405).json({ error: "Method not allowed" });
}
const { amount, from, to, provider = "auto" } = req.body;
try {
let result;
if (provider === "exchange") {
result = await exchangeConverter.convert(amount, from, to);
} else if (provider === "free") {
result = await freeConverter.convert(amount, from, to);
} else {
// Auto-select provider
const majorCurrencies = ["USD", "EUR", "GBP", "JPY"];
if (majorCurrencies.includes(from) && majorCurrencies.includes(to)) {
try {
result = await freeConverter.convert(amount, from, to);
} catch {
result = await exchangeConverter.convert(amount, from, to);
}
} else {
result = await exchangeConverter.convert(amount, from, to);
}
}
res.status(200).json(result);
} catch (error) {
res.status(500).json({ error: error });
}
}
```
---
## 🌍 Supported Currencies
| Provider |
Currencies |
Best For |
| FreeCurrencyAPI |
33 major currencies |
High-volume major currency pairs |
| ExchangeRate-API |
163+ global currencies |
Exotic currencies & global coverage |
### Major Currencies (Both Providers)
| 🇺🇸 USD - US Dollar |
🇪🇺 EUR - Euro |
🇬🇧 GBP - British Pound |
| 🇯🇵 JPY - Japanese Yen |
🇨🇦 CAD - Canadian Dollar |
🇦🇺 AUD - Australian Dollar |
| 🇨🇭 CHF - Swiss Franc |
🇨🇳 CNY - Chinese Yuan |
🇮🇳 INR - Indian Rupee |
### Exotic Currencies (ExchangeRate-API Only)
| 🇰🇪 KES - Kenyan Shilling |
🇦🇫 AFN - Afghan Afghani |
🇦🇱 ALL - Albanian Lek |
| 🇦🇴 AOA - Angolan Kwanza |
🇦🇲 AMD - Armenian Dram |
🇧🇩 BDT - Bangladeshi Taka |
...and 150+ more exotic currencies!
---
## TypeScript Support
Full TypeScript definitions included:
```
interface ConversionResult {
amount: number;
fromCurrency: string;
toCurrency: string;
convertedAmount: number;
rate: number;
baseCurrency?: string;
provider?: "freecurrencyapi" | "exchangerateapi";
lastUpdated?: string;
}
interface AccountStatus {
accountId: number;
quotas: {
month: { total: number; used: number; remaining: number };
grace: { total: number; used: number; remaining: number };
};
monthlyUsage: {
total: number;
used: number;
remaining: number;
percentage: string;
};
}
```
---
## ⚡ Performance & Limits
| Provider |
Monthly Requests |
Currencies |
Update Frequency |
| FreeCurrencyAPI |
5,000 free |
33 major |
Real-time |
| ExchangeRate-API |
1,500 free |
163+ global |
Daily with timestamps |
| Combined Total |
6,500 requests |
195+ currencies |
Flexible |
---
## 💡 Smart Usage Patterns
### Strategy 1: Provider-Specific Usage
```
// For high-volume major currency pairs
const majorConverter = new FreeCurrencyConverter("fca_key");
const majorResult = await majorConverter.convert(100, "USD", "EUR");
// For exotic currencies
const globalConverter = new ExchangeRateConverter("er_key");
const exoticResult = await globalConverter.convert(100, "USD", "KES");
```
### Strategy 2: Fallback Pattern
```
async function smartConvert(amount, from, to) {
try {
// Try FreeCurrency first for major pairs
if (
["USD", "EUR", "GBP", "JPY"].includes(from) &&
["USD", "EUR", "GBP", "JPY"].includes(to)
) {
return await majorConverter.convert(amount, from, to);
}
} catch (error) {
console.log("Falling back to ExchangeRate-API...");
}
// Fallback to ExchangeRate-API for broader coverage
return await globalConverter.convert(amount, from, to);
}
```
---
## Development
Clone and Setup
```
git clone https://github.com/varadaraj772/real-time-currency-converter.git
cd real-time-currency-converter
npm install
```
Build
```npm run build```
Test
```npm test```
---
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
---
## License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
---