> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet top-up currency conversion

> How Orbit converts a non-USD wallet top-up into your wallet currency, and where the applied exchange rate is recorded for reconciliation.

# Wallet top-up currency conversion

When you top up your wallet in a currency other than your wallet currency,
Orbit converts the payment to your wallet currency at the moment the credit is
applied. You do not need to convert the amount yourself before paying.

## How conversion works

* **Different currencies are converted at credit time.** Orbit applies an
  exchange rate for the pair — for example, EUR → USD — and credits the
  converted amount to your wallet.
* **Same-currency top-ups are credited 1:1.** If you pay in your wallet
  currency, no conversion happens and the full amount is credited.
* **The applied rate is recorded.** Every converted top-up stores the exchange
  rate that was used on the resulting wallet transaction, so each credit traces
  back to the rate in effect when it was applied.

## Where the exchange rate comes from

Orbit resolves the rate for a converted top-up in priority order and uses the
first source that returns a usable rate. Which of these sources are active
depends on how your Orbit deployment is configured, so the source that actually
applies can differ between deployments:

1. **A pinned rate for the pair.** If an administrator has set an explicit rate
   for a currency pair — for example to lock a rate during a launch or in a test
   environment — that rate is used first.
2. **A commercial provider feed.** If your deployment is connected to a
   commercial exchange-rate provider, Orbit uses that provider's hourly-refreshed
   rate. This is the same rate pipeline Orbit uses to price your usage, so a
   converted top-up and your ongoing spend stay consistent. This source is off
   unless the provider has been configured; it is not enabled by default.
3. **A public live feed.** If live fetching has been turned on, Orbit reads a
   current rate from a public exchange-rate feed. This source is also off unless
   an administrator enables it; it is not enabled by default.
4. **A maintained reference table.** Orbit ships a built-in table of reference
   rates, based on published central-bank reference rates and updated by the
   Orbit team between releases. **In a default deployment the two live sources
   above are off, so this table is the source used for every converted top-up —
   it is the default, not a rare fallback.**

The reference table has a staleness ceiling of **60 days**. Orbit will not
credit a converted top-up at a table rate older than that, because a rate that
far out of date may no longer reflect the market.

## If a rate cannot be determined

If no active source returns a usable rate — for example the maintained
reference table has passed its 60-day staleness ceiling and no live source is
enabled — Orbit does not guess. Rather than credit the top-up at an unreliable
rate, it fails the conversion with the `FX_RATE_UNAVAILABLE` error.

* **Card top-ups** through the hosted checkout are retried automatically. Your
  wallet is not credited at a bad rate; the credit is applied on a later retry
  once a valid rate is available again.
* **API-initiated top-ups** return `FX_RATE_UNAVAILABLE` so your integration
  can retry, rather than treating the top-up as complete.

Same-currency top-ups are never affected, because they are credited 1:1 with no
rate lookup.

## Reconciling a converted top-up

Because the rate is captured per top-up, the amount credited to your wallet
always matches the rate in effect at credit time — not the rate at any later
moment. This makes it straightforward to reconcile a converted top-up against
the amount you paid.

## Related

* [Billing API](/api-reference/billing) — top-up and currency parameters.
* [Cryptocurrency payments](/billing/crypto-payments) — non-card top-ups.