Локальный API

Терминал умеет принимать команды снаружи. Внешний скринер, сайт или ваш скрипт отправляет GET-запрос на 127.0.0.1 — и стакан переключается на нужный инструмент. Не надо искать его руками: увидели сигнал у себя, кликнули — терминал уже на этом тикере.

Сервер поднимается внутри терминала и слушает только локальный адрес: из сети к нему не достучаться, доступ есть лишь у программ на этом компьютере.

Настройки

Включать ничего не нужно: сервер работает сразу после установки — он поднимается вместе с терминалом и слушает порт 5055. Достаточно отправить запрос.

Всё, что можно поменять, собрано в Настройки → Функции, раздел Локальный API:

Параметр	По умолчанию	Что задаёт
Локальный API-сервер	включён	Тумблер сервера. Выключите, если не хотите принимать внешние команды
Порт	`5055`	Порт, который слушает терминал. Ниже `1024` система не даст занять без прав администратора — терминал предупредит
Открывать тикер в	Спрашивать каждый раз	Что делать с запросом, если он не указал цель сам: спросить, открыть новую вкладку или сменить тикер в выбранной линковке
Статус	Слушает	Состояние сервера

Строка статуса показывает Слушает и адрес, когда всё работает. Прочие состояния: Выключен, Запускается… и Не запустился на порту — последнее означает, что порт занят другой программой; терминал будет пытаться занять его повторно, но проще сменить порт.

Смена тикера

GET http://127.0.0.1:5055/api/open/{биржа}/{рынок}/{тикер}

Пример из самого терминала:

GET http://127.0.0.1:5055/api/open/binance/futures/BTCUSDT?link=1

Части адреса

Часть	Что писать
биржа	Название биржи, регистр не важен: `binance`, `bybit`, `okx`, `bingx`, `gate` (или `gateio`), `edgex` и остальные поддерживаемые
рынок	Фьючерсы — `f`, `fut`, `futures`, `perp`, `perpetual`, `swap` или `linear`; спот — `s` или `spot`; форекс — `fx` или `forex`; МосБиржа — `moex`
тикер	Инструмент в написании биржи, например `BTCUSDT`

Куда откроется

Запрос может сам указать цель — тогда настройка Открывать тикер в не используется:

Параметр	Результат
`?link=1`	Сменить тикер во всех панелях линковки с этим номером. Если к этой линковке привязан второй инструмент спред-графика, меняется и он
`?target=new_tab`	Открыть новую вкладку с этим инструментом. Принимаются также `newtab` и `tab`

Если параметра нет, терминал поступает по настройке. При значении Спрашивать каждый раз он показывает окно Открыть тикер со списком линковок и вариантом «Новая вкладка»; там же есть галочка Запомнить выбор. В списке есть и линковки, к которым привязан только второй инструмент спред-графика.

Спред: два стакана и график

Одним запросом можно открыть пару инструментов, в том числе с разных бирж: терминал откроет два стакана и спред-график — в новой вкладке или в активной. Скринер нашёл расхождение, вы кликнули — оба стакана и спред уже на экране.

GET http://127.0.0.1:5055/api/spread/{биржа}/{рынок}/{тикер}/{биржа2}/{рынок2}/{тикер2}

Пример:

GET http://127.0.0.1:5055/api/spread/binance/futures/BTCUSDT/bybit/futures/BTCUSDT

Первые три части — первый инструмент (числитель спреда), следующие три — второй (знаменатель). Каждая часть пишется так же, как в запросе смены тикера, — см. Части адреса.

Что откроется

Если в запросе нет номеров линковки, терминал открывает новую вкладку — или, с ?tab=active, добавляет стаканы и спред-график в активную (см. В активной вкладке). Раскладку задаёт параметр layout:

`layout`	Раскладка
`vertical` (по умолчанию)	Сверху рядом стаканы обоих инструментов: первый слева, второй справа. Снизу — спред-график во всю ширину под обоими стаканами, ряды делят высоту поровну
`horizontal`	Стакан первого инструмента, стакан второго и спред-график в один ряд — три равные колонки

Принимаются также v и h, регистр не важен. Параметр действует, только когда терминал строит стаканы и график — в новой вкладке или в активной.

Новая вкладка называется по тикерам, например BTCUSDT÷BTCUSDT. Панели сразу связаны: левый стакан и числитель спреда — в одной линковке, правый стакан и знаменатель — в другой. Сменили тикер в любом стакане — спред перестроился. Номера терминал берёт из свободных: не занятых ни одной панелью и не выбранных в настройке Открывать тикер в. Если свободных номеров не хватило, панели, которым номера не досталось, открываются без линковки.

Таймфрейм графика — ближайший к значению параметра Таймфрейм по умолчанию (Настройки → Торговля → График) из тех, что есть на обеих биржах: спред строится, только когда свечи обоих инструментов одной длительности. Если общего таймфрейма у бирж нет, терминал ответит ошибкой no_common_time_frame — это проверяется при любом спред-запросе, в том числе с номерами линковки.

В активной вкладке

С ?tab=active терминал не открывает новую вкладку, а добавляет стаканы и спред-график в активную вкладку того окна терминала, которое сейчас в фокусе. Если в фокусе нет ни одного окна терминала — обычно так и бывает после клика в браузере, — берётся активная вкладка главного окна. Второе значение — new, оно же по умолчанию: новая вкладка. Регистр не важен.

