Filter AutoConfig pairs based on a global variable's value

Gunbot's AutoConfig feature allows for dynamic and stateful automation through the use of global variables. These variables, which can be set or modified by other AutoConfig jobs, can then be used as conditions in your filters. AutoConfig provides several built-in filterType options specifically for evaluating these global variables, enabling you to create sophisticated, interconnected job workflows.

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.

Global Variables as Filter Conditions

Global AutoConfig variables (managed via setVariable/resetVariable actions and stored in autoconfig-variables.json) can serve as dynamic inputs for your filter logic. Instead of hardcoding values or writing complex custom scripts for simple state checks, you can use dedicated filterType options.

These filter types are:

• variableExact: Passes if the global variable's current value is exactly equal to the specified value.
• variableBiggerThan: Passes if the global variable's current value is numerically greater than the specified value.
• variableSmallerThan: Passes if the global variable's current value is numerically smaller than the specified value.
• variableNotExist: Passes if the specified global variable does not exist in autoconfig-variables.json or is undefined.

Configuring Global Variable Filters

To use these filters, you define a filter rule within your job's filters (or filters2, etc.) object. The key for the filter rule can be any descriptive name. Inside this rule:

1. Set filterType to one of the four types listed above.
2. Add another key-value pair where:
   • The key is the exact name of the global variable you want to evaluate.
   • The value is the value you are comparing against (for variableExact, variableBiggerThan, variableSmallerThan). For variableNotExist, the value is typically an empty string or any placeholder, as it's the existence of the key that matters.

Example: Assume you have a global variable tradingEnabledSystemWide which is set to true or false by another job. You want an addPairs job to only run if this flag is true.

{
  "pairAdderWhenSystemEnabled": {
    "enabled": true,
    "type": "addPairs",
    "schedule": "*/10 * * * *",
    "pairs": {
      "exchange": "binance",
      "include": "USDT-"
    },
    "filters": {
      "isTradingEnabledGlobally": {
        "filterType": "variableExact", // Specify the filter type
        "tradingEnabledSystemWide": true // User defined global variable name and the value to check for
      },
      "standardVolumeFilter": {
        "filterType": "minVolume24h",
        "minVolume": 750000
      }
    },
    "strategy": "spotgrid"
  }
}

In the isTradingEnabledGlobally filter:

• "filterType": "variableExact" indicates the type of check.
• "tradingEnabledSystemWide": true tells AutoConfig to:
  1. Look for a global variable named tradingEnabledSystemWide.
  2. Check if its current value is exactly true.
  3. If both conditions are met, this specific filter rule passes.

The addPairs job will only proceed to add pairs if isTradingEnabledGlobally passes AND standardVolumeFilter passes.

Example with variableBiggerThan: Suppose a global variable riskScore (ranging 0-100) is updated by a market analysis job. An aggressive strategy job should only run if riskScore is above 70.

{
  "aggressiveStrategyActivator": {
    // ... job settings ...
    "filters": {
      "isRiskScoreHigh": {
        "filterType": "variableBiggerThan",
        "riskScore": 70 // Pass if this.variables.riskScore > 70
      }
      // ... other filters ...
    }
    // ... actions ...
  }
}

Example with variableNotExist: Activate a setup job only if a certain initialization flag has not yet been set.

{
  "initialSetupJob": {
    // ... job settings ...
    "filters": {
      "isFirstRun": {
        "filterType": "variableNotExist",
        "initialSetupCompleteFlag": "" // Value here is a placeholder, presence of key matters
      }
    },
    "setVariable": { // Action if filter passes
      "initialSetupCompleteFlag": true
    }
    // ... other setup actions ...
  }
}

This initialSetupJob will only pass its isFirstRun filter (and thus execute its actions, including setting the initialSetupCompleteFlag) if the initialSetupCompleteFlag global variable does not exist. On subsequent runs, the variable will exist, and this filter will fail.

Benefits and Use Cases

• Stateful Automation: Create sequences of jobs where one job sets a flag or counter, and subsequent jobs react to it.
• Global Control Switches: Easily enable or disable entire sets of behaviors across multiple jobs by toggling a single global variable (e.g., enableAggressiveMode: true/false).
• Simplified Logic: For simple variable checks, these built-in filters are more concise and less error-prone than writing a custom JavaScript filter just to read this.variables.myVar === someValue.
• Inter-Job Communication: Allow different AutoConfig jobs to indirectly communicate or signal each other by modifying shared global variables.
• Mode Management: Define system modes (e.g., "bull_market_mode", "bear_market_mode", "ranging_market_mode") as a global variable and have different jobs activate or change behavior based on the current mode.

Important Considerations

• Variable Existence and Type:
  • For variableBiggerThan and variableSmallerThan, ensure the global variable typically holds a numerical value. Comparing a string or boolean with a number might lead to unexpected results based on JavaScript's type coercion rules.
  • If a variable checked by variableExact, variableBiggerThan, or variableSmallerThan does not exist, the filter will generally fail (as undefined is not equal to, bigger, or smaller than most typical values in a predictable way for these comparisons). Use variableNotExist to explicitly check for non-existence.
• Setting Variables: These filters only read global variables. To change global variables, you need an AutoConfig job with setVariable or resetVariable actions.
• Clarity: While powerful, relying too heavily on many interconnected global variables can sometimes make the overall AutoConfig logic harder to trace. Use clear variable names and consider documenting your stateful workflows.

By using global variable filters, you can elevate your AutoConfig strategies from simple, reactive scripts to more intelligent, state-aware automations that adapt to a wider range of conditions and previously recorded states within your Gunbot environment.