Developers

Angebot einer Operation

Quoting ist der einzige heute offene Endpunkt und der wichtigste: Er liefert die positionsweise Aufschlüsselung, die die Website anzeigt. Er benötigt keinen Schlüssel.

POST/api/quoteLive

Vorgang anfragen

Liefert die vollständige Aufschlüsselung eines Verkaufs: den verwendeten Mittelkurs, jede Gebühr in einer eigenen Zeile, den Nettobetrag und den tatsächlich erzielten effektiven Kurs. Die Zeilen summieren sich exakt auf die Differenz zwischen Brutto- und Nettobetrag – die Invariante wird geprüft, bevor die Antwort den Server verlässt, und eine unausgeglichene Antwort wird nie zurückgegeben.

Authentifizierung: heute keine. Der Kurs-Endpunkt ist offen: Ein Kurs gibt keine persönlichen Daten preis.

Parameter

Parameter
Feld	Typ	Beschreibung
`assetId`erforderlich	string	Kennung des hinterlegten Vermögenswerts, z. B. „btc“, „usdt“, „sol“.
`railId`erforderlich	string	Kennung der Auszahlungsmethode, z. B. „sepa_instant“, „br_pix“, „ke_mpesa“.
`networkId`	string	Einzahlungsnetzwerk. Optional: Standardmäßig wird das erste Netzwerk des Vermögenswerts verwendet. Die Netzkosten variieren stark zwischen den Netzwerken, daher ändert dieses Feld den Nettobetrag.
`direction`erforderlich	"sell" \| "receive"	Eingaberichtung. „sell“: Der Betrag ist das, was Sie einzahlen. „receive“: Der Betrag ist das, was Sie erhalten möchten, und die erforderliche Einzahlung wird per binärer Suche ermittelt.
`amount`erforderlich	string	Betrag in Haupteinheiten, als STRING gesendet. Ein JSON-Float würde bei großen Beträgen Untereinheiten verlieren: Ein String ist das einzige Format, bei dem sich Client und Server auf den Cent genau einig sind.

Anfragebash

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

Antwort – reales Beispieljson

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

Die Antwort enthält Cache-Control: no-store. Ein zwischengespeichertes Angebot ist ein veralteter Preis, der als verbindlich angezeigt wird.
Eine Verletzung der Zahlungsgrenze ist kein HTTP-Fehler: Das Angebot wird mit einem limitError-Objekt zurückgegeben, das den Code below_min oder above_max und die genaue Grenze enthält, sodass Ihre Oberfläche die richtige Meldung anzeigen kann, ohne einen zweiten Aufruf zu benötigen.
rateSource gibt an, woher der Preis stammt. Der Wert „mock“ ist die deterministische Entwicklungsquelle: Sie kann nicht in der Produktion starten, wo der Prozess sich weigert zu starten, anstatt eingefrorene Preise anzubieten.

Mögliche Fehler: invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. Vollständiger Katalog

Die Aufschlüsselung lesen

Das Array lines enthält einen Eintrag pro tatsächlicher Gebühr. Eine Nullzeile wird nicht zurückgegeben: Die Anzeige von „Zahlungsweg-Gebühr: 0,00“ fügt nichts hinzu und überlädt die Oberfläche.

Die Aufschlüsselung lesen
code	Wer sie erhält	Was sie ist
`network`	Das Blockchain-Netzwerk	Kosten für die Übertragung des Vermögenswerts, die in Form von Sachwerten von der Einzahlung vor der Umrechnung abgezogen werden. Sie variiert je nach gewähltem Netzwerk, manchmal um einen großen Faktor: Deshalb ändert networkId den Nettobetrag.
`spread`	Wir	Unsere Marge, ausgedrückt als Prozentsatz des umgerechneten Betrags. Sie ist die einzige Position, die unsere Einnahme darstellt.
`rail`	Das Zahlungsinstitut	Gebühr für die Auszahlungsmethode, fest, proportional oder beides. Fehlt, wenn der Zahlungsweg nichts verlangt, was bei den meisten offenen Zahlungswegen der Fall ist.
`fx`	Devisen	Position, die für einen expliziten Wechselkursaufschlag reserviert ist, wenn eine zusätzliche Umrechnung stattfindet. Sie erscheint nicht bei Korridoren, in denen die Zahlungsweg-Währung die Angebotswährung ist.

Die Invariante, die die Tabelle überprüfbar macht

Brutto minus der Summe der Positionen ergibt exakt Netto, bis auf die Untereinheit. Diese Gleichheit wird bei jedem Angebot überprüft, bevor die Antwort den Server verlässt; wenn sie nicht aufgeht, existiert irgendwo eine nicht deklarierte Marge, und die Engine wirft einen Fehler, anstatt sie zurückzugeben. Sie können die Arithmetik nachvollziehen: Das ist der Punkt.

Ein Beispiel mit einer Rail-Gebühr

Der gleiche Betrag über eine Rail, die für den Versand Gebühren erhebt, ergibt die dritte Zeile. Echte Antwort, erhalten von der deterministischen Entwicklungsquelle.

Anfragebash

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

Antwort – echtes Beispieljson

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

Drei Zeilen, drei verschiedene Empfänger: das Netzwerk, wir, das Zahlungsinstitut. Das Feld totalCostBps gibt die gesamte Abweichung vom Mittelkurs in Basispunkten an – die einzige Zahl, die zwischen Diensten vergleichbar ist, da sie alles abdeckt, einschließlich dessen, was sonst in einem Kurs versteckt wäre.

Rail-Grenzen

Ein Betrag außerhalb der Rail-Grenzen erzeugt keinen HTTP-Fehler: Das Angebot wird mit einem limitError-Objekt zurückgegeben. Ihre Oberfläche kann daher den Betrag UND den genauen Grund anzeigen, ohne einen zweiten Aufruf.

Antwortauszug – echtes Beispieljson

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

Mögliche Werte sind below_min und above_max, und limit enthält die Grenze in Haupteinheiten der Rail-Währung. Hinweis: Die Grenze gilt für den NETTO-Betrag, nicht für die Einzahlung – was der Empfänger erhält, muss innerhalb der Rail-Grenzen liegen.

Gültigkeitsfenster

Das Feld lockSeconds gibt an, wie lange der Kurs nach Erstellung der Order eingefroren bleibt. Es hängt vom Asset ab: länger bei einem Stablecoin, kürzer bei einem volatilen.

Das Angebot selbst ist nicht verbindlich: Es ist indikativ, bis eine Order erstellt wird. Der Kurs wird bei Ordererstellung gesperrt, nicht beim Angebotsaufruf.
Das Fenster deckt Ihre Entscheidung ab, nicht die Bestätigungszeit des Netzwerks. Eine Bitcoin-Einzahlung kann eine Stunde Bestätigungen benötigen: Die Sperre schützt vor Marktbewegungen, während Sie entscheiden und einzahlen.
Wenn die Einzahlung nach Ablauf eintrifft, wird die Order neu bewertet und der neue Betrag muss akzeptiert werden. Eine stille Neubepreisung gegenüber dem Kunden ist konstruktionsbedingt unmöglich.
Cachen Sie kein Angebot, um einen Fehler mit veraltetem Kurs zu überdecken. Ein gecachtes Angebot ist ein veralteter Preis, der als verbindlich dargestellt wird – genau das Problem, das der Ablehnungscode verhindert.