currency_sdk 1.0.1

Free, open-source currency conversion SDK for Flutter with 160+ currencies and offline-first architecture. No API keys required.

Currency SDK

Free, open-source currency conversion SDK for Flutter with 160+ currencies and offline-first architecture.

Get real-time exchange rates with automatic caching - works perfectly offline!

✨ Features

• 🌍 160+ Currencies - All major and minor world currencies
• 📱 Offline-First - Works without internet connection
• ⚡ Fast & Lightweight - Instant response with local caching
• 🔄 Auto-Updates - Exchange rates refresh automatically
• 📦 Zero Config - No API keys or setup required
• 🆓 Completely Free - Open source, no usage limits

🚀 Quick Start

Installation

Add to your pubspec.yaml:

dependencies:
  currency_sdk: ^1.0.1

Or install via command line:

flutter pub add currency_sdk

Basic Usage

import 'package:currency_sdk/currency_sdk.dart';

void main() async {
  // Initialize SDK
  final client = CurrencyClient();
  await client.initialize();

  // Convert currency
  final amount = await client.convert(
    amount: 100,
    from: 'USD',
    to: 'EUR',
  );
  print('100 USD = $amount EUR');

  // Get all rates for a base currency
  final rates = await client.getRates('USD');
  print(rates.convert(100, 'GBP')); // Convert to any currency
  print(rates.conversionRates['JPY']); // Access raw rates
}

📖 Documentation

Initialize SDK

final client = CurrencyClient();
await client.initialize();

Must be called before using any other methods. Safe to call multiple times.

Convert Currency

// Simple conversion
final eurAmount = await client.convert(
  amount: 100,
  from: 'USD',
  to: 'EUR',
);

// Get full rate data
final usdRates = await client.getRates('USD');
final gbpAmount = usdRates.convert(100, 'GBP');
final jpyRate = usdRates.conversionRates['JPY'];

Offline Support

The SDK automatically caches exchange rates locally:

// Check connectivity
if (client.isOnline) {
  print('Using live data');
} else {
  print('Using cached data');
}

// Listen to connectivity changes
client.connectivityStream.listen((isOnline) {
  print(isOnline ? 'Connected' : 'Offline');
});

// Preload cache before going offline
await client.syncCurrencies(['USD', 'EUR', 'GBP']);

Get Supported Currencies

final currencies = await client.getSupportedCurrencies();
print('${currencies.length} currencies available'); // 160+
print(currencies); // ['AED', 'AFN', 'ALL', ..., 'ZMW', 'ZWL']

Error Handling

try {
  final amount = await client.convert(
    amount: 100,
    from: 'USD',
    to: 'INVALID',
  );
} on UnsupportedCurrencyException catch (e) {
  print('Currency not supported: ${e.currencyCode}');
} on NoCachedDataException catch (e) {
  print('Offline and no cached data for ${e.baseCurrency}');
} on RateLimitExceededException catch (e) {
  print('Rate limit exceeded. Resets at: ${e.resetAt}');
} on CurrencySDKException catch (e) {
  print('SDK error: ${e.message}');
}

🧪 Example App

See the example directory for a complete Flutter app demonstrating:

• Real-time currency conversion
• Offline mode indicator
• Error handling
• Connectivity monitoring
• Full UI implementation

Run the example:

cd example
flutter run

🔧 Advanced Usage

Manual Cache Management

// Check if cached data exists
if (client.hasCachedData('USD')) {
  print('USD rates cached');
}

// Clear all cached data
await client.clearCache();

// Listen to cache updates
client.cacheUpdateStream.listen((baseCurrency) {
  print('Cache updated for $baseCurrency');
});

Cleanup

// Dispose when done to prevent memory leaks
client.dispose();

📊 Supported Currencies (160+)

USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, SEK, NZD, MXN, SGD, HKD, NOK, KRW, TRY, INR, BRL, ZAR, DKK, PLN, THB, IDR, HUF, CZK, ILS, CLP, PHP, AED, COP, SAR, MYR, RON, TVD, FJD, and 135+ more.

🤝 Contributing

Contributions welcome! Please open an issue or PR on GitHub.

📄 License

MIT License - see LICENSE file for details.

🐛 Issues

Report bugs at: https://github.com/RonKigen/currency_sdk/issues

👨‍💻 Author

Ronald Komen

• LinkedIn: Ronald Komen
• Twitter/X: @RonaldKigen10
• GitHub: @RonKigen

---

Built with ❤️ using Flutter