¡Recordatorio importante!
NO compartas públicamente el mensaje JSON de tu signal bot. Si lo compartiste por accidente, elimina ese bot y crea uno nuevo; de esta manera estarás seguro.
¿Qué es JSON y qué función cumple?
JSON es un tipo de formato que se usa para almacenar y transportar datos. Sus siglas significan JavaScript Object Notation.
Cuando creas un Signal bot o un bot DCA en 3Commas, el sistema genera automáticamente un archivo JSON único, a veces llamado "mensaje JSON". Este archivo incluye todos los datos importantes para que tus bots funcionen. TradingView también usa el formato JSON para transferir datos en las solicitudes POSTERIORES.
Aquí en este artículo te vamos a describir todos los parámetros que incluye el archivo JSON.
La diferencia entre "Indicadores" y "Estrategias".
Los indicadores son scripts que pueden realizar cualquier cálculo escrito en el lenguaje Pine Script de TradingView y mostrarlo en un gráfico.
La función de notificaciones de los indicadores permite enviar una alerta cuando se cumple una condición específica. Tú puedes configurar esta condición o también puede hacerlo el autor del indicador.
Las estrategias también son scripts escritos en el lenguaje Pine Script de TradingView, pero están diseñadas para simular operaciones y realizar pruebas sobre datos históricos para verificar su efectividad en TradingView. En otras palabras, se puede llamar "backtesting". Al ejecutar la estrategia, el sistema muestra las entradas y salidas en el gráfico usando marcadores de flechas.
Las estrategias también admiten una función de alerta que envía una notificación cuando cambia una posición. Así puedes implementar tu estrategia en el mercado real. Sin embargo, es importante que recuerdes que las alertas de TradingView se enviarán cuando se ejecuten las solicitudes, lo cual no es lo mismo que colocar una solicitud. El sistema usará los datos contenidos en la solicitud para crear la notificación de tu alerta y los reemplazará con el valor correspondiente.
Cómo elegir el tipo correcto de alerta: señal personalizada vs. estrategia de TradingView
Elige el tipo de alerta basándote en cómo están estructuradas tus señales:
Señal personalizada: selecciona esta opción si usas fuentes de señales distintas a TradingView o si tus alertas de TradingView envían señales de compra y venta por separado. Tendrás que crear alertas individuales para entrar y salir de las operaciones.
Estrategia de TradingView: selecciona esta opción si tienes una estrategia completa escrita en Pine Script que determine automáticamente los puntos de entrada y salida.
Si ves las opciones de señal de Compra y Venta al crear una alerta en TradingView, significa que estás usando la versión de alerta de un script. En ese caso, elige "Señal personalizada" como tipo de alerta.
¿Cómo se ve el mensaje JSON?
Vamos a analizar más de cerca las especificaciones para las diferentes alertas que admite nuestro Signal Bot. Los valores que aparecen entre dobles llaves son valores de marcador de posición que provienen de la fuente de la señal.
Ejemplo:
{
"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"
}
}
Descripción de los campos principales
“secret”
{
...
"secret": "token",
...
}
“secret” es obligatorio. Es un token único de 3Commas que autentica las solicitudes entrantes dentro de un bot específico y para un solo usuario. El sistema genera este token automáticamente cuando creas el Signal Bot.
Nota importante de seguridad: Cuando configures y envíes webhooks, asegúrate de no exponer estos campos transmitidos al público.
“max_lag”
{
...
"max_lag": "300",
...
}“max_lag” es un campo opcional que representa el retraso máximo que puede ocurrir al ejecutar tu estrategia de trading.
Los retrasos pueden producirse por varias razones, como latencia de red o tiempo de procesamiento de datos. El sistema realiza esta verificación ANTES de que el bot intente colocar una orden.
Especificar un retraso máximo puede ayudarte a evaluar el rendimiento de tu estrategia y gestionar los aspectos de tiempo del trading. Si el retraso supera este umbral, podría indicar problemas en la estrategia o en su ejecución que debes investigar y corregir.
Retraso máximo permitido para el procesamiento de señales: valor entero entre 10 y 86400.
Valor predeterminado: 300. Se mide en segundos.
El valor de “max_lag” se calcula comparando el tiempo entre el envío de la señal (“timestamp”) y el momento en que el bot procesó esa señal por primera vez. Si en el código JSON aparece "max_lag": "300", significa que el retraso permitido es de 300 segundos o 5 minutos. Si el retraso supera el límite especificado, la señal podría considerarse inválida o procesarse con un error.
“timestamp”
{
...
"timestamp": "{{timenow}}",
...
}"timestamp" es un campo opcional que representa la marca de tiempo en la que se generó la señal.
Puedes usar la marca de tiempo para sincronizar datos, analizar tendencias temporales y comprender la secuencia de eventos del mercado.
El sistema acepta la hora de activación de la señal en formato ISO8601.
El dato {{timenow}} que proviene de la fuente de la señal se inserta en este campo.
“trigger_price”
{
...
"trigger_price": "{{close}}",
...
}"trigger_price" es un campo opcional que representa el precio al cual se activó el evento o la condición que generó la señal de trading.
Esto podría ser el precio de un activo que alcanza un determinado nivel, como el cruce de un promedio móvil, un nivel de soporte o resistencia o cualquier otro precio que active una estrategia específica dentro de tu sistema de trading.
La información sobre el precio de activación es importante para entender qué eventos o condiciones provocan la emisión de señales de trading y qué acciones puedes tomar en respuesta.
El dato {{close}} que proviene de la fuente de la señal se inserta en este campo.
“tv_exchange”
{
...
"tv_exchange": "{{exchange}}",
...
}"tv_exchange" es un campo obligatorio que representa la información sobre el exchange al que está asociada la señal o los datos de trading.
Este campo indica el servicio de trading o exchange desde donde se reciben los datos de trading.
Por ejemplo, el valor de "tv_exchange" puede ser BINANCE, OKX, BYBIT, etc., dependiendo del origen de los datos.
Esta información es importante para identificar y rastrear la fuente de los datos y también sirve para analizar datos provenientes de exchanges o servicios específicos.
El dato {{exchange}} que proviene de la fuente de la señal se inserta en este campo.
“tv_instrument”
{
...
"tv_instrument": "{{ticker}}",
...
}"tv_instrument" es un campo obligatorio que representa el instrumento o activo asociado con la señal o los datos de trading.
Este campo indica el instrumento financiero específico, como un contrato de futuros o un par de divisas, para el cual se recibió la señal.
Esta información es clave para identificar el activo que se está operando y analizar su actividad y características en el mercado.
El dato {{ticker}} que proviene de la fuente de la señal se inserta en este campo.
Es importante tener en cuenta el formato utilizado para los pares de trading.
Por ejemplo:
Para el par BTC/USDT en Binance Futures Perpetual: "BTCUSDT.P" (que en la interfaz de usuario de 3Commas aparece como BTCUSDT/USDT).
Ejemplo de cómo se ve una parte del mensaje original en formato JSON:
{
...
"tv_exchange": "{{exchange}}",
"tv_instrument": "{{ticker}}",
...
}
Así puedes modificarlo:
{
...
"tv_exchange": "BINANCE",
"tv_instrument": "BTCUSDT.P",
...
}Al hacer estos cambios, la señal se aplicará al par BTCUSDT/USDT en 3Commas. Asegúrate de revisar dos veces el formato del par de trading para garantizar su precisión.
“action”
"action" es un campo obligatorio que representa la acción que debe tomarse como respuesta a la señal de trading recibida o a la condición detectada.
Importante: Las acciones de la señal pueden variar según el estado de la posición en ese momento.
Algunos ejemplos de valores para "action" incluyen:
1. "enter_long". Comprar un activo o abrir una posición en largo:
{
...
"action": "enter_long",
...
}
En los siguientes casos:
Si ya hay una posición en largo abierta, el bot agregará fondos a esa posición según el valor de order.amount o la cantidad que indicaste al crear el bot.
Si no hay una posición abierta, el bot abrirá una posición en largo con order.amount o la cantidad configurada en la creación del bot.
Si el bot tiene activado el modo "Revertir posición" y hay una posición en corto abierta, el bot cerrará esa posición en corto al precio de mercado (ya sea con ganancia o pérdida) y abrirá una posición en largo con el order.amount o el importe indicado al crear el bot.
2. "enter_short". Vender un activo o abrir una posición en corto.
Ejemplo:
{
...
"action": "enter_short",
...
}
En los siguientes casos:
Si ya hay una posición en corto abierta, el bot agregará fondos a la posición por el valor de order.amount o la cantidad que configuraste al crear el bot.
Si no hay ninguna posición abierta, el bot abrirá una posición en corto con el valor de order.amount o la cantidad que configuraste al crear el bot.
Si el bot tiene activado el modo "Revertir posición" y actualmente hay una posición en largo abierta, el bot cerrará la posición larga de SmartTrade al precio de mercado (sin importar si hay ganancia o pérdida) y abrirá una posición en corto con el valor de order.amount o la cantidad configurada al crear el bot.
3. "exit_long". Vender un activo o cerrar una posición en largo.
Ejemplo:
{
...
"action": "exit_long",
...
}En los siguientes casos:
Si hay una posición en largo abierta, revise la posición. Si el volumen de esa posición es mayor que order.amount, restará esa cantidad (o la que configuraste al crear el bot) de la posición abierta.
Si el volumen de la posición en largo es menor que order.amount, el bot cerrará la posición larga de SmartTrade al precio de mercado.
Si no hay una posición en largo abierta, la señal se ignorará y su estado será "Rechazada".
4. "exit_short". Comprar un activo o cerrar una posición en corto.
Ejemplo:
{
...
"action": "exit_short",
...
}En los siguientes casos:
Si hay una posición en corto abierta, revise la posición. Si el volumen de esa posición es mayor que order.amount, restará esa cantidad (o la que configuraste al crear el bot) de la posición abierta.
Si el volumen de la posición en corto es menor que order.amount, el bot cerrará la posición corta de SmartTrade al precio de mercado.
Si no hay una posición en corto abierta, la señal se ignorará y su estado será "Rechazada".
“bot_uuid”
{
...
"bot_uuid": "signal-bot-uuid",
...
}"bot_uuid" es un campo obligatorio que representa el identificador único del Signal Bot dentro del sistema de 3Commas.
Nota de seguridad importante: Cuando configures y envíes webhooks, asegúrate de no exponer públicamente estos campos transmitidos.
“order.amount”
{
...,
"order": {
"amount": {{place_you_amount_here}},
...
}
}order.amount se usa según la configuración del Signal bot.
Si en el Signal bot configuraste que una fuente externa defina el tamaño de la orden, entonces el bot esperará recibir esa información junto con la señal en este campo.
Si ya especificaste el tamaño de la orden directamente en la configuración del bot, entonces el bot usará solo esa configuración e ignorará cualquier número que ingreses en order.amount.
Por ejemplo, si order.amount vale 100, el bot intentará comprar o vender 100 unidades del activo.
El dato {{place_you_amount_here}} que proviene de la fuente de la señal (como TradingView) se inserta en este campo.
“order.currency_type”
order.currency_type es un parámetro opcional. Define el tipo de moneda (cotizada o base) que se usará en las órdenes.
Esta información es clave para determinar con precisión el tipo de moneda con el que vas a operar, lo que mejora la exactitud del cálculo y la ejecución de las operaciones.
Los valores posibles para "order.currency_type" son:
"quote": significa que el tamaño de la orden se establece en la moneda de cotización, por ejemplo USDT en el par BTC/USDT.
"base": significa que el tamaño de la orden se establece en la moneda base, como ETH en el par ETH/USDT.
"margin_percent": se puede usar para abrir una posición. Representa el porcentaje especificado en el campo “amount” a partir del número configurado en el campo “Margen inicial máximo” de la configuración del bot.
Por ejemplo:
Si el "Margen inicial máximo" es 100 USDT y en margin_percent escribes 50 %, el tamaño real de la orden será 100 * 50 % = 50 USDT, multiplicado por el apalancamiento:
{
...,
"order": {
"amount": "{{place_you_amount_here}}",
"currency_type": "margin_percent"
}
}Puedes cambiarlo de la siguiente manera:
{
...,
"order": {
"amount": "50",
"currency_type": "margin_percent"
}
}"position_percent": se puede usar para cerrar una posición. Representa el porcentaje del tamaño actual de la posición.
Por ejemplo, si tu posición es de $10 000 y "position_percent": está en 50 %, esta señal cerrará la mitad de la posición, es decir, $5000.
Si quieres cerrar toda la posición (en largo o en corto) con la señal, debes ingresar el número 100 en este parámetro.
Ejemplo:
{
...,
"order": {
"amount": "{{place_you_amount_here}}",
"currency_type": "position_percent"
}
}Puedes cambiarlo de la siguiente manera:
{
...,
"order": {
"amount": "50",
"currency_type": "position_percent"
}
}
"order_type"
Es un parámetro opcional. Aquí puedes establecer el tipo de orden de entrada larga o corta como mercado o límite. Solo puedes configurar este parámetro si eliges la opción "Enviar en webhook..." para el tipo de tamaño de orden.
Para una orden de mercado, la parte del mensaje se verá así:
{
...
"order": {
"amount": "30",
"order_type": "market"
}
}
Para una orden limitada, la parte del mensaje se verá así:
{
...
"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"
}
}
Para "price", necesitas especificar el precio exacto para el par donde el bot debe colocar la orden.
Para "price_percent", debes ingresar el valor (sin el símbolo %) que indica a qué distancia del precio actual el bot debe colocar la orden cuando reciba la señal.
También puedes agregar el parámetro "price_percent_ref_type" para definir desde qué tipo de precio quieres calcular la desviación:
current_price: es la opción predeterminada. En este caso, el bot calculará el precio desde el valor actual al momento de recibir la señal.
base_entry_price: el bot calculará desde el precio de la orden base de la operación.
avg_entry_price: el cálculo se hace desde el precio de entrada promedio de la operación.
Si no agregas "price_percent_ref_type" en el código, el bot usará por defecto el precio actual cuando reciba la señal.
Detalles importantes sobre el uso de "price_percent":
El valor de "price_percent" puede estar entre -99 y +1000 (sin el símbolo de %).
Si incluyes tanto "price_percent" como "price", el bot usará solo el valor de "price" e ignorará el porcentaje.
Si envías un precio más alto que el actual para una orden Long, o más bajo para una orden Sell, el bot ejecutará la orden de inmediato al precio de mercado.
"currency_type" se puede configurar como "quote" o "base".
“Take Profit”
Si quieres que tu bot coloque una orden de Take Profit con la señal recibida, puedes incluir esta sección en tu mensaje JSON.
{
...,
"take_profit": {
"enabled": true,
"steps": [
{
"order_type": "limit",
"price_percent": 50,
"volume_percent": 100,
"trailing": {
"enabled": true,
"percent": 0.2
}
}
]
}
}
Esta parte del mensaje se divide en varios comandos:
"enabled": true, activa el Take Profit; "enabled": false, lo desactiva.
"steps": te permite agregar pasos de Take Profit (más adelante se explican en detalle).
"order_type": "limit", orden limitada; "order_type": "market", orden de mercado.
"price_percent": 50, porcentaje de desviación para colocar la orden de Take Profit.
"volume_percent": 100, tamaño de la orden de Take Profit, expresado en porcentaje.
"trailing": puedes activar el trailing con "enabled": true y establecer una desviación con "percent": xx. Para obtener más información sobre la función Trailing Take Profit, lee este artículo.
Notas sobre el Take Profit múltiple:
Puedes configurar hasta 8 pasos de Take Profit usando un mensaje JSON, pero solo hasta 4 pasos desde la interfaz del Signal bot.
La suma de los valores "volume_percent" debe ser exactamente 100 %.
Si vas a activar el trailing, solo puedes hacerlo en el último paso, y recuerda cambiar el "order_type" de Límite a Mercado: "order_type": "market".
Puede obtener más información sobre la función Take Profit Múltiple en este artículo.
Este es un ejemplo del mensaje JSON con 3 pasos de Take Profit y trailing activado en el último paso:
{
...,
"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
}
}
]
}
}Si el mensaje JSON contiene parámetros que no son compatibles con el Signal bot y el bot no puede procesarlos, la señal recibida puede tener el estado "Rechazada".
“Stop Loss”
Si quieres agregar una orden de Stop Loss a tu operación, puedes incluir este parámetro en el mensaje JSON:
{
...,
"stop_loss": {
"enabled": true,
"breakeven": true,
"order_type": "market",
"trigger_price_percent": 5,
"trailing": {
"enabled": true,
"percent": 1
},
"timeout": {
"enabled": true,
"value": 120
}
}
}Esta parte del mensaje se divide en varios comandos:
"enabled": true, activa el Take Profit; "enabled": false, lo desactiva.
"breakeven": si está en "true", se activa; si está en "false", se desactiva. Esta función solo funciona si configuraste al menos 2 objetivos de Take Profit. Puede obtener más información sobre esta función de Breakeven en este artículo.
"order_type": "market", el Stop Loss solo puede ser una orden de mercado.
"trigger_price_percent": 5, porcentaje de desviación de precio para colocar la orden de Stop Loss.
"trailing": puedes activar el trailing con "enabled": true y establecer la desviación con "percent": xx. Para obtener más información sobre el Stop Loss con trailing, lee este artículo.
"timeout": define el tiempo de espera para el Stop Loss, en segundos. Puedes obtener más información sobre esta función en este artículo.
Así podría verse un mensaje JSON si deseas configurar 3 objetivos de Take Profit y un 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
}
}
}¡Importante!
Los parámetros de Take Profit y Stop Loss solo se procesan al abrir una posición. Si la señal se considera como "add_funds", estos parámetros serán ignorados.
Códigos JSON adicionales
"enable" / "disable"
Esta acción activará los Signal bots:
{
...
"action": "enable",
...
}Esta acción detendrá los Signal bots:
{
...
"action": "disable",
...
}
Ejemplos de uso
Detener todos los Signal bots activos en tu cuenta de 3Commas
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable"
}
Detener todos los Signal bots activos en cuentas específicas de exchange
Necesitarás saber el ID de la cuenta de exchange conectada. Ve a la página Mi portafolio, encuentra el exchange que necesitas, haz clic en el menú de los 3 puntos, haz clic en Ver y verás el ID en la barra de direcciones:
Para agregar más de una cuenta de exchange, colócalas entre corchetes y sepáralas con comas:
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"account_ids": [3345345, 3345347]
}
Detén uno o varios Signal bots específicos
Necesitarás saber el UUID de los bots de Signal. Pasa el cursor sobre el botón de información (i) junto al bot y verás su UUID. Si quieres agregar varios bots, escribe los UUID entre comillas dentro de los corchetes y sepáralos con comas:
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"bot_uuid": ["xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"]
}
Detén todos los Signal bots Long activos en tus cuentas de Exchange
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"scopes": ["long", "real"]
}
Detén todos los Signal bots Long activos en la cuenta Demo
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"scopes": ["long", "paper"]
}
Detén los Signal bots activos y cierra las posiciones
{
...
"action": "disable",
"positions_sub_action": "market_close"
...
}
Si quieres cerrar la posición a precio de mercado, necesitas agregar la línea:
"positions_sub_action": "market_close"
Aquí tienes un ejemplo:
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"positions_sub_action": "market_close"
}
Si quieres cancelar la posición y manejarla manualmente más tarde, necesitas agregar la línea:
"positions_sub_action": "cancel"
Aquí tienes un ejemplo:
{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"positions_sub_action": "cancel"
}
Notas importantes.
En los bots de tipo señal personalizada, la señal para deshabilitar una posición Long o Short también cancelará el bot completo, no solo un lado.
Si quieres deshabilitar por separado los bots Long o Short, necesitas crear dos bots separados: uno con estrategia Long y otro con estrategia Short.
Puedes combinar diferentes parámetros y funcionarán con una lógica de “Y”. Si todos los parámetros cumplen las condiciones, la señal se enviará y se procesará. Si al menos un parámetro no se cumple, la señal se rechazará.
Ejemplo:{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"scopes": ["long", "real"],
"account_ids": [1, 2, 3]
}
Preguntas frecuentes
¿Es posible enviar señales desde un gráfico de Bitcoin a un par de trading diferente?
Claro que sí. Para hacerlo, simplemente reemplaza manualmente los valores de los campos tv_instrument y tv_exchange dentro del mensaje JSON. Es muy importante prestar atención al formato usado para los pares de trading.
Por ejemplo:
BTCUSDT:OKX, par spot en OKX. (BTC/USDT en la interfaz de 3Commas)
BTCUSDT.P:OKX, futuros perpetuos lineales en OKX. (BTC-USDT-SWAP/USDT en la interfaz de 3Commas)
BTCUSD.P:OKX, futuros perpetuos inversos en OKX (BTC-USD-SWAP/BTC en la interfaz de 3Commas)
Así se ve una parte del mensaje JSON original:
{ ... "tv_exchange": "{{exchange}}", "tv_instrument": "{{ticker}}" ... }
Y así podrías modificarlo:
{ ... "tv_exchange": "OKX", "tv_instrument": "1INCHUSDT.P" ... }
Al hacer estos cambios, la señal se aplicará al par 1INCH-USDT-SWAP/USDT en 3Commas. Asegúrate de revisar el formato del par de trading para garantizar que sea correcto.
Únete a la conversación: conéctate con otros traders en nuestra comunidad oficial de Telegram.