feat: optimize SOL price API and integrate through main TokenAPI

- Optimize SOL price calculation with smart caching and auto-tuning
- Add volatility-based TTL (1min volatile, 5min stable markets)
- Implement progressive retry with parameter auto-adjustment
- Add IQR outlier filtering and confidence scoring
- Consolidate from 4 methods to 1 smart method
- Remove direct SVMTokenAPI exposure, integrate via main TokenAPI
- Add comprehensive examples demonstrating optimized functionality
- Update all tests for new optimized API (250 tests passing, 96% coverage)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: codebydivine

examples/endpoints/svm/sol_price.py

@@ -0,0 +1,156 @@
+"""
+Example: Optimized SOL price calculation with smart SVM API.
+
+This example demonstrates the new optimized SOL price functionality:
+1. Super simple price retrieval with smart defaults
+2. Detailed statistics with confidence scoring
+3. Automatic caching with volatility-based TTL
+4. Zero-config usage - just works!
+"""
+
+import asyncio
+import os
+import sys
+import time
+from datetime import datetime
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))))
+
+from dotenv import load_dotenv
+
+from thegraph_token_api import SwapPrograms, TokenAPI
+
+# Load environment variables
+load_dotenv()
+
+
+async def example_simple_usage():
+    """Example: Super simple SOL price - just one line!"""
+    print("\n=== ✨ Optimized Simple Usage ===")
+
+    api_key = os.getenv("THEGRAPH_API_KEY")
+    if not api_key:
+        print("Error: THEGRAPH_API_KEY not found in environment")
+        return
+
+    api = TokenAPI(api_key=api_key)
+    # One line to get SOL price - that's it!
+    price = await api.svm.get_sol_price()
+
+    if price:
+        print(f"💰 Current SOL price: ${price:.2f}")
+        print("✅ Auto-cached with smart TTL based on volatility")
+        print("⚡ Smart retry logic with progressive sampling")
+        print("🎯 Automatic outlier filtering using IQR method")
+    else:
+        print("❌ Failed to get SOL price")
+
+
+async def example_with_confidence():
+    """Example: Get SOL price with confidence and stats."""
+    print("\n=== 📊 Price with Intelligence ===")
+
+    api_key = os.getenv("THEGRAPH_API_KEY")
+    if not api_key:
+        print("Error: THEGRAPH_API_KEY not found in environment")
+        return
+
+    api = TokenAPI(api_key=api_key)
+    # Get detailed stats with one parameter
+    stats = await api.svm.get_sol_price(include_stats=True)
+
+    if stats and stats.get("price"):
+        print(f"💰 Price: ${stats['price']:.2f}")
+        print(f"📈 Confidence: {stats['confidence']:.0%}")
+        print(f"📊 Trades analyzed: {stats['trades_analyzed']}")
+        print(f"📉 Volatility: {stats['std_deviation']:.2f}")
+        print(f"⏰ Data age: {datetime.now().timestamp() - stats['timestamp']:.0f}s")
+
+        # Show confidence interpretation
+        conf = stats["confidence"]
+        if conf >= 0.8:
+            print("🟢 High confidence - excellent data quality")
+        elif conf >= 0.5:
+            print("🟡 Medium confidence - good data quality")
+        else:
+            print("🟠 Low confidence - limited data available")
+    else:
+        print("❌ No price data available")
+
+
+async def example_cached_performance():
+    """Example: Show smart caching in action."""
+    print("\n=== ⚡ Smart Caching Demo ===")
+
+    api_key = os.getenv("THEGRAPH_API_KEY")
+    if not api_key:
+        print("Error: THEGRAPH_API_KEY not found in environment")
+        return
+
+    api = TokenAPI(api_key=api_key)
+
+    # First call - fetches from API
+    start = time.time()
+    price1 = await api.svm.get_sol_price()
+    time1 = time.time() - start
+
+    # Second call - uses smart cache
+    start = time.time()
+    price2 = await api.svm.get_sol_price()
+    time2 = time.time() - start
+
+    print(f"🌐 First call (API): ${price1:.2f} - took {time1:.2f}s")
+    print(f"⚡ Second call (cache): ${price2:.2f} - took {time2:.3f}s")
+    print(f"🚀 Speedup: {time1 / time2:.0f}x faster!")
+
+    # Show cache intelligence
+    stats = await api.svm.get_sol_price(include_stats=True)
+    if stats:
+        volatility = stats["std_deviation"] / stats["price"]
+        ttl = 60 if volatility > 0.05 else 300
+        print(f"🧠 Smart TTL: {ttl}s (based on {volatility:.1%} volatility)")
+
+
+async def example_integration():
+    """Example: Show how it integrates seamlessly with other SVM functions."""
+    print("\n=== 🔗 Seamless Integration ===")
+
+    api_key = os.getenv("THEGRAPH_API_KEY")
+    if not api_key:
+        print("Error: THEGRAPH_API_KEY not found in environment")
+        return
+
+    api = TokenAPI(api_key=api_key)
+    # All in one API session - share connections efficiently
+
+    # Get current SOL price
+    sol_price = await api.svm.get_sol_price()
+
+    # Get recent Jupiter swaps
+    swaps = await api.svm.swaps(program_id=SwapPrograms.JUPITER_V6, limit=3)
+
+    # Get SOL balance example (if you have a token account)
+    # balances = await api.svm.balances(mint="So11111111111111111111111111111111111111112")
+
+    if sol_price:
+        print(f"💰 Current SOL price: ${sol_price:.2f}")
+
+    if swaps:
+        print(f"📋 Recent Jupiter swaps: {len(swaps)}")
+        if len(swaps) > 0:
+            latest = swaps[0]
+            print(f"   Latest: {getattr(latest, 'datetime', 'N/A')}")
+
+    print("🎯 All data fetched in same session with optimized connections!")
+
+
+async def main():
+    """Run all examples."""
+    await example_simple_usage()
+    await example_with_confidence()
+    await example_cached_performance()
+    await example_integration()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/thegraph_token_api/__init__.py

