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

  1. Token Sourcing Jobs: Discover new tokens from various platforms

  2. Data Fetching Jobs: Collect relevant data about tokens

  3. Evaluation Jobs: Analyze the collected data and make decisions

  4. Monitoring Jobs: Continuously track active tokens for updates

2.3 Data Flow

  1. Token sourcing discovers potential tokens

  2. Evaluation initialization creates a tree of data fetching jobs

  3. Data fetchers collect necessary information

  4. Once all data is collected, evaluation jobs analyze the token

  5. 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 tokens

  • Trending Tokens (birdeyeTrendingScannerJob): Popular tokens based on trading activity

  • Token Lists (birdeyeTokenListScannerJob): Comprehensive token lists

  • All 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

  1. Source jobs identify potential tokens

  2. The processTokenSources function filters and processes these tokens

  3. Valid 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:

  1. Retrieves token information from database

  2. Checks if market cap is sufficient

  3. Creates a dependency tree of data fetching operations

  4. Schedules data fetching jobs

  5. 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 assessment

  • Markets (fetchMarketsJobFn): Trading venues and volume

  • Top Traders (fetchTopTradersJobFn): Information about major traders

  • OHLCV (ohlcvJob): Price candle data for technical analysis

5.2.2 On-chain Data

  • Pairs (fetchPairsJobFn): Trading pairs on decentralized exchanges

  • Paid Orders (fetchPaidOrdersJobFn): Orders with paid promotions

  • Token Sniffer (tokenSnifferJob): Security audit information

5.2.3 Social and AI Analysis

  • Social (tokenDataFetcherSocialJob): Social media sentiment and activity

  • Narrative (fetchNarrativeJob): AI-driven analysis of token narrative

  • Price 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 assessment

  • Buy Evaluation (evaluateBuyJob): Analysis for buying opportunities

  • Sell 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:

  1. Fresh Data Check Logic:

  1. 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

  1. Source jobs discover potential tokens

  2. processTokenSources filters and processes tokens

  3. evaluateTokenInitDataFetchingJob initializes evaluation

  4. Data fetchers collect necessary information

  5. evaluateTokenFetchedDataJob makes a decision about the token

16.2 Active Token Monitoring

  1. reEvaluateTokenJob identifies tokens needing updates

  2. Data fetchers refresh stale data

  3. Evaluation jobs reassess tokens based on new data

  4. activePriceSnapshotsJob maintains current price information

16.3 Buy/Sell Signal Generation

  1. evaluateBuyJob or evaluateSellJob analyzes token data

  2. Technical and social indicators are considered

  3. AI predictions influence the decision

  4. A signal is generated if criteria are met

17. Integration with External Services

The system integrates with several external APIs:

  1. Birdeye: For token discovery and market data

  2. Dexscreener: For DEX data and promotions

  3. LunarCrush: For social metrics and sentiment

  4. SolSniffer/TokenSniffer: For security audits

  5. 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