Developers

Een operatie quoteren

Quoting is het enige eindpunt dat vandaag open is, en het belangrijkste: het retourneert de regel-voor-regel uitsplitsing die de site toont. Het vereist geen sleutel.

POST/api/quoteLive

Een transactie offerte aanvragen

Geeft de volledige uitsplitsing van een verkoop: de gebruikte middenkoers, elke vergoeding op een eigen regel, het nettobedrag en de effectieve koers die daadwerkelijk is verkregen. De regels tellen op tot exact het verschil tussen bruto en netto — de invariant wordt gecontroleerd voordat het antwoord de server verlaat, en een niet-gebalanceerd antwoord wordt nooit geretourneerd.

Authenticatie: vandaag geen. Het quote-eindpunt is open: een quote onthult geen persoonlijke gegevens.

Parameters

Parameters
Veld	Type	Beschrijving
`assetId`vereist	string	Identificatie van het gestorte activum, bijvoorbeeld “btc”, “usdt”, “sol”.
`railId`vereist	string	Identificatie van de uitbetalingsmethode, bijvoorbeeld “sepa_instant”, “br_pix”, “ke_mpesa”.
`networkId`	string	Stortingsnetwerk. Optioneel: het eerste netwerk van het activum wordt standaard gebruikt. Netwerkkosten variëren sterk tussen netwerken, dus dit veld verandert het nettobedrag.
`direction`vereist	"sell" \| "receive"	Invoerrichting. “sell”: het bedrag is wat u stort. “receive”: het bedrag is wat u wilt ontvangen, en de vereiste storting wordt bepaald via binair zoeken.
`amount`vereist	string	Bedrag in hoofdeenheden, verzonden als een STRING. Een JSON float zou kleine eenheden verliezen bij grote bedragen: een string is het enige formaat waarop client en server het eens zijn tot op de cent.

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 antwoord bevat Cache-Control: no-store. Een gecachte offerte is een verouderde prijs die als vaste prijs wordt gepresenteerd.
Een overschrijding van een limiet van een betaalroute is geen HTTP-fout: de offerte wordt geretourneerd met een limitError-object met de code below_min of above_max en de exacte limiet, zodat uw interface de juiste melding kan tonen zonder een tweede aanroep.
rateSource geeft aan waar de prijs vandaan komt. De waarde “mock” is de deterministische ontwikkelingsbron: deze kan niet opstarten in productie, waar het proces weigert te starten in plaats van bevroren prijzen te offerten.

Mogelijke fouten: invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. Volledige catalogus

De uitsplitsing lezen

De lines-array bevat één item per echte kostenpost. Een nulregel wordt niet geretourneerd: het tonen van “railfee: 0.00” voegt niets toe en vervuilt de interface.

De uitsplitsing lezen
code	Wie het ontvangt	Wat het is
`network`	Het blockchainnetwerk	Kosten voor het verplaatsen van het actief, in natura afgehouden van de storting vóór conversie. Het varieert met het gekozen netwerk, soms met een grote factor: daarom verandert networkId het nettobedrag.
`spread`	Wij	Onze marge, uitgedrukt als percentage van het geconverteerde bedrag. Het is de enige regel die onze inkomsten zijn.
`rail`	De betaalinstelling	Uitbetalingsmethodevergoeding, vast, proportioneel of beide. Afwezig wanneer de rail niets in rekening brengt, wat het geval is voor de meeste open rails.
`fx`	Wisselkoers	Regel gereserveerd voor een expliciete wisselspread wanneer een extra conversie plaatsvindt. Het verschijnt niet op corridors waar de railvaluta de quoteringsvaluta is.

De invariant die de tabel controleerbaar maakt

bruto minus de som van de regels is exact gelijk aan netto, tot op de kleinste munteenheid. Die gelijkheid wordt bij elke quote gecontroleerd voordat het antwoord vertrekt; als het niet klopt, bestaat er een niet-aangegeven marge ergens, en de engine gooit een fout in plaats van het te retourneren. U kunt de rekenkunde opnieuw doen: dat is het punt.

Een voorbeeld met een railvergoeding

Hetzelfde bedrag naar een rail die kosten in rekening brengt voor verzending, brengt de derde regel naar voren. Echte respons, verkregen op de deterministische ontwikkelingsbron.

Verzoekbash

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

Respons — echt voorbeeldjson

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

Drie regels, drie verschillende ontvangers: het netwerk, wij, de betaalinstelling. Het veld totalCostBps geeft het totale verschil ten opzichte van de mid-marketkoers in basispunten — het enige getal dat de moeite waard is om tussen diensten te vergelijken, omdat het alles dekt, inclusief wat anders binnen een koers verborgen zou blijven.

Raillimieten

Een bedrag buiten de railgrenzen levert geen HTTP-fout op: de quote wordt geretourneerd, met een limitError-object. Uw interface kan dus het bedrag EN de exacte reden tonen, zonder tweede aanroep.

Fragment uit de respons — echt voorbeeldjson

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

Mogelijke waarden zijn below_min en above_max, en limit bevat de grens in hoofdeenheden van de railvaluta. Let op: de grens is van toepassing op het NETTO-bedrag, niet op de storting — wat de begunstigde ontvangt, is wat binnen de raillimieten moet passen.

Geldigheidsvenster

Het veld lockSeconds vermeldt hoe lang de koers bevroren blijft zodra de order is aangemaakt. Het hangt af van het activum: langer bij een stablecoin, korter bij een volatiel activum.

De quote zelf is niet bindend: deze is indicatief totdat een order wordt aangemaakt. De koers wordt vastgelegd bij het aanmaken van de order, niet bij de quote-aanroep.
Het venster dekt uw beslissing, niet de bevestigingstijd van het netwerk. Een bitcoin-storting kan een uur aan bevestigingen nodig hebben: de lock beschermt tegen marktbewegingen terwijl u beslist en stort.
Als de storting na het verstrijken van de geldigheid aankomt, wordt de order opnieuw gequoteerd en moet het nieuwe bedrag worden geaccepteerd. Een stille herprijzing tegen de klant is door constructie onmogelijk.
Cache geen quote om een verouderde-koersfout te verdoezelen. Een gecachte quote is een verouderde prijs die als bindend wordt gepresenteerd, wat precies het probleem is dat de weigeringscode voorkomt.