Skip to main content
This guide walks you through setting up the Currency Converter API for local development.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.12 or higher
  • Docker & Docker Compose (for running PostgreSQL and Redis)
  • Git for version control
You’ll also need API keys from all three exchange rate providers:

Fixer.io

Free tier available

OpenExchangeRates

Free tier available

CurrencyAPI

Free tier available
Fixer.io’s free tier only supports EUR as the base currency. For testing with other base currencies, use OpenExchangeRates or CurrencyAPI as your primary provider during development.

​
Clone the repository

Start by cloning the repository and navigating to the project directory: 
git clone https://github.com/yourorg/currency-converter.git
cd currency-converter

​
Set up Python environment

1

Create a virtual environment

Create and activate a Python virtual environment:
python -m venv .venv
source .venv/bin/activate
2

Install dependencies

Install all required Python packages:
pip install -r requirements.txt
Key dependencies include:
  • fastapi[all] - Web framework with ASGI server
  • sqlalchemy & asyncpg - Async database ORM
  • alembic - Database migrations
  • redis - Redis client for caching
  • httpx - Async HTTP client for providers
  • pytest & pytest-asyncio - Testing framework
3

Configure environment variables

Copy the example environment file and add your API keys:
cp .env.example .env
Edit .env and fill in your configuration:
.env
# Application Settings
APP_NAME="Currency Converter Service"
DEBUG=true
ENVIRONMENT="development"

# Database Configuration
DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/currency_converter"

# Redis Configuration
REDIS_URL="redis://localhost:6379/0"

# API Provider Settings
FIXERIO_API_KEY="your_fixer_api_key_here"
OPENEXCHANGE_APP_ID="your_openexchange_app_id_here"
CURRENCYAPI_KEY="your_currencyapi_key_here"
Never commit the .env file to version control. It’s already in .gitignore.

​
Start infrastructure services

The API requires PostgreSQL and Redis to run. You can start them using Docker Compose: 
docker-compose -f docker/docker-compose.yml up -d
This command starts:
  • PostgreSQL on port 5432
  • Redis on port 6379
Verify the services are running: 
docker-compose -f docker/docker-compose.yml ps
To run only the infrastructure without the API container, use:
docker-compose -f docker/docker-compose.yml up -d db redis

​
Run database migrations

The project uses Alembic for managing database schema. Apply all migrations to create the necessary tables: 
alembic upgrade head
This creates two main tables:
  • supported_currencies - List of all supported currency codes
  • rate_history - Historical exchange rate data

​
Common migration commands

# Create a new migration after modifying ORM models
alembic revision --autogenerate -m "describe your change"

# Apply all pending migrations
alembic upgrade head

# Rollback the last migration
alembic downgrade -1

# View migration history
alembic history

​
Start the development server

Run the API server with auto-reload enabled: 
uvicorn api.main:app --reload
The API is now available at:
  • API Base: http://localhost:8000
  • Interactive Docs: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc
On first startup, the API will automatically fetch supported currencies from all three providers and store them in the database and cache. This process is called “bootstrapping” and happens during the application lifespan startup.

​
Verify your setup

Test the API with a simple conversion request: 
curl http://localhost:8000/api/convert/USD/EUR/100
You should receive a response like: 
{
  "from_currency": "USD",
  "to_currency": "EUR",
  "amount": 100,
  "converted_amount": 92.55,
  "rate": 0.9255,
  "timestamp": "2026-03-04T10:30:00"
}

​
Configuration details

All configuration is managed through config/settings.py using pydantic-settings. The Settings class reads values from environment variables or the .env file:
config/settings.py
class Settings(BaseSettings):
    DATABASE_URL: str = 'sqlite+aiosqlite:///./currency_converter.db'
    REDIS_URL: str = 'redis://localhost:6379'
    FIXERIO_API_KEY: str = ''
    OPENEXCHANGE_APP_ID: str = ''
    CURRENCYAPI_KEY: str = ''
    APP_NAME: str = 'Currency Converter API'
    DEBUG: bool = True

    model_config = SettingsConfigDict(
        env_file='.env',
        case_sensitive=False,
        extra='ignore'
    )
The get_settings() function is decorated with @lru_cache, ensuring settings are loaded only once per process.

​
Development without Docker

If you prefer not to use Docker, you can install PostgreSQL and Redis locally: 
# Install via Homebrew
brew install postgresql@14 redis

# Start services
brew services start postgresql@14
brew services start redis
Update your .env file with the appropriate connection strings for your local installations.

​
Common pitfalls

If providers are unreachable at startup (e.g., bad API keys), the app will raise ProviderError and exit.Solution: Verify your API keys in the .env file are correct and that you have an active internet connection.
If you see connection errors, ensure:
  • PostgreSQL is running: docker-compose ps
  • The DATABASE_URL in .env matches your setup
  • The database exists: createdb currency_converter
Ensure Redis is running and accessible:
docker-compose -f docker/docker-compose.yml ps redis
redis-cli ping  # Should return PONG
Make sure your virtual environment is activated:
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

​
Next steps

Testing guide

Learn how to run tests and write new test cases

Adding providers

Add support for new exchange rate providers

Architecture

Understand the system architecture

API reference

Explore the API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us