currency_api.client

Documentation for eth_defi.currency_api.client Python module.

HTTP client for the fawazahmed0 Exchange API.

Fetches the daily exchange rate document for a single date and base currency, with jsDelivr → pages.dev host fallback, and classifies the outcome so the scanner can distinguish “permanently missing” from “retry later”.

Rate direction: the API returns base[quote] = units of quote per 1 unit of base (e.g. for base usd, usd["eur"] = 0.878 means 1 USD = 0.878 EUR). We keep this raw value; USD-per-unit is the inverse 1 / rate.

Canonical API documentation: https://github.com/fawazahmed0/exchange-api

Module Attributes

DEFAULT_TIMEOUT

Default per-request timeout in seconds.

Functions

fetch_rates_for_date(session, date, ...[, ...])

Fetch and classify the exchange rate document for a single date.

Classes

DateRates

Parsed exchange rates for one date and base currency.

FetchResult

Classified result of fetching one date.
FetchStatus

Outcome of a single date fetch.

  • ok: the date document was retrieved (some requested quotes may still be absent — see FetchResult.missing_quotes).

  • unavailable: HTTP 404 on both hosts — the whole date has no data.

  • transient_error: network error / 5xx / malformed body — must be retried.

alias of Literal[‘ok’, ‘unavailable’, ‘transient_error’]

DEFAULT_TIMEOUT = 30.0

Default per-request timeout in seconds.

class DateRates

Bases: object

Parsed exchange rates for one date and base currency.

Variables

  • date – UTC calendar date of the quotes.

  • base_currency – Lower-cased base currency code (e.g. usd).

  • source – Provider identifier written to the source column.

  • rows – List of (quote_currency, rate) tuples where rate is units of the quote currency per 1 unit of the base currency (raw API value).

date: datetime.date

UTC calendar date of the quotes.

base_currency: str

Lower-cased base currency code.

source: str

Provider identifier.

rows: list[tuple[str, float]]

(quote_currency, rate) tuples, raw API values.

__init__(date, base_currency, source, rows)
Parameters
Return type

None

class FetchResult

Bases: object

Classified result of fetching one date.

Variables

  • date – The date that was requested.

  • status – See FetchStatus.

  • rates – Parsed rates for the present quotes, or None when not ok.

  • missing_quotes – Requested quote currencies that were absent from an otherwise-200 body. Never fabricated — handed back so the scanner can grace/record them.

date: datetime.date

The date that was requested.

status: Literal['ok', 'unavailable', 'transient_error']

Outcome classification.

rates: Optional[eth_defi.currency_api.client.DateRates]

Parsed rates for present quotes, or None.

missing_quotes: tuple[str, ...]

Requested quotes absent from a 200 body.

__init__(date, status, rates=None, missing_quotes=<factory>)
Parameters
Return type

None

fetch_rates_for_date(session, date, base_currency, quote_currencies, source, timeout=30.0)

Fetch and classify the exchange rate document for a single date.

Tries the jsDelivr host first, falling back to the pages.dev host on a 404 or transient failure. A date is only declared unavailable when both hosts return a definitive 404.

Parameters

  • session (requests.sessions.Session) – Shared requests session from create_currency_api_session().

  • date (datetime.date) – UTC calendar date to fetch.

  • base_currency (str) – Lower-cased base currency code; interpolated into the URL (never hardcoded usd).

  • quote_currencies (tuple[str, ...]) – Quote currency codes to extract from the document.

  • source (str) – Provider identifier stored on the returned DateRates.

  • timeout (float) – Per-request timeout in seconds.

Returns

A FetchResult classifying the outcome.

Return type

eth_defi.currency_api.client.FetchResult