feat: prioritize Jupiter Price API V3 for token price fetching with fallbacks

[Hebx]

Prioritized Token Price Fetching with Jupiter Price API V3

Description

This PR implements a prioritized price fetching system for wallet token holdings, prioritizing Jupiter's Price API V3 for real-time Solana token prices, with intelligent fallbacks to CoinGecko and Birdeye APIs.

Type of Change

• New feature (non-breaking change which adds functionality)
• Enhancement (improves existing functionality)

What's Changed

🚀 New Features

1. Jupiter Price API V3 Integration

• Batch Price Fetching: Implemented fetchTokenPricesFromJupiter() to fetch prices for multiple tokens in a single API call
• Dedicated Price Endpoint: Uses Jupiter's dedicated /price/v3 endpoint instead of swap quote API
  • Lite tier: https://lite-api.jup.ag/price/v3 (no API key required)
  • Pro tier: https://api.jup.ag/price/v3 (with API key)
• Efficient: Reduces API calls from N (one per token) to 1 (batch request)

2. Prioritized Fallback Chain

Implemented intelligent fallback system with three tiers:

1. Jupiter Price API V3 (Priority 1) - Real-time DEX prices, most accurate for Solana tokens
2. CoinGecko API (Priority 2) - Reliable fallback for tokens Jupiter doesn't have
3. Birdeye API (Priority 3) - Final fallback for remaining tokens

3. Arbitrary Token Support

• Extended price fetching beyond SOL to support all SPL tokens
• Added fetchTokenPriceFromCoinGecko() for arbitrary Solana tokens
• Special handling for SOL (uses CoinGecko ID-based API)

🔧 Improvements

Enhanced Logging

• Detailed logging at each step of the price fetching process
• Tracks which tokens are found/missing at each fallback tier
• Logs API responses and errors for debugging
• Clear indicators of which price source was used for each token

Better Error Handling

• Graceful handling when Jupiter doesn't have prices (expected for low-liquidity/new tokens)
• Proper error handling for rate limits (Birdeye 429 errors)
• Fallback to hardcoded prices for stablecoins (USDC, USDT)

Response Format Fix

• Fixed Jupiter Price API V3 response parsing
  • Response is directly the data object (not wrapped in { data: {...} })
  • Price field is usdPrice (not price)

Technical Details

API Endpoints Used

1. Jupiter Price API V3

   • Endpoint: GET /price/v3?ids=token1,token2,token3
   • Response: { [mintAddress]: { usdPrice: number, blockId: number, decimals: number, priceChange24h: number } }
   • Reference: Jupiter Price API V3 Docs

2. CoinGecko API

   • Endpoint: GET /api/v3/simple/token_price/solana?contract_addresses={address}&vs_currencies=usd
   • Special case: SOL uses ID-based endpoint (/simple/price?ids=solana)

3. Birdeye API (existing, unchanged)

   • Endpoint: GET /defi/v3/token/market-data/multiple?list_address={addresses}

Performance Improvements

• Before: N API calls (one per token) to Birdeye
• After: 1 batch call to Jupiter + fallbacks only for missing tokens
• Result: Faster price fetching, especially for wallets with many tokens

Why Jupiter First?

1. Real-time accuracy: Prices derived from actual DEX swap transactions
2. Solana-native: Optimized for Solana ecosystem tokens
3. Efficient: Batch API supports multiple tokens in one request
4. Free tier available: No API key required for basic usage

Fallback Rationale

• CoinGecko: Reliable for established tokens, good coverage
• Birdeye: Comprehensive Solana token coverage, but rate-limited
• Hardcoded: Stablecoins (USDC, USDT) always ~$1.00

Testing

Tested Scenarios

✅ SOL price fetching (Jupiter → CoinGecko fallback)
✅ USDC price fetching (Jupiter → hardcoded fallback)
✅ Multiple tokens batch request
✅ Tokens not in Jupiter (fallback to CoinGecko/Birdeye)
✅ Rate-limited Birdeye (graceful degradation)
✅ Response format parsing (usdPrice field)

Breaking Changes

None - this is a non-breaking enhancement. Existing functionality remains unchanged, with improved price accuracy and performance.

Migration Notes

No migration required. The changes are backward compatible and automatically improve price fetching for all wallet holdings.

---

Note

Prioritizes Jupiter Price API V3 for wallet pricing with batch requests and fallbacks to CoinGecko/Birdeye, adds tests, improves env handling, and streamlines CI/CD and release tagging with version bumps.

• Backend (wallet pricing):
  • Jupiter Price API V3 integration: Batch fetch via price/v3 with fetchTokenPricesFromJupiter and single-token wrappers; supports arbitrary SPL tokens and SOL.
  • Prioritized fallbacks: Jupiter → CoinGecko → Birdeye, plus stablecoin hardcoded prices; stricter price validation and detailed logging.
  • Route updates: Refactor apps/server/src/routes/wallet/holdings.ts to use new pricing flow and enrich holdings.
  • Env handling: Load .env without overriding CI vars in apps/server/src/server.ts and src/lib/supabase.ts, with clearer missing-var errors.
  • Tests: Add unit/integration tests for Jupiter Price API V3 and fallback logic in __tests__/jupiter-price-api-v3.test.ts and __tests__/holdings-price-fallback.test.ts.
• CI/CD:
  • Deploy: Simplify Vercel production deploy to a single npx vercel deploy step in .github/workflows/deploy-vercel-production.yml.
  • Release (Changesets): Gate tag creation on CHANGELOG.md updates; create tag to trigger Vercel deploy and GitHub release.
  • Release: Use tag as release name in .github/workflows/release.yml.
  • Tests workflow: Add secret validation, set GRID_ENV, improve server health checks, and artifact uploads.
• Versioning:
  • Bump versions to 0.1.1 and add CHANGELOGs for apps/client, apps/server, and packages/shared.

^{Written by Cursor Bugbot for commit 5332a2a. This will update automatically on new commits. Configure here.}

[github-actions]

✅ Changeset Detected

Thanks for adding a changeset! This change will be included in the next release.

[cursor]

This PR is being reviewed by Cursor Bugbot

Details

You are on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.