twrate 🇹🇼 — Taiwan Exchange Rate API and CLI for Python

twrate is a Python package and command-line tool for querying live foreign exchange rates from Taiwanese banks. It fetches TWD exchange-rate board data from multiple bank sources concurrently, so you can compare spot rates, cash rates, mid-rates, and spreads for currencies such as USD/TWD, JPY/TWD, EUR/TWD, and more.

Use twrate when you need a lightweight Taiwan exchange rate API for scripts, data pipelines, dashboards, or terminal-based rate checks.

✨ Features

• 🏦 Taiwan bank exchange rates from 17 supported banks.
• ⚡ Async Python API built for concurrent fan-out with asyncio and httpx.
• 💱 CLI for quick lookup: run twrate USD to compare USD/TWD rates across banks.
• 📊 Normalized Rate model with spot buy/sell, cash buy/sell, mid-rate, spread, currency pair, and fetch timestamp.
• ✅ Typed package with Pydantic validation and py.typed support.
• 🧩 Bank-specific fetchers that keep each source isolated and easy to maintain.

🏦 Supported Taiwanese banks

Availability depends on each bank's public website or API. Some banks may publish only spot rates, only selected currencies, or temporarily unavailable data.

📦 Installation

twrate requires Python 3.12 or later.

pip install twrate

For local development, use uv:

uv sync
uv run twrate USD

You can also run the CLI without installing it into the current environment:

uvx twrate USD

🚀 Quick start

💱 Compare USD/TWD rates in the terminal

twrate USD

Example output:

                            USD 各行即時牌價
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
┃ 銀行                ┃ 即期買進 ┃ 即期賣出 ┃ 即期點差 ┃ 現鈔買進 ┃ 現鈔賣出 ┃ 現鈔點差 ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
│ 台灣銀行 (Bank ... │ 30.0950  │ 30.2450  │ 0.50%    │ 29.7700  │ 30.4400  │ 2.22%    │
│ 星展銀行 (DBS ...  │ 30.0760  │ 30.2790  │ 0.67%    │ 29.8630  │ 30.4700  │ 2.01%    │
└─────────────────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘

🐍 Fetch rates from one bank in Python

import asyncio

from twrate import Exchange, fetch_rates


async def main() -> None:
    rates = await fetch_rates(Exchange.BOT)

    usd_rates = [rate for rate in rates if rate.source == "USD"]
    for rate in usd_rates:
        print(rate.symbol, rate.spot_buy, rate.spot_sell, rate.spot_spread)


if __name__ == "__main__":
    asyncio.run(main())

⚡ Fetch all banks concurrently

import asyncio

from twrate import Exchange, Rate, fetch_rates


async def fetch_all_rates() -> list[Rate]:
    tasks = [fetch_rates(exchange) for exchange in Exchange]
    results = await asyncio.gather(*tasks, return_exceptions=True)

    rates: list[Rate] = []
    for exchange, result in zip(Exchange, results, strict=False):
        if isinstance(result, Exception):
            print(f"Failed to fetch {exchange.value}: {result}")
            continue

        rates.extend(result)

    return rates


if __name__ == "__main__":
    all_rates = asyncio.run(fetch_all_rates())
    usd_rates = [rate for rate in all_rates if rate.source == "USD"]
    print(usd_rates)

📊 Rate model

Each fetcher returns a list of normalized Rate objects:

Missing or zero bank values are normalized to None.

🛠️ Development

Install dependencies and run commands through uv:

uv sync
uv run pytest
uv run twrate USD

Run the full test suite with coverage:

uv run pytest -v -s --cov=src tests

🤝 Contributing

Contributions are welcome. Good first issues include:

• Fixing a bank fetcher when a public page or API changes.
• Adding tests and sample fixtures for existing fetchers.
• Improving parsing for currencies with partial spot or cash data.
• Adding a new Taiwanese bank source while preserving the shared Rate model.

When adding or updating a fetcher, keep it bank-specific, async-first, and covered by tests where possible.

📄 License

twrate is released under the terms in LICENSE.