Developers

Котирування операції

Котирування — це єдина кінцева точка, відкрита сьогодні, і найважливіша: вона повертає деталізацію по рядках, яку показує сайт. Їй не потрібен ключ.

POST/api/quoteLive

Цитувати операцію

Повертає повну деталізацію продажу: використаний міжбанківський курс, кожна комісія окремим рядком, чиста сума та фактичний курс, який реально отримано. Рядки точно дорівнюють різниці між валовою та чистою сумою — інваріант перевіряється перед тим, як відповідь покидає сервер, і незбалансована відповідь ніколи не повертається.

Автентифікація: сьогодні жодної. Кінцева точка котирування відкрита: котирування не розкриває жодних персональних даних.

Параметри

Параметри
Поле	Тип	Опис
`assetId`обов'язковий	string	Ідентифікатор активу, що вноситься, наприклад «btc», «usdt», «sol».
`railId`обов'язковий	string	Ідентифікатор методу виплати, наприклад «sepa_instant», «br_pix», «ke_mpesa».
`networkId`	string	Мережа внесення. Необов'язково: за замовчуванням використовується перша мережа активу. Вартість мережі значно відрізняється між мережами, тому це поле змінює чисту суму.
`direction`обов'язковий	"sell" \| "receive"	Напрямок введення. «sell»: сума — це те, що ви вносите. «receive»: сума — це те, що ви хочете отримати, а необхідний депозит визначається бінарним пошуком.
`amount`обов'язковий	string	Сума в основних одиницях, надіслана як РЯДОК. JSON-число з плаваючою комою втратило б дрібні одиниці для великих сум: рядок — це єдиний формат, у якому клієнт і сервер узгоджуються до цента.

Запитbash

curl -sS -X POST https://fiatside.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{
    "assetId": "usdt",
    "railId": "sepa_instant",
    "networkId": "tron",
    "direction": "sell",
    "amount": "1000"
  }'

Відповідь — реальний прикладjson

{
  "deposit": { "amount": "1000.000000", "ticker": "USDT", "decimals": 6 },
  "gross": "921.68",
  "net": "912.28",
  "currency": "EUR",
  "currencyDecimals": 2,
  "midRate": "0.92168430",
  "effectiveRate": "0.91228000",
  "totalCostBps": 102,
  "lines": [
    { "code": "network", "amount": "1.11", "basis": "Cout reseau tron, preleve en USDT" },
    { "code": "spread",  "amount": "8.29", "basis": "0.90 % du montant converti" }
  ],
  "settlement": { "p50Minutes": 1, "p95Minutes": 12 },
  "lockSeconds": 1800,
  "rateAsOf": 1788356981608,
  "rateSource": "mock",
  "limitError": null
}

Відповідь містить Cache-Control: no-store. Кешована цитата — це застаріла ціна, подана як тверда.
Порушення ліміту каналу — це не помилка HTTP: цитата повертається з об'єктом limitError, що містить код below_min або above_max і точний ліміт, тому ваш інтерфейс може показати правильне повідомлення без додаткового виклику.
rateSource вказує, звідки взялася ціна. Значення «mock» — це детерміноване джерело для розробки: воно не може запуститися у виробництві, де процес відмовляється запускатися, а не цитує заморожені ціни.

Можливі помилки: invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. Повний каталог

Читання деталізації

Масив lines містить один запис на кожну реальну комісію. Нульовий рядок не повертається: показувати «комісія каналу: 0.00» нічого не додає і захаращує інтерфейс.

Читання деталізації
code	Хто її отримує	Що це
`network`	Блокчейн-мережа	Вартість переміщення активу, що стягується в натуральній формі з депозиту до конвертації. Вона змінюється залежно від обраної мережі, іноді в рази: саме тому networkId змінює чисту суму.
`spread`	Ми	Наша маржа, виражена у відсотках від конвертованої суми. Це єдиний рядок, який є нашим доходом.
`rail`	Платіжна установа	Комісія за спосіб виплати, фіксована, пропорційна або обидві. Відсутня, коли канал нічого не стягує, що характерно для більшості відкритих каналів.
`fx`	Обмін валюти	Рядок, зарезервований для явного обмінного спреду, коли відбувається додаткова конвертація. Він не з'являється на коридорах, де валюта каналу є валютою котирування.

Інваріант, який робить таблицю перевірюваною

gross мінус сума рядків точно дорівнює net, до меншої одиниці. Ця рівність перевіряється для кожного котирування перед тим, як відповідь покине систему; якщо вона не сходиться, десь існує незадекларована маржа, і рушій видає помилку, а не повертає її. Ви можете перерахувати арифметику: у цьому суть.

Приклад із комісією за платіжний канал

Та сама сума через канал, який стягує комісію за відправлення, виводить третій рядок. Реальна відповідь, отримана на детермінованому джерелі розробки.

Запитbash

curl -sS -X POST https://fiatside.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{
    "assetId": "usdt",
    "railId": "ke_mpesa",
    "networkId": "tron",
    "direction": "sell",
    "amount": "1000"
  }'

Відповідь — реальний прикладjson

{
  "gross": "129525.90",
  "net": "128141.44",
  "currency": "KES",
  "totalCostBps": 107,
  "lines": [
    { "code": "network", "amount": "155.44", "basis": "Cout reseau tron, preleve en USDT" },
    { "code": "spread",  "amount": "582.17", "basis": "0.45 % du montant converti" },
    { "code": "rail",    "amount": "646.85", "basis": "0.50 % du montant converti" }
  ],
  "settlement": { "p50Minutes": 2, "p95Minutes": 45 },
  "limitError": null
}

Три рядки, три різні отримувачі: мережа, ми, платіжна установа. Поле totalCostBps показує загальну різницю від середньоринкового курсу в базисних пунктах — єдине число, яке варто порівнювати між сервісами, оскільки воно охоплює все, включно з тим, що інакше було б приховано в курсі.

Ліміти каналів

Сума поза межами каналу не викликає помилку HTTP: котирування повертається з об'єктом limitError. Тому ваш інтерфейс може показати суму ТА точну причину без додаткового виклику.

Витяг із відповіді — реальний прикладjson

{
  "net": "3.47",
  "currency": "EUR",
  "limitError": { "code": "below_min", "limit": "20.00" }
}

Можливі значення: below_min та above_max, а limit містить межу в основних одиницях валюти каналу. Зверніть увагу: межа застосовується до ЧИСТОЇ суми, а не до депозиту — те, що отримує бенефіціар, має вкладатися в ліміти каналу.

Вікно дійсності

Поле lockSeconds вказує, як довго курс буде зафіксований після створення ордера. Це залежить від активу: довше для стейблкоїна, коротше для волатильного.

Саме котирування не є твердим: воно орієнтовне, доки не створено ордер. Курс фіксується при створенні ордера, а не при виклику котирування.
Вікно охоплює ваше рішення, а не час підтвердження мережі. Депозит у біткоїнах може потребувати години підтверджень: блокування захищає від руху ринку, поки ви вирішуєте та вносите депозит.
Якщо депозит надходить після закінчення терміну, ордер переоцінюється, і нова сума має бути прийнята. Мовчазне переоцінювання проти клієнта неможливе за конструкцією.
Не кешуйте котирування, щоб приховати помилку застарілого курсу. Кешоване котирування — це застаріла ціна, подана як тверда, що є саме тією проблемою, яку запобігає код відмови.