djangorestframework-unirate

Django REST Framework integration for the UniRate currency-exchange API. Drop-in API views for live exchange rates, conversion, and supported-currency lookups — plus serializer fields and a cached, settings-driven client — all keeping your UniRate API key safely server-side.

• Drop-in endpoints — mount three ready-made views (rates, convert, currencies) under any URL prefix; clients call your API, never UniRate directly, so the key never reaches the browser.
• Serializer fields — CurrencyCodeField (normalises/validates ISO-4217 codes) and ConvertedAmountField (live-converts a model's amount into a target currency).
• Thin & aligned — wraps the official unirate-api Python client, so behaviour and error semantics match every other UniRate library. Optional Django-cache integration. Zero extra runtime deps.

Companion to UniRateBackend in django-money: django-money gives you a UniRate exchange backend; this package gives you a UniRate-powered REST surface on top of DRF.

Install

pip install djangorestframework-unirate

Add it to INSTALLED_APPS and configure your key:

INSTALLED_APPS = [
    # ...
    "rest_framework",
    "rest_framework_unirate",
]

UNIRATE_API_KEY = "your-api-key"  # or set the UNIRATE_API_KEY env var

Get a free API key at unirateapi.com.

Quick start — drop-in endpoints

# urls.py
from django.urls import include, path

urlpatterns = [
    path("api/fx/", include("rest_framework_unirate.urls")),
]

That exposes:

from defaults to UNIRATE_DEFAULT_BASE_CURRENCY (USD); amount defaults to 1. Currency codes are case-insensitive and normalised to upper-case.

Serializer fields

ConvertedAmountField

Adds a live-converted amount to any serializer, derived from a sibling currency field:

from rest_framework import serializers
from rest_framework_unirate.fields import ConvertedAmountField

class ProductSerializer(serializers.Serializer):
    name = serializers.CharField()
    price = serializers.FloatField()
    currency = serializers.CharField()
    price_eur = ConvertedAmountField(
        amount_field="price",
        from_currency_field="currency",   # or from_currency="USD"
        to_currency="EUR",                # or omit + pass context={"target_currency": ...}
    )

CurrencyCodeField

A CharField that upper-cases input and enforces a 3-letter alphabetic code. Pass validate_supported=True to additionally check it against the live /api/currencies list (one cached call):

from rest_framework_unirate.fields import CurrencyCodeField

class QuoteSerializer(serializers.Serializer):
    base = CurrencyCodeField()
    quote = CurrencyCodeField(validate_supported=True)

Using the client directly

from rest_framework_unirate.client import get_accessor

accessor = get_accessor()
accessor.get_rate("USD", "EUR")          # 0.92
accessor.get_rates("USD")                # {"EUR": 0.92, "GBP": 0.79, ...}
accessor.convert("USD", "EUR", 100)      # 92.0
accessor.get_supported_currencies()      # ["USD", "EUR", ...]

Configuration

Error handling

The bundled views map unirate client errors onto sensible HTTP responses:

Because the API key is server-side, an upstream 401 is treated as a gateway misconfiguration (502), not as a client auth failure. To apply the same mapping to your own DRF views, set the handler globally:

REST_FRAMEWORK = {
    "EXCEPTION_HANDLER": "rest_framework_unirate.exceptions.unirate_exception_handler",
}

Rate limits

Latest rates, conversion, and the currency list are free-tier endpoints. Historical rates and time-series are Pro-gated and return 403 on the free tier. Set UNIRATE_CACHE_TIMEOUT to cut your upstream call volume.

Compatibility

• Python 3.10–3.13
• Django 4.2, 5.0, 5.1, 5.2
• Django REST Framework 3.15–3.16

Other UniRate clients

UniRate ships official client libraries and framework integrations across the ecosystem. The repos below are all maintained under the UniRate-API org.

• Languages: Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift
• Web frameworks: Next.js · SvelteKit · NestJS · Django / Wagtail · Django REST Framework · FastAPI · Flask · React · tRPC
• Static-site generators: Astro · Eleventy · Hugo
• Data / orchestration: Airflow · dbt · LangChain
• Workflow / no-code: n8n · Google Sheets · MCP server
• Editors / tools: VS Code · Obsidian
• Specialty bridges: RubyMoney · NodaMoney (.NET)

Get a free API key at unirateapi.com.

License

MIT — see LICENSE.