Конвертации — обмен активов в стейбл

Конвертации позволяют вашей 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 в ответе показывает, по какой модели прошёл обмен.

Эндпоинты

Метод	Путь	Назначение
`POST`	`/v1/public/conversions/quote`	живая котировка (preview), без создания заявки
`POST`	`/v1/public/conversions`	создать конвертацию
`GET`	`/v1/public/conversions/{uuid}`	статус конвертации

Рекомендуемый поток — 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 — узнать актуальный курс, ожидаемый выход и минимальную сумму к получению без создания заявки. Заявка при этом не создаётся, балансы не блокируются.

Запрос

TS=$(date +%s)
BODY='{"sourceAssetCode":"ETH","targetAssetCode":"USDT_ERC20","network":"ETHEREUM","amountIn":"1.5","maxSlippageBps":100}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl -X POST https://wallet.your-exchange.com/v1/public/conversions/quote \
  -H "X-Api-Id: pk_live_a1b2c3d4" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Ответ

{
  "ok": true,
  "data": {
    "sourceAssetCode": "ETH",
    "targetAssetCode": "USDT_ERC20",
    "network": "ETHEREUM",
    "amountIn": "1.5",
    "amountOut": "4820.13",
    "minAmountOut": "4771.93",
    "rate": "3213.42",
    "slippageBps": 100,
    "ttlSeconds": 30,
    "executable": true
  }
}

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

sourceAssetCode

string

required

Код актива-источника (например, ETH, LINK, TRX). До 64 символов.

targetAssetCode

string

required

Код целевого актива — стейбл (например, USDT_ERC20, USDT_TRC20). До 64 символов.

network

string

required

Сеть исполнения (например, ETHEREUM, TRON). До 32 символов.

amountIn

string

required

Сумма к конвертации — строка-число, формат ^\d+(\.\d+)?$ (например, "1.5"). Без знака минус и без экспоненты.

maxSlippageBps

integer

Допустимое проскальзывание в bps (1% = 100 bps). Диапазон 1…5000. Если не передан — берётся значение из настроек оператора.

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

sourceAssetCode

string

Код актива-источника (эхо запроса).

targetAssetCode

string

Код целевого актива (эхо запроса).

network

string

Сеть исполнения (эхо запроса).

amountIn

string

Сумма к конвертации (эхо запроса).

amountOut

string

Ожидаемый выход в целевом активе.

minAmountOut

string

Минимум к получению с учётом slippage — ниже него своп не исполнится.

rate

string

Курс = amountOut / amountIn.

slippageBps

integer

Применённое проскальзывание в bps.

ttlSeconds

integer

Сколько секунд котировка считается актуальной.

executable

boolean

true — котировку можно исполнить; false — это только оценка (см. предупреждение ниже).

executable: false означает, что провайдер вернул только оценочный курс — нет рабочего драйвера или ключа на стороне оператора, либо нет ликвидности, либо сумма вне диапазона провайдера. Создать конвертацию по неисполнимой котировке нельзя: POST /v1/public/conversions сразу вернёт ошибку VALIDATION_FAILED. Сначала дождитесь, пока оператор настроит провайдера.

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

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

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

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

Запрос

TS=$(date +%s)
BODY='{"sourceAssetCode":"ETH","targetAssetCode":"USDT_ERC20","network":"ETHEREUM","amountIn":"1.5","maxSlippageBps":100}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl -X POST https://wallet.your-exchange.com/v1/public/conversions \
  -H "X-Api-Id: pk_live_a1b2c3d4" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "X-Idempotency-Key: 7c2f9e1a-4d6b-4a2e-9f10-3b8c1d2e5a40" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Ответ

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

{
  "ok": true,
  "data": {
    "uuid": "8e0a1b2c-3d4e-4f5a-9b6c-7d8e9f0a1b2c",
    "status": "queued",
    "sourceAssetCode": "ETH",
    "targetAssetCode": "USDT_ERC20",
    "network": "ETHEREUM",
    "sourceAmount": "1.5",
    "quotedAmountOut": "4820.13",
    "executedAmountOut": null,
    "quotedRate": "3213.42",
    "executedRate": null,
    "minAmountOut": "4771.93",
    "providerKind": "dex",
    "failReason": null,
    "createdAt": "2026-06-25T20:00:00.000Z",
    "settledAt": null
  }
}

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

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

