К основному содержимому

Signal боты: Формат JSON для типа оповещения — Пользовательский сигнал

Узнайте подробнее, что такое JSON файл в ботах с типом Пользовательский сигнал и какие параметры он включает.

Важное напоминание!

Никогда не делитесь JSON сообщением вашего Signal бота. Если вы случайно поделились им, удалите бота и создайте нового — в этом случае вы будете в безопасности.

Что такое JSON и какую функцию он выполняет?

JSON — это формат, который используется для хранения и передачи данных. Это аббревиатура от JavaScript Object Notation.

При создании Signal или DCA бота в 3Commas, система автоматически генерирует уникальный JSON файл (иногда его называют JSON сообщение). Он включает все важные данные, необходимые для правильной работы вашего бота. TradingView использует формат JSON для передачи данных в POST запросе.

В этой статье мы опишем все параметры, которые включает JSON-файл.

Разница между Индикаторами и Стратегиями.

Индикаторы — это скрипты, написанные на языке Pine Script в TradingView, которые могут выполнять любые расчеты и отображать их на графике.

Функциональность уведомлений у индикаторов позволяет отправлять оповещение при выполнении определенного условия. Условие может быть задано пользователем или автором индикатора.

Стратегии — это также скрипты на языке Pine Script, но они предназначены для симуляции торговли и тестирования на исторических данных TradingView, то есть, другими словами, для бэктестов.

В результате работы стратегии точки входа и выхода отображаются на графике с помощью стрелок.

Стратегии также поддерживают функцию оповещений, которые отправляют уведомление при изменении позиции. Таким образом, вы можете реализовать стратегию на реальном рынке. Данные, содержащиеся в запросе, используются для создания оповещения и в оповещении подставляются соответствующие значения.


Выбор правильного типа оповещения: Пользовательский сигнал или TradingView Стратегия

Выбирайте тип оповещения в зависимости от структуры ваших сигналов:

  • Пользовательский сигнал: Выберите этот вариант, если вы используете источники сигналов, отличные от TradingView, или если ваши оповещения TradingView отправляют отдельные сигналы Buy и Sell (покупки и продажи). В этом случае необходимо создавать отдельные оповещения для входа и выхода из сделки.

  • TradingView Стратегия: Выберите этот вариант, если у вас есть полноценная стратегия на Pine Script, которая автоматически определяет точки входа и выхода.

Если при создании оповещения в TradingView вы видите варианты Buy и Sell, значит вы используете алерт-версию скрипта. В таком случае вам следует выбрать тип оповещения — Пользовательский сигнал.


Как выглядит JSON сообщение

Давайте подробнее рассмотрим различные JSON сообщения, которые поддерживаются Signal ботом. Значения в двойных фигурных скобках, являются значениями-заполнителями, которые поступают из источника сигнала.

Пример:

{
"secret": "the unique token for your bot, don't share it with anyone!",
"max_lag": "300",
"timestamp": "{{timenow}}",
"trigger_price": "{{close}}",
"tv_exchange": "{{exchange}}",
"tv_instrument": "{{ticker}}",
"action": "enter_long",
"bot_uuid": "signal-bot-uuid",
"order": {
"amount": "{{place_you_amount_here}}",
"currency_type": "quote"
}
}

Совет: Точные и динамические значения

  • Если вы хотите задать точные значения, такие как биржа, торговая пара или объем, не используйте фигурные скобки {{ }}.

  • Скобки {{ }} используются только тогда, когда источник сигнала (например, TradingView) автоматически заполняет эти поля.

  • Пример (точные значения):

    "tv_exchange": "BINANCE",
    "tv_instrument": "BTCUSDT.P"
  • Неправильное:

    "tv_exchange": "{{BINANCE}}",
    "tv_instrument": "{{BTCUSDT.P}}"

Описание основных полей

“secret”

{
...
"secret": "token",
...
}

“secret” — обязательное поле. Это уникальный токен для определения входящих запросов в рамках конкретного бота и пользователя. Токен генерируется автоматически при создании Signal бота.

Важное примечание: Не делитесь публично этим параметром!


“max_lag”

{
...
"max_lag": "300",
...
}

"max_lag" — необязательное поле. Определяет максимальную задержку, которая может возникнуть при выполнении вашей стратегии.

Задержки могут возникать по различным причинам. Проверка выполняется ДО того, как бот попытается разместить ордер.

