index.md

Dexscreen Documentation

Welcome to the Dexscreen documentation! This Python SDK provides a stable, reliable, and feature-rich interface for the Dexscreener.com API, enabling real-time DeFi data monitoring and analysis.

🎯 Quick Start: New to Dexscreen? Start with our Getting Started Guide for installation and your first queries.

🚀 Quick Navigation

Section	Description	Best For
Getting Started	Installation, setup, and your first queries	New users, quick setup
Query API	Single query methods for fetching data	One-time data fetching, API reference
Streaming API	Real-time subscription methods for live updates	Real-time monitoring, trading bots
Data Models	Complete reference for all data structures	Understanding API responses
Filtering	Advanced filtering and configuration options	Optimizing subscriptions, reducing noise
Examples	Complete working examples for common use cases	Learning by example, production patterns

📚 Documentation Structure

🎯 Getting Started

• Getting Started Guide - Installation, basic setup, and your first queries
• Examples - Complete, runnable examples for common use cases

💡 New User Path: Getting Started → Examples → Query API → Streaming API

📖 API Reference

• Query API - Comprehensive guide to all query methods for one-time data fetching
• Streaming API - Real-time subscription methods for continuous updates
• Data Models - Complete reference for all data structures and types
• Filtering - Advanced filtering, rate limiting, and performance optimization

⚠️ Important: Always check the Data Models reference when working with API responses.

⚡ Quick Start

Installation

Using uv (recommended):

uv add dexscreen

Using pip:

pip install dexscreen

Basic Usage Examples

📊 Get Token Price:

from dexscreen import DexscreenerClient

client = DexscreenerClient()

# Get all USDC pairs on Ethereum
pairs = client.get_pairs_by_token_address(
    "ethereum",
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"  # USDC
)

if pairs:
    # Find the most liquid pair
    best_pair = max(pairs, key=lambda p: p.liquidity.usd if p.liquidity else 0)
    print(f"USDC Price: ${best_pair.price_usd:.4f}")
    print(f"24h Volume: ${best_pair.volume.h24:,.0f}")

🔄 Real-time Monitoring:

import asyncio
from dexscreen import DexscreenerClient, FilterPresets

async def price_alert(pair):
    print(f"{pair.base_token.symbol}: ${pair.price_usd:.4f}")

async def main():
    client = DexscreenerClient()

    # Monitor USDC/WETH pair for price changes > 0.1%
    await client.subscribe_pairs(
        chain_id="ethereum",
        pair_addresses=["0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"],
        callback=price_alert,
        filter=FilterPresets.significant_price_changes(0.001)  # 0.1%
    )

    await asyncio.sleep(60)  # Monitor for 1 minute
    await client.close_streams()

asyncio.run(main())

📖 Learn More: See Examples for complete, production-ready code examples.

🔍 Need Help? Check our troubleshooting section below or browse the Examples for common patterns.

📊 API Quick Reference

🔍 Query Methods (Full Reference)

Method	Description	Rate Limit	Use Case
get_pair(address)	Get pair by address (any chain)	300/min	Quick price check
get_pair_by_pair_address(chain_id, pair_address)	Get specific pair on specific chain	300/min	Detailed pair info
get_pairs_by_token_address(chain_id, token_address)	Get all pairs for a token	300/min	Token analysis
search_pairs(query)	Search pairs by name/symbol/address	300/min	Token discovery
get_latest_token_profiles()	Latest token profiles	60/min	New token tracking
get_latest_boosted_tokens()	Latest boosted tokens	60/min	Promoted tokens

📡 Streaming Methods (Full Reference)

Method	Description	Best For
subscribe_pairs(chain_id, pair_addresses, callback)	Monitor specific pairs	Price alerts, trading
subscribe_tokens(chain_id, token_addresses, callback)	Monitor all pairs of tokens	Token monitoring
unsubscribe_pairs(chain_id, pair_addresses)	Stop monitoring pairs	Dynamic management
unsubscribe_tokens(chain_id, token_addresses)	Stop monitoring tokens	Dynamic management
get_active_subscriptions()	List active subscriptions	Debugging, monitoring
close_streams()	Clean up all connections	Cleanup, shutdown

⚠️ Rate Limits: The SDK automatically handles rate limiting with intelligent retry logic.

🔑 Key Features

✨ Core Functionality

• 🌐 Complete API Coverage - All Dexscreener endpoints with full feature parity
• ⚡ Real-time Updates - HTTP-based streaming with configurable polling intervals
• 🎯 Smart Filtering - Client-side filtering with customizable thresholds to reduce noise
• 🔗 Multi-chain Support - Monitor multiple blockchains simultaneously with independent configurations

🛡️ Reliability & Performance

