VERY IMPORTANT NOTES!
DO NOT share publicly the JSON message from your signal bot. If you accidentally did share, please delete this bot and create a new one - in this case you will be safe.
DO NOT add additional parameters or code into the JSON file unless it's described in this article. Otherwise, you may encounter errors while processing the signals from your strategy.
Values enclosed in double curly braces are TradingView placeholder values. For Signal Bot TradingView Strategy, only placeholders with the prefix "strategy" are used in strategy alerts.
{
"secret": "token",
"max_lag": "300",
"timestamp": "{{timenow}}",
"trigger_price": "{{close}}",
"tv_exchange": "{{exchange}}",
"tv_instrument": "{{ticker}}",
"action": "{{strategy.order.action}}",
"bot_uuid": "signal-bot-uuid",
"strategy_info": {
"market_position": "{{strategy.market_position}}",
"market_position_size": "{{strategy.market_position_size}}",
"prev_market_position": "{{strategy.prev_market_position}}",
"prev_market_position_size": "{{strategy.prev_market_position_size}}"
},
"order": {
"amount": "{{strategy.order.contracts}}",
"currency_type": "base"
}
}
Fields description.
It is important to note that if a signal is received that includes parameters not described in this specification, then those parameters will not be read during signal processing.
"secret" - mandatory for use. A unique 3Commas token for authenticating incoming requests within the framework of a specific bot and one user. The token is generated automatically when creating a Signal Bot.
Important security note: When setting up and sending webhooks, make sure that you do not disclose these transmitted fields to the public.
“timestamp” - used optionally and represents a timestamp indicating the time at which this signal was generated.
The timestamp can be used to synchronize data, analyze time trends, and understand the sequence of events in the market.
The alert trigger time is accepted in ISO8601 format.
{{timenow}} data comes to this field from TradingView.
"max_lag" - used optionally and represents the maximum delay that may occur during the execution of your trading strategy. The delay can occur for various reasons, such as network delays or data processing time. The check is performed BEFORE the bot attempts to place an order.
Specifying the maximum delay can be useful for evaluating the performance of your strategy and for managing the timing of trading. If the delay exceeds this threshold, it may signal problems in the trading strategy or its execution that need to be considered and possibly resolved.
The maximum allowable signal processing delay: An integer value between 10 and 86400.
Default: 300. Measured in seconds.
The "max_lag" value is calculated by comparing the time between sending the signal "timestamp" and the moment when the bot first processed this signal. If in the JSON code "max_lag": "300", it means that the allowable delay is 300 seconds or 5 minutes. If the delay value exceeds the specified limit, the signal may be considered invalid or processed with an error.
"trigger_price" - mandatory for use. Represents the price at which the event or condition that triggered the trading signal was generated.
This can be the price of an asset reaching a certain level, such as the price of crossing a moving average, support or resistance level, or the price reaching a level to execute a specific strategy in your trading system.
Information about the trigger price is important for understanding which events or conditions trigger trading signals and what actions can be taken in response to these signals.
{{close}} data comes to this field from TradingView.
"tv_exchange" - mandatory for use. Represents the information about the exchange associated with this trading signal or data. This field indicates the trading service or exchange from which trading data is received.
For example, the "tv_exchange" value can be BINANCE, OKX, BYBIT, and so on, depending on where the trading data is coming from.
This information is important for identifying and tracking the source of trading data and can also be used to analyze data from specific exchanges or services.
{{exchange}} data comes to this field from TradingView.
"tv_instrument" - mandatory for use. Represents the information about the asset to which this trading signal or data relates. This field indicates the specific financial instrument, such as futures, currency pairs, for which trading data was received.
For example, for the currency pair BTC/USDT on Binance Futures - "BTCUSDT.P" and so on.
This information is important for identifying the traded asset and analyzing its trading activity and characteristics.
{{ticker}} data comes to this field from TradingView.
“action” - mandatory for use. Represents the action that should be taken in response to the received trading signal or condition.
Examples of "action" values may include:
"buy" - buy an asset or enter a long position.
"sell" - sell an asset or exit the current position.
{{strategy.order.action}} data comes to this field from TradingView.
Please note the following:
If the strategy was launched before the Signal bot and an entry into a position or exit from a position has already been made within the framework of this strategy, then there may be a temporary data desynchronization with the strategy. For example, an order that was executed on the TradingView chart cannot be executed by the Signal bot on the 3Commas side.
Table of bot behavior when receiving signal data at different stages of the strategy:
strategy.order.action (field "action") - in the signal received from the TradingView JSON, represents information about the action taken by your trading strategy. This can be one of the following:
"buy" - indicates that your strategy decides to buy an asset.
"sell" - indicates that your strategy decides to sell an asset.
"close" - indicates that your strategy decides to close the current position (either bought or sold).
These values allow you to understand what actions are being taken in your trading strategy based on the data received from TradingView JSON.
strategy.market_position (field "market_position") - indicates the current market position that is managed by your strategy. This value can take different forms depending on what position is open on the market:
"long" - means that your strategy is currently managing a long position on the market, that is, you have open positions to buy an asset.
"short" - means that your strategy is currently managing a short position on the market, that is, you have open positions to sell an asset.
"flat" - means that your strategy is not managing any open positions on the market at the moment, that is, you are not holding either long or short positions.
This information is important for monitoring the current state of your strategy and making decisions about further actions based on the current market position.
strategy.prev_market_position (field "prev_market_position") - indicates the previous market position that was managed by your strategy. This value represents the state of the market position before the last action was taken in your strategy. Examples of values:
"long" - means that your strategy in the previous state managed a long position on the market;
"short" - means that your strategy in the previous state managed a short position on the market;
"flat" - means that your strategy in the previous state did not manage any open positions on the market.
This information is useful for tracking changes in market positions and analyzing how your strategy makes decisions about entering and exiting positions in different market conditions.
Example of a sent signal:
Depending on what commands are contained in the signal, the bot will perform the following actions:
Impossible parameter combinations will cause the Signal bot to display an error and transfer the signal to the ‘Failed’ status.
Users can view these failed signals in the bot's signal table.
Here are some examples of parameter combinations that will result in the signal being marked as ‘Failed’:
“bot_uuid” - mandatory for use. The identification code of the Signal Bot in the 3Commas system.
Important security note: When configuring and sending webhooks, make sure you do not disclose these transmitted fields to the public.
“market_position” - mandatory for use. Indicates the current market position. This can be one of the following values:
"long" (long position): This means that you have an open long position on the market, that is, you are holding the asset in anticipation of its rise.
"short" (short position): This means that you have an open short position on the market, that is, you have sold the asset in anticipation of its decline.
"flat" (flat position): This means that you have no open positions on the market, that is, you are not holding either long or short positions.
This information is useful for traders and investors to understand the current market situation and make appropriate trading decisions, such as opening new positions, closing existing ones, or changing their strategy depending on market conditions.
{{strategy.market_position}} data comes to this field from TradingView.
“market_position_size” - mandatory for use. Represents the size of the current market position. This number indicates the number of assets that you currently have in an open position on the market.
For example, if "market_position_size" is equal to 100, this means that you have 100 units of the asset open.
This information is important for assessing the size of your positions on the market and managing risks, as the position size directly affects the potential losses or profits from trading.
{{strategy.market_position_size}} data comes to this field from TradingView.
“prev_market_position” - mandatory for use. Represents information about the previous market position. This indicates the state of the market position before the last action was taken in your trading strategy.
The value of "prev_market_position" can be one of the following:
"long" (long position): This means that your strategy was managing a long position on the market before the last action was taken.
"short" (short position): This means that your strategy was managing a short position on the market before the last action was taken.
"flat" (flat position): This means that your strategy was not managing any open positions on the market before the last action was taken. In this case, you were not holding either long or short positions.
This information is useful for analyzing changes in market positions and understanding how your strategy makes decisions about entering and exiting positions in different market conditions.
{{strategy.prev_market_position}} data comes to this field from TradingView.
“prev_market_position_size” - mandatory for use. Represents the size of the previous market position. This indicates the number of assets that were in an open position on the market before the last action was taken in your trading strategy.
For example, if "prev_market_position_size" is equal to 100, this means that you had 100 units of the asset open in the previous market position.
This information is useful for analyzing changes in the size of market positions and understanding how your strategy manages trading volume in different market scenarios.
{{strategy.prev_market_position_size}} data comes to this field from TradingView.
“order.amount” - mandatory for use. Represents the number of assets that need to be bought or sold as a result of a trading order.
For example, if "order.amount" is equal to 100, this means that 100 units of the asset need to be bought or sold.
{{strategy.order.contracts}} data comes to this field from TradingView.
“order.currency_type” - mandatory for use. Represents the currency type associated with the trading order. This indicates the type of currency used for trading or settlements in the context of this order.
This information is important for determining the currency used in trading and ensuring the correctness of calculations and execution of trading operations.
The value of "order.currency_type" can only be one of the following:
"base" - means that the order size is sent in the currency in which the bot buys coins, for example XRP, DOGE, BTC, ETH.
Additional fields.
"enable"/"disable"
This action will activate Signal bots:
{
...
"action": "enable",
...
}This action will stop Signal bots:
{
...
"action": "disable",
...
}
Examples of the use.
Stop all active Signal bots on your 3Commas account
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable"
}
Stop all active Signal bots on specific exchange accounts
You will need to know your connected exchange account's ID - on My Portfolio page find the needed exchange, click on the 3-dots menu, click on View and you will see the ID on the URL bar:
To add more than 1 exchange account, you will need to place them in the square brackets and divide them with comma:
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"account_ids": [3345345, 3345347]
}
Stop one or several specific Signal bots
You will need to know the Signal bots' UUID. Hover over the i button near the bot and you will see its UUID. If you want to add several bots, you can write the UUIDs with the quotes inside the square brackets and divide them with comma:
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"bot_uuid": ["xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"]
}
Stop all active Long Signal bots on your exchange accounts
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"scopes": ["long", "real"]
}
Stop and close the positions of the active Signal bots
{
...
"action": "disable",
"positions_sub_action": "market_close"
...
}
If you want to close the position at market price, you need to add the line:
"positions_sub_action": "market_close"
Here is an example:
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"positions_sub_action": "market_close"
}
If you want to cancel the position and handle it manually later, you need to add the line:
"positions_sub_action": "cancel"
Here is an example:
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"positions_sub_action": "cancel"
}
Important notes.
In Custom signal type of bots the signal to disable Long or Short position will also cancel the bot itself, not just one side.
If you want to disable separately Long or Short bots you need to create two separate bots - one with Long strategy and one with Short.
Different parameters can be combined and they will work with an "AND" logic. If all parameters meet the conditions, the signal will come through and be processed. The signal will be rejected if at least one parameter is not met.
Example:{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"scopes": ["long", "real"],
"account_ids": [1, 2, 3]
}