config.yaml

The config.yaml file can be divided into two sections: global configuration and bot configuration. The global configuration defines the parameters that are used across the entire application and applied everywhere, while the bot configuration defines the configuration for an invididual bot.

Data Types

A few parameters require values in a specific format that will be described here:

Order Algorithms

Trademade supports the following order algorithms, which can be defined when either opening a new position or when exiting a position manually or via a stop.

Global Configuration

account

• Required

Your Interactive Brokers account number. This is the default account that will be used to place all trades. A bot can override this parameter by specifying its own account: value. You can specify a real or paper trading account here.

token

• Required

Your Trademade access token. This secret value is provided on the Account dasboard page and is required to download the Trademade engine and access the service. Do not share this value with anyone.

telegramUser

• Required

Your Telegram username. Trademade will only accept messages from the username provided in this value.

telegramBotToken

• Required

The API key that will be used for your Trademade Telegram bot. This value is provided by BotFather when you set up a new bot.

pause

• Optional (default: false)

Indicates if the Trademade engine should be paused at startup. The engine can be started by running the /resume Telegram command.

twsPort

• Required

The port number used to connect to Trader Workstation/IB Gateway. This value is available from the API settings window in the TWS Global Settings.

twsClientId

• Optional (default: 2)

The client ID that Trademade will use when connecting to TWS. You should not need to change this value.

timezone

• Optional (default: America/New_York)

The timezone used to interpret times in the bot configuration. This should be a timezone listed in the tz database. The timezone set in this value will be used when evaluating any scripts.

It is strongly recommended that you use the default value.

pidFile

• Required

The pid file is used to record the process ID of the Trademade process, to ensure that multiple copies of Trademade are not running at the same time. You should not need to change the default value.

databaseFile

• Required

The database file that Trademade will use to store its trade data and settings. You should not need to change the default value.

autoUpdate

• Optional (default: true)

When this option is enabled, Trademade will periodically check for updates. If an update is detected Trademade will be automatically restarted, unless:

• The config.yaml file has been changed.
• The config.yaml file is invalid.
• The default revision has been overridden.

When auto update is disabled, Trademade will send a Telegram notification when a new update is detected.

nlvOverride

• Optional (default: 0)

Setting this value allows you to override your account NLV (in USD) when using leverage to determine trade sizing. This can be useful if wish to only dedicate a portion of your overall NLV to your trading strategies without having external NLV changes impact your trade sizing.

tradeNotifications

• Optional (default: all)

Trade notifications allow you to specify which classes of notifications should be sent via Telegram. Error notifications will always be sent. The parameter value must be a YAML list of strings, e.g.:

tradeNotifications: [ open, close, stop ]

This would cause Trademade to send notifications when trades are opened, closed or stopped.

Supported values

confirmEnable

• Optional (default: true)

When this option is enabled, Trademade will display a prompt asking for confirmation before enabling a bot with the /config command.

stopGracePeriodMs

• Optional (default: 500)

Sets the default stop grace period, in milliseconds. This is the amount of time that Trademade will wait before submitting a stop order to exit a position. This can be overridden on a given bot.

hardDeltaStopGracePeriodMs

• Optional (default: 500)

Sets the grace period for a hard delta stop, in milliseconds. Trademade will close the position after this delta has been consistently breached.

initScript

• Optional

Defines a Javascript snippet that will be run at Trademade initialization. This script can be used to define functions that can be used in entryFilter and scripts. Note that modifying global variables is not supported (changes will not be persisted between script executions).

A common pattern is to use the initScript parameter to load a script from an external Javascript file:

  initScript: load('script.js');

On Windows, this may fail without specifying an absolute path to the file. The call to load should provide an absolute path:

  initScript: load('C:\\Users\\<user>\\AppData\\Local\\Trademade\\script.js');

scripts

• Optional

Allows for custom scripting logic to run at set times or intervals. For example:

scripts:
  - interval: 15m
    script: 'telegramCommand("status")'

This script would perform a Telegram /status command every 15 minutes.

Multiple entries can be defined. Each entry must define either a time: or interval: parameter, which map to Time and Duration types, respectively.

Scripts will only run while Trademade is connected to TWS.

See the Scripting reference for details on available objects and functions.

externals

• Optional

Externals are API endpoints that Trademade will call at either a set time or interval. For example:

externals:
  - id: fomc
    url: https://is-it-fomc-day.com/api
    interval: 30m

