dexpaprika-sdk 0.2.0__py3-none-any.whl

dexpaprika_sdk/__init__.py

@@ -0,0 +1,34 @@
+"""
+DexPaprika SDK for Python
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A Python client library for the DexPaprika API,
+providing access to token, pool, and DEX data
+across multiple blockchain networks.
+
+:copyright: (c) 2024 CoinPaprika
+:license: MIT, see LICENSE for more details.
+"""
+
+from .client import DexPaprikaClient
+# Import models for easier access
+from .models import (
+    Network, Dex, DexesResponse,
+    Token, Pool, PoolsResponse, TimeIntervalMetrics,
+    PoolDetails, OHLCVRecord, Transaction, TransactionsResponse,
+    TokenSummary, TokenDetails,
+    DexInfo, SearchResult,
+    Stats
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "DexPaprikaClient",
+    # Models
+    "Network", "Dex", "DexesResponse",
+    "Token", "Pool", "PoolsResponse", "TimeIntervalMetrics",
+    "PoolDetails", "OHLCVRecord", "Transaction", "TransactionsResponse",
+    "TokenSummary", "TokenDetails",
+    "DexInfo", "SearchResult",
+    "Stats"
+]

dexpaprika_sdk/api/__init__.py

@@ -0,0 +1,15 @@
+from .base import BaseAPI
+from .networks import NetworksAPI
+from .pools import PoolsAPI
+from .tokens import TokensAPI
+from .search import SearchAPI
+from .utils import UtilsAPI
+
+__all__ = [
+    "BaseAPI",
+    "NetworksAPI",
+    "PoolsAPI",
+    "TokensAPI",
+    "SearchAPI",
+    "UtilsAPI",
+]

dexpaprika_sdk/api/base.py

