dexscreen 0.0.1__py3-none-any.whl

dexscreen/utils/filters.py

@@ -0,0 +1,226 @@
+"""
+Token pair filtering utilities for reducing noise and controlling update frequency
+"""
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from ..core.models import TokenPair
+
+
+@dataclass
+class FilterConfig:
+    """Configuration for token pair filtering"""
+
+    # Change detection fields - which fields to monitor for changes
+    change_fields: list[str] = field(default_factory=lambda: ["price_usd", "price_native", "volume.h24", "liquidity"])
+
+    # Significant change thresholds (None means any change triggers)
+    price_change_threshold: Optional[float] = None  # e.g., 0.01 for 1%
+    volume_change_threshold: Optional[float] = None  # e.g., 0.10 for 10%
+    liquidity_change_threshold: Optional[float] = None  # e.g., 0.05 for 5%
+
+    # Rate limiting
+    max_updates_per_second: Optional[float] = None  # e.g., 1.0 for max 1 update/sec
+
+
+class TokenPairFilter:
+    """Filter for token pair updates based on configuration"""
+
+    def __init__(self, config: Optional[FilterConfig] = None):
+        """
+        Initialize filter with optional configuration.
+        If no config provided, acts as a simple change detector.
+        """
+        self.config = config or FilterConfig()
+        self._cache: dict[str, dict[str, Any]] = {}
+        self._last_update_times: dict[str, float] = {}
+
+    def should_emit(self, key: str, pair: TokenPair) -> bool:
+        """
+        Check if update should be emitted based on filter rules.
+
+        Args:
+            key: Unique identifier for the subscription (e.g., "ethereum:0x...")
+            pair: The token pair data
+
+        Returns:
+            True if update should be emitted, False otherwise
+        """
+        # Check rate limiting first
+        if not self._check_rate_limit(key):
+            return False
+
+        # Check for changes
+        if not self._has_relevant_changes(key, pair):
+            return False
+
+        # Check if changes are significant enough
+        if not self._are_changes_significant(key, pair):
+            return False
+
+        # Update cache and emit
+        self._update_cache(key, pair)
+        return True
+
+    def _check_rate_limit(self, key: str) -> bool:
+        """Check if rate limit allows this update"""
+        if self.config.max_updates_per_second is None:
+            return True
+
+        current_time = time.time()
+        last_update = self._last_update_times.get(key, 0)
+
+        min_interval = 1.0 / self.config.max_updates_per_second
+        if current_time - last_update < min_interval:
+            return False
+
+        self._last_update_times[key] = current_time
+        return True
+
+    def _has_relevant_changes(self, key: str, pair: TokenPair) -> bool:
+        """Check if monitored fields have changed"""
+        if key not in self._cache:
+            return True  # First update
+
+        cached_values = self._cache[key]
+        current_values = self._extract_values(pair)
+
+        # Check each monitored field
+        for field_name in self.config.change_fields:
+            if (
+                field_name in current_values
+                and field_name in cached_values
+                and current_values[field_name] != cached_values[field_name]
+            ):
+                return True
+
+        return False
+
+    def _are_changes_significant(self, key: str, pair: TokenPair) -> bool:
+        """Check if changes meet significance thresholds"""
+        if key not in self._cache:
+            return True  # First update is always significant
+
+        cached_values = self._cache[key]
+
+        # Check price change threshold
+        if self.config.price_change_threshold is not None and not self._check_threshold(
+            cached_values.get("price_usd"), pair.price_usd, self.config.price_change_threshold
+        ):
+            return False
+
+        # Check volume change threshold
+        if self.config.volume_change_threshold is not None:
+            current_volume = pair.volume.h24 if pair.volume else None
+            cached_volume = cached_values.get("volume.h24")
+            if not self._check_threshold(cached_volume, current_volume, self.config.volume_change_threshold):
+                return False
+
+        # Check liquidity change threshold
+        if self.config.liquidity_change_threshold is not None:
+            current_liquidity = pair.liquidity.usd if pair.liquidity else None
+            cached_liquidity = cached_values.get("liquidity.usd")
+            if not self._check_threshold(cached_liquidity, current_liquidity, self.config.liquidity_change_threshold):
+                return False
+
+        return True
+
+    def _check_threshold(self, old_value: Optional[float], new_value: Optional[float], threshold: float) -> bool:
+        """Check if change exceeds threshold"""
+        if old_value is None or new_value is None:
+            return True  # Can't compare, allow update
+
+        if old_value == 0:
+            return new_value != 0  # Any change from 0 is significant
+
+        change_ratio = abs(new_value - old_value) / abs(old_value)
+        return change_ratio >= threshold
+
+    def _extract_values(self, pair: TokenPair) -> dict[str, Any]:
+        """Extract values for monitored fields"""
+        values = {}
+
+        for field_name in self.config.change_fields:
+            if "." in field_name:
+                # Handle nested fields like "volume.h24"
+                parts = field_name.split(".")
+                obj: Any = pair
+
+                for part in parts:
+                    obj = getattr(obj, part, None)
+                    if obj is None:
+                        break
+
+                values[field_name] = obj
+            else:
+                # Direct field
+                values[field_name] = getattr(pair, field_name, None)
+
+        return values
+
+    def _update_cache(self, key: str, pair: TokenPair):
+        """Update cached values"""
+        self._cache[key] = self._extract_values(pair)
+
+    def reset(self, key: Optional[str] = None):
+        """Reset filter state for a specific key or all keys"""
+        if key:
+            self._cache.pop(key, None)
+            self._last_update_times.pop(key, None)
+        else:
+            self._cache.clear()
+            self._last_update_times.clear()
+
+
+# Preset configurations
+class FilterPresets:
+    """Common filter configurations"""
+
+    @staticmethod
+    def simple_change_detection() -> FilterConfig:
+        """Basic change detection (default behavior)"""
+        return FilterConfig()
+
+    @staticmethod
+    def significant_price_changes(threshold: float = 0.01) -> FilterConfig:
+        """Only emit on significant price changes"""
+        return FilterConfig(change_fields=["price_usd"], price_change_threshold=threshold)
+
+    @staticmethod
+    def significant_all_changes(
+        price_threshold: float = 0.005,
+        volume_threshold: float = 0.10,
+        liquidity_threshold: float = 0.05,
+    ) -> FilterConfig:
+        """Only emit on significant changes in any metric"""
+        return FilterConfig(
+            price_change_threshold=price_threshold,
+            volume_change_threshold=volume_threshold,
+            liquidity_change_threshold=liquidity_threshold,
+        )
+
+    @staticmethod
+    def rate_limited(max_per_second: float = 1.0) -> FilterConfig:
+        """Rate limit updates"""
+        return FilterConfig(max_updates_per_second=max_per_second)
+
+    @staticmethod
+    def ui_friendly() -> FilterConfig:
+        """Suitable for UI updates - rate limited with significance thresholds"""
+        return FilterConfig(
+            price_change_threshold=0.001,  # 0.1% price change
+            volume_change_threshold=0.05,  # 5% volume change
+            max_updates_per_second=2.0,  # Max 2 updates per second
+        )
+
+    @staticmethod
+    def monitoring() -> FilterConfig:
+        """For monitoring dashboards - less frequent updates"""
+        return FilterConfig(
+            price_change_threshold=0.01,  # 1% price change
+            volume_change_threshold=0.10,  # 10% volume change
+            liquidity_change_threshold=0.05,  # 5% liquidity change
+            max_updates_per_second=0.2,  # Max 1 update per 5 seconds
+        )