The externals element defines an array of external objects that can contain the following parameters:

Externals that use the interval element will be initially fetched shortly after Trademade initialization.

See the Scripting reference for details on how to access externals through scripts.

Templates

Templates allow you to simplify your configuration by grouping parameters that are common between bots into a single template. That template can then be included from a bot's configuration. This can greatly reduce the size of your configuration file as well as improve maintainability.

Templates can be defined under a templates: element. The template itself should have a name, which will be used when referencing it from a bot configuration. All bot configuration parameters can be used in a template. For example:

templates:
  - name: Puts
    type: Put
    symbol: SPX
    quantity: 2
    profitTargetPercent: 0.9
    minDTE: 1
    maxDTE: 4

The above snippet would define a template named Puts with the specified parameters. Then, to reference the template from a bot configuration:

bots:
  - name: 7D Put
    template: Puts
    targetDelta: -0.07
  - name: 5D Put
    template: Puts
    targetDelta: -0.05
    profitTargetPercent: 0.95

All of the parameters from the Puts template will be merged into the parameters defined by the bot. The bot's parameters take precedence over the parameters defined in the template. In the example above, the profit target for the 5D Put bot use 95%, while 7D Put would use the 90% value that is defined by the template.

Templates can also reference other templates, allowing for further generalization:

templates:
  - name: Base
    symbol: SPX
    minDTE: 1
    maxDTE: 4
  - name: Calls
    template: Base
    type: Call
  - name: Puts
    template: Base
    type: Put

General Bot Configuration

Bots are defined as a sequence of maps in YAML. Indentation matters!

For example, this configuration defines two bots:

bots:
  - name: 7D Put
    symbol: SPX
    type: Put
    quantity: 2
    targetDelta: -0.07
    profitTargetPercent: 0.8
    minDTE: 1
    maxDTE: 4
  - name: 3D Call
    symbol: SPX
    type: Call
    quantity: 4
    targetDelta: 0.03
    profitTargetPercent: 1
    minDTE: 1
    maxDTE: 4

A bot is defined as a mapping of parameters, which will be described below.

name

• Required

The name of your bot. This can be anything. Emoji are supported.

template

• Optional

Bot template name.

symbol

• Required

The symbol to trade. This must be either SPX or XSP.

type

• Required

The type of position for the bot. This can be one of: Put, Call, PutCreditSpread, CallCreditSpread, ShortStrangle, IronCondor, LongPut, LongCall, PutDebitSpread, or CallDebitSpread.

All of the spread types and IronCondor require spread parameters.

openOrderAlgo

• Optional (default: Normal)

Defines the order algorithm that Trademade will use when opening a new position.

See the order algorithms for a listing of available values.

account

• Optional

The Interactive Brokers account to use for the bot. Setting this parameter overrides the global account: setting.

disableOnOpen

• Optional

If this setting is set to true, the bot will be disabled immediately after opening a position. The bot being disabled has no effect on stops or profit targets while the position is open.

nlvOverride

• Optional (default: 0)

Setting this value allows you to override your account NLV (in USD) when using leverage to determine trade sizing for a specific bot. This value will override any defined global nlvOverride value.

entryFilter

• Optional

Defines a custom script that will be evaluated to determine if a position should be entered. Scripts are run before Trademade attempts to select a contract for the position. The value must be valid Javascript that evaluates to a boolean value. If the script returns true, the position will be entered. If the script returns false, the position will not be entered.

As an example, this script would prevent entry into a new position if SPX is below 4000:

bots:
  - name: 7D Put
    symbol: SPX
    type: Put
    quantity: 2
    targetDelta: -0.07
    profitTargetPercent: 0.8
    minDTE: 1
    maxDTE: 4
    entryFilter: 'spx.last > 4000'

The scripting engine supports ECMAScript 6 and the Javascript standard library is available. For example, you could filter a bot so that it only enters positions on Monday with something like:

new Date().getDay() == 1

You can use multiline YAML statements to construct more complex entry filters, e.g.:

bots:
  - name: 7D Put
    ...
    entryFilter: |
      function shouldEnter() {
        return spx.last > 4000
      }
      shouldEnter()

See the Scripting reference for details on available objects and functions.

scripts

• Optional

Scripts will run on open positions and allow you to manage a position using custom defined logic.

Scripts can run at a set interval or at a specific time. For example:

