eltoque-python 0.1.1

Unofficial Python SDK for elTOQUE exchange-rate data. A modern, typed client for the official elTOQUE exchange-rate API, with sync and async interfaces.

Independent project. eltoque-python is community-maintained. It is not developed, sponsored, endorsed or supported by elTOQUE.

Exchange rates are indicative, not official. Source: elTOQUE. Access requires registration and an application-specific API token.

import os

from eltoque import ElToqueClient

with ElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"]) as client:
    response = client.get_latest_rates()
    print(response.data)  # the provider's JSON, untouched

Leer en español: docs/quickstart.es.md

Why use it?

• Sync and async clients with the same methods and behavior.
• Typed public API (py.typed, checked with mypy --strict).
• Safe by default: HTTPS only, explicit timeouts, no redirects followed (your token is never forwarded to another host), bounded response size, and the token never appears in repr, error messages or logs.
• Predictable errors: one exception family, one subclass per documented HTTP status.
• Rate-limit aware: parses X-RateLimit-* and Retry-After; retries are opt-in and bounded.
• Pure Python, one runtime dependency (httpx), works in plain scripts, notebooks, Django, Flask, FastAPI or AWS Lambda.
• Tested offline with mocked HTTP: no token needed to develop or run the test suite.

Installation

pip install eltoque-python

Requires Python 3.11 or newer. To work on the SDK itself, install from a clone with pip install -e ..

Get your API token

The SDK does not grant API access. Each application that integrates the API needs its own token, requested from elTOQUE:

1. Fill in the official form: https://tasas-token.eltoque.com/
2. Read the terms of use.
3. Keep the token secret and read it from the environment:

export ELTOQUE_API_TOKEN="your-application-token"

Never commit a token, share it with third parties, or ship it in a browser bundle.

Quickstart

Latest rates (rolling last 24 hours)

import os

from eltoque import ElToqueClient

with ElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"]) as client:
    response = client.get_latest_rates()
    print(response.data)

A specific window (shorter than 24 hours)

import os
from datetime import datetime

from eltoque import ElToqueClient

with ElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"]) as client:
    response = client.get_rates(
        datetime(2022, 10, 27, 0, 0, 0),
        datetime(2022, 10, 27, 23, 59, 59),
    )
    print(response.data)

Async

import asyncio
import os

from eltoque import AsyncElToqueClient


async def main() -> None:
    async with AsyncElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"]) as client:
        response = await client.get_latest_rates()
        print(response.data)


asyncio.run(main())

Handling errors

import os

from eltoque import ElToqueClient, ElToqueError, ElToqueRateLimitError

with ElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"], max_retries=2) as client:
    try:
        response = client.get_latest_rates()
    except ElToqueRateLimitError as error:
        print(f"Rate limited, retry in {error.retry_after} s")
    except ElToqueError as error:
        print(f"Request failed: {error}")
    else:
        print(response.rate_limit.remaining, "requests left in this window")

API reference

Clients

ElToqueClient (sync) and AsyncElToqueClient (async, await every method) share this constructor:

Using a client after it was closed raises ElToqueError.

RatesResponse

Exceptions

ElToqueError
├── ElToqueConfigurationError   invalid token, base_url, timeout, retries
├── ElToqueValidationError      invalid arguments, detected before any request
├── ElToqueNetworkError         connection, DNS, TLS, protocol failures
├── ElToqueTimeoutError
├── ElToqueDecodeError          200 response that is not valid JSON, or too large
└── ElToqueAPIError             has .status_code, .body_excerpt, .rate_limit, .retry_after
    ├── ElToqueBadRequestError       400
    ├── ElToqueAuthenticationError   401
    ├── ElToqueUnprocessableError    422
    ├── ElToqueRateLimitError        429
    └── ElToqueServerError           5xx

Other 3xx/4xx statuses raise the base ElToqueAPIError. See docs/errors.md.

Date and time rules

• date_from and date_to must be naive datetime objects. Timezone-aware values are rejected, because the API does not document its time zone and the SDK will not guess one.
• They are sent as YYYY-MM-DD HH:MM:SS (microseconds are dropped).
• date_from must be earlier than date_to, and the window must be shorter than 24 hours, otherwise the API answers HTTP 400. The SDK rejects invalid windows before any request.
• get_rates_for_day is a convenience; it is not guaranteed to be a complete local calendar day.

Rate limits and retries

By default each API key may make 60 requests/minute and up to 10 requests/second; your key may have different limits. Over the limit the API answers 429 with a Retry-After header.

• Retries are off (max_retries=0). Every retry consumes quota.
• With max_retries > 0 the SDK retries only 429, 502, 503, 504 and transport failures, never 400, 401 or 422.
• Retry-After is honored. If the server asks for longer than 30 s (or the 60 s total budget), the error is raised instead of waiting.
• There is no background polling, caching or bulk collection. You decide when to call.

Known limitations

• Only one operation is documented by the provider: GET /v1/trmi. That is all this SDK calls.
• The provider does not publish the schema of a successful response, so RatesResponse.data is untyped and no field (currency names, timestamps, ...) is guaranteed. Typed rate models will come only after the schema is validated with authorized access.
• The time zone of the API is undocumented (see above).
• Installing this SDK does not give you access to the API; you need your own approved token.

Supported Python versions

Python 3.11, 3.12, 3.13 and 3.14. No framework is required.

Development

uv sync                      # or: pip install -e . && pip install pytest pytest-asyncio pytest-cov ruff mypy build twine
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest                # offline, no token needed
uv run python -m build
uv run twine check dist/*

Optional live check, only with your own authorized token (never run in CI). One request; the script prints the response shape, never provider values. See docs/live-testing.md:

ELTOQUE_API_TOKEN=... ELTOQUE_ALLOW_LIVE_TESTS=1 python scripts/live_check.py

Security and legal

• Treat your token like a password. See docs/security.md.
• This project is not affiliated with elTOQUE. When you display rates, name elTOQUE as the source and describe them as reference estimates, as the terms of use require. Do not modify the data, share your key, resell the data or mass-extract it.
• The MIT license covers this SDK's source code only. It grants no rights over elTOQUE's API, data, name or trademarks.

Official resources

• API landing page: https://tasas.eltoque.com/
• Interactive docs: https://tasas.eltoque.com/docs/
• OpenAPI document: https://tasas.eltoque.com/static/swagger.json
• What is and is not verified: docs/api-contract.md

Community

• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Release notes: CHANGELOG.md