Data Fetcher System
AIQ Data Fetcher - Technical Documentation

1. System Overview
The AIQ Data Fetcher is a robust, asynchronous system designed to collect, analyze, and evaluate cryptocurrency token data from various sources. The system uses a job queue architecture to process tasks in parallel, with dependencies between tasks, enabling efficient data processing and analysis.
The system serves multiple purposes:
Sourcing new tokens from various platforms (Birdeye, Dexscreener, etc.)
Fetching token data from multiple APIs
Analyzing token metrics and social signals
Evaluating tokens for potential trading opportunities
Continuously monitoring active tokens
2. Core Architecture
2.1 Job Queue System
The data fetcher uses BullMQ, a Redis-based queue system, to manage and process jobs. This allows:
Parallel processing of independent tasks
Dependency management between related tasks
Rate limiting to respect API constraints
Automatic retries for failed jobs
Progress tracking for long-running operations
2.2 Key Components
Token Sourcing Jobs: Discover new tokens from various platforms
Data Fetching Jobs: Collect relevant data about tokens
Evaluation Jobs: Analyze the collected data and make decisions
Monitoring Jobs: Continuously track active tokens for updates
2.3 Data Flow
Token sourcing discovers potential tokens
Evaluation initialization creates a tree of data fetching jobs
Data fetchers collect necessary information
Once all data is collected, evaluation jobs analyze the token
For promising tokens, monitoring begins to track updates
3. Rate Limiting Implementation
The system implements precise rate limiting to respect API constraints while maximizing throughput. In index.ts, specific limiters are defined:
For development environments, these are replaced with a more conservative limiter:
These limiters are applied to specific worker types when initializing BullMQ workers:
4. Token Sourcing
The system sources tokens from multiple platforms:
4.1 Birdeye Sources
New Listings (
birdeyeNewListingsScannerJob): Recently listed tokensTrending Tokens (
birdeyeTrendingScannerJob): Popular tokens based on trading activityToken Lists (
birdeyeTokenListScannerJob): Comprehensive token listsAll Tokens List (
birdeyeAllTokensListScannerJob): Extensive token catalog with filtering
4.2 Dexscreener Sources
Token Boosts (
dexscreenerBoostScannerJob): Tokens featured through paid promotions
4.3 Data Processing Flow
Source jobs identify potential tokens
The
processTokenSourcesfunction filters and processes these tokensValid tokens are passed to evaluation jobs
4.4 Token Filtering Logic
The system uses specific filtering criteria in birdeyeAllTokensListScannerJob.ts:
5. Token Evaluation Process
5.1 Initialization
The evaluateTokenInitDataFetchingJob is the entry point for token evaluation:
Retrieves token information from database
Checks if market cap is sufficient
Creates a dependency tree of data fetching operations
Schedules data fetching jobs
Sets up a flow to evaluate results once data is collected
5.1.1 Market Cap Validation Logic
5.2 Data Fetching
The system fetches various types of data about tokens:
5.2.1 Technical Data
Overview (
fetchOverviewJobFn): Basic token information (price, liquidity, etc.)Security (
fetchSecurityJobFn): Security metrics and risk assessmentMarkets (
fetchMarketsJobFn): Trading venues and volumeTop Traders (
fetchTopTradersJobFn): Information about major tradersOHLCV (
ohlcvJob): Price candle data for technical analysis
5.2.2 On-chain Data
Pairs (
fetchPairsJobFn): Trading pairs on decentralized exchangesPaid Orders (
fetchPaidOrdersJobFn): Orders with paid promotionsToken Sniffer (
tokenSnifferJob): Security audit information
5.2.3 Social and AI Analysis
Social (
tokenDataFetcherSocialJob): Social media sentiment and activityNarrative (
fetchNarrativeJob): AI-driven analysis of token narrativePrice Trend Prediction (
fetchPriceTrendPredictionJob): AI prediction of price movements
5.3 Core Data Fetching Logic
The core data fetching logic is in tokenDataFetcherJob:
5.4 Evaluation Finalization
Once data is collected, one of these jobs processes the results:
Status Evaluation (
evaluateTokenFetchedDataJob): General token assessmentBuy Evaluation (
evaluateBuyJob): Analysis for buying opportunitiesSell Evaluation (
evaluateSellJob): Analysis for selling opportunities
6. Job Conditional Logic Details
6.1 Token Data Fetcher Job
In tokenDataFetcherJob.ts, the job implements sophisticated conditional logic:
Fresh Data Check Logic:
Error/Retry Fallback Logic:
6.2 Social Data Fetcher Logic
In dataFetcherSocialJob.ts, complex conditional logic handles partial data availability:
6.3 Narrative Fetcher Error Handling
In dataFetcherNarrativeJob.ts:
7. Dependency Management
The system manages dependencies between data fetching tasks using a directed acyclic graph (DAG). The copycatProcessor handles complex dependency patterns:
7.1 Dependency Tree Construction
7.2 CopyCat Job Creation
The algorithm detects reused dependencies and creates "copy cat" jobs to optimize execution:
7.3 CopyCat Processor
The copyCat processor itself monitors the original job and returns its result:
8. Data Caching and Expiration
The system uses timestamp-based data expiration to optimize API usage:
8.1 Expiration Check
8.2 Expiration Configuration
Each data fetcher has its own expiresInSeconds configuration in the database, allowing customization per data type. When storing data:
9. OHLCV Data Collection
The ohlcvJob.ts implements a pagination system to handle the API limitations:
10. Token Sniffer Integration
The tokenSnifferJob.ts uses different implementations based on blockchain:
Each chain has specific audit logic:
11. In-Progress Fetching and Recovery
For complex data fetchers like social, the system handles partial data and in-progress states:
This allows long-running jobs to be resumed if interrupted, and for partial data to be used when complete data cannot be obtained.
12. Monitoring and Maintenance
12.1 Re-evaluation
The reEvaluateTokenJob periodically checks tokens:
12.2 Token Balance Checking
The re-evaluation process checks if tokens have active holders before sending sell signals:
12.3 Price Snapshots
The activePriceSnapshotsJob maintains current price data:
This creates an optimized structure where tokens are first grouped by blockchain, then into batches of appropriate size for the API.
13. Worker Configuration
13.1 Concurrency Settings
The system uses different concurrency settings per job type:
For evaluation jobs, higher concurrency is used since they're CPU-bound rather than I/O bound:
13.2 Worker Health Management
Workers monitor their own health and job performance:
13.3 Graceful Shutdown
The system implements graceful shutdown to prevent data loss:
14. Error Metrics Collection
The system tracks error metrics to monitor performance:
15. Database Batching
Database operations are batched to optimize performance:
16. Common Workflows
16.1 New Token Discovery and Evaluation
Source jobs discover potential tokens
processTokenSourcesfilters and processes tokensevaluateTokenInitDataFetchingJobinitializes evaluationData fetchers collect necessary information
evaluateTokenFetchedDataJobmakes a decision about the token
16.2 Active Token Monitoring
reEvaluateTokenJobidentifies tokens needing updatesData fetchers refresh stale data
Evaluation jobs reassess tokens based on new data
activePriceSnapshotsJobmaintains current price information
16.3 Buy/Sell Signal Generation
evaluateBuyJoborevaluateSellJobanalyzes token dataTechnical and social indicators are considered
AI predictions influence the decision
A signal is generated if criteria are met
17. Integration with External Services
The system integrates with several external APIs:
Birdeye: For token discovery and market data
Dexscreener: For DEX data and promotions
LunarCrush: For social metrics and sentiment
SolSniffer/TokenSniffer: For security audits
AI Services: For narrative and price trend prediction
18. Conclusion
The AIQ Data Fetcher system is a sophisticated platform for token discovery, analysis, and evaluation. Its job-based architecture allows for efficient, scalable data processing, while its comprehensive data collection and analysis capabilities enable informed trading decisions.
Key strengths of the system include:
Efficient handling of multiple API integrations with proper rate limiting
Sophisticated dependency management for complex data workflows
Robust error handling with appropriate fallbacks and retries
Comprehensive monitoring and maintenance of active tokens
Scalable architecture that can be extended to new data sources and blockchains
Last updated