Указание максимальной задержки может быть полезным для оценки эффективности вашей стратегии и управления временными аспектами торговли. Если задержка превышает этот порог, это может сигнализировать о проблемах в торговой стратегии или её исполнении, которые необходимо проверить и, возможно, устранить.

Максимально допустимая задержка: целое число от 10 до 86400.

Значение по умолчанию: 300. Измеряется в секундах.

Значение "max_lag" рассчитывается путем сравнения времени отправки сигнала "timestamp" и момента, когда бот впервые обработал этот сигнал. Если в JSON сообщении указано "max_lag": "300", это означает, что допустимая задержка составляет 300 секунд или 5 минут. Если значение задержки превышает указанный лимит, сигнал может считаться недействительным или будет обработан с ошибкой.


“timestamp”

{
...
"timestamp": "{{timenow}}",
...
}

“timestamp” — необязательное поле. Представляет отметку времени, когда был сгенерирован сигнал.

Отметка времени может использоваться для синхронизации данных, анализа временных трендов и понимания временной последовательности событий.

Время срабатывания сигнала принимается в формате ISO8601.

Значения {{timenow}} поступают в это поле из источника сигнала.


“trigger_price”

{
...
"trigger_price": "{{close}}",
...
}

"trigger_price" - необязательное поле. Представляет цену, при которой условие сработало.

Это может быть цена актива, достигшего определенного ценового уровня, пересечение скользящей средней, достижение уровня поддержки или сопротивления.

Информация о цене срабатывания важна для понимания того, какие события или условия вызывают срабатывание сигналов и какие действия можно предпринять при их срабатывании.

Значения {{close}} поступают из источника сигнала.


“tv_exchange”

{
...
"tv_exchange": "{{exchange}}",
...
}

"tv_exchange" — обязательное поле, представляющее информацию о бирже, к которой относится сигнал или данные.

Это поле указывает на биржу, откуда были получены данные.

Например, значение "tv_exchange" может быть BINANCE, OKX, BYBIT и так далее, в зависимости от того, откуда поступают данные.

Эта информация важна для идентификации и отслеживания источника данных, а также может использоваться для анализа данных с конкретных бирж.

Значения {{exchange}} поступают из источника сигнала.


“tv_instrument”

{
...
"tv_instrument": "{{ticker}}",
...
}

tv_instrument" — обязательное поле. Представляет актив, связанный с сигналом.

Это поле указывает на конкретный финансовый инструмент, такой как фьючерсный контракт или валютная пара, для которого были получены данные.

Эта информация важна для идентификации торгуемого актива и анализа его торговой активности и характеристик.

Значения {{ticker}} поступают из источника сигнала.

Важно обратить внимание на формат, используемый для торговых пар.

Например:

  • Для пары BTC/USDT на Binance Futures perpetual: "BTCUSDT.P" (BTCUSDT/USDT в интерфейсе 3Commas)

Пример того, как часть исходного сообщения выглядит в формате JSON:

{
...
"tv_exchange": "{{exchange}}",
"tv_instrument": "{{ticker}}",
...
}

Вот как вы можете изменить это:

{
...
"tv_exchange": "BINANCE",
"tv_instrument": "BTCUSDT.P",
...
}

Внеся эти изменения, сигнал будет применен к паре BTCUSDT/USDT в 3Commas. Обязательно проверьте формат пары, чтобы убедиться в его корректности.


“action”

"action" — обязательное поле. Представляет действие, которое должно быть выполнено в ответ на полученный сигнал.

Обратите внимание: действия сигнала могут отличаться в зависимости от состояния позиции.

Примеры значений "action":

1. "enter_long" - Купить актив или открыть лонг позицию.

{
...
"action": "enter_long",
...
}

В случае:

  • если лонг позиция уже открыта, бот добавит средства к этой позиции в размере, указанном при создании бота или в поле “amount”;

  • если открытой позиции нет, бот откроет лонг позицию в размере, указанном при создании бота или в поле “amount”;

  • если в боте включен режим "Разворот позиции" и открыта шорт позиция, бот закроет шорт позицию по рыночной цене (независимо от того, прибыльная ли она или убыточная) и откроет лонг позицию в размере, указанном при создании бота или в поле “amount”.

2. "enter_short" - Продать актив или открыть шорт позицию.

Example:

{
...
"action": "enter_short",
...
}

