Important reminder!
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.
What is JSON, and what job it does?
JSON is a type of format that is used to store and transport the data. It stands for JavaScript Object Notation.
While creating Signal bot or a DCA bot on 3Commas, the system automatically generates a unique JSON-file, sometimes it's called "JSON message". It includes all important data to make your bots work. TradingView uses the JSON format to transfer the data in the POST-request.
Here in this article we will describe all parameters JSON file includes.
The difference between "Indicators" and "Strategies".
Indicators are scripts that can perform any calculations written in TradingView's Pine Script language and display them on a chart.
The notification functionality of indicators allows sending a notification when a specific condition is met. The condition can be set either by the user or by the indicator's author.
Strategies are also scripts written in the TradingView Pine Script programming language, but designed to simulate trading and perform testing on historical data to check its effectiveness on TradingView, in other words, it can be named backtesting. As a result of running the strategy, entries, and exits are displayed on the chart using arrow markers.
Strategies also support an alert function that sends a notification when a position changes. Thus, you can implement your strategy on the real market. However, it is important to remember that TradingView alerts will come when requests are executed, which is not the same as placing a request. The data contained in the request will be used to create a notification for your alert and will be replaced with the corresponding value.
How does the JSON message look like
Let's take a closer look at the specifications for the various alerts supported by our Signal Bot. The values enclosed in double curly braces are placeholder values that come from the signal source.
Example:
{
"secret": "the unique token for your bot, don't share it with anyone!",
"max_lag": "300",
"timestamp": "{{timenow}}",
"trigger_price": "{{close}}",
"tv_exchange": "{{exchagne}}",
"tv_instrument": "{{ticker}}",
"action": "enter_long",
"bot_uuid": "signal-bot-uuid",
"order": {
"amount": "{{place_you_amount_here}}",
"currency_type": "quote"
}
}
Main fields description
“secret”
{
...
"secret": "token",
...
}“secret” - mandatory to use. It's a unique 3Commas token for authenticating incoming requests within a specific bot and for a single user. The token is automatically generated when the Signal Bot is created.
Important security note: When setting up and sending webhooks, make sure you do not expose these transmitted fields to public view!
“max_lag”
{
...
"max_lag": "300",
...
}"max_lag" - is an optional field representing the maximum delay that can occur when executing your trading strategy.
Delays can occur for various reasons, such as network latency or data processing time. The check is performed BEFORE the bot attempts to place an order.
Specifying a maximum delay can be useful for evaluating your strategy's performance and managing the time aspects of trading. If the delay exceeds this threshold, it may signal issues in the trading strategy or its execution that must be investigated and possibly addressed.
Maximum allowable signal processing delay: 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.
“timestamp”
{
...
"timestamp": "{{timenow}}",
...
}“timestamp” - is an optional field representing the timestamp of when the signal was generated.
The timestamp can be used to synchronize data, analyze time trends, and understand the temporal sequence of market events.
The signal trigger time is accepted in ISO8601 format.
{{timenow}} data comes to this field from the signal source.
“trigger_price”
{
...
"trigger_price": "{{close}}",
...
}"trigger_price" is an optional field representing the price at which the event or condition triggered the trading signal.
This could be the price of an asset reaching a certain level, such as a crossover of a moving average, support or resistance level, or a price that triggers a specific strategy in your trading system.
The trigger price information is important for understanding what events or conditions cause trading signals to fire and what actions can be taken in response to those signals.
{{close}} data comes from the signal source to this field.
“tv_exchange”
{
...
"tv_exchange": "{{exchagne}}",
...
}"tv_exchange" is a required field representing the information about the exchange to which the trading signal or data is associated.
This field indicates the trading service or exchange from which the trading data is received.
For example, the "tv_exchange" value could 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 the trading data and can also be used to analyze data from specific exchanges or services.
{{exchange}} data comes to this field from the signal source.
“tv_instrument”
{
...
"tv_instrument": "{{ticker}}",
...
}"tv_instrument" is a required field representing the instrument or asset associated with the trading signal or data.
This field indicates the specific financial instrument, such as a futures contract or currency pair, for which the trading data was received.
This information is important for identifying the asset being traded and analyzing its trading activity and characteristics.
{{ticker}} data comes to this field from the signal source.
It is important to note the format used for trading pairs.
For example:
For the currency pair BTC/USDT on Binance Futures perpetual: "BTCUSDT.P" (BTCUSDT/USDT in the 3Commas user interface)
Example of how part of the original message looks in JSON format:
{
...
"tv_exchange": "{{exchange}}",
"tv_instrument": "{{ticker}}",
...
}Here's how you can change it:
{
...
"tv_exchange": "BINANCE",
"tv_instrument": "BTCUSDT.P",
...
}By making these changes, the signal will be applied to the BTCUSDT/USDT pair on 3Commas. Be sure to double-check the trading pair format to ensure accuracy.
“action”
"action" is a required field that represents the action that should be taken in response to the received trading signal or condition.
Please note: Signal actions may differ under different position conditions.
Examples of "action" values may include:
1. "enter_long" - Buy an asset or enter a long position:
{
...
"action": "enter_long",
...
}In case:
if a Long position is open, then the bot will add the funds to this position with an amount of order.amount or the amount indicated while creating the bot;
if there is no open position, the bot will open a Long position with the order.amount or the amount indicated while creating the bot;
If the bot has the "Reverse position" mode turned ON and the Short position is open, the bot will close the Short position at market price (no matter if it's in profit or loss) and open a Long position with the order.amount or the amount indicated while creating the bot.
2. "enter_short" - Sell an asset or enter the Short position.
Example:
{
...
"action": "enter_short",
...
}
In the following cases:
if a short position is open the bot will add funds to the position in the amount of order.amount or the amount specified when the bot was created.
if there is no open position the bot will open a short position in the amount of order.amount or the amount specified when the bot was created.
if the "Reverse position" mode is enabled in the bot and a long position is currently open the bot will close the SmartTrade long position at market price and open a short position (regardless of whether it is currently in profit or loss) in the amount of order.amount or the amount specified when the bot was created.
3. "exit_long" - Sell an asset or exit the long position.
Example:
{
...
"action": "exit_long",
...
}In the following cases:
if a long position is open, check the position. If the volume of the long position is greater than order.amount, then subtract order.amount or the amount specified when the bot was created from the open position.
if the volume of the long position is less than order.amount, then the bot will close the SmartTrade long position at market price.
if there is no open long position the signal is ignored with a status of 'Rejected'.
4. "exit_short" - Buy an asset or exit from the short position.
Example:
{
...
"action": "exit_short",
...
}In the following cases:
if a short position is open check the position. If the volume of the short position is greater than order.amount, then subtract order.amount or the amount specified when the bot was created from the open position.
if the volume of the short position is less than order.amount, then the bot will close the SmartTrade short position at market price.
if there is no open short position the signal is ignored with a status of 'Rejected'.
“bot_uuid”
{
...
"bot_uuid": "signal-bot-uuid",
...
}"bot_uuid" is a required field that represents the unique identifier of the Signal Bot in the 3Commas system.
Important security note - when configuring and sending webhooks, make sure you do not expose these transmitted fields to public view.
“order.amount”
{
...,
"order": {
"amount": {{place_you_amount_here}},
...
}
}order.amount - is used depending on other Signal bot settings.
If in the Signal bot an external source to specify the order size is mentioned, then the bot will wait that the order size information will arrive with signal in this field.
If the order size is already specified in the bot itself, then the bot will take into consideration only these specified settings, and it will ignore the order.amount value even if you enter there any number.
For example, if order.amount equals 100, then the bot will try to buy or sell 100 units of asset.
{{place_you_amount_here}} data comes to this field from the signal source (like TradingView).
“order.currency_type”
“order.currency_type” - is an optional parameter. It sets the currency type (Quote or Base) that will be used in the orders.
This information is important to determine the currency type used in trading, and it provides the accuracy in calculation and trading operations execution.
The value of the "order.currency_type" can be such as:
"quote" - means that the order size is set in Quote currency like USDT in BTC/USDT pair.
"base" - means that the order size is set in Base currency like ETH in ETH/USDT pair.
"margin_percent" - can be set to open the position. It represents the percentage specified in the “amount” field from the number specified in the “Max. initial margin” field of the bot settings.
For example:
“Max. initial margin” is 100 USDT. In the margin_percent setting we write 50%. Real order size will be 100*50%=50 USDT multiplied by the leverage:
{
...,
"order": {
"amount": "{{place_you_amount_here}}",
"currency_type": "margin_percent"
}
}Here is how we can change it:
{
...,
"order": {
"amount": "50",
"currency_type": "margin_percent"
}
}
"position_percent" - can be used to close the position and represents the percentage of the current position size.
For example, if your position is $10000 and "position_percent" is set to 50%, then you will close with this signal half of your current position, or $5000.
If you'd like to close with the signal the entire position (Long or Short) you need to put in this parameter number 100.
Example:{
...,
"order": {
"amount": "{{place_you_amount_here}}",
"currency_type": "position_percent"
}
}You can change it as follows:
{
...,
"order": {
"amount": "50",
"currency_type": "position_percent"
}
}
"order_type"
It is an optional parameter. Here, you can set the Entry long or the Entry short order type to either Market or Limit. You can set this parameter only if you choose the "Send in webhook..." option for an order size type.
For Market order, the message part looks like this:
{
...
"order": {
"amount": "30",
"order_type": "market"
}
}
For Limit order, the message part looks like this:
{
...
"order": {
"amount": "30",
"order_type": "limit",
"currency_type": "quote",
"price": "0.58",
//don't add both "price" and "price_percent"
"price_percent": -5
"price_percent_ref_type": "avg_entry_price"
}
}For "price," you need to specify the exact price for the pair where the bot should place an order.
For "price_percent", you need to input the value (without %) at what distance from the price the bot should place the order when the signal is received.
Also, you can add "price_percent_ref_type" parameter to specify what type of deviation you want to use:
current_price- this is the default setting - in this case the price will be calculated from the current price when the signal was received.base_entry_price- this price is calculated from the deal's Base order price.avg_entry_price- this price is calculated from the average entry price of the deal.
If “price_percent_ref_type” is not added to the code, the bot will, by default, count from the current price at the moment it receives the signal.
Here are some details about using "price_percent" parameters:
"
price_percent" value can be in this range: -99 – +1000 (without “%” symbol);if you input both "
price_percent" and "price", only the "price" parameter will count, and the percent will be ignored;if you send the price higher than current for Long or lower than current for Sell, the order will be executed immediately by the market price;
"currency_type"can be set to either"quote"or"base".
“Take Profit”
If you want your bot to place the Take profit order with the received signal, you can add this into your JSON message:
{
...,
"take_profit": {
"enabled": true,
"steps": [
{
"order_type": "limit",
"price_percent": 50,
"volume_percent": 100,
"trailing": {
"enabled": true,
"percent": 0.2
}
}
]
}
}This part of the message is divided into several commands:
"enabled": true, - turned on, "enabled": false, - turned off;
"steps": - ability to add Take profit steps (explained further in this article);
"order_type": "limit", - limit order, "order_type": "market", - market order;
"price_percent": 50, - price deviation percent to place the Take profit order;
"volume_percent": 100, - size of Take profit order, in percent;
"trailing" - you can enable trailing ("enabled": true,) to your Take profit order and set a deviation ("percent": xx). More about the Trailing take profit feature you can read in this article.
Notes about Multiple take profit.
Multiple take profit can be set to a maximum of 8 steps via JSON message and only up to 4 steps via the Signal bot settings interface.
The sum of "volume_percent" values must equal 100%!
If you want to enable the trailing feature, it can be applied only to the last step. And don't forget to change the "order_type" from Limit to Market - "order_type": "market".
You can read more about the Multiple take profit feature in this article.
Here is an example of the Take profit message with 3 take profit steps and trailing enabled on the last step:
{
...,
"take_profit": {
"enabled": true,
"steps": [
{
"order_type": "limit",
"price_percent": 10,
"volume_percent": 50
},
{
"order_type": "limit",
"price_percent": 20,
"volume_percent": 30
},
{
"order_type": "market",
"price_percent": 30,
"volume_percent": 20,
"trailing": {
"enabled": true,
"percent": 0.2
}
}
]
}
}
If some parameters in the JSON message are not compatible with Signal bot and the bot cannot process them, the signal might have a "Rejected" status.
“Stop Loss”
If you want to add Stop loss order to your trade, you can add this parameter in the JSON message:
{
...,
"stop_loss": {
"enabled": true,
"breakeven": true,
"order_type": "market",
"trigger_price_percent": 5,
"trailing": {
"enabled": true,
"percent": 1
},
"timeout": {
"enabled": true,
"value": 120
}
}
}This part of message is divided into several commands:
"enabled": true, - turned on, "enabled": false, - turned off;
"breakeven" - if "true" it's on, if "false" it's off. Works only if you set at least 2 Take profit targets. You can read more about the Breakeven feature in this article.
"order_type": "market", - Stop loss can be only a market order;
"trigger_price_percent": 5, - price deviation percent to place the Stop loss order;
"trailing" - you can enable trailing ("enabled": true,) to your Stop loss order and set a deviation ("percent": xx). More about the Trailing stop loss feature you can read in this article.
"timeout" - Stop loss timeout, counted in seconds. You can read more about this feature in this article.
Here is the example of how JSON message can look if you want to set 3 Take profit targets and a Stop loss:
{
"secret": "token",
"tv_exchange": "BINANCE",
"tv_instrument": "BTCUSDT.P",
"action": "enter_long",
"bot_uuid": "signal-bot-uuid",
"order": {
"amount": 100,
"currency_type": "quote",
},
"take_profit": {
"enabled": true,
"steps": [
{
"order_type": "limit",
"price_percent": 10,
"volume_percent": 50
},
{
"order_type": "limit",
"price_percent": 20,
"volume_percent": 30
},
{
"order_type": "market",
"price_percent": 30,
"volume_percent": 20,
"trailing": {
"enabled": true,
"percent": 0.2
}
}
]
},
"stop_loss": {
"enabled": true,
"breakeven": false,
"order_type": "market",
"trigger_price_percent": 5,
"trailing": {
"enabled": true,
"percent": 1
},
"timeout": {
"enabled": false,
"value": 120
}
}
}Important addition!
Take profit and Stop loss parameters can only be processed while opening a position! If the signal is considered as an "add_funds", these parameters will be ignored!
Additional JSON codes
"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]
}
FAQ
Is it possible to send signals from a Bitcoin chart to a different trading pair?
Absolutely. To do this, simply replace the placeholders tv_instrument and tv_exchange within the JSON message manually. It's important to pay attention to the format used for trading pairs.
For instance:
BTCUSDT:OKX - spot pair on OKX. (BTC/USDT in 3Commas UI)
BTCUSDT.P:OKX - perpetual linear futures on OKX. (BTC-USDT-SWAP/USDT in 3Commas UI)
BTCUSD.P:OKX - perpetual inverse futures on OKX (BTC-USD-SWAP/BTC in 3Commas UI)
Here's an example of how part of the original JSON message looks:
{ ... "tv_exchange": "{{exchange}}", "tv_instrument": "{{ticker}}" ... }
And here's how you might modify it:
{ ... "tv_exchange": "OKX", "tv_instrument": "1INCHUSDT.P" ... }
By making these changes, the signal would then apply to the 1INCH-USDT-SWAP/USDT pair on 3Commas. Remember to double-check the trading pair format to ensure accuracy.