Skip to main content

How to specify the time interval for historical data in AutoConfig?

· 6 min read

Gunbot’s AutoConfig uses historical ticker data for filter analysis. Alongside the amount of historical data (via history), you also control the time interval between those points with historyInterval in each AutoConfig job.

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.

The Significance of historyInterval​

AutoConfig maintains two types of ticker data:

  1. Snapshots: frequent, recent market data captures configured by snapshots.
  2. Historical data: less frequent points stored for long-term analysis, with the count set by history.

historyInterval links these two data types. It defines how much time should elapse before AutoConfig promotes an old snapshot into the historical data pool. The value is typically interpreted in minutes; internally, Gunbot often converts it to seconds (for example, historyInterval * 60) for timestamp comparisons.

When the oldest snapshot in the snapshots array is older than historyInterval relative to the most recent historical point (or since the job started, if no history exists), it can be added to the history array.

Configuring historyInterval​

Set historyInterval as a numeric value in your AutoConfig job JSON. This number represents minutes.

Example AutoConfig job:

{
  "longTermTrendJob": {
    "enabled": true,
    "schedule": "*/5 * * * *", // Job runs every 5 minutes
    "type": "addPairs",
    "snapshots": 120, // Store 120 recent 5-minute snapshots (10 hours of recent data)
    "history": 200,   // Store 200 historical data points
    "historyInterval": 30, // User setting: Interval in minutes for historical data points
    "pairs": {
      "exchange": "bitget",
      "include": "USDT-BTC,USDT-ETH"
      // ... other pair settings
    },
    "filters": {
      "customHistoryCheck": {
        "filterType": "custom",
        "script": " /* JavaScript using this.history for analysis */ "
      }
    }
    // ... other job settings
  }
}

In the example:

  • historyInterval: 30 means a new historical data point is logged about every 30 minutes.
  • With history: 200, the job stores about 200 * 30 minutes = 6000 minutes, which is 100 hours (just over 4 days).

Actual timing depends on the job’s schedule and snapshot timestamps. If a job runs every 5 minutes, the oldest snapshot can be promoted when it is old enough per historyInterval compared to the latest history entry.

How historyInterval Affects Your Strategy​

  1. Data granularity:

    • A smaller historyInterval (for example, 5 or 10 minutes) provides more detailed data but covers a shorter period for a fixed history count.
    • A larger historyInterval (for example, 60 or 240 minutes) provides a longer view with less detail between points.

  2. Total historical span: the time span is history * historyInterval.

    • history: 100, historyInterval: 15 minutes → 100 * 15 = 1500 minutes (25 hours).
    • history: 100, historyInterval: 60 minutes → 100 * 60 = 6000 minutes (100 hours).

  3. Filter sensitivity: filters that compare points across time (for example, minSlopePctIntervalHistory) behave differently depending on interval size. A slope over hourly intervals reflects broader trends than a slope over 5-minute intervals.

  4. Resource usage: historyInterval doesn’t increase storage (that’s controlled by history), but very small intervals can lead to more frequent processing if other logic reacts to updates in the history array.

Selecting the Right historyInterval​

Choose an interval that matches your strategy timeframe:

  • Intra-day trends (hours to a day): 15, 30, or 60 minutes.
    • Example: history: 96, historyInterval: 15 (24 hours of data, 96 points).
  • Multi-day or weekly trends: 120, 240, or 1440 minutes (1 day).
    • Example: history: 168, historyInterval: 60 (7 days of data, 168 hourly points).
  • Balancing detail and span: if you need fine-grained detail and a long history, increase history. If only broad trends matter, increase historyInterval and keep history smaller.

Practical tip: keep historyInterval greater than the job’s schedule interval. If a job runs every 5 minutes, a historyInterval of 1–2 minutes is not logical because new snapshots are not generated that frequently by that job. AutoConfig typically promotes the oldest snapshot when its timestamp is old enough compared to the last history entry based on historyInterval.

Using historyInterval with historySource in Filters​

Many built-in AutoConfig filters that operate on historical data include a historySource parameter. This typically points to an index in the this.history[jobName] array. historyInterval tells you the approximate time spacing between those indices.

For example, if historyInterval: 60 minutes:

  • historySource: 0 refers to the oldest data point, roughly history * 60 minutes ago.
  • historySource: 1 refers to the next data point, roughly (history - 1) * 60 minutes ago.

Understanding this relationship helps when configuring filters like minPricePctChangeIntervalHistory.

// Conceptual JavaScript usage in a custom filter
// this.history[jobName] is an array of historical snapshots.
// The time difference between historicalData[i] and historicalData[i+1] is
// determined by the 'historyInterval' (user setting).

const jobName = 'myJob'; // Placeholder
const historicalData = this.history[jobName];
const configuredIntervalMinutes = this.config.AutoConfig[jobName].historyInterval;

if (historicalData && historicalData.length >= 2) {
  const latestHistoryPoint = historicalData[historicalData.length - 1];
  const secondLatestHistoryPoint = historicalData[historicalData.length - 2];

  // Timestamps are usually in seconds Unix format
  const timeDiffSeconds = latestHistoryPoint.timestamp - secondLatestHistoryPoint.timestamp;
  const timeDiffMinutes = timeDiffSeconds / 60;

  // timeDiffMinutes should be approximately equal to configuredIntervalMinutes
  // (allowing for minor variations due to job scheduling)

  // console.log(`Expected interval: ${configuredIntervalMinutes} min, Actual interval: ${timeDiffMinutes.toFixed(2)} min`);
}

By choosing an appropriate historyInterval, you define the time spacing in this.history and control how AutoConfig filters interpret long-term market history.