For AI agents: Documentation index at /llms.txt

Skip to content
docs.internetcomputer.org

Exchange Rate Canister

The exchange rate canister (XRC) is a system canister running on the uzr34 system subnet that provides exchange rates to other canisters. It serves as an onchain oracle for asset prices, querying external exchanges via HTTPS outcalls and returning the median rate across all responses.

The canister ID is uf6dk-hyaaa-aaaaq-qaaaq-cai.

The NNS cycle minting canister uses the XRC to obtain up-to-date ICP/XDR rates, which it needs to convert ICP to cycles.

Requesting a rate

Section titled “Requesting a rate”

A request takes the form:

type GetExchangeRateRequest = record {
  base_asset: Asset;
  quote_asset: Asset;
  timestamp: opt nat64;
};

An Asset is a record with a symbol (for example, "ICP" or "USD") and a class (Cryptocurrency or FiatCurrency). The base and quote assets can be any combination of cryptocurrency and fiat currency, for example BTC/ICP, ICP/USD, or USD/EUR.

The optional timestamp is a Unix timestamp in seconds with 1-minute granularity (seconds are ignored). If omitted, the rate for the current minute is returned. To improve reliability, using the start of the previous minute is advisable, since some exchanges may not yet have data for the current minute.

The response is a GetExchangeRateResult variant (Ok: ExchangeRate or Err: ExchangeRateError). A successful response includes the rate as a scaled 64-bit integer, plus metadata: the decimals field (divide the rate by 10^decimals to get the human-readable price), the number of sources queried and rates received for each asset, the standard deviation, and the forex timestamp if applicable.

Cycle cost

Section titled “Cycle cost”

Every request must include 1 billion cycles. Unused cycles are refunded. At least 1M cycles are charged even on error, to prevent denial-of-service attacks. For the full cost breakdown by request type, see Exchange rate canister (XRC).

How rates are computed

Section titled “How rates are computed”

When a cryptocurrency rate is not cached, the XRC queries all supported exchanges using HTTPS outcalls to get the asset’s price against USDT. It then takes the median of all received rates, making the result resistant to outliers. For a cryptocurrency/cryptocurrency pair like BTC/ICP, the XRC derives the rate from independent BTC/USDT and ICP/USDT rates using a cross-product approach before taking the median.

For fiat currencies, the XRC downloads daily forex rates from forex data providers on a fixed schedule. USD/USDT is derived by taking the median of rates for several stablecoins against USDT, based on the assumption that at least half of the included stablecoins maintain their USD peg at any given time.

If the XRC receives largely inconsistent rates from exchanges, it returns an ExchangeRateError::InconsistentRatesReceived error.

Next steps

Section titled “Next steps”