Metadata-Version: 2.5
Name: exchangerate-dev
Version: 0.1.0
Summary: Typed clients for the exchangerate.dev API
Project-URL: Homepage, https://exchangerate.dev/docs
Author-email: "Nusantara Ventures, LLC" <hello@exchangerate.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: api,currency,decimal,exchange-rates,forex,fx,sdk
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# Exchangerate for Python

Python clients for indicative FX reference rates from exchangerate.dev. Read latest
and historical rates, currency pairs, indices, and account usage, or convert an
amount between currencies. These rates are not for settlement or trading.

## Install

Requires Python 3.10 or newer. The only dependency is httpx.

```sh
pip install exchangerate-dev
```

## Quickstart

Set `EXCHANGERATE_API_KEY` in your environment, then run:

```python
from exchangerate_dev import Exchangerate

with Exchangerate() as client:
    latest = client.rates.latest(base="USD", symbols=["EUR", "IDR"])
    print(latest.rates["EUR"])
    print(latest.meta.request_id)
    converted = client.convert.amount("USD", "IDR", amount="100")
    print(converted)
```

The context manager closes the client. `AsyncExchangerate` provides asynchronous
access. Supply `api_key=` to configure a key explicitly. The default base URL is
`https://api.exchangerate.dev`; override it with `EXCHANGERATE_BASE_URL` or
`base_url=`. Pass `symbols` as a list of currency codes.

Use `currencies.list()` to read available currency codes and
`account.usage_daily(days=...)` to inspect daily account usage.

## Decimals

Rates and amounts use exact `decimal.Decimal` values, never floats. The `rates`
dictionary maps currency codes to decimals. Pass conversion amounts as strings
to preserve decimal input. Every response carries `meta` with `request_id` and
rate-limit values from headers.

## Errors and retries

`errors.Unauthorized`, `errors.RateLimited`, `errors.NotFound`, and
`errors.BadRequest` extend `errors.ApiError`, which exposes `status`, `code`,
`detail`, and `request_id`. `errors.RateLimited` also carries `retry_after`.
All client errors derive from `errors.ExchangerateError`. Import `errors` from
`exchangerate_dev` when handling these exceptions.

Requests retry up to twice by default for short-window rate limits and temporary
unavailability. Quota exhaustion is not retried.

## Pagination iterators

Use `rates.range_iter(...)`, `rates.timeseries_iter(...)`, and
`indices.timeseries_iter(index_slug, ...)` to consume items across pages. Use
`for` with `Exchangerate` and `async for` with `AsyncExchangerate`. Their
corresponding methods without `_iter` return a single page.

Links: [Documentation](https://exchangerate.dev/docs)

MIT licensed
