Filter AutoConfig pairs based on a per-pair variable's value

Gunbot's AutoConfig feature allows for highly granular control by using per-pair variables. These variables store stateful information unique to each trading pair on a specific exchange. To leverage this, AutoConfig offers built-in filter types like pairVariableExact, pairVariableBiggerThan, and pairVariableSmallerThan, enabling your jobs to make decisions based on the unique history or status of each pair.

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.

Per-Pair Variables: Individualized State Tracking

Per-pair variables in AutoConfig allow you to assign and update key-value information that is specific to one trading pair on one exchange (e.g., a variable for USDT-BTC on binance is distinct from the same variable for USDT-ETH on binance, or for USDT-BTC on kraken). These are managed using setPairVariable or resetPairVariable actions in AutoConfig jobs and are stored in autoconfig-pairVariables.json.

AutoConfig provides dedicated filter types to read these variables:

• pairVariableExact: Passes if the per-pair variable's current value for the pair being evaluated is exactly equal to the specified value.
• pairVariableBiggerThan: Passes if the per-pair variable's value is numerically greater than the specified value.
• pairVariableSmallerThan: Passes if the per-pair variable's value is numerically smaller than the specified value.
• (Note: A direct "pairVariableNotExist" filter type might not be explicitly listed like its global counterpart. Checking for non-existence often involves custom JavaScript or careful use of pairVariableExact with an unlikely value, though custom scripts offer more robust checking for undefined properties.)

Configuring Per-Pair Variable Filters

When defining a filter rule in your job:

1. Set filterType to pairVariableExact, pairVariableBiggerThan, or pairVariableSmallerThan.
2. The next key-value pair defines the variable and its target value:
   • The key is the exact name of the per-pair variable.
   • The value is the value to compare against.
3. Optionally, you can provide a third key-value pair. If this third parameter is a string, it's interpreted as the exchangeName where the per-pair variable should be looked up. This is useful if you want to check a variable for the current pair but stored under a different exchange's context (an advanced use case). If omitted, it defaults to the current job's exchangeName.

Example: Let's say an earlier job sets a per-pair variable tradingPhase for USDT-BTC on binance to "phase1". Now, another job wants to act only on pairs that are in "phase1".

{
  "phase1ActionJob": {
    "enabled": true,
    "type": "manageOverrides",
    "schedule": "*/5 * * * *",
    "pairs": {
      "exchange": "binance", // This job operates on binance
      "include": "USDT-BTC"
    },
    "filters": {
      "isInPhase1": {
        "filterType": "pairVariableExact", // Specify the filter type
        "tradingPhase": "phase1" // Per-pair variable name and the value to check for
                                 // AutoConfig will look for this.pairVariables.binance['USDT-BTC'].tradingPhase
      }
      // ... other filters for this job
    },
    "overrides": { // Actions for pairs in phase1
      "GAIN": 0.5
    },
    "setPairVariable": { // Optionally, move to next phase
      "tradingPhase": "phase2"
    }
  }
}

In the isInPhase1 filter:

• "filterType": "pairVariableExact" defines the comparison.
• "tradingPhase": "phase1" tells AutoConfig to check the tradingPhase variable specifically for the pair being evaluated by this job instance (e.g., USDT-BTC on binance). If this.pairVariables.binance['USDT-BTC'].tradingPhase equals "phase1", the filter passes.

Example with pairVariableBiggerThan and explicit exchange: Imagine you store a customScore for USDT-BTC under a general globalAnalysis exchange key in pairVariables (perhaps from an external script). A job running on binance for USDT-BTC wants to check this score.

{
  "binanceBtcActionBasedOnGlobalScore": {
    // ... job settings for binance, pair USDT-BTC ...
    "filters": {
      "scoreIsHighEnough": {
        "filterType": "pairVariableBiggerThan",
        "customScore": 80, // Variable name and value to compare against
        "lookupExchange": "globalAnalysis" // Third parameter: Look for customScore under 'globalAnalysis' exchange key
                                          // Checks this.pairVariables.globalAnalysis['USDT-BTC'].customScore
      }
    }
    // ... actions ...
  }
}

Advantages and Scenarios

• Individual Pair State Machines: Manage complex, multi-stage strategies for each pair independently. A pair can transition through states like "initialBuy", "firstDcaComplete", "awaitingProfitTarget", each tracked by a per-pair variable.
• Custom Counters per Pair: Count how many times a specific event (e.g., a partial fill, a specific filter pass) has occurred for USDT-ETH, separately from BTC-ETH.
• Pair-Specific Cooldowns or Timers: After an action, set a timestamp as a per-pair variable (lastActionTime). Another filter can check if enough time has passed (currentTime - this.pairVariables[e][p].lastActionTime > cooldownPeriod) before allowing another action for that specific pair. (This example would likely need a custom filter for the time comparison).
• Targeted Actions: If one job identifies that USDT-BTC needs a specific override due to unique conditions, it can set a flag like btcNeedsSpecialOverride: true. A subsequent manageOverrides job can filter for this specific flag on USDT-BTC to apply the change.

Key Points

• Variable Scope: These filters operate on variables scoped to exchangeName -> pairName -> variableName.
• Data Types: For pairVariableBiggerThan and pairVariableSmallerThan, ensure the per-pair variable generally holds a number. String comparisons might not behave as expected numerically.
• Existence: If a per-pair variable does not exist for the specific pair/exchange combination, filters like pairVariableExact will typically fail (as undefined won't match most values). pairVariableBiggerThan and pairVariableSmallerThan will also likely fail. To check for non-existence, a custom filter evaluating typeof this.pairVariables[exchange]?.[pair]?.yourVar === 'undefined' is more robust.
• Setting Variables: These filters are for reading per-pair variables. To set or modify them, use the setPairVariable or resetPairVariable actions in an AutoConfig job.
• Default Exchange: If the optional third parameter (for lookupExchange) is not provided, the filter defaults to checking the variable under the current job's pairs.exchange context.

Per-pair variable filters are essential for building AutoConfig workflows where the history or specific status of individual trading pairs dictates future actions. They allow for a much more nuanced and adaptive automation strategy compared to relying solely on global variables or current market conditions.