feat(backend): Introduce ICPSwap as rates fallback provider (#12286)

AntonioVentilii · github-actions[bot] · web-flow · commit 0de701ab6d71 · 2026-04-02T09:15:45.000Z
# Motivation

CoinGecko does not always return USD prices for ICRC ledger tokens. The
app already uses ICPSwap as a fallback on the frontend; the backend
should do the same so cached rates in the canister stay useful when
CoinGecko is missing data.

# Changes

- Added ICPSwap as a supplemental HTTP source for missing ICRC prices,
aligned with the public ICPSwap API used on the frontend.
- Introduced a `SupplementalPriceProvider` trait and a composite refresh
flow: CoinGecko runs first; only tokens without a valid USD price are
passed to ordered supplementals (ICPSwap first today), so adding more
providers later is a small change.
- Only valid prices are written: invalid primary rows no longer
overwrite good cached values.

# Tests

Added tests.

---------

Co-authored-by: github-actions &lt;41898282+github-actions[bot]@users.noreply.github.com&gt;
diff --git a/src/backend/src/exchange/composite.rs b/src/backend/src/exchange/composite.rs
@@ -0,0 +1,145 @@
+use std::collections::BTreeMap;
+
+use shared::types::exchange::ExchangeData;
+
+use crate::{
+    exchange::{
+        provider::ExchangePriceProvider, providers::coingecko::CoinGeckoProvider,
+        supplemental::SupplementalPriceProvider,
+    },
+    types::storable::StoredTokenId,
+};
+
+/// Whether the backend should treat this snapshot as a usable USD price.
+pub(crate) fn has_valid_price(data: &ExchangeData) -> bool {
+    data.price.is_some_and(|p| p.is_finite() && p > 0.0)
+}
+
+fn merge_valid_primary(
+    primary: Vec<(StoredTokenId, ExchangeData)>,
+) -> BTreeMap<StoredTokenId, ExchangeData> {
+    primary
+        .into_iter()
+        .filter(|(_, d)| has_valid_price(d))
+        .collect()
+}
+
+fn still_missing(
+    requested: &[StoredTokenId],
+    current: &BTreeMap<StoredTokenId, ExchangeData>,
+) -> Vec<StoredTokenId> {
+    requested
+        .iter()
+        .filter(|t| !current.contains_key(t))
+        .cloned()
+        .collect()
+}
+
+/// Runs the primary provider, then each supplemental in order, merging only valid prices.
+///
+/// Later supplementals only see tokens that still lack a valid price after earlier steps.
+pub(crate) async fn fetch_all_prices(
+    primary: &CoinGeckoProvider,
+    supplementals: &[Box<dyn SupplementalPriceProvider>],
+    token_ids: &[StoredTokenId],
+) -> Vec<(StoredTokenId, ExchangeData)> {
+    let primary_rows = primary.fetch_prices(token_ids).await.unwrap_or_else(|e| {
+        ic_cdk::println!("Primary exchange provider failed: {e}");
+        Vec::new()
+    });
+
+    let mut map = merge_valid_primary(primary_rows);
+    let mut missing = still_missing(token_ids, &map);
+
+    for provider in supplementals {
+        if missing.is_empty() {
+            break;
+        }
+
+        match provider.supplement(&missing).await {
+            Ok(filled) => {
+                for (id, data) in filled {
+                    if has_valid_price(&data) {
+                        map.insert(id, data);
+                    }
+                }
+                missing = still_missing(token_ids, &map);
+            }
+            Err(err) => {
+                ic_cdk::println!(
+                    "Supplemental exchange provider {} failed: {err}",
+                    provider.id()
+                );
+            }
+        }
+    }
+
+    token_ids
+        .iter()
+        .filter_map(|t| map.get(t).map(|d| (t.clone(), d.clone())))
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use candid::Principal;
+    use shared::types::token_id::TokenId;
+
+    use super::*;
+
+    #[test]
+    fn has_valid_price_accepts_positive_finite() {
+        let d = ExchangeData {
+            timestamp_ns: 0,
+            price: Some(1.5),
+            price_24h_change_pct: None,
+            market_cap: None,
+        };
+        assert!(has_valid_price(&d));
+    }
+
+    #[test]
+    fn has_valid_price_rejects_none_zero_nan() {
+        let none = ExchangeData {
+            timestamp_ns: 0,
+            price: None,
+            price_24h_change_pct: None,
+            market_cap: None,
+        };
+        assert!(!has_valid_price(&none));
+
+        let zero = ExchangeData {
+            timestamp_ns: 0,
+            price: Some(0.0),
+            price_24h_change_pct: None,
+            market_cap: None,
+        };
+        assert!(!has_valid_price(&zero));
+
+        let nan = ExchangeData {
+            timestamp_ns: 0,
+            price: Some(f64::NAN),
+            price_24h_change_pct: None,
+            market_cap: None,
+        };
+        assert!(!has_valid_price(&nan));
+    }
+
+    #[test]
+    fn still_missing_skips_tokens_present_in_map() {
+        let p = Principal::from_text("ryjl3-tyaaa-aaaaa-aaaba-cai").unwrap();
+        let t = StoredTokenId(TokenId::Icrc(p));
+        let mut map = BTreeMap::new();
+        map.insert(
+            t.clone(),
+            ExchangeData {
+                timestamp_ns: 0,
+                price: Some(1.0),
+                price_24h_change_pct: None,
+                market_cap: None,
+            },
+        );
+        let requested = vec![t.clone()];
+        assert!(still_missing(&requested, &map).is_empty());
+    }
+}
diff --git a/src/backend/src/exchange/mod.rs b/src/backend/src/exchange/mod.rs
@@ -1,5 +1,7 @@
+mod composite;
 pub(crate) mod provider;
 mod providers;
+mod supplemental;
 
 use std::time::Duration;
 
@@ -11,7 +13,11 @@ use shared::types::{
 };
 
 use crate::{
-    exchange::{provider::ExchangePriceProvider, providers::coingecko::CoinGeckoProvider},
+    exchange::{
+        composite::fetch_all_prices,
+        providers::{coingecko::CoinGeckoProvider, icpswap::IcpSwapProvider},
+        supplemental::SupplementalPriceProvider,
+    },
     read_state,
     state::{mutate_state, with_api_keys},
     types::storable::{Candid, StoredTokenId},
@@ -74,20 +80,14 @@ fn update_price(token_id: &StoredTokenId, exchange_data: &ExchangeData) {
     });
 }
 
