dexscreener-python 0.1.0__py3-none-any.whl

dexscreener/__init__.py

@@ -0,0 +1,11 @@
+"""dexscreener-python — async DexScreener API client."""
+
+from .client import DexScreenerClient
+from .models import DexPairData
+
+__all__ = [
+    "DexPairData",
+    "DexScreenerClient",
+]
+
+__version__ = "0.1.0"

dexscreener/client.py

@@ -0,0 +1,458 @@
+"""
+Async DexScreener API client.
+
+Free public API — no authentication required.
+Rate limit: ~300 req/min (~5/s).
+API docs: https://docs.dexscreener.com/api/reference
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from decimal import Decimal
+from typing import Any
+
+import httpx
+
+from .models import DexPairData
+
+logger = logging.getLogger(__name__)
+
+_BASE_URL = "https://api.dexscreener.com"
+
+# 429 retry settings
+_MAX_429_RETRIES = 3
+_429_BASE_BACKOFF = 2.0
+
+
+def _retry_after_seconds(resp: httpx.Response) -> float | None:
+    header = resp.headers.get("Retry-After")
+    if not header:
+        return None
+    try:
+        return max(0.0, float(header))
+    except (TypeError, ValueError):
+        return None
+
+
+def _safe_decimal(val: Any) -> Decimal:
+    if val is None:
+        return Decimal("0")
+    try:
+        return Decimal(str(val))
+    except Exception:
+        return Decimal("0")
+
+
+def _safe_int(val: Any) -> int:
+    try:
+        return int(val or 0)
+    except (ValueError, TypeError):
+        return 0
+
+
+class DexScreenerClient:
+    """Async DexScreener API client with rate limiting and 429 handling.
+
+    Works on any chain DexScreener supports: solana, ethereum, base, bsc,
+    arbitrum, polygon, avalanche, etc.
+
+    Example::
+
+        async with DexScreenerClient() as client:
+            pairs = await client.get_token_pairs("solana", token_address)
+            print(pairs[0].price_usd)
+    """
+
+    __slots__ = (
+        "_http",
+        "_cache",
+        "_cache_ttl",
+        "_429_cooldown_until",
+        "_429_consecutive",
+        "_rate_limit",
+        "_rate_tokens",
+        "_rate_last_refill",
+    )
+
+    def __init__(
+        self,
+        *,
+        rate_limit: float = 5.0,
+        cache_ttl: float = 8.0,
+    ) -> None:
+        """
+        Args:
+            rate_limit: Max requests per second (default 5.0).
+            cache_ttl: Default cache TTL in seconds.
+        """
+        self._http: httpx.AsyncClient | None = None
+        self._cache: dict[str, tuple[Any, float]] = {}  # key → (value, expires_at)
+        self._cache_ttl = cache_ttl
+        self._429_cooldown_until: float = 0.0
+        self._429_consecutive: int = 0
+        self._rate_limit = max(rate_limit, 0.1)
+        self._rate_tokens = rate_limit
+        self._rate_last_refill = time.monotonic()
+
+    async def __aenter__(self) -> DexScreenerClient:
+        await self.startup()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.shutdown()
+
+    async def startup(self) -> None:
+        self._http = httpx.AsyncClient(
+            timeout=httpx.Timeout(10.0),
+            headers={"Accept": "application/json"},
+        )
+
+    async def shutdown(self) -> None:
+        if self._http:
+            await self._http.aclose()
+            self._http = None
+
+    # -- Public API ----------------------------------------------------------
+
+    async def get_token_pairs(
+        self,
+        chain: str,
+        token_address: str,
+    ) -> list[DexPairData]:
+        """Get all trading pairs for a token, sorted by liquidity (highest first).
+
+        Args:
+            chain: Chain identifier (e.g., "solana", "ethereum", "base").
+            token_address: Token contract/mint address.
+        """
+        cache_key = f"pairs:{chain}:{token_address}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+
+        data = await self._get_with_retry(
+            f"{_BASE_URL}/tokens/v1/{chain}/{token_address}",
+            "token_pairs",
+        )
+        raw_pairs = data if isinstance(data, list) else data.get("pairs", []) if data else []
+        pairs = self._parse_pairs(raw_pairs)
+        pairs.sort(key=lambda p: p.liquidity_usd, reverse=True)
+        self._cache_set(cache_key, pairs)
+        return pairs
+
+    async def get_pair_by_address(
+        self,
+        chain: str,
+        pair_address: str,
+    ) -> DexPairData | None:
+        """Get data for a specific pair address.
+
+        Returns None if the pair is not found.
+        """
+        cache_key = f"pair:{chain}:{pair_address}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+
+        data = await self._get_with_retry(
+            f"{_BASE_URL}/pairs/v1/{chain}/{pair_address}",
+            "pair",
+        )
+        raw_pair = (
+            data[0]
+            if isinstance(data, list) and data
+            else data.get("pair", data) if data else None
+        )
+        if not raw_pair:
+            return None
+
+        pairs = self._parse_pairs([raw_pair])
+        result = pairs[0] if pairs else None
+        if result:
+            self._cache_set(cache_key, result)
+        return result
+
+    async def get_token_price(
+        self,
+        chain: str,
+        token_address: str,
+    ) -> Decimal | None:
+        """Get the best available USD price for a token.
+
+        Uses the highest-liquidity pair. Returns None if no price available.
+        """
+        pairs = await self.get_token_pairs(chain, token_address)
+        if not pairs:
+            return None
+        best = pairs[0]
+        return best.price_usd if best.price_usd > 0 else None
+
+    async def get_token_liquidity(
+        self,
+        chain: str,
+        token_address: str,
+    ) -> Decimal:
+        """Get total USD liquidity across all pairs for a token."""
+        pairs = await self.get_token_pairs(chain, token_address)
+        return sum((p.liquidity_usd for p in pairs), Decimal("0"))
+
+    async def get_tokens_batch(
+        self,
+        chain: str,
+        token_addresses: list[str],
+    ) -> dict[str, DexPairData]:
+        """Fetch market data for up to 30 tokens in a single request.
+
+        Returns a dict keyed by token address → best DexPairData (highest liquidity).
+        Tokens with no data are absent from the result.
+        """
+        if not token_addresses:
+            return {}
+
+        BATCH_SIZE = 30
+        result: dict[str, DexPairData] = {}
+
+        for i in range(0, len(token_addresses), BATCH_SIZE):
+            batch = token_addresses[i : i + BATCH_SIZE]
+            comma_addrs = ",".join(batch)
+
+            data = await self._get_with_retry(
+                f"{_BASE_URL}/tokens/v1/{chain}/{comma_addrs}",
+                "batch_tokens",
+            )
+            raw_pairs = data if isinstance(data, list) else data.get("pairs", []) if data else []
+            pairs = self._parse_pairs(raw_pairs)
+
+            for pair in pairs:
+                addr = pair.base_token_address
+                if addr and (
+                    addr not in result
+                    or pair.liquidity_usd > result[addr].liquidity_usd
+                ):
+                    result[addr] = pair
+
+        return result
+
+    async def search_pairs(self, query: str) -> list[DexPairData]:
+        """Search for pairs by token name, symbol, or address."""
+        data = await self._get_with_retry(
+            f"{_BASE_URL}/latest/dex/search",
+            "search",
+            params={"q": query},
+        )
+        raw_pairs = data.get("pairs", []) if data else []
+        return self._parse_pairs(raw_pairs)
+
+    async def get_boosted_tokens(
+        self,
+        chain: str | None = None,
+    ) -> list[dict]:
+        """Get currently boosted (promoted) tokens.
+
+        Boosted tokens are paid promotions — treat with caution.
+
+        Args:
+            chain: Optional chain filter (e.g., "solana"). If None, returns all chains.
+        """
+        cache_key = f"boosted:{chain or 'all'}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+
+        data = await self._get_with_retry(
+            f"{_BASE_URL}/token-boosts/latest/v1",
+            "boosted",
+        )
+        items = data if isinstance(data, list) else []
+        if chain:
+            items = [item for item in items if item.get("chainId") == chain]
+
+        self._cache_set(cache_key, items, ttl=30.0)
+        return items
+
+    async def is_token_boosted(
+        self,
+        chain: str,
+        token_address: str,
+    ) -> bool:
+        """Check if a token is currently boosted (paid promotion)."""
+        boosted = await self.get_boosted_tokens(chain)
+        return any(
+            b.get("tokenAddress", "").lower() == token_address.lower()
+            for b in boosted
+        )
+
+    # -- Internal helpers ----------------------------------------------------
+
+    async def _wait_429_cooldown(self) -> None:
+        now = time.time()
+        if now < self._429_cooldown_until:
+            wait = self._429_cooldown_until - now
+            logger.info("dexscreener 429 cooldown: waiting %.1fs", wait)
+            await asyncio.sleep(wait)
+
+    def _trigger_429_cooldown(self, endpoint: str) -> None:
+        self._429_consecutive += 1
+        backoff = 3.0 * (2 ** min(self._429_consecutive - 1, 3))
+        self._429_cooldown_until = time.time() + backoff
+        logger.warning(
+            "dexscreener 429 cooldown set: endpoint=%s consecutive=%d backoff=%.1fs",
+            endpoint,
+            self._429_consecutive,
+            backoff,
+        )
+
+    def _clear_429_cooldown(self) -> None:
+        if self._429_consecutive > 0:
+            self._429_consecutive = 0
+
+    async def _rate_limit_acquire(self) -> None:
+        """Simple token bucket rate limiter."""
+        now = time.monotonic()
+        elapsed = now - self._rate_last_refill
+        self._rate_tokens = min(
+            self._rate_limit,
+            self._rate_tokens + elapsed * self._rate_limit,
+        )
+        self._rate_last_refill = now
+
+        if self._rate_tokens < 1.0:
+            wait = (1.0 - self._rate_tokens) / self._rate_limit
+            await asyncio.sleep(wait)
+            self._rate_tokens = 0.0
+        else:
+            self._rate_tokens -= 1.0
+
+    async def _get_with_retry(
+        self,
+        url: str,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """GET with 429 retry + global cooldown."""
+        if self._http is None:
+            raise RuntimeError("DexScreenerClient.startup() not called")
+
+        await self._wait_429_cooldown()
+
+        for attempt in range(_MAX_429_RETRIES + 1):
+            await self._rate_limit_acquire()
+
+            try:
+                resp = await self._http.get(url, params=params)
+
+                if resp.status_code == 429:
+                    self._trigger_429_cooldown(endpoint)
+                    backoff = _429_BASE_BACKOFF * (2 ** attempt)
+                    logger.warning(
+                        "dexscreener 429: endpoint=%s attempt=%d backoff=%.1fs",
+                        endpoint,
+                        attempt + 1,
+                        backoff,
+                    )
+                    await asyncio.sleep(backoff)
+                    continue
+
+                self._clear_429_cooldown()
+
+                if resp.status_code != 200:
+                    logger.warning(
+                        "dexscreener HTTP %d: endpoint=%s",
+                        resp.status_code,
+                        endpoint,
+                    )
+                    return None
+
+                return resp.json()
+
+            except Exception as exc:
+                logger.warning(
+                    "dexscreener request failed: endpoint=%s error=%s",
+                    endpoint,
+                    exc,
+                )
+                return None
+
+        logger.warning(
+            "dexscreener 429 exhausted retries: endpoint=%s",
+            endpoint,
+        )
+        return None
+
+    # -- Cache ---------------------------------------------------------------
+
+    def _cache_get(self, key: str) -> Any:
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+        value, expires_at = entry
+        if time.monotonic() > expires_at:
+            del self._cache[key]
+            return None
+        return value
+
+    def _cache_set(self, key: str, value: Any, ttl: float | None = None) -> None:
+        self._cache[key] = (value, time.monotonic() + (ttl or self._cache_ttl))
+
+    # -- Parsing -------------------------------------------------------------
+
+    def _parse_pairs(self, raw_pairs: list[dict]) -> list[DexPairData]:
+        """Parse raw pair data into structured DexPairData objects."""
+        pairs: list[DexPairData] = []
+
+        for raw in raw_pairs:
+            if not isinstance(raw, dict):
+                continue
+
+            base = raw.get("baseToken", {})
+            quote = raw.get("quoteToken", {})
+            volume = raw.get("volume", {})
+            price_change = raw.get("priceChange", {})
+            txns = raw.get("txns", {})
+            liquidity = raw.get("liquidity", {})
+
+            txns_5m = txns.get("m5", {})
+            txns_1h = txns.get("h1", {})
+            txns_24h = txns.get("h24", {})
+
+            pair = DexPairData(
+                chain_id=raw.get("chainId", ""),
+                dex_id=raw.get("dexId", ""),
+                pair_address=raw.get("pairAddress", ""),
+                base_token_address=base.get("address", ""),
+                base_token_symbol=base.get("symbol", ""),
+                base_token_name=base.get("name", ""),
+                quote_token_address=quote.get("address", ""),
+                quote_token_symbol=quote.get("symbol", ""),
+                price_usd=_safe_decimal(raw.get("priceUsd")),
+                price_native=_safe_decimal(raw.get("priceNative")),
+                market_cap=_safe_decimal(raw.get("marketCap")),
+                fdv=_safe_decimal(raw.get("fdv")),
+                liquidity_usd=_safe_decimal(liquidity.get("usd")),
+                liquidity_base=_safe_decimal(liquidity.get("base")),
+                liquidity_quote=_safe_decimal(liquidity.get("quote")),
+                volume_5m=_safe_decimal(volume.get("m5")),
+                volume_1h=_safe_decimal(volume.get("h1")),
+                volume_6h=_safe_decimal(volume.get("h6")),
+                volume_24h=_safe_decimal(volume.get("h24")),
+                price_change_5m=_safe_decimal(price_change.get("m5")),
+                price_change_1h=_safe_decimal(price_change.get("h1")),
+                price_change_6h=_safe_decimal(price_change.get("h6")),
+                price_change_24h=_safe_decimal(price_change.get("h24")),
+                buys_5m=_safe_int(txns_5m.get("buys")),
+                sells_5m=_safe_int(txns_5m.get("sells")),
+                buys_1h=_safe_int(txns_1h.get("buys")),
+                sells_1h=_safe_int(txns_1h.get("sells")),
+                buys_24h=_safe_int(txns_24h.get("buys")),
+                sells_24h=_safe_int(txns_24h.get("sells")),
+                pair_created_at=_safe_int(raw.get("pairCreatedAt")),
+                is_boosted=bool(raw.get("boosts")),
+                url=raw.get("url", ""),
+                raw=raw,
+            )
+            pairs.append(pair)
+
+        return pairs

dexscreener/models.py

@@ -0,0 +1,92 @@
+"""DexPairData model — typed representation of a DexScreener trading pair."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any
+
+
+@dataclass(slots=True)
+class DexPairData:
+    """Parsed pair data from DexScreener."""
+
+    # Identity
+    chain_id: str = ""
+    dex_id: str = ""
+    pair_address: str = ""
+    base_token_address: str = ""
+    base_token_symbol: str = ""
+    base_token_name: str = ""
+    quote_token_address: str = ""
+    quote_token_symbol: str = ""
+
+    # Price
+    price_usd: Decimal = Decimal("0")
+    price_native: Decimal = Decimal("0")
+
+    # Market data
+    market_cap: Decimal = Decimal("0")
+    fdv: Decimal = Decimal("0")
+    liquidity_usd: Decimal = Decimal("0")
+    liquidity_base: Decimal = Decimal("0")
+    liquidity_quote: Decimal = Decimal("0")
+
+    # Volume (USD)
+    volume_5m: Decimal = Decimal("0")
+    volume_1h: Decimal = Decimal("0")
+    volume_6h: Decimal = Decimal("0")
+    volume_24h: Decimal = Decimal("0")
+
+    # Price changes (percentage)
+    price_change_5m: Decimal = Decimal("0")
+    price_change_1h: Decimal = Decimal("0")
+    price_change_6h: Decimal = Decimal("0")
+    price_change_24h: Decimal = Decimal("0")
+
+    # Transactions
+    buys_5m: int = 0
+    sells_5m: int = 0
+    buys_1h: int = 0
+    sells_1h: int = 0
+    buys_24h: int = 0
+    sells_24h: int = 0
+
+    # Age
+    pair_created_at: int = 0  # Unix timestamp ms
+
+    # Metadata
+    is_boosted: bool = False
+    url: str = ""
+
+    # Raw response
+    raw: dict = field(default_factory=dict)
+
+    @property
+    def buy_sell_ratio_5m(self) -> float:
+        """Buy/sell ratio over 5 minutes. >1 = more buying."""
+        total = self.buys_5m + self.sells_5m
+        if total == 0:
+            return 1.0
+        return self.buys_5m / max(self.sells_5m, 1)
+
+    @property
+    def buy_sell_ratio_1h(self) -> float:
+        """Buy/sell ratio over 1 hour."""
+        total = self.buys_1h + self.sells_1h
+        if total == 0:
+            return 1.0
+        return self.buys_1h / max(self.sells_1h, 1)
+
+    @property
+    def has_liquidity(self) -> bool:
+        """Token has meaningful liquidity (>$1000)."""
+        return self.liquidity_usd > Decimal("1000")
+
+    @property
+    def pair_age_seconds(self) -> int:
+        """How old the pair is in seconds."""
+        if self.pair_created_at <= 0:
+            return 0
+        return max(0, int(time.time()) - (self.pair_created_at // 1000))

dexscreener_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: dexscreener-python
+Version: 0.1.0
+Summary: Async DexScreener API client with rate limiting, 429 retry, and response caching.
+Project-URL: Homepage, https://github.com/JinUltimate1995/dexscreener-python
+Project-URL: Repository, https://github.com/JinUltimate1995/dexscreener-python
+Project-URL: Issues, https://github.com/JinUltimate1995/dexscreener-python/issues
+Author: JinUltimate
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,crypto,defi,dex,dexscreener,ethereum,solana,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <h1>dexscreener-python</h1>
+  <p><strong>async dexscreener api client for python.</strong></p>
+  <p>rate limiting. 429 retry. response caching. request dedup. works on any chain.</p>
+
+  <br/>
+
+  <a href="https://github.com/JinUltimate1995/dexscreener-python/actions"><img src="https://img.shields.io/github/actions/workflow/status/JinUltimate1995/dexscreener-python/ci.yml?branch=main&style=flat-square&label=tests" /></a>
+  <a href="https://pypi.org/project/dexscreener-python/"><img src="https://img.shields.io/pypi/v/dexscreener-python?style=flat-square" /></a>
+  <img src="https://img.shields.io/pypi/pyversions/dexscreener-python?style=flat-square" />
+  <img src="https://img.shields.io/badge/typed-py.typed-blue?style=flat-square" />
+  <img src="https://img.shields.io/badge/async-first-blue?style=flat-square" />
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />
+</div>
+
+---
+
+> extracted from a production trading system. handles rate limits gracefully.
+
+## 🛡️ Why this library?
+
+dexscreener's api is free and powerful, but:
+
+- **429s kill your app** if you don't handle them
+- **no python client exists** that handles rate limits properly
+- **concurrent requests** for the same token waste your quota
+
+this library solves all three:
+
+```python
+from dexscreener import DexScreenerClient
+
+async with DexScreenerClient() as client:
+    # get all trading pairs for a token
+    pairs = await client.get_token_pairs("solana", "So11111111111111111111111111111111111111112")
+
+    for pair in pairs:
+        print(f"{pair.base_token_symbol}: ${pair.price_usd} | liq: ${pair.liquidity_usd}")
+```
+
+429s → automatic exponential backoff (3s → 6s → 12s).
+duplicate requests → deduplicated into one HTTP call.
+results → cached with configurable TTL.
+
+## 📦 Install
+
+```bash
+pip install dexscreener-python
+```
+
+requires python 3.11+
+
+## ⚡ Features
+
+| feature | description |
+|---|---|
+| **any chain** | solana, ethereum, base, bsc, arbitrum — anything dexscreener supports |
+| **adaptive rate limiting** | token bucket that backs off on 429 and recovers after success |
+| **global 429 cooldown** | one 429 pauses ALL requests briefly (prevents request storms) |
+| **response cache** | configurable TTL per endpoint. concurrent calls share one request. |
+| **batch support** | fetch up to 30 tokens in a single request |
+| **typed data** | `DexPairData` dataclass with computed properties (buy/sell ratio, age, etc.) |
+
+## 🔧 Usage
+
+### 💰 Token Pairs
+
+```python
+pairs = await client.get_token_pairs("solana", token_address)
+
+best_pair = pairs[0]  # sorted by liquidity (highest first)
+print(f"Price: ${best_pair.price_usd}")
+print(f"Liquidity: ${best_pair.liquidity_usd}")
+print(f"24h Volume: ${best_pair.volume_24h}")
+print(f"Buy/Sell 5m: {best_pair.buy_sell_ratio_5m:.2f}")
+print(f"Age: {best_pair.pair_age_seconds // 3600}h")
+```
+
+### 💵 Token Price
+
+```python
+price = await client.get_token_price("solana", token_address)
+print(f"${price}")
+```
+
+### 📦 Batch Fetch (up to 30 tokens)
+
+```python
+data = await client.get_tokens_batch("solana", [addr1, addr2, addr3])
+for addr, pair in data.items():
+    print(f"{pair.base_token_symbol}: ${pair.price_usd}")
+```
+
+### 🔍 Search
+
+```python
+results = await client.search_pairs("BONK")
+for pair in results:
+    print(f"{pair.base_token_symbol} on {pair.dex_id}: ${pair.price_usd}")
+```
+
+### 🚀 Boosted Tokens
+
+```python
+boosted = await client.get_boosted_tokens("solana")
+# boosted tokens are paid promotions — treat with caution
+```
+
+### 🎯 Specific Pair
+
+```python
+pair = await client.get_pair_by_address("solana", pair_address)
+print(f"{pair.dex_id}: ${pair.price_usd}")
+```
+
+## 📋 DexPairData
+
+all methods return `DexPairData` objects with these fields:
+
+| field | type | description |
+|---|---|---|
+| `chain_id` | str | chain identifier |
+| `dex_id` | str | dex identifier (raydium, uniswap_v3, etc.) |
+| `pair_address` | str | pair contract address |
+| `base_token_address` | str | base token mint/address |
+| `base_token_symbol` | str | token symbol |
+| `price_usd` | Decimal | current price in USD |
+| `price_native` | Decimal | price in native token (SOL, ETH, etc.) |
+| `liquidity_usd` | Decimal | total liquidity in USD |
+| `volume_5m / 1h / 6h / 24h` | Decimal | volume by timeframe |
+| `price_change_5m / 1h / 6h / 24h` | Decimal | price change % |
+| `buys_5m / 1h / 24h` | int | buy transactions |
+| `sells_5m / 1h / 24h` | int | sell transactions |
+| `pair_created_at` | int | unix timestamp (ms) |
+
+computed properties:
+
+| property | description |
+|---|---|
+| `buy_sell_ratio_5m` | buy/sell ratio over 5 minutes (>1 = more buying) |
+| `buy_sell_ratio_1h` | buy/sell ratio over 1 hour |
+| `has_liquidity` | True if liquidity > $1000 |
+| `pair_age_seconds` | pair age in seconds |
+
+## ⚙️ Configuration
+
+```python
+client = DexScreenerClient(
+    rate_limit=5.0,      # requests/second (default: 5.0, dexscreener limit is ~300/min)
+    cache_ttl=8.0,       # default cache TTL in seconds
+)
+```
+
+---
+
+## 🆚 Comparison
+
+| | dexscreener-python | raw `httpx` / `requests` |
+|---|---|---|
+| Rate limiting | ✅ adaptive token bucket | ❌ manual |
+| 429 retry | ✅ exponential backoff | ❌ crash |
+| Global cooldown | ✅ one 429 pauses all | ❌ per-request only |
+| Response cache | ✅ TTL + dedup | ❌ manual |
+| Typed data | ✅ `DexPairData` dataclass | ❌ raw dicts |
+| Batch support | ✅ up to 30 tokens | ❌ manual loop |
+| Async | ✅ native | depends |
+
+## License
+
+MIT
+
+---
+
+## 📦 Also by JinUltimate1995
+
+- **[jupiter-swap-python](https://github.com/JinUltimate1995/jupiter-swap-python)** — Jupiter swap client for Python. Async. Typed.
+- **[pumpfun-python](https://github.com/JinUltimate1995/pumpfun-python)** — PumpFun bonding curve + PumpSwap AMM. Direct swaps from Python.
+- **[solana-rpc-resilient](https://github.com/JinUltimate1995/solana-rpc-resilient)** — Fault-tolerant Solana RPC with automatic failover.

dexscreener_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+dexscreener/__init__.py,sha256=b9cOxsJdhv41bgyCC5nUDGJss5JbZLlhKjC7ZrvUBVY,212
+dexscreener/client.py,sha256=P24VzaLKR9U1lN51ffqfqNYWoOum0Axia2PST_z54T4,14937
+dexscreener/models.py,sha256=bo-NOqb7PCxfXgdxFbbPdSKR8oOgKg7N4X1iCwyDZiQ,2489
+dexscreener/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dexscreener_python-0.1.0.dist-info/METADATA,sha256=xX1apb1FTeWrwJjjzkLD5WeLghdADgOcaNUkVxDrG3I,7271
+dexscreener_python-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+dexscreener_python-0.1.0.dist-info/licenses/LICENSE,sha256=QMTxmT1VJd2-bhYmxC2QwPx9CoAXNPflIa8uhLdG2nE,1068
+dexscreener_python-0.1.0.dist-info/RECORD,,

dexscreener_python-0.1.0.dist-info/WHEEL

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

dexscreener_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JinUltimate
+
+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.