Запрос

TS=$(date +%s)
UUID="8e0a1b2c-3d4e-4f5a-9b6c-7d8e9f0a1b2c"
SIG=$(printf '%s.' "$TS" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl https://wallet.your-exchange.com/v1/public/conversions/$UUID \
  -H "X-Api-Id: pk_live_a1b2c3d4" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

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

{
  "ok": true,
  "data": {
    "uuid": "8e0a1b2c-3d4e-4f5a-9b6c-7d8e9f0a1b2c",
    "status": "settled",
    "sourceAssetCode": "ETH",
    "targetAssetCode": "USDT_ERC20",
    "network": "ETHEREUM",
    "sourceAmount": "1.5",
    "quotedAmountOut": "4820.13",
    "executedAmountOut": "4818.40",
    "quotedRate": "3213.42",
    "executedRate": "3212.27",
    "minAmountOut": "4771.93",
    "providerKind": "dex",
    "failReason": null,
    "createdAt": "2026-06-25T20:00:00.000Z",
    "settledAt": "2026-06-25T20:00:45.000Z"
  }
}

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

uuid

string

Публичный идентификатор конвертации.

status

string

Текущий статус. Полный список — Статусы конвертаций.

sourceAssetCode

string

Код актива-источника.

targetAssetCode

string

Код целевого актива (стейбл).

network

string

Сеть исходного актива.

sourceAmount

string

Сумма, отправленная на конвертацию.

quotedAmountOut

string

Ожидаемый выход на момент создания (что вы видели в котировке).

executedAmountOut

string | null

Фактически полученный выход. null до исполнения.

quotedRate

string

Курс на момент создания.

executedRate

string | null

Фактический курс после исполнения. null до исполнения.

minAmountOut

string

Минимум к получению (защита от проскальзывания).

providerKind

string

Модель исполнения: dex (same-chain), instant_swap (cross-chain) или cex.

failReason

string | null

Причина ошибки при status: "failed", иначе null.

createdAt

string

Дата создания заявки (ISO 8601, UTC).

settledAt

string | null

Дата успешного завершения. null, пока не settled.

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

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

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

Нужно ли передавать котировку в запрос создания?

Нет. POST /v1/public/conversions принимает те же поля, что и quote, и берёт свежую котировку сам. Шаг quote нужен лишь для предпросмотра курса и проверки executable.

Почему создание вернуло VALIDATION_FAILED, хотя quote показал курс?

Вероятнее всего, котировка была неисполнимой (executable: false): нет настроенного драйвера или ключа провайдера, нет ликвидности, либо сумма ниже минимума или вне диапазона провайдера. Текст причины — в error.message. Создать заявку можно только по исполнимой котировке.

Почему заявка в статусе pending_approval, а не queued?

У оператора настроен порог второго подтверждения (four-eyes) для крупных по USD сумм, либо включено принудительное одобрение для выбранного провайдера. Заявка исполнится после ручного подтверждения оператором в Админке. Продолжайте опрашивать статус.

Почему executedAmountOut меньше quotedAmountOut?

Рынок мог сдвинуться в пределах допустимого проскальзывания между котировкой и исполнением. Гарантированный минимум — minAmountOut; ниже него своп не пройдёт.

Можно ли отменить конвертацию через API?

Нет. Отмена (cancelled) — операторское действие в Админке и возможна только до начала исполнения. Публичного эндпоинта отмены нет.

Как повторить неудачную конвертацию?

Создайте новую заявку (тот же POST) — платформа возьмёт актуальную котировку. Используйте новый X-Idempotency-Key, иначе вернётся прежняя завершившаяся заявка.

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

Аутентификация — HMAC-подпись, заголовки, IP whitelist.
Идемпотентность — X-Idempotency-Key и безопасные повторы.
Статусы конвертаций — жизненный цикл и причины ошибок.
Ошибки — единый формат ответа и справочник кодов.
Лимиты запросов — per-site rate-limit.

​Same-chain и cross-chain

​Эндпоинты

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

​Запрос

​Ответ

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

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

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

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

​Запрос

​Ответ

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

​Запрос

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

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

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

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

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

Same-chain и cross-chain

Эндпоинты

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

Запрос

Ответ

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

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

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

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

Запрос

Ответ

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

Запрос

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

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

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

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

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