Fiatside
fr

Developers

API-documentatie

Een API die dezelfde kostenopsplitsing retourneert als de site, regel voor regel, zonder verborgen marge. Deze pagina beschrijft de conventies die alle endpoints delen en vermeldt precies wat vandaag open is.

Wat vandaag open is

Het 1-endpoint is daadwerkelijk blootgesteld en aanroepbaar: het opvragen van een koers. De andere 5 zijn gepubliceerd als contract, zodat u kunt bouwen voordat ze opengaan, en elk draagt een expliciete badge.

We documenteren vooraf omdat dat een integratie helpt. U laten geloven dat het is aangesloten zou dat niet doen: elk endpoint vermeldt zijn status, en voorbeeldantwoorden voor open endpoints zijn werkelijk verkregen antwoorden, geen mock-ups.

01

Basis-URL en versiebeheer

Er bestaan twee basissen naast elkaar: degene die vandaag antwoordt, en de versiebeheerde API die zal komen met uitgegeven sleutels.

Vandaag
/api Live
Versiebeheerde API
/api/v1 Published contract, not open

De versie staat in het pad, niet in een header: een URL moet het overleven om in een ticket te worden geplakt. Een brekende wijziging — een verwijderd veld, een gewijzigd type, andere semantiek — opent een nieuwe versie; de vorige blijft ten minste zes maanden beschikbaar, met de einddatum aangekondigd in de changelog. Een veld toevoegen is niet brekend: uw client moet velden negeren die hij niet kent.

02

Conventies

Ze gelden voor elk endpoint, open of aanstaande. De meeste bestaan om één reden: nooit een cent verliezen onderweg.

Bedragen zijn strings, of gehele getallen van kleinere eenheden

Nooit een float. In JSON is 0.1 + 0.2 niet 0.3, en een groot bedrag verliest kleinere eenheden bij serialisatie. Bedragen in hoofdeenheden worden daarom als strings verzonden, en interne bedragen als gehele getallen van kleinere eenheden met hun decimalenaantal.

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

Decimalen hangen af van de valuta

De euro heeft twee decimalen, de CFA-frank en de Vietnamese dong hebben er geen. Hardcode “× 100” niet: lees currencyDecimals, of het veld decimals uit de referentiegegevens.

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

Cryptobedragen zijn in basiseenheden

De storting wordt geretourneerd met zijn decimalenaantal: 8 voor bitcoin, 6 voor USDT, 18 voor ether. Dezelfde ticker kan bestaan met verschillende decimalen afhankelijk van het netwerk: vertrouw het veld, niet uw geheugen.

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

Tijdstempels

Datums zijn ISO 8601 UTC. Eén bewuste uitzondering: rateAsOf is een Unix-tijdstempel in milliseconden, omdat het een leeftijdsberekening voedt, geen weergave. Het draagt de datum van de marktDATA, niet van uw verzoek: dat onderscheid maakt een verouderde prijs detecteerbaar.

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

Identificaties zijn stabiel

Een identificatie van een actief, rail of land verandert nooit en wordt nooit opnieuw toegewezen. Een gesloten rail behoudt de zijne, met zijn fase en reden: uw integratie kan zien waarom het uw opties verliet, in plaats van een gat te vinden.

Naar mensen gerichte berichten zijn tweetalig

Een weigeringsreden wordt in het Frans en Engels in hetzelfde object geretourneerd. U toont degene die bij uw gebruiker past, zonder dat u een vertaaltabel hoeft te onderhouden.

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

Eerste aanroep

Er is geen sleutel nodig om een koers op te vragen. Deze aanroep werkt zoals hij is.

Verzoekbash
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"
  }'
Antwoord — echt voorbeeldjson
{
  "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
}

Het veld rateSource vermeldt waar de prijs vandaan komt. De waarde “mock” is de deterministische ontwikkelingsbron, die niet kan opstarten in productie: het proces weigert te starten in plaats van bevroren prijzen te quoteren.

04

Secties

05

Wat de API niet zal doen

De beperkingen van een API zijn net zo nuttig om te kennen als de mogelijkheden.

  • Geen uitbetalingen aan derden. De naam van de begunstigde moet overeenkomen met de geverifieerde identiteit van de orderhouder, en betalingsrails controleren nu naam tegen rekening.
  • Geen accountcreatie of identiteitsverificatie via de API. Die stappen gebeuren in een flow waarin de gebruiker ziet wat hij accepteert.
  • Geen sleutel in een URL-parameter. URL's belanden in logs, referrer-headers en geschiedenissen: een sleutel die zo wordt doorgegeven, is een sleutel om in te trekken.
  • Geen caching van een koers aan onze kant. Het antwoord draagt Cache-Control: no-store, en uw integratie moet er niet omheen werken: een gecachte koers is een verouderde prijs die als vast wordt gepresenteerd.
  • Geen endpoint voor aankoop van crypto. De dienst werkt één richting op, van digitaal actief naar wettig betaalmiddel.