How can I schedule an AutoConfig job to run at specific times?

Gunbot's AutoConfig feature automates trading tasks like adding pairs and managing overrides. A key part of control is defining when jobs run. You do this with the schedule parameter in each AutoConfig job, which accepts a cron expression for flexible timing.

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.

Understanding Cron Expressions

The schedule parameter in an AutoConfig job takes a string value known as a "cron expression." Cron is a time-based job scheduler in Unix-like operating systems, and its expression format is a widely used standard for recurring schedules.

A cron expression consists of five fields, separated by spaces:

1. Minute (0 - 59)
2. Hour (0 - 23)
3. Day of the Month (1 - 31)
4. Month (1 - 12)
5. Day of the Week (0 - 6, where 0 is Sunday, or 7 can also be Sunday in some implementations; Gunbot typically uses 0-6 for Sunday-Saturday)

Special characters allow more flexible scheduling:

• * (Asterisk): Represents "any value." For example, * in the hour field means "every hour."
• , (Comma): Used to specify a list of values. For example, 0,15,30,45 in the minute field means "at minutes 0, 15, 30, and 45."
• - (Hyphen): Used to specify a range of values. For example, 9-17 in the hour field means "from 9 AM to 5 PM (inclusive)."
• / (Slash): Used to specify step values. For example, */15 in the minute field means "every 15 minutes." This is equivalent to 0,15,30,45. 0/15 also means the same.

Configuring the schedule Parameter

Define the schedule for an AutoConfig job inside its JSON object in your autoconfig.json file.

Here is an AutoConfig job scheduled to run at the beginning of every hour:

{
  "hourlyPairScanner": {
    "enabled": true,
    "type": "addPairs",
    "schedule": "0 * * * *", // User setting: Cron expression for scheduling
    "pairs": {
      "exchange": "binance",
      "include": "USDT-"
    },
    "filters": {
      "minVolumeFilter": {
        "filterType": "minVolume24h",
        "minVolume": 1000000
      }
    },
    "strategy": "spotgrid"
  }
}

In this configuration, schedule: "0 * * * *" means:

• 0: Run at minute 0.
• *: Run every hour.
• *: Run every day of the month.
• *: Run every month.
• *: Run every day of the week.

Effectively, this job ("hourlyPairScanner") will execute at 1:00, 2:00, 3:00, and so on.

Common Scheduling Examples

Here are common scheduling patterns and their corresponding cron expressions for AutoConfig jobs:

• Every 5 minutes:

  "schedule": "*/5 * * * *"
• Every hour at the 30-minute mark:

  "schedule": "30 * * * *"
• Once a day at midnight:

  "schedule": "0 0 * * *"
• Twice a day, at 8 AM and 8 PM:

  "schedule": "0 8,20 * * *"
• Every Monday at 1 AM:

  "schedule": "0 1 * * 1"
  (Assuming Monday is represented by 1; Sunday is 0)
• On the 1st and 15th of each month at 5:30 AM:

  "schedule": "30 5 1,15 * *"
• Every 10 minutes during market hours (e.g., 9 AM to 5 PM, Monday to Friday):

  "schedule": "*/10 9-17 * * 1-5"

Tips for Scheduling AutoConfig Jobs

1. Resource Management: Be mindful of how frequently your jobs run, especially if they are resource-intensive (e.g., scanning many pairs on multiple exchanges, complex custom filters). Running too many demanding jobs too often can overload your system.
2. Job Dependencies: If one AutoConfig job depends on the output or state set by another (e.g., one job sets a variable, another job filters based on it), ensure their schedules are logically sequenced. You might schedule the dependent job to run shortly after the one it depends on.
3. Market Activity: Align your job schedules with periods of market activity relevant to your strategy. For example, if you're targeting specific market opens or closes, schedule your jobs accordingly.
4. Data Freshness: For jobs that rely on recent market data (like addPairs based on current volume), the schedule determines how up-to-date the data used for filtering will be. More frequent runs mean fresher data but higher resource use.
5. onStart Parameter: In conjunction with schedule, the onStart: true parameter for a job will make it run once immediately when Gunbot starts, in addition to its regular schedule. This can be useful for initializing states or performing an immediate scan.
6. Testing Cron Expressions: There are many online cron expression testers (e.g., crontab.guru) where you can validate your expressions and see a textual description of when they will run. This is highly recommended before deploying a complex schedule.
7. Log Monitoring: After setting up new schedules, monitor your autoconfig-log.txt to confirm that jobs are running at the intended times. Gunbot usually logs when an AutoConfig job is triggered by its schedule.

By mastering cron expressions for the schedule parameter, you gain precise control over AutoConfig jobs and can tailor execution to your strategy and market conditions. This helps ensure automated tasks run reliably and at the right times.