@@ -0,0 +1,225 @@
+from typing import Any, Dict, List, Optional, Union, TYPE_CHECKING, Callable, TypeVar, Set
+import hashlib
+import json
+from datetime import datetime, timedelta
+
+if TYPE_CHECKING:
+    from ..client import DexPaprikaClient
+
+T = TypeVar('T')
+
+class CacheEntry:
+    """Class representing a cached response with an expiration time."""
+    
+    def __init__(self, data: Any, expires_at: Optional[datetime] = None):
+        """
+        Initialize a new cache entry.
+        
+        Args:
+            data: The data to cache
+            expires_at: The time when the cache entry expires
+        """
+        self.data = data
+        self.expires_at = expires_at
+        
+    def is_expired(self) -> bool:
+        """
+        Check if the cache entry has expired.
+        
+        Returns:
+            True if the cache entry has expired, False otherwise
+        """
+        return self.expires_at is not None and datetime.now() > self.expires_at
+
+
+class BaseAPI:
+    """Base class for all API service classes."""
+
+    def __init__(self, client: "DexPaprikaClient"):
+        """
+        Initialize a new API service.
+
+        Args:
+            client: The DexPaprika client instance
+        """
+        self.client = client
+        self._cache: Dict[str, CacheEntry] = {}  # TTL-based cache
+        
+        # Default TTLs for different types of data
+        self._cache_ttls = {
+            "networks": timedelta(hours=24),  # Network list rarely changes
+            "pools": timedelta(minutes=5),    # Pool data changes frequently
+            "tokens": timedelta(minutes=10),  # Token data changes moderately
+            "stats": timedelta(minutes=15),   # Stats change moderately
+            "default": timedelta(minutes=5)   # Default TTL for other endpoints
+        }
+    
+    def _get_cache_key(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> str:
+        """
+        Generate a unique cache key for the request.
+        
+        Args:
+            endpoint: API endpoint
+            params: Query parameters
+            
+        Returns:
+            A unique cache key as a string
+        """
+        key_parts = [endpoint]
+        if params:
+            # Sort params to ensure consistent keys
+            sorted_params = json.dumps(params, sort_keys=True)
+            key_parts.append(sorted_params)
+        
+        key_string = ":".join(key_parts)
+        return hashlib.md5(key_string.encode()).hexdigest()
+    
+    def _get_ttl(self, endpoint: str) -> timedelta:
+        """
+        Get the TTL for a specific endpoint.
+        
+        Args:
+            endpoint: API endpoint
+            
+        Returns:
+            The TTL as a timedelta
+        """
+        for key, ttl in self._cache_ttls.items():
+            if key in endpoint:
+                return ttl
+        return self._cache_ttls["default"]
+    
+    def _get(
+        self, 
+        endpoint: str, 
+        params: Optional[Dict[str, Any]] = None,
+        skip_cache: bool = False,
+        ttl: Optional[timedelta] = None
+    ) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+        """
+        Make a GET request to the specified endpoint.
+
+        Args:
+            endpoint: API endpoint (e.g., "/networks")
+            params: Query parameters
+            skip_cache: Whether to skip the cache and force a fresh request
+            ttl: Custom TTL for this request
+
+        Returns:
+            Response data as a dictionary or list
+        """
+        if skip_cache:
+            return self.client.get(endpoint, params=params)
+            
+        cache_key = self._get_cache_key(endpoint, params)
+        cache_entry = self._cache.get(cache_key)
+        
+        # Return cached data if valid
+        if cache_entry and not cache_entry.is_expired():
+            return cache_entry.data
+            
+        # Get fresh data
+        result = self.client.get(endpoint, params=params)
+        
+        # Cache the result with appropriate TTL
+        if ttl is None:
+            ttl = self._get_ttl(endpoint)
+            
+        expires_at = datetime.now() + ttl
+        self._cache[cache_key] = CacheEntry(result, expires_at)
+            
+        return result
+    
+    def _post(self, endpoint: str, data: Dict[str, Any], params: Optional[Dict[str, Any]] = None) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+        """
+        Make a POST request to the specified endpoint.
+
+        Args:
+            endpoint: API endpoint
+            data: Request body
+            params: Query parameters
+
+        Returns:
+            Response data as a dictionary or list
+        """
+        return self.client.post(endpoint, data=data, params=params)
+        
+    def _clean_params(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Clean None values from params."""
+        return {k: v for k, v in params.items() if v is not None}
+    
+    def _validate_required(self, param_name: str, value: Any) -> None:
+        """
+        Validate that a parameter is not None or empty.
+        
+        Args:
+            param_name: Name of the parameter for error messages
+            value: Value to validate
+            
+        Raises:
+            ValueError: If the value is None or empty
+        """
+        if value is None or (isinstance(value, str) and value.strip() == ""):
+            raise ValueError(f"{param_name} is required")
+    
+    def _validate_enum(self, param_name: str, value: str, valid_values: Set[str]) -> None:
+        """
+        Validate that a parameter is one of a set of valid values.
+        
+        Args:
+            param_name: Name of the parameter for error messages
+            value: Value to validate
+            valid_values: Set of valid values
+            
+        Raises:
+            ValueError: If the value is not one of the valid values
+        """
+        if value is None:
+            return
+            
+        if value not in valid_values:
+            raise ValueError(f"{param_name} must be one of: {', '.join(sorted(valid_values))}")
+    
+    def _validate_range(self, param_name: str, value: Union[int, float], min_val: Optional[Union[int, float]] = None, max_val: Optional[Union[int, float]] = None) -> None:
+        """
+        Validate that a numeric parameter is within a specified range.
+        
+        Args:
+            param_name: Name of the parameter for error messages
+            value: Value to validate
+            min_val: Minimum allowed value (inclusive)
+            max_val: Maximum allowed value (inclusive)
+            
+        Raises:
+            ValueError: If the value is outside the specified range
+        """
+        if value is None:
+            return
+            
+        if min_val is not None and value < min_val:
+            raise ValueError(f"{param_name} must be at least {min_val}")
+            
+        if max_val is not None and value > max_val:
+            raise ValueError(f"{param_name} must be at most {max_val}")
+    
+    def clear_cache(self, endpoint_prefix: Optional[str] = None) -> None:
+        """
+        Clear the cache, optionally only for endpoints with a specific prefix.
+        
+        Args:
+            endpoint_prefix: Optional prefix to filter which cache entries to clear
+        """
+        if endpoint_prefix:
+            # Get cache keys from the original endpoints that contain the prefix
+            keys_to_remove = []
+            for key in list(self._cache.keys()):
+                cache_entry = self._cache[key]
+                if endpoint_prefix in key:
+                    keys_to_remove.append(key)
+                    
+            # Remove the entries
+            for key in keys_to_remove:
+                del self._cache[key]
+        else:
+            # Clear the entire cache
+            self._cache.clear() 

dexpaprika_sdk/api/dexes.py

@@ -0,0 +1,35 @@
+from typing import Optional
+
+from .base import BaseAPI
+from ..models.networks import DexesResponse
+
+
+class DexesAPI(BaseAPI):
+    """API service for DEX-related endpoints."""
+    
+    def list(self, network: str, page: int = 0, limit: int = 10) -> DexesResponse:
+        """
+        Get a list of available decentralized exchanges on a specific network.
+        
+        Args:
+            network: Network ID (e.g., "ethereum", "solana")
+            page: Page number for pagination
+            limit: Number of items per page
+            
+        Returns:
+            Response containing list of DEXes
+            
+        Raises:
+            ValueError: If any parameter is invalid
+        """
+        # Validate parameters
+        self._validate_required("network", network)
+        self._validate_range("page", page, min_val=0)
+        self._validate_range("limit", limit, min_val=1, max_val=100)
+        
+        params = {
+            "page": page,
+            "limit": limit
+        }
+        data = self._get(f"/networks/{network}/dexes", params=params)
+        return DexesResponse(**data) 

dexpaprika_sdk/api/networks.py

@@ -0,0 +1,45 @@
+from typing import List, Optional, Set
+
+from .base import BaseAPI
+from ..models.networks import Network, DexesResponse
+
+
+class NetworksAPI(BaseAPI):
+    """API service for network-related endpoints."""
+    
+    def list(self) -> List[Network]:
+        """
+        Retrieve a list of all supported blockchain networks.
+        
+        Returns:
+            List of Network objects
+        """
+        data = self._get("/networks")
+        return [Network(**item) for item in data]
+    
+    def list_dexes(self, network_id: str, page: int = 0, limit: int = 10) -> DexesResponse:
+        """
+        Get a list of all available dexes on a specific network.
+        
+        Args:
+            network_id: Network ID (e.g., "ethereum", "solana")
+            page: Page number for pagination
+            limit: Number of items per page
+            
+        Returns:
+            Response containing a list of DEXes
+            
+        Raises:
+            ValueError: If any parameter is invalid
+        """
+        # Validate parameters
+        self._validate_required("network_id", network_id)
+        self._validate_range("page", page, min_val=0)
+        self._validate_range("limit", limit, min_val=1, max_val=100)
+        
+        params = {
+            "page": page,
+            "limit": limit,
+        }
+        data = self._get(f"/networks/{network_id}/dexes", params=params)
+        return DexesResponse(**data) 

dexpaprika_sdk/api/pools.py

@@ -0,0 +1,251 @@
+from typing import List, Optional, Dict, Any, Set
+
+from .base import BaseAPI
+from ..models.pools import (
+    PoolsResponse, PoolDetails, OHLCVRecord, TransactionsResponse
+)
+
+
+class PoolsAPI(BaseAPI):
+    """API service for pool-related endpoints."""
+    
+    # Valid values for common parameters
+    VALID_SORT_VALUES: Set[str] = {"asc", "desc"}
+    VALID_ORDER_BY_VALUES: Set[str] = {"volume_usd", "price_usd", "transactions", "last_price_change_usd_24h", "created_at"}
+    VALID_INTERVAL_VALUES: Set[str] = {"1m", "5m", "10m", "15m", "30m", "1h", "6h", "12h", "24h"}
+    
+    def list(
+        self, 
+        page: int = 0, 
+        limit: int = 10, 
+        sort: str = "desc", 
+        order_by: str = "volume_usd"
+    ) -> PoolsResponse:
+        """
+        Get a list of top pools across all networks.
+        
+        Args:
+            page: Page number for pagination
+            limit: Number of items per page
+            sort: Sort order ("asc" or "desc")
+            order_by: Field to order by ("volume_usd", "price_usd", etc.)
+            
+        Returns:
+            Response containing a list of pools
+            
+        Raises:
+            ValueError: If any parameter is invalid
+        """
+        # Validate parameters
+        self._validate_range("page", page, min_val=0)
+        self._validate_range("limit", limit, min_val=1, max_val=100)
+        self._validate_enum("sort", sort, self.VALID_SORT_VALUES)
+        self._validate_enum("order_by", order_by, self.VALID_ORDER_BY_VALUES)
+        
+        # Get top pools
+        params = {"page": page, "limit": limit, "sort": sort, "order_by": order_by}
+        data = self._get("/pools", params=params)
+        
+        # ensure pools exists
+        if 'pools' not in data: data['pools'] = []
+            
+        return PoolsResponse(**data)
+    
+    def list_by_network(
+        self, 
+        network_id: str, 
+        page: int = 0, 
+        limit: int = 10, 
+        sort: str = "desc", 
+        order_by: str = "volume_usd"
+    ) -> PoolsResponse:
+        """
+        Get a list of pools on a specific network.
+        
+        Args:
+            network_id: Network ID (e.g., "ethereum", "solana")
+            page: Page number for pagination
+            limit: Number of items per page
+            sort: Sort order ("asc" or "desc")
+            order_by: Field to order by ("volume_usd", "price_usd", etc.)
+            
+        Returns:
+            Response containing a list of pools
+            
+        Raises:
+            ValueError: If any parameter is invalid
+        """
+        # Validate parameters
+        self._validate_required("network_id", network_id)
+        self._validate_range("page", page, min_val=0)
+        self._validate_range("limit", limit, min_val=1, max_val=100)
+        self._validate_enum("sort", sort, self.VALID_SORT_VALUES)
+        self._validate_enum("order_by", order_by, self.VALID_ORDER_BY_VALUES)
+        
+        # Get network pools
+        params = {"page": page, "limit": limit, "sort": sort, "order_by": order_by}
+        data = self._get(f"/networks/{network_id}/pools", params=params)
+        
+        # ensure pools exists
+        if 'pools' not in data: data['pools'] = []
+            
+        return PoolsResponse(**data)
+    
+    def list_by_dex(
+        self, 
+        network_id: str, 
+        dex_id: str, 
+        page: int = 0, 
+        limit: int = 10, 
+        sort: str = "desc", 
+        order_by: str = "volume_usd"
+    ) -> PoolsResponse:
+        """
+        Get a list of pools for a specific DEX on a network.
+        
+        Args:
+            network_id: Network ID (e.g., "ethereum", "solana")
+            dex_id: DEX ID (e.g., "uniswap_v3")
+            page: Page number for pagination
+            limit: Number of items per page
+            sort: Sort order ("asc" or "desc")
+            order_by: Field to order by ("volume_usd", "price_usd", etc.)
+            
+        Returns:
+            Response containing a list of pools
+            
+        Raises:
+            ValueError: If any parameter is invalid
+        """
+        # Validate parameters
+        self._validate_required("network_id", network_id)
+        self._validate_required("dex_id", dex_id)
+        self._validate_range("page", page, min_val=0)
+        self._validate_range("limit", limit, min_val=1, max_val=100)
+        self._validate_enum("sort", sort, self.VALID_SORT_VALUES)
+        self._validate_enum("order_by", order_by, self.VALID_ORDER_BY_VALUES)
+        
+        # Get dex pools
+        params = {"page": page, "limit": limit, "sort": sort, "order_by": order_by}
+        data = self._get(f"/networks/{network_id}/dexes/{dex_id}/pools", params=params)
+        
+        # ensure pools exists
+        if 'pools' not in data: data['pools'] = []
+            
+        return PoolsResponse(**data)
+    
+    def get_details(
+        self, 
+        network_id: str, 
+        pool_address: str, 
+        inversed: bool = False
+    ) -> PoolDetails:
+        """
+        Get detailed information about a specific pool.
+        
+        Args:
+            network_id: Network ID (e.g., "ethereum", "solana")
+            pool_address: Pool address or identifier
+            inversed: Whether to invert the price ratio
+            
+        Returns:
+            Detailed pool information
+            
+        Raises:
+            ValueError: If any parameter is invalid
+        """
+        # Validate parameters
+        self._validate_required("network_id", network_id)
+        self._validate_required("pool_address", pool_address)
+        
+        # Get pool details
+        params = {"inversed": "true" if inversed else None}
+        params = self._clean_params(params)
+        
+        data = self._get(f"/networks/{network_id}/pools/{pool_address}", params=params)
+        return PoolDetails(**data)
+    
+    def get_ohlcv(
+        self, 
+        network_id: str, 
+        pool_address: str, 
+        start: str, 
+        end: Optional[str] = None, 
+        limit: int = 1, 
+        interval: str = "24h", 
+        inversed: bool = False
+    ) -> List[OHLCVRecord]:
+        """
+        Get OHLCV (Open-High-Low-Close-Volume) data for a specific pool.
+        
+        Args:
+            network_id: Network ID (e.g., "ethereum", "solana")
+            pool_address: Pool address or identifier
+            start: Start time for historical data (ISO-8601, yyyy-mm-dd, or Unix timestamp)
+            end: End time for historical data (max 1 year from start)
+            limit: Number of data points to retrieve (max 366)
+            interval: Interval granularity for OHLCV data (1m, 5m, 10m, 15m, 30m, 1h, 6h, 12h, 24h)
+            inversed: Whether to invert the price ratio in OHLCV calculations
+            
+        Returns:
+            List of OHLCV records
+            
+        Raises:
+            ValueError: If any parameter is invalid
+        """
+        # Validate parameters
+        self._validate_required("network_id", network_id)
+        self._validate_required("pool_address", pool_address)
+        self._validate_required("start", start)
+        self._validate_range("limit", limit, min_val=1, max_val=366)
+        self._validate_enum("interval", interval, self.VALID_INTERVAL_VALUES)
+        
+        # Get price history
+        params = {
+            "start": start,
+            "end": end,
+            "limit": limit,
+            "interval": interval,
+            "inversed": "true" if inversed else None,
+        }
+        params = self._clean_params(params)
+        
+        data = self._get(f"/networks/{network_id}/pools/{pool_address}/ohlcv", params=params)
+        return [OHLCVRecord(**item) for item in data]
+    
+    def get_transactions(
+        self, 
+        network_id: str, 
+        pool_address: str, 
+        page: int = 0, 
+        limit: int = 10, 
+        cursor: Optional[str] = None
+    ) -> TransactionsResponse:
+        """
+        Get transactions of a pool on a network.
+        
+        Args:
+            network_id: Network ID (e.g., "ethereum", "solana")
+            pool_address: Pool address or identifier
+            page: Page number for pagination
+            limit: Number of items per page
+            cursor: Transaction ID used for cursor-based pagination
+            
+        Returns:
+            Response containing a list of transactions
+            
+        Raises:
+            ValueError: If any parameter is invalid
+        """
+        # Validate parameters
+        self._validate_required("network_id", network_id)
+        self._validate_required("pool_address", pool_address)
+        self._validate_range("page", page, min_val=0)
+        self._validate_range("limit", limit, min_val=1, max_val=100)
+        
+        # Get txs
+        params = {"page": page, "limit": limit, "cursor": cursor}
+        params = self._clean_params(params)
+        
+        data = self._get(f"/networks/{network_id}/pools/{pool_address}/transactions", params=params)
+        return TransactionsResponse(**data) 

dexpaprika_sdk/api/search.py

@@ -0,0 +1,28 @@
+from urllib.parse import quote
+
+from .base import BaseAPI
+from ..models.search import SearchResult
+
+
+class SearchAPI(BaseAPI):
+    """API service for search-related endpoints."""
+    
+    def search(self, query: str) -> SearchResult:
+        """
+        Search for tokens, pools, and DEXes by name or identifier.
+        
+        Args:
+            query: Search term (e.g., "uniswap", "bitcoin", or a token address)
+            
+        Returns:
+            Search results across tokens, pools, and DEXes
+            
+        Raises:
+            ValueError: If the query parameter is invalid
+        """
+        # Validate parameters
+        self._validate_required("query", query)
+        
+        params = {"query": query}
+        data = self._get("/search", params=params)
+        return SearchResult(**data)