bots:
  - name: 7D Put
    ...
    scripts:
      - interval: 1m
        script: log('price: ' + bots.current.currentPrice)
      - time: '15:50'
        script: log('delta: ' + bots.current.delta)

This example defines two scripts on the 7D Put bot. The first adjustment runs at a 1 minute interval and will emit the current price of the position to the Trademade log file. The second adjustment will run at 3:50PM and will emit the bot's current delta to the Trademade log file.

Scripts only run during market hours. Time based scripts will run every day at the set time while the position is open. If using an interval script, it cannot be set below 30 seconds.

Multiple entries can be defined. Each entry must define either a time: or interval: parameter, which map to Time and Duration types, respectively.

See the Scripting reference for details on available objects and functions.

maxDailyEntries

• Optional (default: unlimited)

This parameter sets a limit on the number of times in a day a bot will attempt to enter a position. If set to 1, the bot will only enter a position once a day.

maxDailyStops

• Optional (default: unlimited)

This paramter sets the maximum number of daily stops, after which the bot will no longer attempt to enter new positions.

cancelClosingOrderOnLatestEntry

• Optional (default: false)

If this value is set to true Trademade will cancel the closing order for a bot after latestEntryTime. This parameter is only valid for bots that have a non-default profitTargetPercent set.

tags

• Optional

Tags allow some commands to be applied against one or more bots. Multiple tags can be specified on a bot. The parameter value must be a YAML list of strings, e.g.:

bots:
  - name: 7D Put
    tags: [ puts, lowdelta ]
    ...
  - name: 20D Put
    tags: [ puts ]

This would apply two tags, puts and lowdelta to the 7D Put bot, and puts to the 20D Put bot. All bots will automatically be added to the all tag.

The /enable and /disable commands are passed a tag name, which will enable or disable all bots with the given tag. Other commands can optionally accept a tag name as a parameter.

Sizing

quantity

• Optional

Specifies the number of contracts the bot will open. This must be a number value.

leverage

• Optional

Specifies the leverage value, which is used to calculate how many contracts are opened. The leverage value is multiplied by net liquidation value (NLV) and then divided by the notional value of the contract that is being opened:

Number of Contracts = Round((leverage * NLV) / notional)

For example:

• Your NLV is $100,000 and you want to open a 6x leveraged position on a Put Credit Spread.
• Trademade selects a 4350 put contract as the short leg for the PCS.
• 6x leverage would target $600,000 of notional value (6 x $100,000).
• A single 4350 contract carries $435,000 of notional value (4350 * 100).
• $600,000 / $435,000 = 1.38 contracts.
• Trademade will round 1.38, which will result in 1 contract being opened for the position.

The value for leverage is a floating point number.

bpu

• Optional

Specifies the amount of buying power to use when sizing a trade. This value is a percentage and is represented as a floating point number between 0 and 1. The following table determines how sizing is defined, based on the type of bot:

The number of contracts will always be rounded down. This parameter cannot be used for naked short bots. Trademade will raise an error if you attempt to use more than 10% of buying power on a debit position.

For example:

• Your NLV is $100,000 and you wish to open a 50 wide Put Credit Spread that uses 15% of your available buying power.
• $100,000 * 0.15 / (50 * 100) = 3 contracts.

Credit/Debit Targeting

The following parameters define credit and debit related parameters the bot will use when attempting to enter a new position.

A bot must define one of the target parameters listed below.

targetDelta

• Optional

Specifies the delta the bot will target when opening a new position. For put positions this value must be negative and for call positions it must be positive. The value must be expressed as a value between 0-1, e.g. a 7 delta put would be expressed as -0.07 and a 3 delta call would be expressed as 0.03.

For strangle and iron condor position types, the delta should be expressed as a positive value (also between 0-1).

For multi-leg positions, the target delta defines the delta of the short leg.

targetDeltaThreshold

• Optional (default: 0.25)

This value allows you to control how far the bot is willing to deviate from the target delta. The value represents a percentage target of acceptable deviation. For example, when configured with a 15D target delta, with the default delta target threshold of 0.25, the bot would potentially select a contract of between 11.25 and 18.75 delta.

targetOTM

• Optional

The bot will attempt to find a contract that is within the specified out-of-the-money percentage from the underlying. This should be a value between 0-1.

For example, to target a strike that is 1% OTM, you would use 0.01. Continuing the example, if SPX is at 4000, a 1% OTM target would target the 3960 contract.

