Developers

Dokumentacja API

API, która zwraca takie samo zestawienie opłat jak strona, pozycja po pozycji, bez ukrytej marży. Ta strona opisuje konwencje wspólne dla wszystkich punktów końcowych i precyzyjnie określa, co jest dziś otwarte.

Co jest dziś otwarte

Punkt końcowy 1 jest faktycznie wystawiony i wywoływalny: wycena. Pozostałe 5 są opublikowane jako kontrakt, więc można budować, zanim zostaną otwarte, a każdy ma wyraźną odznakę.

Dokumentujemy z wyprzedzeniem, ponieważ pomaga to w integracji. Pozwalanie Ci wierzyć, że jest podłączony, nie pomogłoby: każdy punkt końcowy podaje swój status, a przykładowe odpowiedzi dla otwartych punktów końcowych są odpowiedziami faktycznie uzyskanymi, a nie makietami.

Adres bazowy i wersjonowanie

Współistnieją dwie bazy: ta, która odpowiada dziś, oraz wersjonowane API, które pojawi się wraz z wydanymi kluczami.

Dziś: /api Live
Wersjonowane API: /api/v1 Published contract, not open

Wersja znajduje się w ścieżce, a nie w nagłówku: adres URL musi przetrwać wklejenie do zgłoszenia. Zmiana przełomowa — usunięte pole, zmieniony typ, inna semantyka — otwiera nową wersję; poprzednia pozostaje obsługiwana przez co najmniej sześć miesięcy, a jej data końcowa jest ogłaszana w dzienniku zmian. Dodanie pola nie jest zmianą przełomową: Twój klient musi ignorować pola, których nie zna.

Konwencje

Obowiązują na każdym punkcie końcowym, otwartym lub nadchodzącym. Większość z nich istnieje z jednego powodu: aby nigdy nie stracić ani centa w transporcie.

Kwoty są ciągami znaków lub liczbami całkowitymi jednostek mniejszych

Nigdy liczbą zmiennoprzecinkową. W JSON 0.1 + 0.2 to nie 0.3, a duża kwota traci mniejsze jednostki podczas serializacji. Kwoty w jednostkach głównych są zatem wysyłane jako ciągi znaków, a kwoty wewnętrzne jako liczby całkowite jednostek mniejszych z ich liczbą miejsc po przecinku.

{
  "net": "912.28",
  "currency": "EUR",
  "currencyDecimals": 2
}

Liczba miejsc po przecinku zależy od waluty

Euro ma dwa miejsca po przecinku, frank CFA i dong wietnamski nie mają żadnego. Nie koduj na sztywno „× 100”: odczytaj currencyDecimals lub pole decimals z danych referencyjnych.

{ "amount": "125000", "currency": "XOF", "currencyDecimals": 0 }

Kwoty kryptowalut są w jednostkach bazowych

Depozyt jest zwracany z liczbą miejsc po przecinku: 8 dla bitcoina, 6 dla USDT, 18 dla etera. Ten sam ticker może istnieć z różną liczbą miejsc po przecinku w zależności od sieci: ufaj polu, a nie pamięci.

{ "deposit": { "amount": "1000.000000", "ticker": "USDT", "decimals": 6 } }

Znaczniki czasu

Daty są w formacie ISO 8601 UTC. Jeden celowy wyjątek: rateAsOf to znacznik czasu Uniksa w milisekundach, ponieważ zasila obliczenie wieku, a nie wyświetlanie. Nosi datę danych RYNKOWYCH, a nie Twojego żądania: to rozróżnienie sprawia, że nieaktualna cena jest wykrywalna.

{ "rateAsOf": 1788356981608, "rateSource": "coingecko" }

Identyfikatory są stabilne

Identyfikator aktywa, kanału płatności lub kraju nigdy się nie zmienia i nigdy nie jest ponownie przypisywany. Zamknięty kanał zachowuje swój własny, wraz z fazą i powodem: Twoja integracja może zobaczyć, dlaczego zniknął z Twoich opcji, zamiast znajdować lukę.

Komunikaty skierowane do ludzi są dwujęzyczne

Powód odmowy jest zwracany po francusku i angielsku w tym samym obiekcie. Pokazujesz ten pasujący do Twojego użytkownika, bez konieczności utrzymywania tabeli tłumaczeń po swojej stronie.

{ "reason": { "fr": "…", "en": "…" } }

Pierwsze wywołanie

Do wyceny nie jest potrzebny klucz. To wywołanie działa bez zmian.

Żą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
}

Pole rateSource określa, skąd pochodzi cena. Wartość „mock” to deterministyczne źródło deweloperskie, które nie może zostać uruchomione w produkcji: proces odmawia startu, zamiast podawać zamrożone ceny.

Sekcje

Czego API nie będzie robić

Ograniczenia API są równie przydatne do poznania jak jego możliwości.

Brak wypłat do podmiotów trzecich. Nazwa beneficjenta musi odpowiadać zweryfikowanej tożsamości posiadacza zamówienia, a kanały płatności sprawdzają teraz nazwę względem konta.
Brak tworzenia konta lub weryfikacji tożsamości przez API. Te kroki odbywają się w procesie, w którym użytkownik widzi, co akceptuje.
Brak klucza w parametrze adresu URL. Adresy URL trafiają do logów, nagłówków referrer i historii: klucz przekazany w ten sposób to klucz do unieważnienia.
Brak buforowania wyceny po naszej stronie. Odpowiedź niesie nagłówek Cache-Control: no-store, a Twoja integracja nie powinna go obchodzić: buforowana wycena to nieaktualna cena przedstawiana jako wiążąca.
Brak punktu końcowego zakupu kryptowalut. Usługa działa w jednym kierunku: od aktywa cyfrowego do waluty prawnej.