| Name | dexscreen JSON |
| Version |
0.0.7
JSON |
| download |
| home_page | None |
| Summary | Python wrapper for Dexscreener API with stable HTTP support |
| upload_time | 2025-08-03 10:47:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
api
crypto
cryptocurrency
dexscreener
http
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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
[](https://pepy.tech/project/dexscreen)
[](https://badge.fury.io/py/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
# Default client with 10-second timeout
client = DexscreenerClient()
# Custom timeout client
client = DexscreenerClient(client_kwargs={"timeout": 30})
# 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
## Timeout Configuration
The SDK provides flexible timeout configuration for different use cases:
### Default Timeout
```python
# Default timeout is 10 seconds
client = DexscreenerClient()
```
### Custom Timeout
```python
# Set custom timeout during initialization
client = DexscreenerClient(client_kwargs={"timeout": 30})
# Different timeouts for different scenarios
fast_client = DexscreenerClient(client_kwargs={"timeout": 5}) # Quick responses
stable_client = DexscreenerClient(client_kwargs={"timeout": 60}) # Stable connections
```
### Runtime Timeout Updates
```python
# Update timeout at runtime
await client._client_300rpm.update_config({"timeout": 15})
# Multiple config updates including timeout
await client._client_300rpm.update_config({
"timeout": 25,
"impersonate": "chrome136"
})
```
### Recommended Timeout Values
| Use Case | Timeout (seconds) | Description |
|----------|------------------|-------------|
| Quick Trading | 5-10 | Fast response for time-sensitive operations |
| General Use | 10-15 | Default balanced setting |
| Stable Monitoring | 20-30 | Reliable for long-running subscriptions |
| Poor Networks | 30-60 | Handle unstable connections |
## 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")
# Combine browser impersonation with custom timeout
client = DexscreenerClient(
impersonate="chrome136",
client_kwargs={"timeout": 20}
)
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see LICENSE file for details
Raw data
{
"_id": null,
"home_page": null,
"name": "dexscreen",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "api, crypto, cryptocurrency, dexscreener, http",
"author": null,
"author_email": "solanab <whiredj@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3d/58/bab097fe11e41303369a73dcc5a10aa8c55296b4e5bb713e10d30c4525b0/dexscreen-0.0.7.tar.gz",
"platform": null,
"description": "# Dexscreen\n\nA stable and reliable Python SDK for [Dexscreener.com](https://dexscreener.com/) API with HTTP support:\n\n- **Single Query** - Traditional one-time API calls\n- **Real-time Updates** - Live price updates with configurable intervals\n\n[](https://pepy.tech/project/dexscreen)\n[](https://badge.fury.io/py/dexscreen)\n[](https://pypi.org/project/dexscreen/)\n\n## Features\n\n- \u2705 Complete official API coverage\n- \u2705 Stable HTTP-based streaming\n- \u2705 Automatic rate limiting\n- \u2705 Browser impersonation for anti-bot bypass (using curl_cffi)\n- \u2705 Type-safe with Pydantic models\n- \u2705 Async/sync support\n- \u2705 Simple, focused interface\n\n## Installation\n\nuse uv (Recommended)\n\n```bash\nuv add dexscreen\n```\n\nor pip\n\n```bash\npip install dexscreen\n```\n\n## Quick Start\n\n### Mode 1: Single Query (Traditional API calls)\n\n```python\nfrom dexscreen import DexscreenerClient\n\n# Default client with 10-second timeout\nclient = DexscreenerClient()\n\n# Custom timeout client\nclient = DexscreenerClient(client_kwargs={\"timeout\": 30})\n\n# Get a specific pair by token address\npairs = client.get_pairs_by_token_address(\"solana\", \"JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN\")\nif pairs:\n pair = pairs[0] # Get the first pair\n print(f\"{pair.base_token.symbol}: ${pair.price_usd}\")\n\n# Search for tokens\nresults = client.search_pairs(\"PEPE\")\nfor pair in results[:5]:\n print(f\"{pair.base_token.symbol} on {pair.chain_id}: ${pair.price_usd}\")\n\n# Get token information\nprofiles = client.get_latest_token_profiles()\nboosted = client.get_latest_boosted_tokens()\n```\n\n### Mode 2: Real-time Updates\n\n```python\nimport asyncio\nfrom dexscreen import DexscreenerClient\n\nasync def handle_price_update(pair):\n print(f\"{pair.base_token.symbol}: ${pair.price_usd} ({pair.price_change.h24:+.2f}%)\")\n\nasync def main():\n client = DexscreenerClient()\n\n # Subscribe to pair updates (default interval: 0.2 seconds)\n await client.subscribe_pairs(\n chain_id=\"solana\",\n pair_addresses=[\"JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN\"],\n callback=handle_price_update,\n interval=0.2 # Poll 5 times per second (300/min)\n )\n\n # Let it run for 30 seconds\n await asyncio.sleep(30)\n await client.close_streams()\n\nasyncio.run(main())\n```\n\n### Filtering Options\n\n```python\nfrom dexscreen import DexscreenerClient, FilterPresets\n\n# Default filtering - only receive updates when data changes\nawait client.subscribe_pairs(\n chain_id=\"solana\",\n pair_addresses=[\"JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN\"],\n callback=handle_price_update,\n filter=True, # Default value\n interval=0.2\n)\n\n# No filtering - receive all polling results\nawait client.subscribe_pairs(\n chain_id=\"ethereum\",\n pair_addresses=[\"0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640\"],\n callback=handle_price_update,\n filter=False, # Get all updates even if data hasn't changed\n interval=1.0\n)\n\n# Advanced filtering - only significant price changes (1%)\nawait client.subscribe_pairs(\n chain_id=\"ethereum\",\n pair_addresses=[\"0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640\"],\n callback=handle_price_update,\n filter=FilterPresets.significant_price_changes(0.01)\n)\n\n# Rate limited updates - max 1 update per second\nawait client.subscribe_pairs(\n chain_id=\"ethereum\",\n pair_addresses=[\"0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640\"],\n callback=handle_price_update,\n filter=FilterPresets.rate_limited(1.0)\n)\n```\n\n## Advanced Usage\n\n### Price Monitoring for Arbitrage\n\n```python\nfrom dexscreen import DexscreenerClient\n\nasync def monitor_arbitrage():\n client = DexscreenerClient()\n\n # Monitor same token on different chains\n pairs = [\n (\"ethereum\", \"0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640\"), # USDC/WETH\n (\"bsc\", \"0x7213a321F1855CF1779f42c0CD85d3D95291D34C\"), # USDC/BUSD\n (\"polygon\", \"0x45dDa9cb7c25131DF268515131f647d726f50608\"), # USDC/WETH\n ]\n\n prices = {}\n\n async def track_price(pair):\n key = f\"{pair.chain_id}:{pair.base_token.symbol}\"\n prices[key] = float(pair.price_usd)\n\n # Check for arbitrage opportunity\n if len(prices) > 1:\n min_price = min(prices.values())\n max_price = max(prices.values())\n spread = ((max_price - min_price) / min_price) * 100\n\n if spread > 0.5: # 0.5% spread\n print(f\"ARBITRAGE: {spread:.2f}% spread detected!\")\n\n # Subscribe to all pairs\n for chain, address in pairs:\n await client.subscribe_pairs(\n chain_id=chain,\n pair_addresses=[address],\n callback=track_price,\n interval=0.5\n )\n\n await asyncio.sleep(60) # Monitor for 1 minute\n```\n\n### High-Volume Pairs Discovery\n\n```python\nasync def find_trending_tokens():\n client = DexscreenerClient()\n\n # Search for tokens\n results = await client.search_pairs_async(\"SOL\")\n\n # Filter high volume pairs (>$1M daily volume)\n high_volume = [\n p for p in results\n if p.volume.h24 and p.volume.h24 > 1_000_000\n ]\n\n # Sort by volume\n high_volume.sort(key=lambda x: x.volume.h24, reverse=True)\n\n # Monitor top 5\n for pair in high_volume[:5]:\n print(f\"{pair.base_token.symbol}: Vol ${pair.volume.h24/1e6:.2f}M\")\n\n await client.subscribe_pairs(\n chain_id=pair.chain_id,\n pair_addresses=[pair.pair_address],\n callback=handle_price_update,\n interval=2.0\n )\n```\n\n## Documentation\n\n\ud83d\udcd6 **[Full Documentation](docs/index.md)** - Complete API reference, guides, and examples.\n\n### Quick API Overview\n\n#### Main Client\n\n```python\nclient = DexscreenerClient(impersonate=\"chrome136\")\n```\n\n#### Key Methods\n\n- `get_pairs_by_token_address(chain_id, token_address)` - Get pairs for a token\n- `search_pairs(query)` - Search pairs\n- `subscribe_pairs(chain_id, pair_addresses, callback)` - Real-time pair updates\n- `subscribe_tokens(chain_id, token_addresses, callback)` - Monitor all pairs of tokens\n\n#### Data Models\n\n- `TokenPair` - Main pair data model\n- `TokenInfo` - Token profile information\n- `OrderInfo` - Order information\n\n## Rate Limits\n\nThe SDK automatically handles rate limiting:\n\n- 60 requests/minute for token profile endpoints\n- 300 requests/minute for pair data endpoints\n\n## Timeout Configuration\n\nThe SDK provides flexible timeout configuration for different use cases:\n\n### Default Timeout\n```python\n# Default timeout is 10 seconds\nclient = DexscreenerClient()\n```\n\n### Custom Timeout\n```python\n# Set custom timeout during initialization\nclient = DexscreenerClient(client_kwargs={\"timeout\": 30})\n\n# Different timeouts for different scenarios\nfast_client = DexscreenerClient(client_kwargs={\"timeout\": 5}) # Quick responses\nstable_client = DexscreenerClient(client_kwargs={\"timeout\": 60}) # Stable connections\n```\n\n### Runtime Timeout Updates\n```python\n# Update timeout at runtime\nawait client._client_300rpm.update_config({\"timeout\": 15})\n\n# Multiple config updates including timeout\nawait client._client_300rpm.update_config({\n \"timeout\": 25,\n \"impersonate\": \"chrome136\"\n})\n```\n\n### Recommended Timeout Values\n\n| Use Case | Timeout (seconds) | Description |\n|----------|------------------|-------------|\n| Quick Trading | 5-10 | Fast response for time-sensitive operations |\n| General Use | 10-15 | Default balanced setting |\n| Stable Monitoring | 20-30 | Reliable for long-running subscriptions |\n| Poor Networks | 30-60 | Handle unstable connections |\n\n## Browser Impersonation\n\nThe SDK uses curl_cffi for browser impersonation to bypass anti-bot protection:\n\n```python\n# Use different browser versions\nclient = DexscreenerClient(impersonate=\"chrome134\")\nclient = DexscreenerClient(impersonate=\"safari180\")\n\n# Combine browser impersonation with custom timeout\nclient = DexscreenerClient(\n impersonate=\"chrome136\", \n client_kwargs={\"timeout\": 20}\n)\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see LICENSE file for details\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python wrapper for Dexscreener API with stable HTTP support",
"version": "0.0.7",
"project_urls": {
"Documentation": "https://github.com/solanab/dexscreen#readme",
"Issues": "https://github.com/solanab/dexscreen/issues",
"Repository": "https://github.com/solanab/dexscreen"
},
"split_keywords": [
"api",
" crypto",
" cryptocurrency",
" dexscreener",
" http"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "31a14166456414ab3d8072833691b2de3484470104ab9882c11ef1b1da17329b",
"md5": "e374d80adc0127c128bc476efa46d16f",
"sha256": "ed2f160ba2a6a640b872e880d9df449905ac4fea38682434aef1b9358e0cd1c2"
},
"downloads": -1,
"filename": "dexscreen-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e374d80adc0127c128bc476efa46d16f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 52235,
"upload_time": "2025-08-03T10:47:41",
"upload_time_iso_8601": "2025-08-03T10:47:41.445190Z",
"url": "https://files.pythonhosted.org/packages/31/a1/4166456414ab3d8072833691b2de3484470104ab9882c11ef1b1da17329b/dexscreen-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3d58bab097fe11e41303369a73dcc5a10aa8c55296b4e5bb713e10d30c4525b0",
"md5": "9c1a043d8e647c1cebf38c586d767150",
"sha256": "93216ec13ff8b31c656a057e2f07c218e86c8af3377fc29c9bdaa8cfbeabf4a9"
},
"downloads": -1,
"filename": "dexscreen-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "9c1a043d8e647c1cebf38c586d767150",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 246977,
"upload_time": "2025-08-03T10:47:42",
"upload_time_iso_8601": "2025-08-03T10:47:42.736672Z",
"url": "https://files.pythonhosted.org/packages/3d/58/bab097fe11e41303369a73dcc5a10aa8c55296b4e5bb713e10d30c4525b0/dexscreen-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 10:47:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "solanab",
"github_project": "dexscreen#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dexscreen"
}
