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. Кожне правило обирає одну або кілька валют-джерел та цільову валюту.

Після завершення конвертації, інформація про платіж та вебхуки торговця можуть включати:

{
  "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 платежу, очікуючи на власні аналітичні або інформаційні системи.

Тести прийнятності автоматичної конверсії

Перевірте принаймні: успішне пряме конвертування, конвертацію через проміжну валюту/багатоступеневу, пил нижче мінімуму, тимчасова повторна спроба, повернення до вихідної валюти, недоплата, переплата, дубльоване веб-хуків, відсутність convert та звірка після неоднозначного тайм-ауту.

Крайові випадки ручного конвертування

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