# Pricing and currency conversion

Most providers we route to publish their per-token prices in USD
rather than EUR. To keep accounting and balances simple, **every
balance and every charge is in EUR**, and we convert non-EUR provider
prices to EUR once a day before they reach the catalogue.

This page explains how that conversion works, why the displayed price
on a USD-billed provider isn't quite the same as the headline USD
figure, and what happens when our FX feed is unavailable.

## How the conversion is computed

For each non-EUR provider price we ingest, the stored EUR value is:

```
stored_eur_per_1m_tokens =
    source_per_1m_tokens
    × source_to_eur_rate
    × (1 + fx_buffer_percent / 100)
```

- **`source_per_1m_tokens`** — the price the provider publishes in
  their billing currency (USD for most providers).
- **`source_to_eur_rate`** — the daily rate that converts the
  provider's currency into EUR. The primary source is
  [Airwallex](https://www.airwallex.com/); if Airwallex is
  unavailable, we fall back to the reference rates published by the
  European Central Bank at the
  [eurofxref-daily.xml](https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml)
  endpoint.
- **`fx_buffer_percent`** — a fixed conversion markup applied on top of
  the FX rate, defaulting to **1 %**. The markup covers FX-spread
  drift between the day we fetched the rate and the day we settle
  with the provider, plus payment-rail conversion fees.

For example, a provider publishing `$0.15 per 1M tokens` at a
reference rate of `1 EUR = 0.90 USD` (so `1 USD = 1.111 EUR`) and a
1 % markup becomes:

```
0.15 × 1.111 × 1.01 ≈ 0.1683 EUR per 1M tokens
```

That is what your balance is debited for every 1M tokens you spend on
that model.

## Where you see the dual figures

Providers that already bill in EUR (e.g. `/providers/scaleway`)
render a single figure: their published EUR price, shown as-is with
no conversion. Providers that bill in USD (most of them — OpenAI,
Anthropic, Bedrock, Vertex, Groq, …) render both numbers:

```
$0.15/M (€0.17 billed)
```

The first figure is the upstream price you'd see on the provider's
own pricing page. The second is the EUR value your balance is
debited at, computed with the formula above. Hovering the price
shows the FX rate, the markup, and when the conversion was last
refreshed.

## Refresh cadence

We pull FX rates once per ingest run, which runs daily. When the
fallback ECB feed is in use, note that ECB publishes on TARGET
business days at ~16:00 CET, and Saturday and Sunday reuse Friday's
published rate — the standard ECB convention.

Your debit at request time uses the most recent stored EUR value.
**This means the price you see in the catalogue today may differ
slightly from what was billed yesterday for the same number of
tokens** — by the size of the FX move plus markup drift.

## When the FX feed is unavailable

If we cannot reach our FX sources (both Airwallex and the ECB
fallback) during an ingest run, we **soft-disable** the affected
providers (the USD-billed ones that need conversion) until the feed
recovers. While soft-disabled, those providers are visible in the
catalogue but won't accept new requests, and an internal alert
(`FX_INGEST_STALE`) notifies the team.

We deliberately do not fall back to a hard-coded rate. A guessed rate
is worse than visible unavailability — it can either silently
under-charge our margin or over-charge customers, and neither is
something we want to do quietly.

## What we don't claim

- **We don't offer a rate lock.** The price you see today is the
  price we charge today; tomorrow's rate may differ. If you need a
  fixed price, the model's EUR figure is the one we honour at the
  moment of the request, not a quote held in advance.
- **We don't pass through every provider price change in real time.**
  The catalogue reflects the most recent successful ingest, which is
  daily. A provider price change mid-day will land in the next run.
- **We don't bill in any currency other than EUR.** EUR is our single
  operating currency: balances, charges, the price list, and checkout
  are all EUR. Providers that publish in USD are converted once a day
  as described above, which keeps a single ledger and a single set of
  accounting rules.

## Configuration

For self-hosted operators, the conversion markup can be tuned via the
`LOWROUTER_FX_BUFFER_PERCENT` environment variable (default `1.0`,
clamped to `[0, 20]`). The change takes effect on the next ingest
run.