A professional trading signal system that monitors and analyzes transactions on the HyperLiquid decentralized derivatives exchange. The system detects whale activities, represents a sophisticated approach to real-time trade analysis to detect meaningful trading signals from the noise of market activity then alerts through Telegram.

The system uses a multi-storage approach to efficiently process, store, and analyze trading data:

• Redis: For real-time data buffering, caching, and high-performance trade aggregation
• PostgreSQL: For persistent storage of trade data and whale activity
• ClickHouse: For high-performance analytical queries on historical trade data

• Real-time monitoring of all trades on HyperLiquid
• Intelligent trade aggregation to detect whale activities
• Position tracking and analysis
• Automated alerts via Telegram
• Periodic whale trend analysis
• Memory-efficient processing with garbage collection
• Rate limit monitoring: Tracks all API calls and detects rate limit errors (hit rate limit, peak rate limit, ...) then report to Redis

Redis serves as the primary real-time data buffer and processing engine:

1. JSON Objects: Store trade buffer data with the following structure:

   • tradeBuffer:{address}-{coin}-{position} - JSON containing trade data:
     • px - Array of price data for trades
     • sz - Array of size data for trades
     • amount - Total USD value of trades
     • fromTime - Timestamp of first trade in buffer
     • toTime - Timestamp of last trade in buffer

2. Sorted Sets: Enable efficient threshold-based queries by trade value

   • tradeBufferSorted:{coin}:long - Sorted set of long positions by value
   • tradeBufferSorted:{coin}:short - Sorted set of short positions by value

3. Hash Maps: Track expiration times for trade buffers

   • tradeBufferExpiry - Maps buffer keys to their expiration timestamps

4. String Keys with TTL: Track processed address-coin pairs

   • processed:{address}-{coin} - Prevents duplicate processing with automatic expiry

• Lua Scripts: Atomic operations for trade buffer updates
• Pipelining: Batch Redis commands for better performance
• TTL-based Expiry: Automatic cleanup of old data
• Sorted Sets: Efficient range queries for high-value trades

The system implements a real-time monitoring mechanism using Redis Pub/Sub:

• Trade Buffer Monitoring: The startTradeBufferMonitoring function subscribes to Redis keyspace notifications
• Observable Pattern: Implements the observer pattern to react to changes in trade buffers
• Event-driven Architecture: Reduces polling overhead and enables responsive signal generation

PostgreSQL provides persistent storage for trade data and whale activity:

• Trade Entity: Stores individual trade data
• WhalePerpFilled Entity: Stores aggregated whale position data with metadata

ClickHouse is used for high-performance analytical queries:

• perp_trades Table: Columnar storage optimized for analytical queries on trade data

The system uses a sophisticated algorithm to aggregate individual trades into meaningful whale positions:

1. Real-time Buffering: Each trade is added to Redis buffers using the addToTradeBuffer function
2. Position Tracking: Trades are tracked separately for long and short positions
3. Time-based Aggregation: Trades are grouped within configurable time windows
4. Value Thresholds: Only positions exceeding coin-specific thresholds are considered
5. Blacklist Filtering: Known market makers and exchange addresses are filtered out
6. Position Analysis: Current on-chain positions are fetched to provide context
7. Signal Generation: Meaningful signals are generated based on aggregated data

The system runs several scheduled jobs:

1. Trade Buffer Processing (every 2 minutes):

   • Processes accumulated trade data
   • Generates and sends whale alerts
   • Marks processed pairs to avoid duplicate alerts

2. Memory Check (every 2 minutes):

   • Monitors memory usage
   • Logs memory statistics

3. Whale Activity Summary (every N hours):

   • Analyzes aggregated whale activity
   • Identifies trends across multiple whales
   • Sends consolidated reports

4. Whale Trend Analysis (every 4 hours):

   • Analyzes positions of top traders
   • Identifies market sentiment (bullish/bearish)
   • Reports on popular trading pairs

The system uses dynamic configuration based on market conditions:

• Coin-specific Thresholds: Different value thresholds for different coins
• Leverage-based Configuration: Adjusts thresholds based on maximum leverage
• Time Windows: Configurable time windows for trade aggregation
• Blacklisted Addresses: Filtering of known market makers and exchange addresses

The application can be run in development or production mode:

npm run start:dev

• Node.js 16+
• Redis 6+
• PostgreSQL 13+
• ClickHouse 22+

We welcome contributions! Please fork the repository and create a pull request.

This project is licensed under the MIT License. Please refer to the LICENSE file for more information.