For spread position types, this is the target for the short leg, or both short legs in the case of strangles or condors.

targetCredit

• Optional

The bot will attempt to open a position for the specified credit, which should be a value greater than 0. Trademade will walk the option chain ask price and select the first contract with an ask price that is below the credit specified.

For example, assume the targetCredit: is set to 2. If the 3980 P is 2.10, the 3975 P is 2.0 and the 3970 P is 1.95, Trademade would select the 3970 P contract.

For multi-leg positions, the targetCredit: parameter defines the desired credit for each short leg, not including the price of the longs.

targetDebit

• Optional

For debit position types, this defines the target debit. Similar to targetCredit:, Trademade will select the contract that is closest to the value specified here when opening a new debit position.

minPremium

• Optional

Defines the minimum premium to accept when opening a new credit position. This should be a number value.

If the selected contract's extrinsic value is below the minimum desired premium at the time of contract selection, the position will not be opened.

profitTargetPercent

• Optional (default: 1 for credit positions, 0 for debit positions)

Defines the profit target percentage for the bot. This should be a value between 0-1 for credit positions. For debit positions this value must be greater than 0. By default, there are no profit targets set for either credit or debit positions.

To set a profit target of 80%, set the value to 0.8. For example, if a credit position was opened for 2.00, a profit target of 0.8 would attempt to close the position for 0.40.

With a debit position, a profit target of 3.0 would be 300%. If a debit position was opened for 2.00, a 300% profit target would close the position for 8.00.

Profit target orders are standing orders that are submitted to IBKR shortly after the position has been opened. Trademade will continually monitor the order to ensure that it is recreated if it's canceled.

Spreads

Most multi-leg position types (other than strangles) will use the spreads: parameter to define leg parameters. All of the parameters listed below must be indented under the spread: parameter.

For example, the configuration below defined a 100 wide 15D PCS:

bots:
  - name: 0DTE 15D Put Credit Spread
    symbol: SPX
    type: PutCreditSpread
    quantity: 2
    targetDelta: -0.15
    profitTargetPercent: 0.8
    minDTE: 0
    maxDTE: 0
    spread:
      width: 100

For Iron Condor positions, it is not currently possible to define separate parameters for each side of the position.

width

• Optional

Defines the maximum width of the spread.

When scanning the option chain, Trademade will initially search for the contract at the width specified. Once a contract is selected, it will then walk the chain in the opposite direction in an attempt to find any contracts that are closer but at the same ask price as the initially selected contract.

For example, a 200 wide spread could select a 3790P contract for a long leg. Assume the 3790P is 0.10. If the 3800P and 3810P contracts are also 0.10, Trademade would select the 3810P contract for the long leg.

price

• Optional

The desired price of the leg.

It is possible to combine both width: and price: parameters when configuring a spread. When both width: and price: are defined, Trademade will attempt to find a contract for the specified price, up to a maximum width.

For example, assume width: 200 and price: 0.10. With these parameters, Trademade would search for the cheapest 0.10 contract, but if there are none within 200 points of the short, it would select the 200 wide contract.

percent

• Optional

The desired width of the spread leg as a percentage. Trademade will target a spread leg that is the specified percentage width of the short/long leg. For example, a put credit spread where the short leg is 5000P, a percent value of 1% would be 50 points away and would select the 4950P contract as the long leg.

This value should be between 0 and 1. For example, to define a 1% spread, the value would be set to 0.01.

closeLong

• Optional (default: auto)

Determines what action to take with long positions when a spread or Iron Condor position is closed. This can be one of three values:

Time

The following time-related parameters control when a new position will be entered, as well as the contract expiration date.

minDTE

• Required

The minimum days to expiration to use when selecting the option chain. This value must be greater than or equal to 0.

maxDTE

• Required

The maximum days to expiration to use when selecting the option chain.

For example, to hold a position over a weekend (including long weekends), maxDTE: could be set to 4.

openTime

• Optional (default: '9:30:00')
• Type: Time

Defines the time after which a bot will attempt to open a new position. The combination of openTime and latestEntryTime determines the window during which a bot is effectively enabled.

Examples:

• '09:35:30' - Open a new position at or after 9:35:30 AM.
• '14:00' - Open a new position at or after 2PM.

Trademade is granular to the second. If you specify to the second, the bot will attempt to open a new position at the exact second.

latestEntryTime

• Optional (default: '16:00:00')

Defines the latest time that a bot will attempt to open a new position.

