Developers

API-Dokumentation

Eine API, die dieselbe Gebührenaufschlüsselung wie die Website liefert, Zeile für Zeile, ohne versteckte Marge. Diese Seite beschreibt die Konventionen, die von jedem Endpunkt geteilt werden, und gibt präzise an, was heute offen ist.

Was heute offen ist

Der 1-Endpunkt ist tatsächlich verfügbar und aufrufbar: die Preisstellung. Die anderen 5 sind als Vertrag veröffentlicht, sodass Sie bauen können, bevor sie geöffnet werden, und jeder trägt eine explizite Kennzeichnung.

Wir dokumentieren im Voraus, weil es einer Integration hilft. Ihnen zu suggerieren, dass es verdrahtet ist, wäre nicht hilfreich: Jeder Endpunkt gibt seinen Status an, und Beispielantworten für offene Endpunkte sind tatsächlich erhaltene Antworten, keine Attrappen.

Basis-URL und Versionierung

Zwei Basen koexistieren: diejenige, die heute antwortet, und die versionierte API, die mit ausgegebenen Schlüsseln kommen wird.

Heute: /api Live
Versionierte API: /api/v1 Published contract, not open

Die Version befindet sich im Pfad, nicht in einem Header: Eine URL muss überleben, wenn sie in ein Ticket eingefügt wird. Eine bahnbrechende Änderung – ein entferntes Feld, ein geänderter Typ, andere Semantik – eröffnet eine neue Version; die vorherige wird mindestens sechs Monate lang weiterhin bedient, mit ihrem Enddatum im Änderungsprotokoll angekündigt. Das Hinzufügen eines Feldes ist nicht bahnbrechend: Ihr Client muss Felder ignorieren, die er nicht kennt.

Konventionen

Sie gelten für jeden Endpunkt, offen oder zukünftig. Die meisten existieren aus einem Grund: niemals einen Cent auf der Übertragung verlieren.

Beträge sind Zeichenfolgen oder Ganzzahlen von Untereinheiten

Niemals eine Gleitkommazahl. In JSON ist 0,1 + 0,2 nicht 0,3, und ein großer Betrag verliert bei der Serialisierung Untereinheiten. Beträge in Haupteinheiten werden daher als Zeichenfolgen gesendet, und interne Beträge als Ganzzahlen von Untereinheiten mit ihrer Dezimalstellenanzahl.

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

Dezimalstellen hängen von der Währung ab

Der Euro hat zwei Dezimalstellen, der CFA-Franc und der vietnamesische Dong haben keine. Härten Sie nicht „× 100“ ein: Lesen Sie currencyDecimals oder das Feld decimals aus den Referenzdaten.

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

Kryptobeträge sind in Basiseinheiten

Die Einzahlung wird mit ihrer Dezimalstellenanzahl zurückgegeben: 8 für Bitcoin, 6 für USDT, 18 für Ether. Dasselbe Tickersymbol kann je nach Netzwerk unterschiedliche Dezimalstellen haben: Vertrauen Sie dem Feld, nicht Ihrem Gedächtnis.

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

Zeitstempel

Daten sind ISO 8601 UTC. Eine bewusste Ausnahme: rateAsOf ist ein Unix-Zeitstempel in Millisekunden, weil er eine Altersberechnung speist, keine Anzeige. Er trägt das Datum der Marktdaten, nicht Ihrer Anfrage: Diese Unterscheidung macht einen veralteten Preis erkennbar.

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

Kennungen sind stabil

Eine Kennung für einen Vermögenswert, ein Zahlungssystem oder ein Land ändert sich nie und wird nie neu vergeben. Ein geschlossenes Zahlungssystem behält seine eigene, mit seiner Phase und seinem Grund: Ihre Integration kann sehen, warum es aus Ihren Optionen verschwunden ist, anstatt ein Loch zu finden.

An den Menschen gerichtete Nachrichten sind zweisprachig

Ein Ablehnungsgrund wird in Französisch und Englisch im selben Objekt zurückgegeben. Sie zeigen den, der zu Ihrem Benutzer passt, ohne eine Übersetzungstabelle auf Ihrer Seite pflegen zu müssen.

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

Erster Aufruf

Für die Preisstellung ist kein Schlüssel erforderlich. Dieser Aufruf funktioniert unverändert.

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 – echtes 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
}

Das Feld rateSource gibt an, woher der Preis stammt. Der Wert „mock“ ist die deterministische Entwicklungsquelle, die in der Produktion nicht starten kann: Der Prozess weigert sich zu starten, anstatt eingefrorene Preise zu stellen.

Abschnitte

Was die API nicht tun wird

Die Grenzen einer API zu kennen, ist ebenso nützlich wie ihre Fähigkeiten.

Keine Auszahlungen an Dritte. Der Name des Begünstigten muss mit der verifizierten Identität des Auftragsinhabers übereinstimmen, und Zahlungssysteme prüfen jetzt den Namen gegen das Konto.
Keine Kontoeinrichtung oder Identitätsprüfung über die API. Diese Schritte finden in einem Ablauf statt, in dem der Benutzer sieht, was er akzeptiert.
Kein Schlüssel in einem URL-Parameter. URLs landen in Protokollen, Referrer-Headern und Verläufen: Ein so übergebener Schlüssel ist ein Schlüssel, der widerrufen werden muss.
Kein Zwischenspeichern eines Angebots auf unserer Seite. Die Antwort trägt Cache-Control: no-store, und Ihre Integration sollte nicht versuchen, dies zu umgehen: Ein zwischengespeichertes Angebot ist ein veralteter Preis, der als verbindlich dargestellt wird.
Kein Kryptokauf-Endpunkt. Der Dienst läuft in eine Richtung, von digitalem Vermögenswert zu gesetzlichem Zahlungsmittel.