@@ -22,6 +22,7 @@ async def main():
         # SVM (Solana)
         sol_balances = await api.svm.balances(mint="So11111111111111111111111111111111111111112")
         sol_swaps = await api.svm.swaps(program_id=SwapPrograms.RAYDIUM, limit=5)
+        sol_price = await api.svm.get_sol_price()  # Get current SOL price with smart caching
 
         # Utility
         health = await api.health()

src/thegraph_token_api/simple.py

@@ -322,6 +322,40 @@ async def transfers(
         )
         return convert_list_to_models(data, SolanaTransfer)
 
+    async def get_sol_price(
+        self, *, include_stats: bool = False, network: SolanaNetworkId | str = SolanaNetworkId.SOLANA
+    ) -> float | dict[str, Any] | None:
+        """
+        Get current SOL price in USD with smart caching and auto-optimization.
+
+        This method automatically:
+        - Uses optimal trade sampling based on market conditions
+        - Caches results with volatility-based TTL
+        - Handles retries and outlier filtering
+        - Adapts parameters based on data availability
+
+        Args:
+            include_stats: If True, returns detailed statistics instead of just price
+            network: Solana network to use (default: mainnet)
+
+        Returns:
+            float: Current SOL price in USD (if include_stats=False)
+            dict: Price with statistics (if include_stats=True)
+            None: If no valid price data available
+
+        Example:
+            ```python
+            # Simple usage
+            price = await api.svm.get_sol_price()
+            print(f"SOL price: ${price:.2f}")
+
+            # With detailed stats
+            stats = await api.svm.get_sol_price(include_stats=True)
+            print(f"Price: ${stats['price']:.2f} (confidence: {stats['confidence']:.0%})")
+            ```
+        """
+        return await self._api._svm_get_sol_price(include_stats=include_stats, network=network)  # type: ignore[no-any-return]
+
 
 class TokenAPI:
     """
@@ -350,6 +384,7 @@ class TokenAPI:
         sol_balances = await api.svm.balances(mint="So11111111111111111111111111111111111111112")
         sol_swaps = await api.svm.swaps(program_id=SwapPrograms.RAYDIUM, limit=10)
         sol_transfers = await api.svm.transfers(mint="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")  # pragma: allowlist secret
+        sol_price = await api.svm.get_sol_price()  # Get current SOL price
 
         # Utility
         health = await api.health()
@@ -684,6 +719,15 @@ async def _svm_swaps(
             )
             return self._extract_data(response)
 
+    async def _svm_get_sol_price(
+        self,
+        include_stats: bool = False,
+        network: SolanaNetworkId | str = SolanaNetworkId.SOLANA,
+    ) -> float | dict[str, Any] | None:
+        """Internal SVM SOL price implementation."""
+        async with self._api.svm(str(network)) as client:
+            return await client.get_sol_price(include_stats=include_stats)  # type: ignore[no-any-return]
+
     # ===== Utility Methods =====
 
     async def version(self) -> list[dict[Any, Any]]: