formulas

Формулы:

Формулы позволяют находить курс для валютной пары, даже если биржа напрямую не предоставляет цен для данной пары. Например, нам нужно рассчитать цену BTC -> RUB. Прямого курса нет, но можно рассчитать его через 3ю валюту: BTC -> KGS -> RUB.

Кроме расчета курса при обменах, формулы еще используются для указания мин и макс суммы обмена и скидок. Например, для BTC -> RUB можно задать лимит в любой активной валюте - DOGE или USDT. Он будет пересчитан автоматически по текущему курсу. Поэтому формулы выделены отдельно и не привязаны к направлениям.

Сейчас для каждой пары валют можно задать только одну формулу.

`/api/formula`

Метод: GET
Описание: Загружает сохраненную формулу.
Права: 🟡 админка.

Параметры:

from - код валюты Отдаю, например BTC. Обязательный параметр;
to - код валюты Получаю. Обязательный параметр;

Ответ:

{
  "type": "success",
  "message": null,
  "data": {
    "id": 1,
    "from": "RUB",
    "to": "ETH",
    "tag": "Cbr_RUB_EUR * Binance_EUR_EURI_buy * Binance_EURI_ETH_buy",
    "reserve": "auto",
    "lastUpdated": "2025-06-16 21:48:34",
    "isEnabled": true,
    "price": 0.000004825993433195978,
    "spread": 0.13220134023363964
  },
  "action": null
}

Подробности:

tag - сама формула. Большинство бирж позволяют загрузить поля buy и sell, в таком случае мы можем рассчитать спред. Если нет - то используем поле price, в таком формате данные предоставляет CoinMarketCap.
isEnabled - использовать ли эту формулу. Если выключить, то все направления, где она используется, также будут отключены.
price - текущая цена. Может быть равна 0, если не удается загрузить цену. Число попыток можно задать на странице биржи;
spread - разница между ценой покупки и продажи, в процентах. Может быть равен 0;
Его тоже можно использовать для выбора лучшего варианта. В теории, чем меньше спред - тем этот вариант ближе к реальному;
reserve - запасной вариант, если не удается загрузить курс. Варианты:
- auto - найти новую формулу (по умолчанию);
- CoinMarketCap - переключиться на курс с CoinMarketCap. Это условие срабатывает только один раз. При этом курс добавляется в общий список, что позволяет его использовать для составления других формул в ручном или автоматическом режиме.
- off - отключить формулу и все направления, где она используется.

Если формула не найдена, возвращается warning:
Ответ:

{
  "type": "warning",
  "message": "Формула не найдена",
  "data": null,
  "action": null
}

`/api/formula`

Метод: PUT, POST
Описание: Добавляет новую формулу (PUT) или сохраняет (POST).
Права: 🔴 админка + isEditDirection.

Запрос:

{
  "from": "RUB",
  "to": "ETH",
  "tag": "Cbr_RUB_ZAR * Binance_ZAR_ETH_buy",
  "reserve": "auto",
  "isEnabled": true
}

Все параметры обязательны. Подробности:

from - код валюты Отдаю;
to - код валюты Получаю;
tag - формула;
reserve - запасной вариант, если формула не работает;
isEnabled - использовать ли эту формулу.

Ответ:

{
  "type": "success",
  "message": "Формула RUB -> ETH добавлена",
  "data": null,
  "action": null
}

`/api/formulas/generate`

Метод: GET
Описание: Составляет новую формулу.
Права: 🔴 админка + isEditDirection, т.к. поиск занимает время.

Параметры:

from - код валюты Отдаю, например BTC. Обязательный параметр;
to - код валюты Получаю. Обязательный параметр;
calcMode - режим поиска;
- auto - найти кросс-курс (по умолчанию);
- CoinMarketCap - Загрузить курс с CoinMarketCap;
- fromFile - Загрузить курс из файла на сервере. Файл называется kurs.json, его нужно создать.
  Если курс не задан или <= 0, то запрос с параметром fromFile для данной пары будет выдавать ошибку.

Пример файла kurs.json:

[
    {
        "from": "BTC",
        "to": "USDT",
        "price": 95000.0
    }
]

Алгоритм поиска для auto:

рассчитывается самая короткая формула по количеству вершин: BTC-ETH;
подбираются варианты с числом вершин +1: BTC-USDT-ETH. Максимальное число вершин <=5, т.к. поиск занимает время;
берется референтное значение с CoinMarketCap или, если он недоступен - то берется среднее;
Кросс-курсы сравниваются с этим значением и сортируются в порядке возрастания.

Ответ:

{
  "type": "success",
  "message": null,
  "data": {
    "referentPrice": 0.000004826192891183676,
    "referentSource": "CoinMarketCap",
    "list": [
      {
        "path": "RUB -> USDT -> INJ -> ETH",
        "price": 0.000004826162837544283,
        "tag": "Cbr_RUB_USDT * Bybit_USDT_INJ_buy * Binance_INJ_ETH_buy",
        "spread": 1.7976931348623157e+308
      }
    ]
  },
  "action": null
}

`/api/formulas`

Метод: GET
Описание: Запрашивает список формул.
Права: 🟡 админка.

Параметры:

start - с какого по счету элемента начать выдачу данных. Например, если start = 10, то ответ начнется с 11-го элемента. По умолчанию start = 0.
count - максимальное количество направлений для загрузки за один раз. Например, если count = 50, будет возвращено 50 элементов, начиная с позиции, указанной в start;
isActive:
- true - искать только по активным формулам;
- false - только по отключенным;
- не указывать параметр isActive - по всем формулам;
filter - фильтр по коду валюты или по тексту формулы. Будут найдены все валюты, которые содержат это слово. Например, если задать фильтр USD, будут получены все направления с USDT и USD. Если задать bybit, то будут получены все формулы, которые берут курс с биржи Bybit.

Ответ:

{
  "type": "success",
  "message": null,
  "data": {
    "items": [
      {
        "id": 1,
        "from": "RUB",
        "to": "ETH",
        "tag": "Cbr_RUB_ZAR * Binance_ZAR_ETH_buy",
        "reserve": "auto",
        "lastUpdated": "2025-06-16 22:07:03",
        "isEnabled": true,
        "price": 4.822979924657339e-7,
        "spread": 0.2135622607997012
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 100
  },
  "action": null
}

`/api/formulas`

Метод: DELETE
Описание: Удаляет формулы. Хотя они добавляются автоматически, этот метод тоже может пригодиться. Например, если одна из валют больше не нужна в обменнике.
Права: 🔴 админка + isEditDirection.
Параметры:

ids - список id для удаления. Целые числа, разделенные запятыми.

Права: isEditCurrency

Ответ:

{
  "type": "success",
  "message": "Удалены формулы: BTC -> USDT, BTC -> ETH",
  "data": null,
  "action": null
}