Developers

Wycena operacji

Kalkulacja wyceny to jedyny endpoint otwarty obecnie i najważniejszy: zwraca szczegółowe zestawienie, które wyświetla strona. Nie wymaga klucza.

POST/api/quoteLive

Zacytuj operację

Zwraca pełne zestawienie sprzedaży: zastosowany kurs średni rynkowy, każdą opłatę w osobnej linii, kwotę netto oraz faktyczny kurs, który został uzyskany. Linie sumują się dokładnie do różnicy między kwotą brutto a netto — niezmiennik jest sprawdzany, zanim odpowiedź opuści serwer, a niezbalansowana odpowiedź nigdy nie jest zwracana.

Uwierzytelnianie: brak dzisiaj. Endpoint wyceny jest otwarty: wycena nie ujawnia żadnych danych osobowych.

Parametry

Parametry
Pole	Typ	Opis
`assetId`wymagane	string	Identyfikator zdeponowanego aktywa, na przykład „btc”, „usdt”, „sol”.
`railId`wymagane	string	Identyfikator metody wypłaty, na przykład „sepa_instant”, „br_pix”, „ke_mpesa”.
`networkId`	string	Sieć depozytu. Opcjonalnie: domyślnie używana jest pierwsza sieć aktywa. Koszt sieci znacznie różni się między sieciami, więc to pole zmienia kwotę netto.
`direction`wymagane	"sell" \| "receive"	Kierunek wejściowy. „sell”: kwota to kwota, którą wpłacasz. „receive”: kwota to kwota, którą chcesz otrzymać, a wymagany depozyt jest ustalany przez wyszukiwanie binarne.
`amount`wymagane	string	Kwota w jednostkach głównych, wysyłana jako CIĄG ZNAKÓW. Liczba zmiennoprzecinkowa JSON straciłaby jednostki pomocnicze przy dużych kwotach: ciąg znaków to jedyny format, w którym klient i serwer zgadzają się co do centa.

Żądaniebash

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"
  }'

Odpowiedź — prawdziwy przykładjson

{
  "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
}

Odpowiedź zawiera nagłówek Cache-Control: no-store. Zbuforowana wycena to nieaktualna cena podawana jako wiążąca.
Przekroczenie limitu kanału płatności nie jest błędem HTTP: wycena jest zwracana z obiektem limitError zawierającym kod below_min lub above_max oraz dokładny limit, aby Twój interfejs mógł pokazać właściwy komunikat bez drugiego wywołania.
rateSource określa, skąd pochodzi cena. Wartość „mock” to deterministyczne źródło deweloperskie: nie może wystartować w produkcji, gdzie proces odmawia uruchomienia zamiast wyceniać zamrożone ceny.

Możliwe błędy: invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. Pełny katalog

Odczyt zestawienia

Tablica lines zawiera jeden wpis na każdą rzeczywistą opłatę. Wiersz zerowy nie jest zwracany: pokazywanie „opłata za kanał: 0.00” niczego nie wnosi i zaśmieca interfejs.

Odczyt zestawienia
code	Kto ją otrzymuje	Co to jest
`network`	Sieć blockchain	Koszt przeniesienia aktywa, pobierany w naturze z depozytu przed konwersją. Zmienia się w zależności od wybranej sieci, czasem o duży czynnik: dlatego networkId zmienia kwotę netto.
`spread`	My	Nasza marża, wyrażona jako procent skonwertowanej kwoty. To jedyna pozycja stanowiąca nasz przychód.
`rail`	Instytucja płatnicza	Opłata za metodę wypłaty, stała, proporcjonalna lub obie. Nie występuje, gdy kanał nie pobiera opłat, co ma miejsce w przypadku większości otwartych kanałów.
`fx`	Wymiana walut	Pozycja zarezerwowana dla jawnego spreadu wymiany, gdy zachodzi dodatkowa konwersja. Nie pojawia się na korytarzach, gdzie waluta kanału jest walutą kwotowania.

Niezmiennik umożliwiający weryfikację tabeli

kwota brutto minus suma pozycji równa się dokładnie kwocie netto, co do najmniejszej jednostki. Ta równość jest sprawdzana przy każdej wycenie, zanim odpowiedź opuści system; jeśli się nie bilansuje, oznacza to, że gdzieś istnieje niezadeklarowana marża, i silnik zgłasza błąd zamiast ją zwrócić. Możesz powtórzyć obliczenia: o to chodzi.

Przykład z opłatą za kanał płatności

Ta sama kwota wysłana kanałem, który pobiera opłatę za wysyłkę, ujawnia trzecią linię. Rzeczywista odpowiedź uzyskana na deterministycznym źródle deweloperskim.

Żądaniebash

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"
  }'

Odpowiedź — rzeczywisty przykładjson

{
  "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
}

Trzy linie, trzej różni odbiorcy: sieć, my, instytucja płatnicza. Pole totalCostBps podaje całkowitą różnicę względem kursu średniego rynku w punktach bazowych — jedyną liczbę, którą warto porównywać między usługami, ponieważ obejmuje wszystko, w tym to, co w innym przypadku byłoby ukryte w kursie.

Limity kanałów płatności

Kwota poza zakresem kanału nie powoduje błędu HTTP: zwracana jest wycena z obiektem limitError. Twój interfejs może zatem pokazać kwotę ORAZ dokładny powód, bez drugiego wywołania.

Fragment odpowiedzi — rzeczywisty przykładjson

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

Możliwe wartości to below_min i above_max, a limit zawiera granicę w głównych jednostkach waluty kanału. Uwaga: granica dotyczy kwoty NETTO, nie depozytu — to, co otrzymuje beneficjent, musi mieścić się w limitach kanału.

Okno ważności

Pole lockSeconds określa, jak długo kurs będzie zamrożony po utworzeniu zlecenia. Zależy to od aktywa: dłużej w przypadku stablecoina, krócej w przypadku zmiennego.

Sama wycena nie jest wiążąca: ma charakter orientacyjny do momentu utworzenia zlecenia. Kurs jest blokowany przy tworzeniu zlecenia, nie przy wywołaniu wyceny.
Okno obejmuje Twoją decyzję, nie czas potwierdzenia w sieci. Depozyt w bitcoinie może wymagać godziny na potwierdzenia: blokada chroni przed ruchami rynku, gdy decydujesz i wpłacasz.
Jeśli depozyt wpłynie po wygaśnięciu, zlecenie jest ponownie wyceniane, a nowa kwota musi zostać zaakceptowana. Ciche przeszacowanie wobec klienta jest niemożliwe z założenia.
Nie buforuj wyceny, aby zamaskować błąd nieaktualnego kursu. Zbuforowana wycena to nieaktualna cena przedstawiana jako wiążąca, co jest dokładnie problemem, któremu zapobiega kod odmowy.