В случае:

  • если шорт позиция уже открыта, бот добавит средства к этой позиции в размере, указанном при создании бота или в поле “amount”;

  • если открытой позиции нет, бот откроет шорт позицию в размере, указанном при создании бота или в поле “amount”;

  • если в боте включен режим "Разворот позиции" и открыта лонг позиция, бот закроет лонг позицию по рыночной цене (независимо от того, прибыльная ли она или убыточная) и откроет шорт позицию в размере, указанном при создании бота или в поле “amount”.

3. "exit_long" - Продать актив или выйти из лонг позиции.

Example:

{
...
"action": "exit_long",
...
}

В случае:

  • если лонг позиция открыта и объем лонг позиции больше чем “amount”, тогда будет вычтен объем, указанный при создании бота или в поле “amount”, из открытой позиции.

  • если объем лонг позиции меньше чем “amount”, тогда бот закроет SmartTrade с лонг позицией по рыночной цене.

  • если открытой лонг позиции нет, сигнал проигнорируется со статусом “Отклонено”.

4. "exit_short" - Купить актив или выйти из шорт позиции.

Example:

{
...
"action": "exit_short",
...
}

В случае:

  • если шорт позиция открыта и объем шорт позиции больше чем “amount”, тогда будет вычтен объем, указанный при создании бота или в поле “amount”, из открытой позиции.

  • если объем шорт позиции меньше чем “amount”, тогда бот закроет SmartTrade с шорт позицией по рыночной цене.

  • если открытой лонг позиции нет, сигнал проигнорируется со статусом “Отклонено”.


“bot_uuid”

{
...
"bot_uuid": "signal-bot-uuid",
...
}

"bot_uuid" — обязательное поле. Уникальный идентификатор Signal бота в 3Commas.

Важное примечание: Не делитесь этим параметром в публичном доступе!


“order.amount”

{
...,
"order": {
"amount": {{place_you_amount_here}},
...
}
}

order.amount — используется в зависимости от других настроек Signal бота.

Если в Signal боте указано, что внешний источник должен передавать размер ордера, тогда бот будет ожидать, что информация о размере ордера поступит в этом поле вместе с сигналом.

Если размер ордера уже указан в самом боте, тогда бот будет учитывать только заданные настройки и проигнорирует значение order.amount, даже если вы укажете там какое-то значение.

Значения {{place_you_amount_here}} поступают в это поле из источника сигнала (например, TradingView).


“order.currency_type”

order.currency_type — необязательное или обязательное поле в зависимости от настройки размера ордера вашего бота. Определяет единицу измерения для order.amount.

  • Необязательное, если размер ордера = котируемая, базовая или общий объем инвестиций, % (размер берется из настроек бота; можно не указывать currency_type).

  • Обязательное, если размер ордера = Отправить в webhook… (котируемая, базовая или %)

Напоминание: Если вы не укажете currency_type при любом варианте “Отправить в webhook…”, сигнал завершится с ошибкой.

Значение "order.currency_type" может быть следующим:

  • "quote" — объем в валюте котировки (например, USDT в BTC/USDT)

  • "base" — объем в базовой валюте (например, BTC в BTC/USDT)

  • "margin_percent" — может использоваться для открытия позиции. Представляет процент, указанный в поле “amount”, от значения, указанного в поле “Макс. сумма инвестиций” в настройках бота.
    Например:
    “Макс. использование маржи” составляет 100 USDT. В настройке margin_percent мы указываем 50%. Реальный размер ордера будет 100*50%=50 USDT, умноженные на кредитное плечо:

{
...,
"order": {
"amount": "{{place_you_amount_here}}",
"currency_type": "margin_percent"
}
}

Вот как это можно изменить:

{
...,
"order": {
"amount": "50",
"currency_type": "margin_percent"
}
}
  • "position_percent" — может использоваться для закрытия позиции и представляет процент от текущего размера позиции.

    Например, если ваша позиция составляет $10000 и "position_percent" установлен на 50%, тогда по этому сигналу вы закроете половину текущей позиции, или $5000.

    Если вы хотите закрыть сигналом всю позицию (Лонг или Шорт), необходимо указать в этом поле число 100.

    Пример:

    {
    ...,
    "order": {
    "amount": "{{place_you_amount_here}}",
    "currency_type": "position_percent"
    }
    }

    Вы можете изменить это следующим образом:

    {
    ...,
    "order": {
    "amount": "50",
    "currency_type": "position_percent"
    }
    }

"order_type"

