feat: Implement Real-time External Crypto Price Oracle Connector

[Ugasutun]

Closes #414

Pull Request Description

Title

[Backend] Real-time External Crypto Price Oracle Connector

Issue Reference

#414

Description

Implements a real-time crypto price oracle connector that normalizes portfolio values to USD using CoinGecko API with intelligent caching to prevent rate limiting.

Background & Context

Nestera aggregates net worth into a unified "USD" figure. Summing 1,000 XLM and 1,000 USDC directly is mathematically useless without normalization. This PR combines Soroban ledger stats with CoinGecko pulling in real-time fiat prices for conversion math.

Changes Made

1. Enhanced oracle.service.ts (backend/src/modules/blockchain/oracle.service.ts)

• Added direct axios import alongside NestJS HttpService for fallback API calls
• Implemented @nestjs/cache-manager with 5-minute TTL (300000ms) to prevent CoinGecko API rate limiting
• Added fallback prices for resilience:
  • stellar (XLM): $0.12
  • aqua (AQUA): $0.25
  • usd-coin (USDC): $1.0
• Implemented dual HTTP client strategy: tries HttpService first, falls back to direct axios if needed
• Added new getAllPrices() method for batch price fetching
• Methods:
  • getXLMPrice() - Fetch XLM price in USD
  • getAQUAPrice() - Fetch AQUA price in USD
  • convertXLMToUsd() - Convert XLM amount to USD
  • convertAQUAToUsd() - Convert AQUA amount to USD
  • convertStroopsToUsd() - Convert stroops (smallest XLM unit) to USD
  • getAssetPrices() - Fetch prices for multiple assets

2. Updated analytics.service.ts (backend/src/modules/analytics/analytics.service.ts)

• Modified getPortfolioTimeline() to return both native value and normalized USD value:
  • value: Native XLM amount
  • valueUsd: Normalized USD value
• Uses XLM price from oracle for historical timeline conversion

3. Updated analytics.module.ts (backend/src/modules/analytics/analytics.module.ts)

• Added BlockchainModule import to provide access to OracleService for USD conversion

Acceptance Criteria ✅

• Implement oracle.service.ts relying on axios performing simple REST queries to fetch $XLM, $AQUA USD prices
• Implement heavy logic explicitly utilizing @nestjs/cache-manager to ensure we do NOT rate-limit against the public Oracle APIs (Cache TTL: 5-minutes)
• Inject a conversion layer onto all /analytics responses returning normalized USD decimals
• Target Files: backend/src/modules/blockchain/oracle.service.ts

Technical Details

• API Used: CoinGecko API (https://api.coingecko.com/api/v3)
• Cache TTL: 300,000ms (5 minutes)
• Asset IDs: stellar (XLM), aqua (AQUA), usd-coin (USDC)
• Dependencies: axios, @nestjs/cache-manager, cache-manager

Testing

• TypeScript build completed successfully
• No compilation errors

Related Files

• backend/src/modules/blockchain/oracle.service.ts
• backend/src/modules/analytics/analytics.service.ts
• backend/src/modules/analytics/analytics.module.ts
• backend/src/modules/blockchain/blockchain.module.ts (exports OracleService)

Breaking Changes

None - this is a backward-compatible enhancement that adds USD normalization to existing responses.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nestera	Ready	Preview, Comment	Mar 27, 2026 9:46pm

[drips-wave]

@Ugasutun Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits