Управление созданными объявлениями SmartSwap (подключение по API)

Краткое описание статьи

Данная статья описывает механизм автоматического управления параметрами объявлений созданных в сервисе SmartSwap.

• Получение ключа API: https://app.smartswap.ru/profile
• Авторизация через заголовок с Bearer токеном: Authorization: Bearer <API_KEY>
• Swagger документация по доступным методам:
  https://app.smartswap.ru/api#/external

Мотивация

Зачастую, возникает необходимость скрыть неактуальное объявление либо изменить курс в уже созданном объявлении.

Скрытие объявлений может пригодиться, например, если трейдер работает только в определённые часы и не имеет возможности обрабатывать созданные с ним сделки в нерабочее время (ночью или в дни отдыха). Создание таких безответных сделок приводит к тому что потенциальные тейкеры могут занести трейдеров в личный лист блокировок. А также ухудшает общую статистику трейдера наличием множества отменённых сделок.

Изменение курса в объявлении обычно имеют целью повысить (либо, наоборот, понизить) привлекательность объявления трейдера на доске. Либо учесть интерес трейдера в изменившихся внешних обстоятельствах: изменение условий арбитража, высокая волатильность на рынках, необходимость покрыть издержки на комиссию блокчейна в сделках по которым трейдер выступает продавцом криптовалюты и т.д.

На данный момент в автоматическом режиме в объявлениях SmartSwap поддерживаются только фиксированные курсы либо следование курсу выбранного источника (биржи) с заранее заданной долей прибыли (маржой). Реализация более сложных формул расчёта цены возможна, но из-за отсутствия универсальных требований к методике таких расчётов представляется крайне трудоёмкой и хрупкой к последующим изменениям требований.

Решение проблемы

Далее предлагается пошаговая инструкция по исполнению коротких скриптов для управления параметрами объявлений в POSIX-совместимых системах: MacOS, Linux. Данный опыт, с заменой исполняемых команд, вполне может быть адаптирован и к Windows системам.

Предполагается что пользователь уже имеет аккаунт в системе SmartSwap и по меньшей мере одно созданное объявление.

Шаг 0. Установка необходимого инструментария

Для дальнейшей работы потребуются пакеты: curl, jq

Установка в Ubuntu/Debian

sudo apt install curl jq

Установка в MacOS

brew install curl jq

Шаг 1. Получение ключа API

На сайте сервиса либо в веб-приложении телеграмм бота необходимо перейти в раздел "профиль": https://app.smartswap.ru/profile. Найти и развернуть секцию "Настройка API ключей". В поле "Имя API ключа" занести любое имя ключа. Имя ключа не влияет на функционал. Тем не меннее, лучше чтобы это было семантически значимое имя. Например, для использования скрипта с этим ключом с домашнего ноутбука имеет смыл назвать ключ "домашний ноут". В дальнейшем это упростит управление созданными ключами. В случае утраты ноутбука, например, достаточно будет удалить только этот ключ чтобы предотвратить несанкционированный доступ к Вашим объявлениям. Нажимаем кнопку "Создать".

Предположим, мы получили значение: 18f203e6-1569-4c0b-a3b1-e0f170a4148e

Сохраним значение в переменной окружения:

export SWAP_API_KEY=18f203e6-1569-4c0b-a3b1-e0f170a4148e

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

Шаг 2. Получение данных о размещённых объявлениях

К данному моменту нам доступен следующий функционал с авторизацией через ключи API: https://app.smartswap.ru/api#/external

Сервис использует схему авторизации через Bearer токен. Т.е. заголовок авторизации должен выглядеть как:

Authorization: Bearer <подставляем полученное ранее значение ключа API>

В нашем гипотетическом случае это будет:

Authorization: Bearer 18f203e6-1569-4c0b-a3b1-e0f170a4148e

Для начала получим полный список объявлений со всеми данными:

curl -s \
    -H "Authorization: Bearer ${SWAP_API_KEY}" \
    https://app.smartswap.ru/api/external/offers | \
    jq

В ответе сервера получаем довольно подробные данные о размещённых нами объявлениях. Этот эндпоинт имеет возможность фильтрации по множеству параметров. Для иллюстрации возможностей воспользуемся фильтрами по фиатной валюте (RUB), криптовалюте (BTC) и типу объявления (sell, объявления на продажу):

curl -s \
    -H "Authorization: Bearer ${SWAP_API_KEY}" \
    https://app.smartswap.ru/api/external/offers?kind=sell&currency_iso_code=RUB&chain_id=1&chain_type=BTC&token_address=0x0000000000000000000000000000000000000000 | \
    jq

Если у Вас получился пустой вывод это просто означает что в Вашем конкретном случае нет объявлений подходящих под выбранный фильтр. Скорректируйте фильтры под свои нужны и попробуйте выполнить данный запрос с актуальными настройками параметров.

Полный список настроек криптовалют для параметров chain_id, chain_type, token_address можно получить следующим образом:

curl -s \
    https://app.smartswap.ru/api/public/tokens?active=true | \
    jq -r '["name", "chain_id", "chain_type", "token_address"], (.[] | [.name, .chain_id, .chain_type, .address]) | @tsv' | \
    column -ts #39;\t'

Шаг 3. Скрытие и показ объявлений

Выберем только свои активные объявления чтобы не затронуть видимость объявлений которые уже скрыты на данный момент.

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

curl -s \
    -H "Authorization: Bearer ${SWAP_API_KEY}" \
    https://app.smartswap.ru/api/external/offers?active=true | \
    jq '.[].id' > active-ids.txt

Итоговый результат с идентификаторами активных объявлений сохраняется в файл active-ids.txt. Можно просмотреть собранные идентификаторы командой:

cat active-ids.txt

Эндпоинты принимают параметры в формате json. Чтобы скрыть конкретное объявление используем команду:

curl -s -o /dev/null \
  -H "Authorization: Bearer ${SWAP_API_KEY}" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{"active":false}' \
  https://app.smartswap.ru/api/external/offers/{id}/active

Где вместо {id} подставляем идентификатор скрываемого объявления.

Теперь скроем все объявления из файла. Проходим в цикле по идентификаторам и для каждого вызываем эндпоинт меняющий видимость объявления:

while read line; do \
  curl -s -f -o /dev/null \
    -H "Authorization: Bearer ${SWAP_API_KEY}" \
    -H 'Content-Type: application/json' \
    -X PUT \
    -d '{"active":false}' \
    "https://app.smartswap.ru/api/external/offers/${line}/active" && \
    echo "Объявление ${line} скрыто" || \
    echo "Не удалось скрыть объявление ${line}"; \
done < active-ids.txt

Аналогичным образом восстанавливаем видимость объявлений обратно. Заменив в параметрах {"active":false} на {"active":true}:

while read line; do \
  curl -s -f -o /dev/null \
    -H "Authorization: Bearer ${SWAP_API_KEY}" \
    -H 'Content-Type: application/json' \
    -X PUT \
    -d '{"active":true}' \
    "https://app.smartswap.ru/api/external/offers/${line}/active" && \
    echo "Объявление ${line} активировано" || \
    echo "Не удалось активировать объявление ${line}"; \
done < active-ids.txt

Мы полностью восстановили видимость всех объявлений которые были ранее скрыты. Приберём за собой:

rm active-ids.txt

Шаг 4. Управление курсом в объявлении

Для изменения курса в объявлении необходимо воспользоваться эндпонитом: https://app.smartswap.ru/api#!/external/putExternalOffersIdRate

Курс может быть установлен одним из двух способов:

• Фиксированный курс. Для этого необходимо выставить параметр custom_rate в нужное значение курса. Например:

curl -s \
  -H "Authorization: Bearer ${SWAP_API_KEY}" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{"custom_rate":100}' \
  https://app.smartswap.ru/api/external/offers/{id}/rate

• Автоматическое следование за курсом выбранной биржи с фиксированным отступом (маржой) в процентах. На момент написания текста доступно два источника курсов: Binance - 1, Bybit - 2.

Например, чтобы задать в объявлении автоматическое следование за курсом биржи Bybit с маржой 5% необходимо выполнить команду:

curl -s \
  -H "Authorization: Bearer ${SWAP_API_KEY}" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{"margin":5,"external_rate_source_id":2}' \
  https://app.smartswap.ru/api/external/offers/{id}/rate

Имейте ввиду, что итоговый курс в объявлении всегда рассчитывается как добавление маржи к курсу биржи. То есть, положительное значение маржи в 5% будет всегда добавлено к текущему курсу выбранной биржи, независимо от того является ли это объявлением на продажу или на закуп. С учётом этого, позитивный экономический эффект возникает когда маржа является положительным числом (прибавляется к курсу) в объявлениях на продажу криптовалюты, либо отрицательным числом (вычитается из курса) в объявлениях на закуп криптовалюты.

Шаг 5. Изменение параметров объявления

Кроме признака видимости и курса к изменениям доступно также ограниченное количество полей в объявлении:

• Нижняя граница суммы сделки (min) в базовой валюте (криптовалюте)
• Верхняя граница суммы сделки (max) в базовой валюте (криптовалюте)
• Условия сделки (terms)

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

curl -s \
  -H "Authorization: Bearer ${SWAP_API_KEY}" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{"min":0,"max":10,"terms":"Новые улучшенные условия"}' \
  https://app.smartswap.ru/api/external/offers/{id}

Нижняя и верхняя граница сделки указываются в базовой валюте объявления. То есть в криптовалюте. В сделке на продажу USDT за рубли это будет, соответственно, USDT. Но на доске, границы объявлений отображаются в котировочной валюте. В которую переводятся согласно курсу в объявлении.

Описание эндпоинта: https://app.smartswap.ru/api#!/external/putExternalOffersId