Use AutoConfig filters for volume percentage change over snapshots

Detecting significant changes in trading volume can be a key indicator for identifying emerging opportunities or increased risk. Gunbot's AutoConfig provides minVolumePctChangeInterval and maxVolumePctChangeInterval filter types to assess how much a pair's current trading volume has changed compared to its average volume over a recent period, defined by a number of ticker snapshots.

Use the AutoConfig wizard

Nearly every option that follows can be set without editing files by hand.
Click the ⋮ (three-dots) menu ➜ AutoConfig, step through the wizard, and press Save; it will write a correct autoconfig.json for you.

Detecting Volume Dynamics

While absolute volume filters (minVolume24h, maxVolume24h) check if a pair's current 24-hour volume is above or below a fixed threshold, the "percentage change interval" filters look at the rate of change in volume. This can highlight pairs that are rapidly gaining or losing trading activity, even if their absolute volume isn't yet very high or low.

The calculation generally involves:

1. Determining the current 24-hour volume (currentQuoteVolume) from the most recent ticker snapshot.
2. Calculating the average 24-hour volume (avgQuoteVolume) over a specified number of preceding snapshots (or all available snapshots for the job if lastSnapshots is not set).
3. Calculating the percentage change: ((currentQuoteVolume - avgQuoteVolume) / avgQuoteVolume) * 100.

Filter Types and Configuration

1. filterType: "minVolumePctChangeInterval":

   • Purpose: Passes if the pair's current 24-hour volume has increased by at least a specified percentage compared to its recent average volume.
   • Use Case: Identifying pairs experiencing a surge in trading activity, potentially indicating a breakout, news event, or start of a strong trend.
   • Configuration:

     "volumeSpikeDetector": {
       "filterType": "minVolumePctChangeInterval",
       // Key for percentage (e.g., minPctChange, threshold); value is the minimum % increase
       "minimumVolumeIncreasePercent": 50, // Pass if current volume is >= 50% above average
       "lastSnapshots": 24 // Optional: Calculate average over last 24 snapshots
                            // If omitted, uses all available snapshots for the job.
     }

2. filterType: "maxVolumePctChangeInterval":

   • Purpose: Passes if the pair's current 24-hour volume has increased by no more than (or decreased relative to) a specified percentage compared to its recent average volume.
   • Use Case: Identifying pairs with stable or declining volume, or avoiding pairs with excessively sudden (and perhaps unsustainable) volume spikes if the threshold is set to a high positive value. Can also be used with negative percentages to find pairs whose volume is significantly dropping.
   • Configuration:

     "stableOrDecliningVolume": {
       "filterType": "maxVolumePctChangeInterval",
       // Key for percentage; value is the maximum % increase (or point for decrease)
       "maximumVolumeIncreasePercent": 10, // Pass if current volume is <= 10% above average
                                          // To find declining volume, you might use a negative value,
                                          // e.g., -20, meaning volume dropped by 20% or more.
       "lastSnapshots": 24
     }

General Configuration Structure:

{
  "volumeTrendScanner": {
    "enabled": true,
    "type": "addPairs",
    "schedule": "*/10 * * * *",
    "snapshots": 60, // Job maintains 60 snapshots
    "pairs": { /* ... exchange and include ... */ },
    "filters": {
      "significantVolumeIncrease": {
        "filterType": "minVolumePctChangeInterval",
        "minVolumePctUp": 100, // Volume must have at least doubled
        "lastSnapshots": 12    // Compared to average of last 12 snapshots (e.g., 2 hours if job runs every 10 mins)
      },
      "notExcessivelySpiked": {
        "filterType": "maxVolumePctChangeInterval",
        "maxVolumePctUp": 500, // Volume increase should not be more than 5x
        "lastSnapshots": 12
      }
      // ... other standard filters like minVolume24h, maxSpreadPct ...
    },
    "strategy": "stepgrid"
  }
}

In volumeTrendScanner, a pair passes if its current 24h volume has at least doubled (minVolumePctUp: 100) compared to the average of its last 12 snapshots, AND this increase is not more than 500% (maxVolumePctUp: 500), potentially filtering out extreme, short-lived anomalies while capturing strong build-ups.

Key Considerations

1. quoteVolume Used: These filters operate on the quoteVolume field from the ticker snapshots. This means the volume is denominated in the pair's quote currency (e.g., USDT for BTC-USDT, BTC for ETH-BTC).
2. lastSnapshots Parameter:
   • This optional parameter within the filter definition determines the lookback period for calculating the average volume.
   • If lastSnapshots is specified (e.g., 24), the average is based on the 24 snapshots immediately preceding the current one.
   • If lastSnapshots is omitted, the average is calculated over all available snapshots currently held by the AutoConfig job (up to the job's main snapshots setting).
   • The job must have collected at least as many snapshots as lastSnapshots (or a few, if lastSnapshots is omitted) for the calculation to be meaningful. Scripts should be robust to initial runs where fewer snapshots exist.
3. Arbitrary Key for Percentage Value: The key name for the percentage threshold (e.g., minimumVolumeIncreasePercent, maxVolumePctUp) is for your description. AutoConfig uses filterType and then expects the numerical percentage value from one of the other keys, and lastSnapshots if present.
4. Handling Zero Average Volume: If the average volume over the lookback period was zero (e.g., a very new or dead coin), the percentage change calculation would involve division by zero. AutoConfig should handle this gracefully (likely by failing the filter), but it's a point to be aware of for extremely illiquid assets.
5. Complementary to Absolute Volume: These percentage change filters are often best used alongside absolute volume filters (minVolume24h). A 100% increase on a tiny volume (e.g., from $100 to $200) is less significant than a 50% increase on a substantial volume (e.g., from $1M to $1.5M).
6. Interpreting maxVolumePctChangeInterval:
   • A positive value (e.g., 50) means "pass if volume increased by 50% or less (including decreases)."
   • A negative value (e.g., -20) means "pass if volume decreased by 20% or more (i.e., current volume is 80% or less of the average)."

Filters based on volume percentage change allow AutoConfig to identify dynamic shifts in market interest and activity. minVolumePctChangeInterval is excellent for spotting momentum build-ups, while maxVolumePctChangeInterval can help find pairs with stable volume or those experiencing a significant drop-off in trading activity. These provide a more nuanced view than static volume thresholds alone.