For example, a value of '15:30' would effectively disable a bot from entering any new positions after 3:30PM.

doubleUpBeforeExpiration

• Optional

This parameter determines if a position should be doubled up before expiration. If a position is being held to expiration, it may be desirable to open another position just before the current one expires.

For example, a strategy that sells 1DTE calls with a 100% profit target (meaning the position is held to expiration) would want to open a position for the next day before the current day's position expires.

This parameter uses the Duration type.

Stops

Trademade has a number of ways to stop out a position.

Trademade uses IBKR streaming market data feeds to continually monitor opened positions throughout the trading day. Streaming market data is updated a maximum of every 100ms.

When a stop is executed, Trademade will use the orderAlgo stop parameter when submitting the closing order for the position. If the order does not fill within 25 seconds the existing order will be canceled and a market order will be submitted in a final attempt to exit the position.

All stops are optional, and it possible for a position to define multiple stop types.

Most stop loss functions have a grace period that must be exceeded before the stop order will be executed.

All parameters within this section must be placed within a stop: map in the bot configuration, for example:

bots:
  - name: 15D Put
    targetDelta: -0.15
    ...
    stop:
      lossPercent: 2.0

This would define a stop loss of 200% of the credit received when the position was opened.

lossPercent

• Optional

Defines a stop loss as a percentage of the credit received (or debit paid) when opening a position.

For credit position types, this value must be greater than 1. For example, a value of 2 would set a stop loss to 200% of the credit received.

For debit positions, this value must be less than 1 and will stop out the position when the price of the position is below the loss percentage.

The stop is based on the last price of the position. For credit positions, the last price must be above (or below, for debit positions) the configured threshold for more than gracePeriodMs before the stop will be executed.

lossValue

• Optional

Defines a stop with an absolute value, for example 2.0.

For credit positions, when the last price of the position is above (or below, for debit positions) the specified value for more than gracePeriodMs, the position will be stopped out.

lossITM

• Optional

Defines a stop when the last underlying position price moves in-the-money by the specified percentage, which must be a value between 0 and 1. This stop type is only valid for credit positions.

For example, assume lossITM: 0.005, which would be 0.5%. For a 3950P contract, the underlying would need to move below 3930.25 and stay below that level for gracePeriodMs before the stop would be executed.

delta

• Optional

Defines a delta stop on a position. For short put positions, the value must be negative. For all other positions types, the value should be positive.

Delta on a position is calculated using the mid price of the contract. When the current position delta is above the configured delta stop value for more than gracePeriodMs the stop will be executed.

hardDelta

• Optional

Defines a hard delta stop on a position. This requires that the delta parameter also be set, and this value must be above (or below) the delta value.

Once the position's delta has breached this value for hardDeltaStopGracePeriodMs milliseconds, a hard delta stop will be triggered.

deltaOffset

• Optional

Similar to delta, this parameter will set a delta stop using an offset from the delta at the time the position was entered. For credit positions the delta of the short side will be used as the base for the offset, and for debit positions the long side.

hardDeltaOffset

• Optional

Similar to hardDelta, this parameter will define a hard delta stop using an offset from the delta at the time the position was entered. For credit positions the delta of the short side will be used as the base for the offset, and for debit positions the long side.

deltaCheck

• Optional (default: all)

For positions with delta stops, this allows customization of how delta on the position should be checked when evaluating for stops.

beforeExpirationTime

• Optional

Determines if a position should be automatically closed before it expires. This must be a Time type. For example, '15:30' would automatically close the position at 3:30PM.

An optional suffix can be added to the value that will prevent the position from being closed if the position delta is above the delta specified here. Building on the previous example, a value of '15:30; 0.1' would not close the position at 3:30PM if the position delta is greater than 10.

gracePeriodMs

• Optional (default: 500)

Sets the stop grace period, in milliseconds. The stop condition must be breached consistently for the specified amount of time before Trademade will submit a stop order to exit the position.

For example, for a bot with a delta stop defined, the delta of the position must be exceeded for the specified value before a stop order will be submitted.

orderAlgo

• Optional (default: Fast)

Order algorithm to use when stopping out of a position. See the order algorithms table for a list of available values.

The Relative value can only be used when stopping out a single leg position, or when the closeLong value is set to auto or false for a multi-leg position. If Relative is used with a multi leg position, Trademade will fall back to using the Fast algorithm.

The algorithm is used for both normal and hard stops.