Developers

Documentazione API

Un'API che restituisce la stessa ripartizione delle commissioni del sito, riga per riga, senza margine nascosto. Questa pagina descrive le convenzioni condivise da ogni endpoint e indica con precisione ciò che è aperto oggi.

Cosa è aperto oggi

L'endpoint 1 è effettivamente esposto e chiamabile: il quoting. Gli altri 5 sono pubblicati come contratto, così puoi sviluppare prima che vengano aperti, e ciascuno riporta un badge esplicito.

Documentiamo in anticipo perché aiuta un'integrazione. Lasciarti credere che sia collegato non sarebbe d'aiuto: ogni endpoint dichiara il proprio stato e le risposte di esempio per gli endpoint aperti sono risposte realmente ottenute, non simulazioni.

URL di base e versionamento

Coesistono due basi: quella che risponde oggi e l'API versionata che arriverà con le chiavi emesse.

Oggi: /api Live
API versionata: /api/v1 Published contract, not open

La versione vive nel percorso, non in un header: un URL deve sopravvivere all'essere incollato in un ticket. Una modifica sostanziale — un campo rimosso, un tipo cambiato, una semantica diversa — apre una nuova versione; la precedente rimane servita per almeno sei mesi, con la sua data di fine annunciata nel changelog. Aggiungere un campo non è sostanziale: il tuo client deve ignorare i campi che non conosce.

Convenzioni

Valgono su ogni endpoint, aperto o imminente. La maggior parte esiste per un solo motivo: non perdere mai un centesimo in transito.

Gli importi sono stringhe o interi di unità minori

Mai un float. In JSON, 0.1 + 0.2 non è 0.3 e un importo elevato perde unità minori nella serializzazione. Gli importi in unità maggiori sono quindi inviati come stringhe e gli importi interni come interi di unità minori con il loro numero di decimali.

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

I decimali dipendono dalla valuta

L'euro ha due decimali, il franco CFA e il dong vietnamita non ne hanno. Non codificare in modo rigido "× 100": leggi currencyDecimals o il campo decimals dai dati di riferimento.

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

Gli importi in criptovaluta sono in unità di base

Il deposito viene restituito con il suo numero di decimali: 8 per bitcoin, 6 per USDT, 18 per ether. Lo stesso ticker può esistere con decimali diversi a seconda della rete: fidati del campo, non della tua memoria.

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

Timestamp

Le date sono ISO 8601 UTC. Un'eccezione deliberata: rateAsOf è un timestamp Unix in millisecondi, perché alimenta un calcolo di età, non una visualizzazione. Riporta la data dei dati di mercato, non della tua richiesta: questa distinzione rende rilevabile un prezzo obsoleto.

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

Gli identificativi sono stabili

Un identificativo di asset, canale o paese non cambia mai e non viene mai riassegnato. Un canale chiuso mantiene il proprio, con la sua fase e il motivo: la tua integrazione può vedere perché è uscito dalle tue opzioni, invece di trovare un buco.

I messaggi rivolti agli utenti sono bilingui

Un motivo di rifiuto viene restituito in francese e inglese nello stesso oggetto. Mostri quello che corrisponde al tuo utente, senza tabella di traduzione da mantenere dalla tua parte.

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

Prima chiamata

Nessuna chiave è necessaria per il quoting. Questa chiamata funziona così com'è.

Richiestabash

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

Risposta — esempio realejson

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

Il campo rateSource indica da dove proviene il prezzo. Il valore "mock" è la sorgente di sviluppo deterministica, che non può avviarsi in produzione: il processo rifiuta di partire piuttosto che quotare prezzi congelati.

Sezioni

Cosa l'API non farà

I limiti di un'API sono utili da conoscere quanto le sue capacità.

Niente pagamenti a terzi. Il nome del beneficiario deve corrispondere all'identità verificata del titolare dell'ordine e i canali di pagamento ora verificano il nome rispetto al conto.
Nessuna creazione di account o verifica dell'identità tramite l'API. Questi passaggi avvengono in un flusso in cui l'utente vede ciò che accetta.
Nessuna chiave in un parametro URL. Gli URL finiscono nei log, negli header referrer e nelle cronologie: una chiave passata in quel modo è una chiave da revocare.
Nessuna memorizzazione nella cache di una quotazione lato nostro. La risposta include Cache-Control: no-store e la tua integrazione non dovrebbe aggirarlo: una quotazione in cache è un prezzo obsoleto presentato come fermo.
Nessun endpoint di acquisto di criptovalute. Il servizio funziona in una direzione: da asset digitale a valuta legale.