Открытые панели вкладки остаются как были — со своими потоками данных с биржи, номерами линковки и пропорциями, заданными вручную, — колонки только сужаются, освобождая место справа. Панель, развёрнутая на всю вкладку — кнопкой Развернуть в заголовке или горячей клавишей Развернуть/Восстановить, — возвращается к обычному размеру.
Стаканы и спред-график встают справа от открытых панелей, во всю высоту вкладки, в раскладке по layout.
Каждая колонка нового блока — в vertical их две, в horizontal три — получает среднюю ширину уже открытых колонок. Поэтому блоки повторных запросов с одной раскладкой выходят одинаковыми: в пустой вкладке три блока займут по трети. Панель, закреплённая булавкой Зафиксировать размер, сохраняет свою ширину — см. Размер панели.
Пустую вкладку — в ней одна панель без содержимого — блок занимает целиком.
Имя вкладки не меняется.
Новые стаканы берут свободные номера линковки — или указанные в запросе, см. Параметры; панели вкладки сохраняют свои.
Окно терминала выходит на передний план, в ответе action — active_tab.

Параметры

Запрос может сам указать линковки инструментов, раскладку и вкладку, в которой строить спред:

Параметр	Что задаёт
`?link=1`	Линковка первого инструмента
`?link2=2`	Линковка второго инструмента
`?layout=horizontal`	Раскладка: все три панели в один ряд. Без параметра — стаканы сверху, график снизу
`?tab=active`	Добавить стаканы и спред-график справа в активную вкладку, а не открывать новую. Открытые панели остаются на месте

GET http://127.0.0.1:5055/api/spread/binance/futures/BTCUSDT/bybit/futures/BTCUSDT?link=1&link2=2

Настройка Открывать тикер в к спред-запросу не применяется: без номеров он всегда строит стаканы и график — в новой вкладке или, с tab=active, в активной; окна Открыть тикер не бывает.
Если хотя бы в одной из указанных линковок есть панели, новые панели не создаются: первый инструмент уходит во все панели линковки link, второй — во все панели линковки link2, в том числе в графики, у которых к одной из этих линковок привязан второй инструмент, — у них меняется второй инструмент. Панели ищутся во всех окнах терминала.
Если все указанные линковки пусты, терминал строит те же стаканы и график — по layout и tab — с этими номерами; недостающий номер берётся из свободных.
Номера link и link2 должны различаться, иначе ошибка same_link.
Когда инструменты уходят в панели линковок, layout и tab ни на что не влияют, но всё равно проверяются: неизвестное значение даст ошибку unknown_layout или unknown_tab.
?target=new_tab (а также newtab и tab) принимается, но ничего не меняет: где строить спред, решает tab, а с номерами — номера.

Ответы

Успешный ответ — JSON с полем action:

{
  "ok": true,
  "action": "linked",
  "exchange": "Binance",
  "market": "Futures",
  "symbol": "BTCUSDT",
  "link": "1",
  "panes": 2
}

`action`	Что произошло
`linked`	Тикер сменён в панелях линковки; в `panes` — сколько панелей переключилось
`new_tab`	Открыта новая вкладка
`active_tab`	Только спред: стаканы и спред-график добавлены в активную вкладку
`asked`	Показано окно выбора — дальше решает человек за терминалом

В ответе на спред-запрос есть ещё поля второго инструмента — exchange2, market2, symbol2 — и номера link и link2. action в нём бывает только new_tab, active_tab или linked. При new_tab и active_tab в link и link2 — номера новых стаканов; если свободного номера не нашлось, поля нет. При linked — номера из запроса: номера, которого в запросе не было, нет и в ответе. panes считает панели обеих линковок.

{
  "ok": true,
  "action": "new_tab",
  "exchange": "Binance",
  "market": "Futures",
  "symbol": "BTCUSDT",
  "exchange2": "Bybit",
  "market2": "Futures",
  "symbol2": "BTCUSDT",
  "link": "4",
  "link2": "5"
}

Ошибка возвращается тем же JSON с полями error и message:

Код HTTP	`error`	Причина
400	`unknown_exchange`	Биржа не распознана
400	`unknown_market`	Неизвестный тип рынка
400	`unsupported_market`	Биржа не поддерживает этот рынок
400	`empty_symbol`	Тикер пустой
400	`unknown_target`	Непонятное значение `?target=`
400	`same_link`	Только спред: в `link` и `link2` один и тот же номер
400	`unknown_layout`	Только спред: непонятное значение `?layout=`
400	`unknown_tab`	Только спред: непонятное значение `?tab=`
404	`symbol_not_found`	Такого инструмента у биржи нет
409	`exchange_not_connected`	К бирже нет активного подключения
409	`no_common_time_frame`	Только спред: у бирж двух инструментов нет общего таймфрейма
429	`rate_limited`	Слишком часто: лимит — 5 запросов в секунду
429	`duplicate`	Тот же запрос уже в работе
503	`terminal_unavailable`	Терминал ещё не готов принять команду
504	`terminal_timeout`	Терминал не ответил за 3 секунды

Если ошибка спред-запроса касается одного инструмента — биржи, рынка, тикера, подключения или того, что инструмент не найден, — в ней есть поле leg со значением 1 или 2: к какому инструменту она относится.

Проверка связи

GET http://127.0.0.1:5055/api/ping

Отвечает {"ok":true,"app":"..."}. Удобно, чтобы скрипт понял, запущен ли терминал, прежде чем слать команды.

Что нужно знать

Запросы принимаются и со страниц в браузере: сервер отдаёт CORS-заголовки, поэтому кнопку «открыть в терминале» можно повесить на свой сайт или расширение.
Лимит — 5 запросов в секунду. Он защищает от цикла в чужом скрипте: каждый запрос это вкладка, стакан и потоки данных с биржи.
Спред-запрос считается одним запросом в лимите 5 в секунду.
Биржа должна быть подключена. Если активного подключения нет, терминал ответит exchange_not_connected — см. Обзор подключений.