Use acUserData.json external data in AutoConfig custom filters

Gunbot's AutoConfig is powerful for on-the-fly decision-making based on market data and internal states. However, sometimes you may need to incorporate external information or custom datasets into your filter logic. AutoConfig facilitates this through the acUserData.json file, whose contents are made available to custom JavaScript filters via the this.userData context variable.

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 acUserData.json File: Your Custom Data Source

The acUserData.json file is a simple yet powerful mechanism for injecting your own data into AutoConfig.

1. Creation: You manually create this file in the root directory of your Gunbot installation (the same place where config.js and autoconfig.json reside).
2. Format: It must be a valid JSON file. You can structure the data within it using any valid JSON constructs: objects, arrays, strings, numbers, booleans.
3. Gunbot's Role: When Gunbot starts, or when it detects changes to acUserData.json (this behavior might vary slightly between versions, but typically it's watched for changes), it reads and parses this file.
4. Accessibility: The parsed content of acUserData.json is then made available to your AutoConfig custom filter scripts through the this.userData context object.

Example acUserData.json content:

{
  "approvedPairs": ["USDT-BTC", "USDT-ETH", "BTC-ETH"],
  "marketSentiment": {
    "overall": "neutral",
    "btcDominanceFactor": 0.65
  },
  "customThresholds": {
    "minVolumeForTier1": 1000000,
    "minVolatilityForAggressive": 3.5
  },
  "notes": "Data last updated 2023-10-27"
}

Accessing Data with this.userData in Custom Filters

Once acUserData.json is in place and populated, your custom JavaScript filter scripts can reference its content through this.userData.

Consider an AutoConfig job that adds pairs, but only if they are on an "approved list" maintained in acUserData.json:

{
  "whitelistPairAdder": {
    "enabled": true,
    "type": "addPairs",
    "schedule": "0 * * * *", // Hourly
    "pairs": {
      "exchange": "binance",
      "include": "USDT-" // Consider all USDT pairs initially
    },
    "filters": {
      "isOnApprovedList": {
        "filterType": "custom",
        "script": "/* Using this.userData */ \n const currentPair = this.pairName; \n \n // Check if approvedPairs list exists in userData and currentPair is in it \n if (this.userData && this.userData.approvedPairs && Array.isArray(this.userData.approvedPairs)) { \n   if (this.userData.approvedPairs.includes(currentPair)) { \n     console.log(currentPair + ' is on the approved list. Filter passes.'); \n     return true; \n   } else { \n     console.log(currentPair + ' is NOT on the approved list.'); \n     return false; \n   } \n } else { \n   console.log('approvedPairs list not found or not an array in acUserData.json.'); \n   return false; // Fail safe if data is missing or malformed \n }"
      },
      "basicVolumeCheck": { // Could be another standard filter
          "filterType": "minVolume24h",
          "minVolume": 50000
      }
    },
    "strategy": "spotgrid"
  }
}

In the isOnApprovedList custom filter:

• this.userData && this.userData.approvedPairs && Array.isArray(this.userData.approvedPairs): This robustly checks if this.userData exists, if it has an approvedPairs property, and if that property is an array, before attempting to use it. This prevents errors if acUserData.json is missing, empty, or malformed.
• this.userData.approvedPairs.includes(currentPair): If the checks pass, it uses the standard JavaScript includes method to see if the currentPair (e.g., "USDT-BTC") is present in the approvedPairs array loaded from acUserData.json.

Potential Use Cases for this.userData

1. Dynamic Whitelists/Blacklists: Maintain lists of pairs to specifically include or exclude from AutoConfig actions, without editing autoconfig.json jobs directly. You can update acUserData.json externally (e.g., via another script or manually).
2. External Signal Integration: If you have an external system that generates buy/sell signals or sentiment scores (e.g., from a custom AI model, a paid signal group API you poll, or manual research), you can write these signals into acUserData.json. Your AutoConfig filters can then read these signals. Example acUserData.json: {"signals": {"USDT-BTC": "strong_buy", "USDT-ETH": "neutral"}}Example script: if (this.userData.signals?.[this.pairName] === 'strong_buy') return true;
3. Tiered Parameters: Define different sets of parameters or thresholds in acUserData.json (e.g., "tier1_settings", "tier2_settings"). Your filter logic could then apply different conditions based on which tier a pair falls into (perhaps determined by another variable or a characteristic of the pair).
4. Global Control Flags: Similar to this.variables, but potentially managed more easily externally. For instance, a global "trading_enabled_for_alts" flag in acUserData.json could be checked by filters.
5. API Key Storage (Use with Extreme Caution): While technically possible, storing sensitive data like API keys in acUserData.json is generally not recommended due to security implications if the file is not properly secured. Gunbot's main config.js has better mechanisms for handling encrypted API keys.

Managing acUserData.json

• Valid JSON: Always ensure acUserData.json is valid JSON. Use a JSON validator if you're editing it manually. An invalid JSON file will likely cause this.userData to be empty or lead to errors.
• Updates: Gunbot typically watches acUserData.json for changes and reloads it. If you update the file while Gunbot is running, the changes should become available to subsequent filter executions. A Gunbot restart also ensures it's loaded.
• File Size: While there's no hard limit, extremely large acUserData.json files might impact Gunbot's startup time or memory usage during parsing. Keep it reasonably sized and focused on the data your filters actually need.
• Backup: Since acUserData.json contains your custom data, include it in your regular Gunbot configuration backups.

The acUserData.json file and its corresponding this.userData object in custom filters provide a flexible bridge between your AutoConfig logic and external data sources or manually curated information. This significantly extends the adaptability and intelligence you can build into your automated Gunbot trading strategies.