Developers

Cotización de una operación

La cotización es el único endpoint abierto hoy, y el más importante: devuelve el desglose línea por línea que muestra el sitio. No necesita clave.

POST/api/quoteLive

Cotizar una operación

Devuelve el desglose completo de una venta: el tipo de mercado medio utilizado, cada cargo en su propia línea, el importe neto y el tipo efectivo realmente obtenido. Las líneas suman exactamente la diferencia entre el bruto y el neto: la invariante se comprueba antes de que la respuesta salga, y una respuesta desequilibrada nunca se devuelve.

Autenticación: ninguna hoy. El endpoint de cotización está abierto: una cotización no revela datos personales.

Parámetros

Parámetros
Campo	Tipo	Descripción
`assetId`obligatorio	string	Identificador del activo depositado, por ejemplo «btc», «usdt», «sol».
`railId`obligatorio	string	Identificador del método de pago, por ejemplo «sepa_instant», «br_pix», «ke_mpesa».
`networkId`	string	Red de depósito. Opcional: por defecto se utiliza la primera red del activo. El coste de la red varía mucho entre redes, por lo que este campo cambia el importe neto.
`direction`obligatorio	"sell" \| "receive"	Dirección de entrada. «sell»: el importe es lo que usted deposita. «receive»: el importe es lo que desea recibir, y el depósito requerido se resuelve mediante búsqueda binaria.
`amount`obligatorio	string	Importe en unidades principales, enviado como CADENA. Un float JSON perdería unidades menores en importes grandes: una cadena es el único formato en el que cliente y servidor coinciden hasta el céntimo.

Solicitudbash

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

Respuesta — ejemplo realjson

{
  "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 respuesta lleva Cache-Control: no-store. Una cotización en caché es un precio obsoleto servido como firme.
La superación de un límite de vía no es un error HTTP: la cotización se devuelve con un objeto limitError que lleva el código below_min o above_max y el límite exacto, para que su interfaz pueda mostrar el mensaje correcto sin una segunda llamada.
rateSource indica de dónde procede el precio. El valor «mock» es la fuente de desarrollo determinista: no puede arrancar en producción, donde el proceso se niega a iniciarse en lugar de cotizar precios congelados.

Posibles errores: invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. Catálogo completo

Lectura del desglose

La matriz de líneas contiene una entrada por cargo real. Una línea cero no se devuelve: mostrar “tarifa de canal: 0.00” no añade nada y satura la interfaz.

Lectura del desglose
code	Quién lo recibe	Qué es
`network`	La red blockchain	Costo de mover el activo, tomado en especie del depósito antes de la conversión. Varía con la red elegida, a veces por un factor amplio: por eso networkId cambia el importe neto.
`spread`	Nosotros	Nuestro margen, expresado como porcentaje del importe convertido. Es la única línea que es nuestro ingreso.
`rail`	La entidad de pago	Comisión del método de pago, fija, proporcional o ambas. Ausente cuando el canal no cobra nada, que es el caso de la mayoría de los canales abiertos.
`fx`	Cambio de divisa	Línea reservada para un spread de cambio explícito cuando ocurre una conversión adicional. No aparece en corredores donde la divisa del canal es la divisa de cotización.

El invariante que hace verificable la tabla

bruto menos la suma de las líneas es igual a neto exactamente, hasta la unidad menor. Esa igualdad se comprueba en cada cotización antes de que la respuesta salga; si no cuadra, existe un margen no declarado en algún lugar, y el motor se bloquea en lugar de devolverlo. Puede rehacer la aritmética: ese es el punto.

Un ejemplo con una tarifa de red

La misma cantidad hacia una red que cobra por el envío saca a relucir la tercera línea. Respuesta real, obtenida en la fuente de desarrollo determinista.

Solicitudbash

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

Respuesta: ejemplo realjson

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

Tres líneas, tres destinatarios diferentes: la red, nosotros, la institución de pago. El campo totalCostBps da la diferencia total con respecto al tipo de mercado medio en puntos básicos: el único número que merece la pena comparar entre servicios, porque lo cubre todo, incluido lo que de otro modo se ocultaría dentro de un tipo.

Límites de la red

Una cantidad fuera de los límites de la red no produce un error HTTP: se devuelve la cotización, con un objeto limitError. Su interfaz puede mostrar la cantidad Y la razón exacta, sin una segunda llamada.

Extracto de respuesta: ejemplo realjson

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

Los valores posibles son below_min y above_max, y limit contiene el límite en unidades principales de la moneda de la red. Nota: el límite se aplica al importe NETO, no al depósito: lo que recibe el beneficiario es lo que debe encajar dentro de los límites de la red.

Ventana de validez

El campo lockSeconds indica cuánto tiempo se congelará el tipo una vez creada la orden. Depende del activo: más tiempo en una stablecoin, menos en uno volátil.

La cotización en sí no es firme: es indicativa hasta que se crea una orden. El tipo se fija en la creación de la orden, no en la llamada de cotización.
La ventana cubre su decisión, no el tiempo de confirmación de la red. Un depósito de bitcoin puede necesitar una hora de confirmaciones: el bloqueo protege contra el movimiento del mercado mientras usted decide y deposita.
Si el depósito llega después del vencimiento, la orden se vuelve a cotizar y el nuevo importe debe ser aceptado. Un re-precio silencioso contra el cliente es imposible por construcción.
No almacene en caché una cotización para disimular un error de tipo obsoleto. Una cotización en caché es un precio obsoleto presentado como firme, que es exactamente el problema que el código de rechazo previene.