This document outlines the core business logic and mathematical formulas used in the Home Page of the Live Volatile Crypto Tracker.

1. Market Data Sourcing

The application uses Binance WebSockets to receive real-time price updates for both Spot and Futures markets.

• Spot WebSocket: wss://stream.binance.com:9443/ws/!ticker@arr
• Futures WebSocket: wss://fstream.binance.com/stream?streams=!ticker@arr
• Filtering: Only symbols ending with USDT are tracked.

2. Price History Management

The application maintains a sliding window of price records for each detected coin in memory.

• Storage: spotCoinDataRef and futuresCoinDataRef (React Refs) store an object where keys are symbols and values are arrays of prices.
• Sliding Window: New prices are appended to the array, and oldest prices are removed once the maxDataPoints limit is reached.
• Formula (Window Management):

  If length(prices) > maxDataPoints:
      Remove first (oldest) element
  

3. Volatility Calculation Formula

The core metric for identifying volatile coins is the percentage change between the first recorded price in the current window and the most recent price.

• Percentage Change Formula:

  change = ((lastPrice - firstPrice) / firstPrice) * 100
  

• Precision: The result is rounded to 2 decimal places.

4. Eligibility & Detection Logic

A coin is considered "volatile" and displayed on the home page if it meets the following criteria:

1. Minimum Records: recordCount >= minListingRecords (Default: 20)
   • Prevents showing coins with insufficient history to establish a trend.
2. Fluctuation Threshold: abs(change) >= fluctuationThreshold (Default: 0.5%)
   • Only coins moving more than the specified percentage (up or down) are shown.
3. Bookmark Exception: Bookmarked coins remain in the list even if they fall below the threshold.

5. UI Stability & Sorting

To provide a smooth user experience, the application implements specific sorting and update logic.

• Initial Load/Manual Refresh: Coins are sorted by absolute volatility: abs(change) descending.
• Real-time Updates:
  • To prevent the UI from "jumping", existing coins maintain their relative vertical positions.
  • New volatile coins are appended to the end of the list.
  • Full re-sorting is throttled to minimize visual jarring.
• Exit Animation:
  • When a coin falls below the threshold, it is not removed immediately.
  • It stays for an EXIT_ANIMATION_DURATION (Default: 10 seconds).
  • A "Removing..." label appears, and the card fades out during the final 5 seconds.

6. Watchlist & Bookmarking Logic

Users can "star" coins to add them to a persistent watchlist.

• Persistence: Bookmarks are saved in localStorage.
• Visual Feedback:
  • Green Indicator: Coin is currently volatile (above threshold).
  • Amber Indicator: Coin is in the watchlist but currently below the volatility threshold.
• Sectioning: Bookmarked coins are grouped at the top in a "Watchlist" accordion.

7. Configurable Parameters (Settings)

Users can customize the detection logic via the Settings menu:

8. Development Standards

• Update Frequency: The logic loop runs every 1 second to ensure near-instant detection.
• State Management: Uses React useState for UI rendering and useRef for high-frequency data (WebSocket results) to optimize performance.