Это необязательный параметр. Здесь вы можете установить тип ордера для Лонг ордера на вход или Шорт ордера на входМаркет или Лимит. Вы можете задать этот параметр только если выбрали тип размера ордера “Отправить в webhook…”.

Для рыночного (маркет) ордера сообщение выглядит так:

{
...
"order": {
"amount": "30",
"order_type": "market"
}
}

Для лимитного ордера сообщение выглядит так:

{
...
"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"
}
}

Для "price," необходимо указать точную цену пары, по которой бот должен разместить ордер.

Для "price_percent" необходимо указать значение (без символа %) — на каком расстоянии от цены бот должен разместить ордер при получении сигнала.

Также вы можете добавить параметр "price_percent_ref_type", чтобы указать, от какой цены должно рассчитываться отклонение:

  • current_price - это значение по умолчанию — в этом случае цена будет рассчитываться от текущей цены на момент получения сигнала.

  • base_entry_price - цена рассчитывается от цены базового ордера.

  • avg_entry_price - цена рассчитывается от средней цены входа по сделке.

Если “price_percent_ref_type” не добавлен в код, бот по умолчанию будет рассчитывать отклонение от текущей цены на момент получения сигнала.

Вот некоторые детали использования параметра "price_percent":

  • "price_percent" может быть в диапазоне от -99 до +1000 (без символа %);

  • если вы укажете одновременно "price_percent" и "price", будет учитываться параметр "price", а "price_percent" будет проигнорирован;

  • если вы отправите цену выше текущей для Лонг или ниже текущей для Шорт, ордер будет исполнен немедленно по рыночной цене;

  • "currency_type" может быть установлен как "quote" или "base".


Тейк-профит

Если вы хотите, чтобы бот разместил Тейк-профит ордер после получения сигнала, вы можете добавить его в ваше JSON сообщение:

{
...,
"take_profit": {
"enabled": true,
"steps": [
{
"order_type": "limit",
"price_percent": 50,
"volume_percent": 100,
"trailing": {
"enabled": true,
"percent": 0.2
}
}
]
}
}

Эта часть сообщения разделена на несколько команд:

  • "enabled": true — включен, "enabled": false — отключен;

  • "steps" — возможность добавить шаги для Тейк-профит (подробнее объясняется далее в статье);

  • "order_type": "limit" — лимитный ордер, "order_type": "market" — рыночный (маркет) ордер;

  • "price_percent": 50 — процент отклонения цены для размещения Тейк-профит ордера;

  • "volume_percent": 100 — размер Тейк-профит ордера в процентах;

  • "trailing" — вы можете включить трейлинг ("enabled": true) для Тейк-профит ордера и задать отклонение ("percent": xx). Подробнее о функции Трейлинг Тейк-профит вы можете прочитать в этой статье.

Примечания о Тейк-профите с несколькими целями

  • Для Тейк-профит можно настроить максимум 8 шагов через JSON сообщение и только до 4 шагов через интерфейс Signal бота.

  • Сумма значений "volume_percent" должна равняться 100%!

  • Если вы хотите включить функцию трейлинга, то она будет применена только к последнему шагу. И не забудьте изменить "order_type" с limit на market — "order_type": "market".

Подробнее о функции Тейк-профите с несколькими целями вы можете прочитать в этой статье.

Вот пример сообщения с 3 шагами Тейк-профита и включенным трейлингом на последнем шаге:

{
...,
"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
}
}
]
}
}

Если некоторые параметры в JSON сообщении несовместимы с Signal ботом и бот не может их обработать, сигнал может получить статус “Отклонен”.


Стоп-лосс

Если вы хотите добавить Стоп-лосс ордер к вашей сделке, вы можете добавить этот параметр в JSON сообщение:

{
...,
"stop_loss": {
"enabled": true,
"breakeven": true,
"order_type": "market",
"trigger_price_percent": 5,
"trailing": {
"enabled": true,
"percent": 1
},
"timeout": {
"enabled": true,
"value": 120
}
}
}

Эта часть сообщения разделена на несколько команд:

  • "enabled": true — включен, "enabled": false — отключен;

  • "breakeven" — если "true", включен, если "false", отключен. Работает только если вы установили как минимум 2 цели для Тейк-профит. Подробнее о функции Стоп-лосс в безубыток.

  • "order_type": "market" — Стоп-лосс может быть только рыночным ордером;

  • "trigger_price_percent": 5 — процент отклонения цены для размещения ордера;

  • "trailing" — вы можете включить трейлинг ("enabled": true) для Стоп-лосс ордера и задать отклонение ("percent": xx). Подробнее о функции Трейлинг Стоп-лосс вы можете прочитать в этой статье;

  • "timeout" — таймаут Стоп-лосс, измеряется в секундах. Подробнее о таймауте вы можете прочитать в этой статье.