dexscreen/utils/ratelimit.py

@@ -0,0 +1,65 @@
+import asyncio
+import collections
+import threading
+import time
+from collections import deque
+
+
+class RateLimitError(Exception):
+    """Raised when rate limit is exceeded"""
+
+    pass
+
+
+class RateLimiter:
+    def __init__(self, max_calls: int, period: float):
+        self.calls: deque[float] = collections.deque()
+
+        self.period = period
+        self.max_calls = max_calls
+
+        self.sync_lock = threading.Lock()
+        self.async_lock = asyncio.Lock()
+
+    def __enter__(self):
+        with self.sync_lock:
+            sleep_time = self.get_sleep_time()
+
+            if sleep_time > 0:
+                time.sleep(sleep_time)
+
+            return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        with self.sync_lock:
+            self._clear_calls()
+
+    async def __aenter__(self):
+        async with self.async_lock:
+            sleep_time = self.get_sleep_time()
+
+            if sleep_time > 0:
+                await asyncio.sleep(sleep_time)
+
+            return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        async with self.async_lock:
+            self._clear_calls()
+
+    def get_sleep_time(self) -> float:
+        if len(self.calls) >= self.max_calls:
+            until = time.time() + self.period - self._timespan
+            return until - time.time()
+
+        return 0
+
+    def _clear_calls(self):
+        self.calls.append(time.time())
+
+        while self._timespan >= self.period:
+            self.calls.popleft()
+
+    @property
+    def _timespan(self) -> float:
+        return self.calls[-1] - self.calls[0]

