Convert API

Convert API позволяет обменивать валюты внутри баланса вашего мерчанта по текущей рыночной цене — тот же движок, что работает во вкладке Обмен в личном кабинете, теперь доступный из вашего бэкенда.

Получить цену конверта

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Исполнить конверт

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Ошибки

При ошибке ответ содержит state: 1 и error_code — общие для /v1/convert/price и /v1/convert:

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

Автоматическая конвертация входящих платежей

Автоконвертация — настройка проекта для входящих платежей и пополнений статических кошельков. Она задаётся в панели управления мерчанта, а не дополнительными полями запроса /v1/payment. Каждое правило связывает одну или несколько исходных валют с целевой валютой.

После успешной конвертации данные платежа и webhook-уведомления мерчанта могут содержать:

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

Эти суммы намеренно относятся к разным этапам обработки:

• payment_amount — сумма, обнаруженная в блокчейне, в исходной валюте платежа;
• merchant_amount — чистая сумма мерчанта в исходной валюте до конвертации;
• convert.amount — сумма, зачисленная в валюте convert.to_currency;
• convert.rate и convert.commission — фактический результат выполненной конвертации, а не исходные данные для локального пересчёта.

Сбой автоконвертации и резервный сценарий

Конвертация выполняется после получения платежа в блокчейне. Недоступность рынка, минимальный размер ордера, ограничения точности, тайм-аут биржи или недостаточная исполнимая ликвидность могут задержать конвертацию либо сделать её невозможной.

• Депозиты ниже глобального или проектного минимума не проходят конвертацию и зачисляются в исходной валюте.
• После временного сбоя система может повторить попытку асинхронно.
• Крупные или неликвидные депозиты после исчерпания попыток могут быть зачислены в исходной валюте.
• Поэтому платёж может быть корректно получен, даже если конвертация в целевую валюту не состоялась.

Сначала сохраните подтверждённый платёж, затем определите фактически зачисленную валюту по данным платежа, необязательному блоку convert и балансам мерчанта. Не задерживайте обработку подтверждающего webhook из-за ожидания собственной аналитики или уведомлений.

Приёмочные тесты автоконвертации

Как минимум проверьте: успешную прямую конвертацию; конвертацию через промежуточную валюту или несколько переходов; сумму ниже минимальной; повтор после временного сбоя; зачисление в исходной валюте; недоплату; переплату; дубликат webhook; отсутствие convert; сверку после неоднозначного тайм-аута.

Нестандартные ситуации при ручной конвертации

• /v1/convert/price возвращает ориентировочный предварительный расчёт; движение рынка может изменить фактический результат исполнения.
• amount_type: from фиксирует сумму исходной валюты, а amount_type: to запрашивает сумму целевой валюты. Не меняйте это значение между показом экрана подтверждения и отправкой запроса.
• Если для пары нет прямого рынка, обмен может пройти через промежуточную валюту. Статус partially_completed означает, что завершён только один этап и средства находятся в промежуточной валюте.
• Если запрос завершился тайм-аутом, сначала выполните сверку и только затем повторяйте операцию: рыночный ордер мог исполниться, даже если HTTP-ответ потерян.
• Статус failed требует сверки и не даёт права самостоятельно проводить компенсирующую запись по локальному балансу; учёт списания и возврата ведёт платформа.