dexscreen 0.0.1__tar.gz

dexscreen-0.0.1/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

dexscreen-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install Dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run Linting
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run pyright dexscreen/
+
+      - name: Run Tests
+        run: uv run pytest tests/unit --cov=dexscreen

dexscreen-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build_and_publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

dexscreen-0.0.1/.gitignore

@@ -0,0 +1,166 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Editor directories
+.zed/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# PyCharm
+/.idea
+
+# uv
+# uv.lock
+
+# VS Code
+.vscode/
+
+# zed
+.zed
+
+# macOS
+.DS_Store
+
+# AI
+.claude
+CLAUDE.md
+
+/note
+
+# ruff
+.ruff_cache
+
+api_test_results.json
+api_multi_test_results.json
+
+/logs
+
+# Node.js
+node_modules/
+# PyPI credentials
+.pypi

dexscreen-0.0.1/.nvmrc

@@ -0,0 +1 @@
+22

dexscreen-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,77 @@
+# 精简版 pre-commit 配置 - 使用 ruff 替代大部分功能
+repos:
+  # Ruff - Python linter 和 formatter (替代了很多 pre-commit-hooks)
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check (linting)
+        entry: ruff check --fix
+        language: system
+        types:
+          - python
+        require_serial: true
+      - id: ruff-format
+        name: ruff format
+        entry: ruff format
+        language: system
+        types:
+          - python
+        require_serial: true
+
+  # Pyright - 类型检查
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright type check
+        entry: pyright
+        language: system
+        types:
+          - python
+        pass_filenames: false
+        # 只在这些目录运行
+        files: ^(dexscreen|tests|examples)/.*\.py$
+
+  # 只保留 ruff 不能处理的必要检查
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-json
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  # yamllint 替代 check-yaml，支持自定义标签
+  - repo: local
+    hooks:
+      - id: yamllint
+        name: yamllint
+        entry: yamllint
+        language: system
+        types:
+          - yaml
+        args:
+          - -c=.yamllint
+
+  # yamlfix - YAML formatter
+  - repo: local
+    hooks:
+      - id: yamlfix
+        name: yamlfix
+        entry: yamlfix
+        language: system
+        types:
+          - yaml
+        args:
+          - --config-file
+          - pyproject.toml
+
+  # prettier - Markdown formatting
+  - repo: local
+    hooks:
+      - id: prettier
+        name: prettier markdown format
+        entry: pnpm prettier --write
+        language: system
+        types:
+          - markdown
+        require_serial: true

dexscreen-0.0.1/.prettierignore

@@ -0,0 +1,28 @@
+# Build artifacts
+htmlcov/
+site/
+dist/
+build/
+*.egg-info/
+
+# Cache directories
+.pytest_cache/
+.ruff_cache/
+.pyright/
+__pycache__/
+node_modules/
+.pnpm-store/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+
+# Other
+*.log
+.coverage
+.DS_Store

dexscreen-0.0.1/.prettierrc.json

@@ -0,0 +1,15 @@
+{
+  "printWidth": 120,
+  "proseWrap": "always",
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "endOfLine": "lf",
+  "overrides": [
+    {
+      "files": "*.md",
+      "options": {
+        "proseWrap": "always"
+      }
+    }
+  ]
+}

dexscreen-0.0.1/.yamllint

@@ -0,0 +1,32 @@
+extends: default
+
+rules:
+  line-length:
+    max: 120
+    level: warning
+  truthy:
+    allowed-values: ['true', 'false', 'on', 'off']
+  document-start:
+    present: false  # 不强制要求文档开头的 ---
+  comments:
+    min-spaces-from-content: 1  # 注释前至少1个空格
+
+yaml-files:
+  - '*.yaml'
+  - '*.yml'
+
+ignore: |
+  .venv/
+  site/
+  htmlcov/
+  .pytest_cache/
+  .ruff_cache/
+  .pyright/
+  .git/
+  pnpm-lock.yaml
+
+# 允许 Python 标签
+allowed-tags:
+  - "tag:yaml.org,2002:python/name:*"
+  - "!ENV"
+  - "!relative"

dexscreen-0.0.1/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.

dexscreen-0.0.1/PKG-INFO

@@ -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