Developers

Quotazione di un'operazione

Il quoting è l'unico endpoint aperto oggi, ed è il più importante: restituisce il dettaglio riga per riga che il sito mostra. Non richiede chiave.

POST/api/quoteLive

Preventiva un'operazione

Restituisce la ripartizione completa di una vendita: il tasso di mercato medio utilizzato, ogni commissione su una propria riga, l'importo netto e il tasso effettivo realmente ottenuto. Le righe sommano esattamente alla differenza tra lordo e netto: l'invariante viene verificato prima che la risposta lasci il sistema, e una risposta sbilanciata non viene mai restituita.

Autenticazione: nessuna oggi. L'endpoint delle quotazioni è aperto: una quotazione non rivela dati personali.

Parametri

Parametri
Campo	Tipo	Descrizione
`assetId`obbligatorio	string	Identificatore dell'asset depositato, ad esempio "btc", "usdt", "sol".
`railId`obbligatorio	string	Identificatore del metodo di pagamento, ad esempio "sepa_instant", "br_pix", "ke_mpesa".
`networkId`	string	Rete di deposito. Opzionale: viene utilizzata di default la prima rete dell'asset. Il costo di rete varia molto tra le reti, quindi questo campo modifica l'importo netto.
`direction`obbligatorio	"sell" \| "receive"	Direzione di input. "sell": l'importo è ciò che depositi. "receive": l'importo è ciò che desideri ricevere, e il deposito richiesto viene risolto tramite ricerca binaria.
`amount`obbligatorio	string	Importo in unità principali, inviato come STRINGA. Un float JSON perderebbe le unità secondarie su importi elevati: una stringa è l'unico formato su cui client e server concordano al centesimo.

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
}

La risposta include Cache-Control: no-store. Una preventiva memorizzata nella cache è un prezzo obsoleto servito come fermo.
Una violazione del limite del canale non è un errore HTTP: la preventiva viene restituita con un oggetto limitError che riporta il codice below_min o above_max e il limite esatto, così la tua interfaccia può mostrare il messaggio corretto senza una seconda chiamata.
rateSource indica da dove proviene il prezzo. Il valore "mock" è la sorgente di sviluppo deterministica: non può avviarsi in produzione, dove il processo rifiuta di partire piuttosto che quotare prezzi congelati.

Possibili errori: invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. Catalogo completo

Lettura del dettaglio

L'array lines contiene una voce per ogni addebito reale. Una riga zero non viene restituita: mostrare "commissione circuito: 0.00" non aggiunge nulla e appesantisce l'interfaccia.

Lettura del dettaglio
code	Chi lo riceve	Cos'è
`network`	La rete blockchain	Costo del trasferimento dell'asset, prelevato in natura dal deposito prima della conversione. Varia con la rete scelta, a volte di un ampio fattore: è per questo che networkId cambia l'importo netto.
`spread`	Noi	Il nostro margine, espresso come percentuale dell'importo convertito. È l'unica riga che costituisce il nostro ricavo.
`rail`	L'istituto di pagamento	Commissione del metodo di pagamento, fissa, proporzionale o entrambe. Assente quando il circuito non addebita nulla, come per la maggior parte dei circuiti aperti.
`fx`	Cambio valuta	Riga riservata a uno spread di cambio esplicito quando avviene una conversione aggiuntiva. Non appare nei corridoi in cui la valuta del circuito è la valuta di quotazione.

L'invariante che rende verificabile la tabella

lordo meno la somma delle righe è uguale al netto esattamente, fino all'unità minima. Questa uguaglianza viene verificata su ogni quotazione prima che la risposta parta; se non torna, esiste un margine non dichiarato da qualche parte, e il motore solleva un errore piuttosto che restituirla. Puoi rifare l'aritmetica: è questo il punto.

Un esempio con una commissione di rete

Lo stesso importo verso una rete che addebita l'invio fa emergere la terza riga. Risposta reale, ottenuta sulla sorgente di sviluppo deterministica.

Richiestabash

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

Risposta — esempio realejson

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

Tre righe, tre destinatari diversi: la rete, noi, l'istituto di pagamento. Il campo totalCostBps indica lo scarto totale dal tasso di mercato medio in punti base — l'unico numero che vale la pena confrontare tra servizi, perché copre tutto, incluso ciò che altrimenti si nasconderebbe dentro un tasso.

Limiti di rete

Un importo fuori dai limiti di rete non produce un errore HTTP: la quotazione viene restituita, con un oggetto limitError. La tua interfaccia può quindi mostrare l'importo E il motivo esatto, senza una seconda chiamata.

Estratto di risposta — esempio realejson

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

I valori possibili sono below_min e above_max, e limit contiene il limite in unità principali della valuta di rete. Nota: il limite si applica all'importo NETTO, non al deposito — ciò che il beneficiario riceve è ciò che deve rientrare nei limiti di rete.

Finestra di validità

Il campo lockSeconds indica per quanto tempo il tasso sarà congelato una volta creato l'ordine. Dipende dall'asset: più lungo su una stablecoin, più breve su uno volatile.

La quotazione in sé non è vincolante: è indicativa finché non viene creato un ordine. Il tasso si blocca alla creazione dell'ordine, non alla chiamata di quotazione.
La finestra copre la tua decisione, non il tempo di conferma della rete. Un deposito in bitcoin può richiedere un'ora di conferme: il blocco protegge dal movimento del mercato mentre decidi e depositi.
Se il deposito arriva dopo la scadenza, l'ordine viene riquotato e il nuovo importo deve essere accettato. Una riquotazione silenziosa contro il cliente è impossibile per costruzione.
Non memorizzare nella cache una quotazione per mascherare un errore di tasso obsoleto. Una quotazione in cache è un prezzo obsoleto presentato come vincolante, che è esattamente il problema che il codice di rifiuto previene.