Вот пример того, как может выглядеть JSON сообщение, если вы установите 3 цели Тейк-профит и Стоп-лосс:

{
"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
}
}
}

Важное примечание!

Тейк-профит и Стоп-лосс могут быть обработаны только при открытии позиции! Если сигнал рассматривается как "add_funds", эти параметры будут проигнорированы!


Дополнительные параметры для JSON сообщения

"enable"/"disable"

Это действие активирует Signal бота:

{
...
"action": "enable",
...
}

Это действие остановит Signal бота:

{
...
"action": "disable",
...
}

Примеры использования

Остановить всех активных Signal ботов на вашем аккаунте 3Commas

{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable"
}

Остановить всех активных Signal ботов конкретной биржи

Вам нужно знать ID подключенного аккаунта (биржи) — на странице Мое портфолио найдите нужную биржу, нажмите на меню из 3 точек, выберите Просмотр, и вы увидите ID в адресной строке браузера:

Чтобы добавить более одного аккаунта, необходимо поместить их в квадратные скобки и разделить запятой:

{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"account_ids": [3345345, 3345347]
}

Остановить одного или нескольких конкретных ботов

Вам нужно знать UUID этих ботов. Наведите курсор на кнопку ⓘ рядом с ботом, и вы увидите его UUID. Если вы хотите добавить несколько ботов, вы можете записать UUID в кавычках внутри квадратных скобок и разделить их запятой:

{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"bot_uuid": ["xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"]
}

Остановить всех активных Signal ботов с Лонг стратегией

{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"scopes": ["long", "real"]
}

Остановить Signal ботов и закрыть их активные позиции

{
...
"action": "disable",
"positions_sub_action": "market_close"
...
}

Если вы хотите закрыть позицию по рыночной цене, необходимо добавить строку:

"positions_sub_action": "market_close"

Пример:

{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"positions_sub_action": "market_close"
}

Если вы хотите отменить позицию и управлять вручную позже, необходимо добавить строку:

"positions_sub_action": "cancel"

Пример:

{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"positions_sub_action": "cancel"
}

Важные примечания

  • Для ботов с типом “Пользовательский сигнал”, сигнал на отключение Лонг или Шорт позиции также отменит и другую позицию.

  • Если вы хотите отключать отдельно Лонг или Шорт ботов, необходимо создать два отдельных бота — один со стратегией Лонг и один со стратегией Шорт.

  • Разные параметры могут быть объединены и будут работать по логике “И”. Если все параметры соответствуют условиям, сигнал будет принят и обработан. Сигнал будет отклонен, если хотя бы один параметр не выполнен.
    Пример:

{
"secret": "xxxxxxxxx.xxxxxxxxxxx.xxxxxxxxxxx",
"max_lag": "300",
"timestamp": "{{timenow}}",
"action": "disable",
"scopes": ["long", "real"],
"account_ids": [1, 2, 3]
}


Частые вопросы

Можно ли отправлять сигналы с графика BTC на другую торговую пару?

Да. Для этого просто вручную замените tv_instrument и tv_exchange в JSON сообщении. Важно обращать внимание на формат, используемый для торговых пар.

Например:

BTCUSDT:OKX - спотовая пара на OKX (BTC/USDT в интерфейсе 3Commas)

BTCUSDT.P:OKX - бессрочные линейные фьючерсы на OKX (BTC-USDT-SWAP/USDT в интерфейсе 3Commas)

​BTCUSD.P:OKX - бессрочные инверсные фьючерсы на OKX (BTC-USD-SWAP/BTC в интерфейсе 3Commas)

Вот пример того, как выглядит часть исходного сообщения:

{ ... "tv_exchange": "{{exchange}}", "tv_instrument": "{{ticker}}" ... }

А вот как вы можете его изменить:

{ ... "tv_exchange": "OKX", "tv_instrument": "1INCHUSDT.P" ... }

Внеся эти изменения, сигнал будет применен к паре 1INCH-USDT-SWAP/USDT в 3Commas. Не забудьте проверить формат торговой пары.


Присоединяйтесь к общению с другими трейдерами в нашем официальном Telegram сообществе.

Нашли ответ на свой вопрос?