• 🚦 Automatic Rate Limiting - Intelligent retry logic with exponential backoff
• 🕵️ Browser Impersonation - Advanced anti-bot bypass using curl_cffi
• 🔒 Type Safety - Full Pydantic model validation with comprehensive error handling
• 📊 Batch Operations - Efficient batch processing for multiple queries

🎨 Developer Experience

• 🐍 Async/Sync Support - Both synchronous and asynchronous APIs
• 📝 Rich Documentation - Comprehensive guides with practical examples
• 🔧 Flexible Configuration - Customizable filters, intervals, and callbacks
• 🐛 Debug-Friendly - Detailed logging and error messages

🛠️ Common Use Cases

💰 Trading & DeFi

📈 Price Monitoring - Complete Example

# Track significant price movements (1% threshold)
await client.subscribe_pairs(
    chain_id="ethereum",
    pair_addresses=["0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"],
    callback=price_alert,
    filter=FilterPresets.significant_price_changes(0.01)
)

🔄 Arbitrage Detection - Complete Example

# Monitor USDC across multiple chains for price differences
chains = ["ethereum", "polygon", "arbitrum"]
for chain in chains:
    await client.subscribe_pairs(chain, usdc_pairs[chain], arbitrage_callback)

📊 Analytics & Research

🔍 New Token Discovery - Complete Example

# Monitor all pairs of a token for new DEX listings
await client.subscribe_tokens(
    chain_id="solana",
    token_addresses=["JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"],
    callback=new_pair_callback
)

📈 Portfolio Tracking - Complete Example

# Track multiple assets with custom filters per chain
for chain_id, config in portfolio_config.items():
    await client.subscribe_pairs(
        chain_id=chain_id,
        pair_addresses=config['pairs'],
        callback=portfolio_callback,
        filter=config['filter']
    )

🚨 Monitoring & Alerts

⚠️ Volume Surge Detection - Complete Example

# Detect unusual trading activity
volume_config = FilterConfig(
    change_fields=["volume.m5", "volume.h1"],
    volume_change_threshold=0.50  # 50% volume increase
)

💧 Liquidity Monitoring - Complete Example

# Track liquidity additions/removals
liquidity_config = FilterConfig(
    change_fields=["liquidity.usd"],
    liquidity_change_threshold=0.10  # 10% liquidity change
)

🔗 More Examples: Visit the Examples page for complete, production-ready implementations.

📊 Performance Tips: See our performance optimization section and filtering guide for best practices.

Best Practices

⚡ Performance Optimization

1. 🎯 Use Appropriate Intervals

   # High-frequency trading: 0.2s
   interval=0.2
   
   # Portfolio monitoring: 5-10s
   interval=5.0
   
   # Long-term alerts: 30-60s
   interval=30.0

2. 🔍 Apply Smart Filtering - Learn more

   # Only significant changes
   filter=FilterPresets.significant_price_changes(0.01)
   
   # Rate-limited updates
   filter=FilterPresets.rate_limited(1.0)  # Max 1/second

🛡️ Error Handling & Resource Management

1. 🚨 Handle Errors Gracefully

   async def safe_callback(pair):
       try:
           await process_update(pair)
       except Exception as e:
           logger.error(f"Callback error: {e}")
           # Don't let errors crash subscriptions

2. 🧹 Clean Up Resources

   try:
       await client.subscribe_pairs(...)
       await asyncio.sleep(300)  # Run for 5 minutes
   finally:
       await client.close_streams()  # Always cleanup

Check active subscriptions

active = client.get_active_subscriptions()
print(f"Active subscriptions: {len(active)}")

🎯 Development Guidelines

• Rate Limits: SDK handles automatically, but monitor your usage
• Type Safety: Use type hints for better IDE support
• Testing: Use small intervals and short durations during development
• Logging: Enable debug logging for troubleshooting

📖 Deep Dive: Read the Getting Started Guide for detailed setup instructions.

🔗 External Resources

📚 Documentation & Code

• 📖 Complete API Documentation - Detailed method reference
• 🎯 Getting Started Tutorial - Step-by-step setup guide
• 💡 Practical Examples - Production-ready code samples
• GitHub Repository - Source code and issues

🌐 Related Services

• Dexscreener.com - Official Dexscreener platform
• Dexscreener API Docs - Upstream API documentation
• PyPI Package - Official package repository

---

Need Help?

Issue Type	Resource
Getting Started	Getting Started Guide
API Questions	Query API or Streaming API
Code Examples	Examples Page
Bug Reports	GitHub Issues
Feature Requests	GitHub Discussions

---

📄 License

MIT License - See LICENSE file for complete terms and conditions.

🙏 Contributing: We welcome contributions! Please read our contributing guidelines in the GitHub repository.