feat(backend): integrate exchange rate oracle for real-time fiat value conversion

[0xDeon]

Problem

Every page in the dApp that shows vault balances, deposit amounts, or settlement previews needs to display a fiat-equivalent value (USD, NGN, GHS, KES). Right now none of this is wired — the frontend either shows raw USDC amounts with no conversion or hardcodes a mock exchange rate. This becomes especially critical for the offramp flow where the user needs to see exactly how much local currency they will receive before confirming.

What's Needed

A lightweight exchange rate service baked into the Go API that can convert between the assets Nester uses (USDC, XLM) and the fiat currencies supported by the offramp (NGN, GHS, KES, USD).

Suggested Data Sources (in priority order)

1. Stellar DEX / AMM — on-chain USDC/XLM rate via Horizon's /order_book endpoint. Most accurate for Stellar-native assets, no third-party dependency.
2. DeFiLlama prices API — free, no key required. Good fallback.
3. CoinGecko — secondary fallback. Rate-limited on free tier.

For fiat rates (XLM/NGN, USDC/NGN etc.), these should chain through USD as an intermediate: USDC → USD (effectively 1:1) and USD → NGN via a forex API (e.g. ExchangeRate-API, Open Exchange Rates, or a Central Bank API for NGN).

Implementation Plan

New package: apps/api/internal/oracle/

oracle/
  rate.go          // ExchangeRate type, Provider interface
  stellar.go       // Horizon order book source
  defillama.go     // DeFiLlama fallback
  fiat.go          // Forex feed for NGN/GHS/KES
  cache.go         // In-memory TTL cache (30s for crypto, 5min for fiat)
  service.go       // Aggregates sources with fallback logic

New endpoint:

GET /api/v1/rates?base=USDC&quote=NGN
GET /api/v1/rates?base=XLM&quote=USD

Response:

{
  "success": true,
  "data": {
    "base": "USDC",
    "quote": "NGN",
    "rate": 1647.50,
    "source": "horizon+forex",
    "fetched_at": "2026-04-02T12:00:00Z",
    "expires_at": "2026-04-02T12:05:00Z"
  }
}

Wire into existing flows:

• Settlement service: include estimated_local_amount in settlement creation response
• Vault handler: include usd_value on vault balance responses

Caching Strategy

• Crypto rates: 30-second TTL (stale-while-revalidate acceptable)
• Fiat rates: 5-minute TTL
• On source failure: serve stale + set stale: true flag in response, never error the whole request

Acceptance Criteria

• GET /api/v1/rates returns conversion rate for any supported pair
• Rates are cached in-memory and not fetched on every request
• Stale data is served with a warning flag if all sources fail (never a 5xx)
• Settlement response includes estimated_local_amount pre-calculated
• Unit tests for cache logic and fallback chain
• Supported pairs at minimum: USDC→NGN, USDC→GHS, USDC→KES, USDC→USD, XLM→USD

[ifeanyiBatman]

@ifeanyiBatman has applied to work on this issue as part of the Stellar Wave Program's 4th wave.

Hey team 👋🏾, backend Go dev here on the Drips wave. I would love to take ownership of this oracle integration.

My approach will be to define a clean Provider interface in the oracle package to handle the fallback chain seamlessly (Horizon → DeFiLlama → CoinGecko). For the caching layer, I will build a thread-safe in-memory store using sync.RWMutex to handle the 30s crypto / 5m fiat TTLs, ensuring we gracefully degrade to serving stale data with the stale: true flag rather than throwing 5xx errors if upstreams fail.

Once the service is rock solid and unit-tested, I'll wire it into the new GET /api/v1/rates endpoint and inject the fiat conversions into the settlement and vault handlers. Let me know if I can get assigned to this!

ℹ️ Repo Maintainers: To accept this application, review their application or assign @ifeanyiBatman to this issue.

[Mkalbani]

@Mkalbani has applied to work on this issue as part of the Stellar Wave Program's 4th wave.

Hi maintainers, can I work on this. I've worked on a similar work. Thank you.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Mkalbani to this issue.

[Salmatcre8]

@Salmatcre8 has applied to work on this issue as part of the Stellar Wave Program's 4th wave.

Hi! I'd like to work on this issue.
Experience: Go backend development, exchange rate API integration (forex & crypto), caching strategies (TTL, stale-while-revalidate), and financial data pipelines with fallback chains.
Approach:

Package Structure (1 hour)

internal/oracle/
types.go // ExchangeRate, Provider interface
stellar.go // Horizon /order_book integration
defillama.go // DeFiLlama API client
forex.go // ExchangeRate-API for NGN/GHS/KES
cache.go // TTL cache with sync.Map (30s crypto, 5min fiat)
service.go // Fallback orchestrator

Rate Providers (3 hours)

Stellar: Horizon /order_book?selling=USDC&buying=XLM → midpoint price
DeFiLlama: https://coins.llama.fi/prices/current/coingecko:stellar for XLM/USD
Forex: ExchangeRate-API for USD→NGN/GHS/KES (free tier, 1500 req/month)
Chain conversions: USDC→NGN = USDC→USD × USD→NGN
Interface: type Provider interface { FetchRate(base, quote string) (float64, error) }

Cache + Fallback (2 hours)

In-memory cache with expiry timestamps
Fallback chain: Stellar → DeFiLlama → serve stale with stale: true
Never return error if stale data exists (graceful degradation)
Background refresh on cache miss

API Endpoint (1.5 hours)

GET /api/v1/rates?base=USDC&quote=NGN
Validate base/quote pairs (whitelist: USDC, XLM, USD, NGN, GHS, KES)
Response includes source, timestamps, stale flag
Wire into settlement handler: add estimated_local_amount field

Tests (2 hours)

Mock HTTP clients for each provider
Test fallback chain (primary fail → secondary)
Cache hit/miss scenarios
Stale data serving on total failure
Integration test for chained conversions

Timeline: PR ready in 4-5 days
Questions:

Preferred forex API (ExchangeRate-API vs Open Exchange Rates)?
Should rates endpoint require authentication?
Background refresh goroutine or lazy-fetch only?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Salmatcre8 to this issue.

[drips-wave]

Congratulations, @Salmatcre8! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on April 29, 2026.

🧑‍💻 @Salmatcre8: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @Salmatcre8 as part of the Stellar Wave Program's 4th Wave 🥳

😎 @Salmatcre8: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.