💱 XCurrency NCI

A modern, lightweight TypeScript library for real-time currency conversion

✨ Features

• 🌍 350+ Currency Support - Fiat currencies, cryptocurrencies, and precious metals
• 🔄 Real-time Exchange Rates - Live data from reliable currency APIs
• 📝 TypeScript First - Full type safety and IntelliSense support
• 🚀 Modern ES Modules - Built for modern Node.js applications
• 🎯 Simple API - Intuitive function calls with Promise-based async operations
• 📦 Zero Dependencies - Lightweight with no external runtime dependencies
• 🛡️ Error Handling - Comprehensive error handling and validation

🚀 Quick Start

Installation

# Using npm
npm install xcurrency-nci

# Using yarn
yarn add xcurrency-nci

# Using pnpm
pnpm add xcurrency-nci

Basic Usage

import { convert } from "xcurrency-nci";

// Convert 100 USD to EUR
const euros = await convert(100, "usd", "eur");
console.log(`100 USD = ${euros.toFixed(2)} EUR`);

// Convert Bitcoin to USD
const usdValue = await convert(1, "btc", "usd");
console.log(`1 BTC = $${usdValue.toFixed(2)} USD`);

// Convert between any supported currencies
const result = await convert(50, "gbp", "jpy");
console.log(`50 GBP = ¥${result.toFixed(2)} JPY`);

📖 API Documentation

convert(amount, from, to)

Converts an amount from one currency to another using real-time exchange rates.

Parameters

| Parameter | Type | Description | | --------- | -------------- | ------------------------------------------------ | | amount | number | The amount to convert | | from | CurrencyCode | Source currency code (e.g., 'usd', 'eur', 'btc') | | to | CurrencyCode | Target currency code (e.g., 'usd', 'eur', 'btc') |

Returns

• Promise<number> - The converted amount

Example

try {
  const result = await convert(100, "usd", "eur");
  console.log(`Converted amount: ${result}`);
} catch (error) {
  console.error("Conversion failed:", error.message);
}

CurrencyCode Type

TypeScript type that includes all supported currency codes. This provides autocomplete and type safety when using the library.

import { CurrencyCode } from "xcurrency-nci";

const sourceCurrency: CurrencyCode = "usd";
const targetCurrency: CurrencyCode = "eur";

💰 Supported Currencies

XCurrency NCI supports 350+ currencies including:

🏦 Fiat Currencies

• Major: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY
• Regional: INR, BRL, RUB, KRW, MXN, SGD, HKD, NOK, SEK, PLN
• All ISO 4217 standard currencies

💎 Cryptocurrencies

• Major: BTC, ETH, BNB, ADA, SOL, DOT, AVAX, MATIC
• DeFi: UNI, AAVE, CRV, COMP, MKR, SNX
• Stablecoins: USDT, USDC, DAI, BUSD, TUSD

🥇 Precious Metals

• XAU (Gold Ounce)
• XAG (Silver Ounce)
• XPD (Palladium Ounce)
• XPT (Platinum Ounce)

The library supports all currencies defined in the internal currencies mapping, including but not limited to:

Fiat Currencies: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SOS, SRD, STN, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMW, ZWL

Cryptocurrencies: 1INCH, AAVE, ADA, AGIX, AKT, ALGO, AMP, APE, APT, AR, ARB, ATOM, AVAX, AXS, BAKE, BAT, BCH, BNB, BSV, BSW, BTC, BTCB, BTG, BTT, BUSD, CAKE, CELO, CFX, CHZ, COMP, CRO, CRV, CSPR, CVX, DAI, DASH, DCR, DFI, DOGE, DOT, DYDX, EGLD, ENJ, EOS, ETC, ETH, FEI, FIL, FLOW, FLR, FRAX, FTT, GALA, GMX, GNO, GRT, GT, GUSD, HBAR, HNT, HOT, HT, ICP, IMX, INJ, KAS, KAVA, KCS, KDA, KLAY, KNC, KSM, LDO, LEO, LINK, LRC, LTC, LUNA, LUNC, MANA, MBX, MINA, MKR, NEAR, NEO, NEXO, NFT, OKB, ONE, OP, ORDI, PAXG, PEPE, POL, QNT, QTUM, RPL, RUNE, RVN, SAND, SHIB, SNX, SOL, STX, SUI, THETA, TON, TRX, TUSD, TWT, UNI, USDC, USDD, USDP, USDT, VET, WAVES, WEMIX, WOO, XAUT, XCH, XDC, XEC, XEM, XLM, XMR, XRP, XTZ, ZEC, ZIL

🛠️ Development

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm

Setup

# Clone the repository
git clone <repository-url>
cd node-currency

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build the project
pnpm build

# Run tests
pnpm test

Project Structure

node-currency/
├── src/
│   ├── index.ts          # Main export file
│   └── currencies.ts     # Currency mappings
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── register.js          # TypeScript loader

🔧 Configuration

The library uses the fawazahmed0 Currency API for real-time exchange rates. No API key is required, making it easy to get started.

Error Handling

The library provides comprehensive error handling:

import { convert } from "xcurrency-nci";

try {
  const result = await convert(100, "usd", "eur");
  console.log(result);
} catch (error) {
  if (error.message.includes("Failed to fetch")) {
    console.error("Network error - check your internet connection");
  } else if (error.message.includes("Exchange rate not found")) {
    console.error("Currency pair not supported");
  } else {
    console.error("Conversion error:", error.message);
  }
}

📝 Examples

Basic Currency Conversion

import { convert } from "xcurrency-nci";

async function examples() {
  // Fiat to Fiat
  const eurAmount = await convert(100, "usd", "eur");
  console.log(`100 USD = ${eurAmount.toFixed(2)} EUR`);

  // Crypto to Fiat
  const btcInUsd = await convert(1, "btc", "usd");
  console.log(`1 BTC = $${btcInUsd.toLocaleString()} USD`);

  // Fiat to Crypto
  const ethAmount = await convert(1000, "usd", "eth");
  console.log(`$1000 USD = ${ethAmount.toFixed(4)} ETH`);

  // Precious Metals
  const goldPrice = await convert(1, "xau", "usd");
  console.log(`1 oz Gold = $${goldPrice.toFixed(2)} USD`);
}

examples().catch(console.error);

Building a Currency Calculator

import { convert, CurrencyCode } from "xcurrency-nci";

class CurrencyCalculator {
  async convertCurrency(amount: number, from: CurrencyCode, to: CurrencyCode) {
    try {
      const result = await convert(amount, from, to);
      return {
        success: true,
        amount: result,
        formatted: this.formatCurrency(result, to),
      };
    } catch (error) {
      return {
        success: false,
        error: error.message,
      };
    }
  }

  private formatCurrency(amount: number, currency: CurrencyCode): string {
    const symbols: Record<string, string> = {
      usd: "$",
      eur: "€",
      gbp: "£",
      jpy: "¥",
    };

    const symbol = symbols[currency] || currency.toUpperCase();
    return `${symbol}${amount.toFixed(2)}`;
  }
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚡ Performance

• Fast: Efficient API calls with minimal overhead
• Reliable: Built-in error handling and retry logic
• Lightweight: No external dependencies
• Modern: ES2020+ with async/await support

🙏 Acknowledgments

• fawazahmed0 Currency API for providing free currency exchange rates
• The open-source community for inspiration and best practices

Made with ❤️ by Vishwajeet