mzeshawn/currencyarchiveapi repository overview

⁠Currency Archive API - Docker Image

Fast, Free Currency Exchange API with 25+ Years of Historical Data

⁠What Is This?

A production-ready REST API that provides instant currency conversions and historical exchange rate data for 160+ currencies spanning from 1999 to present day. Built with .NET 8, this containerized solution loads 25 years of forex data into memory for millisecond-fast responses without requiring external databases.

Perfect for financial analysis, machine learning projects, forex applications, and educational purposes.

⁠Why Choose This Container?

All historical data loads into memory at startup (~25 MB RAM). No PostgreSQL, MongoDB, or Redis needed—just pull and run.

⁠Complete Historical Coverage

• 9,500+ trading days of forex data (1999-2025)
• 160+ currencies including major pairs, exotics, and cryptocurrencies
• Daily rates with proper EUR-based cross-rate calculations

⁠Production Ready

• Built on .NET 8 with optimized performance
• Global exception handling with RFC-7807 error responses
• Swagger/OpenAPI documentation included
• CORS and rate limiting configured

⁠Developer Friendly

• RESTful API design with intuitive endpoints
• Comprehensive Swagger UI at /swagger
• Versioned API (v1.0) for future compatibility
• Detailed error messages and validation

⁠Quick Start

⁠Run the Container

docker pull mzeshawn/currencyarchiveapi:latest
docker run -d -p 8080:8080 --name currencyapi mzeshawn/currencyarchiveapi:latest

Access the API at http://localhost:8080 or explore the interactive documentation at http://localhost:8080/swagger.

⁠Docker Compose

version: '3.8'
services:
  currencyapi:
    image: mzeshawn/currencyarchiveapi:latest
    container_name: currency-archive-api
    ports:
      - "8080:8080"
    restart: unless-stopped

⁠Key Features

• Convert between any of 160+ currencies
• Pull historical rates from any date back to 1999
• Get time-series data across custom date ranges
• Financial analytics: volatility, returns, momentum indicators
• Rolling window stats for trend analysis
• Switch base currency on the fly
• Filter results by currency symbols
• Proper error handling (RFC-7807)
• Health check endpoint for orchestration

⁠API Endpoints

All endpoints are versioned (/api/v1/) except health.

⁠Conversion Endpoints

• GET /api/v1/convert - Convert between any two currencies
  • Params: from, to, amount, date (optional, defaults to latest)
• GET /api/v1/currencies - Get available currencies for a specific date
  • Params: date

⁠Historical Rates Endpoints

• GET /api/v1/historical - Get all exchange rates for a specific date
  • Params: date, base (optional), symbols (optional)
• GET /api/v1/timeseries - Get rates over a date range
  • Params: start_date, end_date, base (optional), symbols (optional)
• GET /api/v1/fluctuation - Analyze currency fluctuations between dates
  • Params: start_date, end_date, base (optional), symbols (optional)

⁠Analytics Endpoints

• GET /api/v1/rolling-metrics - Rolling window statistics
  • Params: start_date, end_date, window_size, base (optional), symbols (optional)
• GET /api/v1/financial-metrics - Comprehensive financial analysis (volatility, returns, momentum)
  • Params: start_date, end_date, base (optional), symbols (optional)

⁠Health Endpoint

• GET /api/health - Service health and data load status

Full API documentation available at /swagger endpoint.

⁠Use Cases

Financial Applications

• Build forex trading platforms without expensive API subscriptions
• Implement currency converters for e-commerce platforms
• Create personal finance apps with multi-currency support

Data Science & ML

• Train time series forecasting models with 25 years of clean data
• Perform currency correlation and volatility analysis
• Backtest quantitative trading strategies

Education & Research

• Learn financial data APIs without monthly costs
• Study exchange rate patterns and economic trends
• Practice full-stack development with real-world data

Business Analytics

• Historical currency reporting for international transactions
• Multi-currency financial consolidation
• Exchange rate impact analysis

⁠Performance Specs

Real-world performance metrics (tested on 2 vCPU, 2 GB RAM):

• Startup Time: 8-12 seconds (loads all 9,500+ JSON files)
• Memory Usage: ~25 MB RAM for complete 26-year dataset
• Single Conversion: < 20 ms response time
• Historical Query (1 date): < 30 ms response time
• Timeseries Query (365 days): < 80 ms response time
• Financial Metrics (1 year analysis): < 150 ms response time
• Rolling Metrics (30-day window, 1 year): < 200 ms response time
• Concurrent Load: 1000+ requests/sec with consistent sub-100ms latency
• Data Range: Full coverage from 1999-01-04 to 2025-12-31

⁠Support & Documentation

• Live Demo: currencyapi.vitalmedx.com⁠
• GitHub Repository: MuhammadZeshan382/CurrencyArchiveAPI⁠
• Issue Tracker: Report bugs or request features⁠
• License: MIT (free for personal and commercial use)

⁠Why Free?

Most currency APIs charge $20-$30/month for limited access. This project exists to provide free, unrestricted access to comprehensive historical forex data for developers, students, and researchers who need it most.

No API keys. No rate limits. No subscription fees.

⁠Star Us on GitHub

If this container saves you time or money, consider starring the GitHub repository⁠ to support the project.

Keywords: currency converter, forex api, exchange rates, historical currency data, docker container, rest api, financial data, currency conversion, time series data, free forex api, exchange rate api, currency rates docker, financial analytics api, .net 8 api, open source currency api