-async fn fetch_and_update_prices(
-    provider: &impl ExchangePriceProvider,
-    token_ids: &[StoredTokenId],
-) {
-    match provider.fetch_prices(token_ids).await {
-        Ok(prices) => {
-            for (token_id, exchange_data) in &prices {
-                update_price(token_id, exchange_data);
-            }
-        }
-        Err(err) => {
-            ic_cdk::println!("Failed to fetch prices: {err}");
-        }
-    }
+/// Ordered supplemental sources that run after `CoinGecko` for tokens still missing a valid USD
+/// price.
+///
+/// To add another provider: implement [`SupplementalPriceProvider`] for a new type (any token
+/// variant you support), place it under `exchange/providers/`, and append `Box::new(...)` here in
+/// priority order (first match wins; later providers only see still-missing tokens).
+fn supplemental_price_providers() -> Vec<Box<dyn SupplementalPriceProvider>> {
+    vec![Box::new(IcpSwapProvider::default())]
 }
 
 pub(crate) async fn refresh_exchange_rates() -> Result<(), ExchangeError> {
@@ -117,7 +117,12 @@ pub(crate) async fn refresh_exchange_rates() -> Result<(), ExchangeError> {
         return Ok(());
     }
 
-    fetch_and_update_prices(&provider, &tokens_to_fetch).await;
+    let supplementals = supplemental_price_providers();
+    let prices = fetch_all_prices(&provider, &supplementals, &tokens_to_fetch).await;
+
+    for (token_id, exchange_data) in prices {
+        update_price(&token_id, &exchange_data);
+    }
 
     Ok(())
 }
diff --git a/src/backend/src/exchange/providers/icpswap/mod.rs b/src/backend/src/exchange/providers/icpswap/mod.rs
@@ -0,0 +1,172 @@
+use ic_cdk::{api::time, management_canister::HttpHeader};
+use serde::Deserialize;
+use serde_json::from_slice;
+use shared::types::{exchange::ExchangeData, token_id::TokenId};
+
+use crate::{
+    exchange::supplemental::{SupplementalPriceProvider, SupplementalPricesFuture},
+    types::storable::StoredTokenId,
+    utils::http_outcall,
+};
+
+const DEFAULT_BASE_URL: &str = "https://api.icpswap.com";
+/// `ICPSwap` token info responses are small JSON objects; keep the cap tight for cycle costs.
+const MAX_RESPONSE_BYTES: u64 = 8_192;
+
+#[derive(Debug, Deserialize)]
+struct IcpSwapEnvelope {
+    code: i64,
+    #[serde(default)]
+    data: Option<IcpSwapTokenBody>,
+}
+
+#[derive(Debug, Deserialize)]
+struct IcpSwapTokenBody {
+    #[serde(rename = "tokenLedgerId")]
+    _token_ledger_id: String,
+    price: String,
+    #[serde(rename = "priceChange24H")]
+    price_change_24h: String,
+}
+
+fn exchange_data_from_icpswap_envelope(
+    parsed: IcpSwapEnvelope,
+    timestamp_ns: u64,
+) -> Option<ExchangeData> {
+    if parsed.code != 0 {
+        return None;
+    }
+    let token = parsed.data?;
+    let price: f64 = token.price.parse().ok()?;
+    if !price.is_finite() || price <= 0.0 {
+        return None;
+    }
+    let price_24h_change_pct = token
+        .price_change_24h
+        .parse()
+        .ok()
+        .filter(|v: &f64| v.is_finite());
+    Some(ExchangeData {
+        timestamp_ns,
+        price: Some(price),
+        price_24h_change_pct,
+        market_cap: None,
+    })
+}
+
+fn parse_icpswap_body(body: &[u8]) -> Option<ExchangeData> {
+    let parsed: IcpSwapEnvelope = from_slice(body).ok()?;
+    exchange_data_from_icpswap_envelope(parsed, time())
+}
+
+/// Supplemental USD prices for ICRC ledger tokens via [ICPSwap](https://api.icpswap.com).
+#[derive(Debug, Clone)]
+pub(crate) struct IcpSwapProvider {
+    base_url: String,
+}
+
+impl Default for IcpSwapProvider {
+    fn default() -> Self {
+        Self {
+            base_url: DEFAULT_BASE_URL.to_string(),
+        }
+    }
+}
+
+impl IcpSwapProvider {
+    #[expect(dead_code)]
+    pub(crate) fn with_base_url(base_url: String) -> Self {
+        Self { base_url }
+    }
+
+    async fn fetch_icrc_token_usd(
+        &self,
+        ledger_text: &str,
+    ) -> Result<Option<ExchangeData>, String> {
+        let url = format!(
+            "{}/info/token/{ledger_text}",
+            self.base_url.trim_end_matches('/')
+        );
+
+        let response = http_outcall::get(
+            &url,
+            vec![HttpHeader {
+                name: "Accept".to_string(),
+                value: "application/json".to_string(),
+            }],
+            MAX_RESPONSE_BYTES,
+        )
+        .await?;
+
+        Ok(parse_icpswap_body(&response.body))
+    }
+}
+
+impl SupplementalPriceProvider for IcpSwapProvider {
+    fn id(&self) -> &'static str {
+        "icpswap"
+    }
+
+    fn supplement<'a>(&'a self, missing: &'a [StoredTokenId]) -> SupplementalPricesFuture<'a> {
+        Box::pin(async move {
+            let mut out = Vec::new();
+
+            for stored in missing {
+                let StoredTokenId(TokenId::Icrc(ledger_id)) = stored else {
+                    continue;
+                };
+
+                let ledger_text = ledger_id.to_text();
+
+                match self.fetch_icrc_token_usd(&ledger_text).await {
+                    Ok(Some(data)) => out.push((stored.clone(), data)),
+                    Ok(None) => {}
+                    Err(err) => {
+                        ic_cdk::println!("ICPSwap price fetch for {ledger_text} failed: {err}");
+                    }
+                }
+            }
+
+            Ok(out)
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_icpswap_body_success() {
+        let json = br#"{"code":0,"message":null,"data":{"tokenLedgerId":"ryjl3-tyaaa-aaaaa-aaaba-cai","tokenName":"x","tokenSymbol":"X","price":"1.25","priceChange24H":"-2.5","tvlUSD":"0","tvlUSDChange24H":"0","txCount24H":"0","volumeUSD24H":"0","volumeUSD7D":"0","totalVolumeUSD":"0","priceLow24H":"0","priceHigh24H":"0","priceLow7D":"0","priceHigh7D":"0","priceLow30D":"0","priceHigh30D":"0"}}"#;
+        let parsed: IcpSwapEnvelope = serde_json::from_slice(json).unwrap();
+        let d = exchange_data_from_icpswap_envelope(parsed, 99).unwrap();
+        assert_eq!(d.timestamp_ns, 99);
+        assert_eq!(d.price, Some(1.25));
+        assert_eq!(d.price_24h_change_pct, Some(-2.5));
+    }
+
+    #[test]
+    fn parse_icpswap_body_rejects_nonzero_code() {
+        let json = br#"{"code":404,"message":"not found","data":null}"#;
+        let parsed: IcpSwapEnvelope = serde_json::from_slice(json).unwrap();
+        assert!(exchange_data_from_icpswap_envelope(parsed, 0).is_none());
+    }
+
+    #[test]
+    fn parse_icpswap_body_filters_non_finite_price_change() {
+        let json =
+            br#"{"code":0,"data":{"tokenLedgerId":"x","price":"1.0","priceChange24H":"NaN"}}"#;
+        let parsed: IcpSwapEnvelope = serde_json::from_slice(json).unwrap();
+        let d = exchange_data_from_icpswap_envelope(parsed, 0).unwrap();
+        assert_eq!(d.price, Some(1.0));
+        assert_eq!(d.price_24h_change_pct, None);
+    }
+
+    #[test]
+    fn parse_icpswap_body_rejects_bad_price() {
+        let json = br#"{"code":0,"data":{"tokenLedgerId":"x","price":"0","priceChange24H":"0"}}"#;
+        let parsed: IcpSwapEnvelope = serde_json::from_slice(json).unwrap();
+        assert!(exchange_data_from_icpswap_envelope(parsed, 0).is_none());
+    }
+}
diff --git a/src/backend/src/exchange/providers/mod.rs b/src/backend/src/exchange/providers/mod.rs
@@ -1 +1,2 @@
 pub(crate) mod coingecko;
+pub(crate) mod icpswap;
diff --git a/src/backend/src/exchange/supplemental.rs b/src/backend/src/exchange/supplemental.rs

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`	`1`	`pub(crate) mod coingecko;`
	`2`	`+pub(crate) mod icpswap;`