Skip to main content
This guide will walk you through setting up and making your first API call to the Currency Converter API.

​
Prerequisites

Before you begin, make sure you have:
The API aggregates rates from all three providers for accuracy, so you’ll need keys for each one.

​
Installation

1

Clone the repository

Clone the project to your local machine:
git clone https://github.com/yourusername/currency-converter.git
cd currency-converter
2

Configure environment variables

Copy the example environment file and add your API keys:
cp docker/.env.example docker/.env
Edit docker/.env with your API credentials:
docker/.env
# API Keys - Required
FIXERIO_API_KEY=your_fixer_key_here
OPENEXCHANGE_APP_ID=your_openexchange_key_here
CURRENCYAPI_KEY=your_currencyapi_key_here

# Database and Redis URLs
DATABASE_URL=postgresql://postgres:postgres@db:5432/currency_converter
REDIS_URL=redis://redis:6379/0
Never commit your .env file with real API keys to version control.
3

Start the services

Launch all services using Docker Compose:
docker-compose -f docker/docker-compose.yml up --build
This command will:
  • Start PostgreSQL database
  • Start Redis cache
  • Create database tables
  • Initialize supported currencies from providers
  • Start the FastAPI server on port 8000
You should see logs indicating the application is ready:
INFO: Application ready
INFO: Uvicorn running on http://0.0.0.0:8000
4

Verify the installation

Check that the API is running by opening the interactive documentation:
curl http://localhost:8000/docs
You should see the Swagger UI interface in your browser at http://localhost:8000/docs

​
Make your first API call

Now that the API is running, let’s convert some currency.

​
Convert currency

Convert 100 USD to EUR using the path parameter format: 
curl http://localhost:8000/api/convert/USD/EUR/100

{
  "from_currency": "USD",
  "to_currency": "EUR",
  "original_amount": 100.00,
  "converted_amount": 92.55,
  "exchange_rate": 0.9255,
  "timestamp": "2026-03-04T14:30:00Z",
  "source": "averaged"
}

​
Get exchange rate

Fetch the current exchange rate between two currencies: 
curl http://localhost:8000/api/rate/GBP/JPY
Response
{
  "from_currency": "GBP",
  "to_currency": "JPY",
  "rate": 188.45,
  "timestamp": "2026-03-04T14:30:00Z",
  "source": "averaged"
}

​
List supported currencies

Get all available currency codes: 
curl http://localhost:8000/api/currencies
Response
{
  "currencies": [
    "USD",
    "EUR",
    "GBP",
    "JPY",
    "AUD",
    "CAD",
    "CHF",
    "CNY",
    "SEK",
    "NZD"
  ]
}
The API only supports currencies that are available across all three providers. This ensures consistent results.

​
Understanding the response

The conversion response includes several important fields:
FieldDescription
from_currencyThe source currency code (ISO 4217)
to_currencyThe target currency code
original_amountThe amount you requested to convert
converted_amountThe result after applying the exchange rate
exchange_rateThe averaged rate used for conversion
timestampWhen the rate was fetched (ISO 8601)
sourceProvider information (typically “averaged”)

​
How it works

Under the hood, your request triggers the following flow:
1

Cache check

The API first checks Redis cache for a recent rate (within 5 minutes)
2

Provider aggregation

If not cached, the API fetches rates from all three providers in parallel:
  • Fixer.io
  • OpenExchangeRates
  • CurrencyAPI
3

Rate averaging

Successful responses are averaged together. If one provider fails, the others are used.
4

Caching and persistence

The averaged rate is:
  • Cached in Redis (5 minute TTL)
  • Stored in PostgreSQL for historical tracking
5

Response

The conversion is calculated and returned to you
Subsequent requests for the same currency pair within 5 minutes will be served from cache instantly.

​
Next steps

Now that you have the API running, explore these topics:

​
Troubleshooting

​
Port already in use

If port 8000 is already in use, modify the port mapping in docker/docker-compose.yml or stop the conflicting service.

​
Provider errors at startup

If you see ProviderError during startup:
  1. Verify your API keys are correct in docker/.env
  2. Check that all three provider APIs are accessible from your network
  3. Ensure you haven’t exceeded free tier rate limits

​
Database connection errors

If PostgreSQL fails to connect:
  1. Ensure Docker Compose started all services successfully
  2. Check that port 5432 is not blocked by another PostgreSQL instance
  3. Review Docker logs: docker-compose -f docker/docker-compose.yml logs db
The application will exit if it cannot connect to all three providers at startup, as it needs to initialize the supported currencies list.

Build docs developers (and LLMs) love

Get started for freeTalk to us