API Reference

from django_cfg.apps.tools.currency.models import CurrencyRate

rate = CurrencyRate.get_rate("KRW", "USD")
# Returns: CurrencyRate instance or None

value = CurrencyRate.get_rate_value("KRW", "USD")
# Returns: Decimal("0.000678") or None

CurrencyRate.set_rate(
    base="KRW",
    quote="USD",
    rate=Decimal("0.000678"),
    provider="manual"
)

rate.pair  # "KRW/USD"

rate.age_seconds  # 3600 (1 hour)

from django_cfg.modules.django_currency import MoneyField

MoneyField(
    max_digits=15,           # Total digits
    decimal_places=2,        # Decimal precision
    default_currency="USD",  # Currency for new records
    target_currency="USD",   # Conversion target
    null=True,               # Allow NULL
    blank=True,              # Allow empty in forms
    **kwargs                 # Standard DecimalField kwargs
)

from django_cfg.modules.django_currency import (
    PriceFormatter,
    price_formatter,  # Singleton instance
    format_price,
    format_price_full,
)

format_price(150_000_000, "IDR")           # "Rp 150M"
format_price(9500, "USD")                   # "$9,500"
format_price(1500, "USD", suffix="/month")  # "$1,500/month"

format_price_full(
    amount=150_000_000,
    currency="IDR",
    target_amount=9500,
    target_currency="USD",
    suffix="/month",
)  # "$9,500 (Rp 150M)/month"

from django_cfg.modules.django_admin import MoneyFieldDisplay

MoneyFieldDisplay(
    name="price",                  # Base field name
    title="Price",                 # Column header
    currency_field=None,           # Auto: {name}_currency
    target_field=None,             # Auto: {name}_target
    target_currency="USD",         # Target currency code
    rate_field=None,               # Auto: {name}_rate
    rate_at_field=None,            # Auto: {name}_rate_at
    show_rate=True,                # Show rate info
    precision=2,                   # Decimal places
    compact=True,                  # Single-line display
)

display = MoneyFieldDisplay(name="price")
display.get_field_names()
# Returns: {
#     "amount": "price",
#     "currency": "price_currency",
#     "target": "price_target",
#     "rate": "price_rate",
#     "rate_at": "price_rate_at",
# }

display.get_currency_symbol("USD")  # "$"
display.get_currency_symbol("KRW")  # "₩"

from django_cfg import CurrencyConfig

CurrencyConfig(
    enabled=True,               # Enable currency app
    target_currency="USD",      # Default conversion target
    update_interval=3600,       # Rate update interval (seconds)
    update_on_startup=True,     # Update stale rates on startup
    auto_update_enabled=True,   # Enable RQ scheduled task
)

config = CurrencyConfig(enabled=True, auto_update_enabled=True)
schedules = config.get_rq_schedules()
# Returns list of RQScheduleConfig for update_all_rates task

from django_cfg.apps.tools.currency.services import get_converter

converter = get_converter()
 
# Convert amount
result = converter.convert(50_000_000, "KRW", "USD")
# result.result: Decimal("33900")
# result.rate.rate: Decimal("0.000678")
# result.rate.source: "hybrid"
 
# Get rate (from DB or fetch if expired)
rate = converter.get_rate("KRW", "USD")
 
# Force refresh from provider
fresh_rate = converter.refresh_rate("KRW", "USD")

from django_cfg.apps.tools.currency.services.clients import HybridCurrencyClient
 
client = HybridCurrencyClient()
rate = await client.get_rate("KRW", "USD")

from django_cfg.apps.tools.currency.services.clients import CoinPaprikaClient
 
client = CoinPaprikaClient()
rate = await client.get_rate("BTC", "USD")

from django_cfg.apps.tools.currency.models import Currency

from django_cfg.apps.tools.currency.services import (
    sync_currencies,
    sync_currencies_if_needed,
    sync_all,
    get_currency_stats,
)

result = sync_all()
# Returns: {
#     "currencies": {"created": 5, "skipped": 63, ...} or None,
#     "rates": {"updated": 66, "failed": 1, ...} or None,
# }
 
# Force update even if fresh
result = sync_all(force_currencies=True, force_rates=True)
 
# Custom target currency
result = sync_all(target_currency="EUR")

result = sync_currencies()
# Returns: {
#     "created": 5,
#     "updated": 0,
#     "skipped": 63,
#     "created_codes": ["HUF", "RON", ...],
# }
 
# Update existing currency metadata (name, symbol)
result = sync_currencies(update_existing=True)

result = sync_currencies_if_needed()
# Returns: sync result or None if skipped
 
result = sync_currencies_if_needed(min_count=50)

stats = get_currency_stats()
# Returns: {
#     "total": 68,
#     "active": 68,
#     "inactive": 0,
#     "fiat": 50,
#     "crypto": 18,
#     "rates": 66,
# }

# Update rates only
python manage.py update_currency_rates
 
# Sync currencies only
python manage.py update_currency_rates --sync-currencies
 
# Sync currencies + update rates
python manage.py update_currency_rates --all
 
# Show statistics
python manage.py update_currency_rates --stats
 
# Verbose output with sample rates
python manage.py update_currency_rates --verbose
 
# Custom target currency
python manage.py update_currency_rates --target EUR
 
# Update existing currency metadata
python manage.py update_currency_rates --sync-currencies --update-existing

from django_cfg.apps.tools.currency.tasks import (
    sync_all,
    update_all_rates,
    refresh_rate,
    mark_stale_rates,
)

result = sync_all()
# Force sync/update
result = sync_all(force_currencies=True, force_rates=True)

result = update_all_rates()
# Returns: {
#     "status": "success",
#     "updated": 45,
#     "failed": 2,
#     "errors": ["BTC/XYZ: Currency not found"]
# }
 
# With options
result = update_all_rates(
    currencies=["USD", "EUR", "KRW"],
    target_currency="USD",
)

result = refresh_rate("KRW", "USD")
# Returns: {
#     "pair": "KRW/USD",
#     "rate": "0.000678",
#     "source": "hybrid",
#     "timestamp": "2025-01-18T12:00:00Z"
# }

result = mark_stale_rates(max_age_hours=24)
# Returns: {
#     "marked_stale": 5,
#     "cutoff": "2025-01-17T12:00:00Z"
# }

from django_cfg.apps.tools.currency.services.exceptions import (
    CurrencyError,           # Base exception
    CurrencyNotFoundError,   # Pair not supported
    RateFetchError,          # Provider fetch failed
    ConversionError,         # Conversion calculation failed
)

try:
    result = converter.convert(100, "INVALID", "USD")
except CurrencyNotFoundError:
    print("Currency pair not supported")
except RateFetchError as e:
    print(f"Failed to fetch rate: {e}")
except ConversionError as e:
    print(f"Conversion failed: {e}")