Skip to main content
Конвертации позволяют вашей CMS обменять накопленные на кошельках обменника активы (например, ETH, LINK, TRX) в стейбл (USDT) через те же ключи API, что и кошелёк — отдельная интеграция с DEX или биржей не нужна. Платформа сама выбирает подключённого провайдера и скрывает его детали за единым контрактом из трёх эндпоинтов.
Какой именно движок исполнит своп (0x, 1inch, Uniswap, SunSwap, Jupiter, ChangeNOW, SimpleSwap…) и его ключи настраивает оператор в Админке. Для вашей интеграции это прозрачно: вы всегда вызываете один и тот же набор эндпоинтов. Если провайдер не выбран явно, платформа сама подбирает лучший по факту котировки среди исполнимых.
Аутентификация — та же HMAC-подпись, что и у депозитов и выплат (см. Аутентификация). Ответы приходят в конверте { "ok": true, "data": … } или { "ok": false, "error": {…} }. Применяется тот же per-site rate-limit. Все суммы и курсы — строки.

Same-chain и cross-chain

В зависимости от выбранного провайдера своп исполняется по одной из двух моделей:
  • Same-chain (DEX). Источник и цель в одной сети, обмен идёт on-chain через роутер (providerKind: "dex"). Результат возвращается на тот же кошелёк сети. Курс рыночный.
  • Cross-chain (instant-swap). Источник и цель могут быть в разных сетях; платформа отправляет актив на адрес провайдера, а результат принимает на свой кошелёк целевой сети (providerKind: "instant_swap"). Курс — плавающий или фиксированный, в зависимости от провайдера.
Для вашей интеграции запрос идентичен в обоих случаях — вы указываете sourceAssetCode, targetAssetCode, network и amountIn. Поле providerKind в ответе показывает, по какой модели прошёл обмен.

Эндпоинты

Рекомендуемый поток — quote → create → poll: сначала получить живую котировку, показать её оператору или принять решение в коде, затем создать заявку и опрашивать её статус до терминального. Исполнение асинхронное: POST /v1/public/conversions создаёт заявку в статусе queued (или pending_approval), а сам своп выполняется в фоне. Опрашивайте GET /v1/public/conversions/{uuid}, пока статус не станет терминальным (settled, failed, refunded, expired, cancelled).

1. Котировка (сколько отдам / получу)

POST /v1/public/conversions/quote — узнать актуальный курс, ожидаемый выход и минимальную сумму к получению без создания заявки. Заявка при этом не создаётся, балансы не блокируются.

Запрос

Ответ

Параметры запроса (тело)

string
required
Код актива-источника (например, ETH, LINK, TRX). До 64 символов.
string
required
Код целевого актива — стейбл (например, USDT_ERC20, USDT_TRC20). До 64 символов.
string
required
Сеть исполнения (например, ETHEREUM, TRON). До 32 символов.
string
required
Сумма к конвертации — строка-число, формат ^\d+(\.\d+)?$ (например, "1.5"). Без знака минус и без экспоненты.
integer
Допустимое проскальзывание в bps (1% = 100 bps). Диапазон 1…5000. Если не передан — берётся значение из настроек оператора.

Поля ответа котировки

string
Код актива-источника (эхо запроса).
string
Код целевого актива (эхо запроса).
string
Сеть исполнения (эхо запроса).
string
Сумма к конвертации (эхо запроса).
string
Ожидаемый выход в целевом активе.
string
Минимум к получению с учётом slippage — ниже него своп не исполнится.
string
Курс = amountOut / amountIn.
integer
Применённое проскальзывание в bps.
integer
Сколько секунд котировка считается актуальной.
boolean
true — котировку можно исполнить; false — это только оценка (см. предупреждение ниже).
executable: false означает, что провайдер вернул только оценочный курс — нет рабочего драйвера или ключа на стороне оператора, либо нет ликвидности, либо сумма вне диапазона провайдера. Создать конвертацию по неисполнимой котировке нельзя: POST /v1/public/conversions сразу вернёт ошибку VALIDATION_FAILED. Сначала дождитесь, пока оператор настроит провайдера.

2. Создание конвертации

POST /v1/public/conversions — тело идентично запросу котировки. Платформа заново берёт живую котировку, проверяет исполнимость, баланс hot-кошелька, минимальную сумму и гейты безопасности, затем ставит заявку в очередь.

Идемпотентность

Создание идемпотентно по заголовку X-Idempotency-Key (UUID): повторный запрос с тем же ключом вернёт ту же заявку, а не создаст вторую. Ключ привязан к вашему сайту, поэтому одинаковый UUID у разных обменников не пересекается. Подробнее — Идемпотентность.

Запрос

Ответ

Возвращается объект конвертации в статусе queued (или pending_approval, если у оператора включён порог второго подтверждения для крупных сумм). Поля executed* и settledAt пока null.

3. Статус конвертации

GET /v1/public/conversions/{uuid} — текущее состояние заявки. Видны только конвертации вашего сайта; чужой uuid возвращает NOT_FOUND (404). Тело запроса пустое, поэтому в подписи message = "<timestamp>." (таймстамп, затем точка).

Запрос

Ответ (исполнено)

Поля объекта конвертации

string
Публичный идентификатор конвертации.
string
Текущий статус. Полный список — Статусы конвертаций.
string
Код актива-источника.
string
Код целевого актива (стейбл).
string
Сеть исходного актива.
string
Сумма, отправленная на конвертацию.
string
Ожидаемый выход на момент создания (что вы видели в котировке).
string | null
Фактически полученный выход. null до исполнения.
string
Курс на момент создания.
string | null
Фактический курс после исполнения. null до исполнения.
string
Минимум к получению (защита от проскальзывания).
string
Модель исполнения: dex (same-chain), instant_swap (cross-chain) или cex.
string | null
Причина ошибки при status: "failed", иначе null.
string
Дата создания заявки (ISO 8601, UTC).
string | null
Дата успешного завершения. null, пока не settled.

Проскальзывание и срок жизни котировки

  • maxSlippageBps задаёт, насколько фактический выход может оказаться ниже ожидаемого. Из него считается minAmountOut — жёсткая граница: если рынок уйдёт сильнее, своп не исполнится и заявка станет failed (для DEX это enforce’ится самим роутером on-chain).
  • ttlSeconds в котировке — справочное время её актуальности. При создании заявки платформа берёт свежую котировку заново, поэтому котировку не нужно «передавать» в create — достаточно тех же входных параметров.

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

Нет. POST /v1/public/conversions принимает те же поля, что и quote, и берёт свежую котировку сам. Шаг quote нужен лишь для предпросмотра курса и проверки executable.
Вероятнее всего, котировка была неисполнимой (executable: false): нет настроенного драйвера или ключа провайдера, нет ликвидности, либо сумма ниже минимума или вне диапазона провайдера. Текст причины — в error.message. Создать заявку можно только по исполнимой котировке.
У оператора настроен порог второго подтверждения (four-eyes) для крупных по USD сумм, либо включено принудительное одобрение для выбранного провайдера. Заявка исполнится после ручного подтверждения оператором в Админке. Продолжайте опрашивать статус.
Рынок мог сдвинуться в пределах допустимого проскальзывания между котировкой и исполнением. Гарантированный минимум — minAmountOut; ниже него своп не пройдёт.
Нет. Отмена (cancelled) — операторское действие в Админке и возможна только до начала исполнения. Публичного эндпоинта отмены нет.
Создайте новую заявку (тот же POST) — платформа возьмёт актуальную котировку. Используйте новый X-Idempotency-Key, иначе вернётся прежняя завершившаяся заявка.

Связанные страницы