Flutter and Dart with the CurrencyCore SDK

The official currencycore Dart package wraps the API for Flutter and Dart. It sets the base URL and bearer token, returns typed models, and exposes one method per endpoint. Use it instead of writing a hand-rolled HTTP layer.

Pass the key at build time with flutter run --dart-define=CURRENCYCORE_API_KEY=cc_test_your_key and read it with String.fromEnvironment. The value is still extractable from a shipped binary, so a production app that must keep the key secret should call your backend instead. Free includes 1,000 requests per month at 60 per minute. Test keys use the same data and quota, capped at 60 per minute; live keys require a paid plan.

dependencies:
  currencycore: ^0.1.2
  dio: ^5.0.0

import 'package:currencycore/currencycore_client.dart';
import 'package:dio/dio.dart';

class Conversion {
  const Conversion({
    required this.from,
    required this.date,
    required this.to,
    required this.result,
    required this.rate,
  });

  final String from;
  final String date;
  final String to;
  final double result;
  final double rate;
}

class CurrencyCoreService {
  static const _apiKey = String.fromEnvironment('CURRENCYCORE_API_KEY');

  late final _api =
      createCurrencyCoreClient(apiKey: _apiKey).getCurrencyCoreApi();

  Future<Conversion> convert({
    required String from,
    required String to,
    required num amount,
  }) async {
    if (_apiKey.isEmpty) {
      throw StateError('Pass --dart-define=CURRENCYCORE_API_KEY=...');
    }

    try {
      final response = await _api.convert(from: from, to: to, amount: amount);
      final row = response.data!.results.first;
      return Conversion(
        from: response.data!.from,
        date: response.data!.date,
        to: row.to,
        result: row.result.toDouble(),
        rate: row.rate.toDouble(),
      );
    } on DioException catch (error) {
      final body = error.response?.data;
      final payload = body is Map ? body['error'] : null;
      final code = payload is Map ? payload['code'] : null;
      throw CurrencyCoreException(
        error.response?.statusCode ?? 0,
        code?.toString() ?? 'http_error',
      );
    }
  }
}

class CurrencyCoreException implements Exception {
  CurrencyCoreException(this.statusCode, this.code);

  final int statusCode;
  final String code;

  @override
  String toString() => '$code (HTTP $statusCode)';
}

The SDK returns the API shape, with one entry per target:

{
  "from": "USD",
  "amount": 100,
  "date": "2026-11-10",
  "results": [{ "to": "INR", "result": 8345.0, "rate": 83.45 }]
}

Catch DioException for API and transport failures. 400 is input, 401 is auth, 403 is a plan or history window, and 429 is a limit. On a 429, read Retry-After before retrying.

Production notes

• A shipped Flutter binary can be reverse engineered, including values passed with --dart-define. Proxy through your backend when the key must stay secret.
• Rates are central-bank reference rates polled hourly, with daily fixings. Do not describe them as instant.
• Cache by date and base. Responses have no ETag, Last-Modified, request ID, or quota headers, so a completed date can use a long TTL while today stays short.
• The SDK is generated from the OpenAPI contract. Pin the package version and read its changelog before a major upgrade.

Next steps

• Official SDKs for TypeScript, Python, Kotlin and Swift
• API reference and error codes
• Caching reference rates for date-based cache keys
• All developer guides