dexscreen-0.0.1.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: dexscreen
+Version: 0.0.1
+Summary: Python wrapper for Dexscreener API with stable HTTP support
+Project-URL: Repository, https://github.com/solanab/dexscreen
+Project-URL: Documentation, https://github.com/solanab/dexscreen#readme
+Project-URL: Issues, https://github.com/solanab/dexscreen/issues
+Author-email: solanab <whiredj@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,crypto,cryptocurrency,dexscreener,http
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: curl-cffi>=0.12
+Requires-Dist: orjson>=3.11
+Requires-Dist: pydantic>=2.11
+Description-Content-Type: text/markdown
+
+# Dexscreen
+
+A stable and reliable Python SDK for [Dexscreener.com](https://dexscreener.com/) API with HTTP support:
+
+- **Single Query** - Traditional one-time API calls
+- **Real-time Updates** - Live price updates with configurable intervals
+
+[![Downloads](https://pepy.tech/badge/dexscreen)](https://pepy.tech/project/dexscreen)
+[![PyPI version](https://badge.fury.io/py/dexscreen.svg)](https://badge.fury.io/py/dexscreen)
+[![Python Version](https://img.shields.io/pypi/pyversions/dexscreen)](https://pypi.org/project/dexscreen/)
+
+## Features
+
+- ✅ Complete official API coverage
+- ✅ Stable HTTP-based streaming
+- ✅ Automatic rate limiting
+- ✅ Browser impersonation for anti-bot bypass (using curl_cffi)
+- ✅ Type-safe with Pydantic models
+- ✅ Async/sync support
+- ✅ Simple, focused interface
+
+## Installation
+
+use uv (Recommended)
+
+```bash
+uv add dexscreen
+```
+
+or pip
+
+```bash
+pip install dexscreen
+```
+
+## Quick Start
+
+### Mode 1: Single Query (Traditional API calls)
+
+```python
+from dexscreen import DexscreenerClient
+
+client = DexscreenerClient()
+
+# Get a specific pair by token address
+pairs = client.get_pairs_by_token_address("solana", "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN")
+if pairs:
+    pair = pairs[0]  # Get the first pair
+    print(f"{pair.base_token.symbol}: ${pair.price_usd}")
+
+# Search for tokens
+results = client.search_pairs("PEPE")
+for pair in results[:5]:
+    print(f"{pair.base_token.symbol} on {pair.chain_id}: ${pair.price_usd}")
+
+# Get token information
+profiles = client.get_latest_token_profiles()
+boosted = client.get_latest_boosted_tokens()
+```
+
+### Mode 2: Real-time Updates
+
+```python
+import asyncio
+from dexscreen import DexscreenerClient
+
+async def handle_price_update(pair):
+    print(f"{pair.base_token.symbol}: ${pair.price_usd} ({pair.price_change.h24:+.2f}%)")
+
+async def main():
+    client = DexscreenerClient()
+
+    # Subscribe to pair updates (default interval: 0.2 seconds)
+    await client.subscribe_pairs(
+        chain_id="solana",
+        pair_addresses=["JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"],
+        callback=handle_price_update,
+        interval=0.2  # Poll 5 times per second (300/min)
+    )
+
+    # Let it run for 30 seconds
+    await asyncio.sleep(30)
+    await client.close_streams()
+
+asyncio.run(main())
+```
+
+### Filtering Options
+
+```python
+from dexscreen import DexscreenerClient, FilterPresets
+
+# Default filtering - only receive updates when data changes
+await client.subscribe_pairs(
+    chain_id="solana",
+    pair_addresses=["JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"],
+    callback=handle_price_update,
+    filter=True,  # Default value
+    interval=0.2
+)
+
+# No filtering - receive all polling results
+await client.subscribe_pairs(
+    chain_id="ethereum",
+    pair_addresses=["0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"],
+    callback=handle_price_update,
+    filter=False,  # Get all updates even if data hasn't changed
+    interval=1.0
+)
+
+# Advanced filtering - only significant price changes (1%)
+await client.subscribe_pairs(
+    chain_id="ethereum",
+    pair_addresses=["0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"],
+    callback=handle_price_update,
+    filter=FilterPresets.significant_price_changes(0.01)
+)
+
+# Rate limited updates - max 1 update per second
+await client.subscribe_pairs(
+    chain_id="ethereum",
+    pair_addresses=["0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"],
+    callback=handle_price_update,
+    filter=FilterPresets.rate_limited(1.0)
+)
+```
+
+## Advanced Usage
+
+### Price Monitoring for Arbitrage
+
+```python
+from dexscreen import DexscreenerClient
+
+async def monitor_arbitrage():
+    client = DexscreenerClient()
+
+    # Monitor same token on different chains
+    pairs = [
+        ("ethereum", "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"),  # USDC/WETH
+        ("bsc", "0x7213a321F1855CF1779f42c0CD85d3D95291D34C"),      # USDC/BUSD
+        ("polygon", "0x45dDa9cb7c25131DF268515131f647d726f50608"),  # USDC/WETH
+    ]
+
+    prices = {}
+
+    async def track_price(pair):
+        key = f"{pair.chain_id}:{pair.base_token.symbol}"
+        prices[key] = float(pair.price_usd)
+
+        # Check for arbitrage opportunity
+        if len(prices) > 1:
+            min_price = min(prices.values())
+            max_price = max(prices.values())
+            spread = ((max_price - min_price) / min_price) * 100
+
+            if spread > 0.5:  # 0.5% spread
+                print(f"ARBITRAGE: {spread:.2f}% spread detected!")
+
+    # Subscribe to all pairs
+    for chain, address in pairs:
+        await client.subscribe_pairs(
+            chain_id=chain,
+            pair_addresses=[address],
+            callback=track_price,
+            interval=0.5
+        )
+
+    await asyncio.sleep(60)  # Monitor for 1 minute
+```
+
+### High-Volume Pairs Discovery
+
+```python
+async def find_trending_tokens():
+    client = DexscreenerClient()
+
+    # Search for tokens
+    results = await client.search_pairs_async("SOL")
+
+    # Filter high volume pairs (>$1M daily volume)
+    high_volume = [
+        p for p in results
+        if p.volume.h24 and p.volume.h24 > 1_000_000
+    ]
+
+    # Sort by volume
+    high_volume.sort(key=lambda x: x.volume.h24, reverse=True)
+
+    # Monitor top 5
+    for pair in high_volume[:5]:
+        print(f"{pair.base_token.symbol}: Vol ${pair.volume.h24/1e6:.2f}M")
+
+        await client.subscribe_pairs(
+            chain_id=pair.chain_id,
+            pair_addresses=[pair.pair_address],
+            callback=handle_price_update,
+            interval=2.0
+        )
+```
+
+## Documentation
+
+📖 **[Full Documentation](docs/index.md)** - Complete API reference, guides, and examples.
+
+### Quick API Overview
+
+#### Main Client
+
+```python
+client = DexscreenerClient(impersonate="chrome136")
+```
+
+#### Key Methods
+
+- `get_pairs_by_token_address(chain_id, token_address)` - Get pairs for a token
+- `search_pairs(query)` - Search pairs
+- `subscribe_pairs(chain_id, pair_addresses, callback)` - Real-time pair updates
+- `subscribe_tokens(chain_id, token_addresses, callback)` - Monitor all pairs of tokens
+
+#### Data Models
+
+- `TokenPair` - Main pair data model
+- `TokenInfo` - Token profile information
+- `OrderInfo` - Order information
+
+## Rate Limits
+
+The SDK automatically handles rate limiting:
+
+- 60 requests/minute for token profile endpoints
+- 300 requests/minute for pair data endpoints
+
+## Browser Impersonation
+
+The SDK uses curl_cffi for browser impersonation to bypass anti-bot protection:
+
+```python
+# Use different browser versions
+client = DexscreenerClient(impersonate="chrome134")
+client = DexscreenerClient(impersonate="safari180")
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see LICENSE file for details

dexscreen-0.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+dexscreen/__init__.py,sha256=W7jJhDNMyzsLsOfQefZJ4pEphfmoIYQbj7rViLplgVg,663
+dexscreen/api/__init__.py,sha256=_fFBxC2rrc4nzeRFS_0MQM3cNFrz-ZtvMKrKXX9gtyI,71
+dexscreen/api/client.py,sha256=_5iQjzx7X4nLhkFimLOPI6dVOcXopgZzya1UNJJns4I,28502
+dexscreen/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dexscreen/core/__init__.py,sha256=_QvgIu4e9RG06TrCTC-BIJMJ5duEFwp1LLTZ7sG4YuM,490
+dexscreen/core/http.py,sha256=pimTHfsV1v2txnlPk8DIaKesxpZi6cFATm9Z8wlS-No,16327
+dexscreen/core/models.py,sha256=7-EN63yyQK92T1ZRhfHwwXJ8Cg1VbO3CY-wdlpljIu4,2573
+dexscreen/stream/__init__.py,sha256=vqoiFQ4LwLjaIEWl7p60StTfG1bSJhyEapjWILVP168,100
+dexscreen/stream/polling.py,sha256=yltLwKHQJkN2RJAkgJFxzKvRwcv9M3DYHl19D_ZYSog,17517
+dexscreen/utils/__init__.py,sha256=2IXzfN8UFzC4iMX3IoK_9rUY-0CtCCsdaFa66Bdv2zw,180
+dexscreen/utils/browser_selector.py,sha256=OB14lfSO6zyen3Qga2Cw2Xc9u9_Y5OkEuIdgLeG2_TA,1186
+dexscreen/utils/filters.py,sha256=rAgcMOLi3VgTvi4ga6p2dBQ-hWlU3DURpCrabyV-V2g,8145
+dexscreen/utils/ratelimit.py,sha256=NncESbX_8RHPSA9vpxH-vnFwoPwssvooOZthqEQ0-G0,1570
+dexscreen-0.0.1.dist-info/METADATA,sha256=imRHIwcAMcMZG_67e8ccYt0z0ueNPWvLgUpm4gqOyE4,7881
+dexscreen-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dexscreen-0.0.1.dist-info/licenses/LICENSE,sha256=YLNduNj40Iu4upUYI6XEXrgBlv0hxMNf6uEVAJITYN0,1064
+dexscreen-0.0.1.dist-info/RECORD,,

dexscreen-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dexscreen-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 solanab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.