Developers

Cotando uma operação

Cotação é o único endpoint aberto hoje, e o mais importante: retorna o detalhamento linha por linha que o site exibe. Não requer chave.

POST/api/quoteLive

Citar uma operação

Retorna o detalhamento completo de uma venda: a taxa de mercado intermediária usada, cada cobrança em sua própria linha, o valor líquido e a taxa efetiva realmente obtida. As linhas somam exatamente a diferença entre bruto e líquido — o invariante é verificado antes de a resposta sair, e uma resposta desbalanceada nunca é retornada.

Autenticação: nenhuma hoje. O endpoint de cotação é aberto: uma cotação não revela dados pessoais.

Parâmetros

Parâmetros
Campo	Tipo	Descrição
`assetId`obrigatório	string	Identificador do ativo depositado, por exemplo “btc”, “usdt”, “sol”.
`railId`obrigatório	string	Identificador do método de pagamento, por exemplo “sepa_instant”, “br_pix”, “ke_mpesa”.
`networkId`	string	Rede de depósito. Opcional: a primeira rede do ativo é usada por padrão. O custo da rede varia muito entre redes, portanto este campo altera o valor líquido.
`direction`obrigatório	"sell" \| "receive"	Direção de entrada. “sell”: o valor é o que você deposita. “receive”: o valor é o que você deseja receber, e o depósito necessário é resolvido por busca binária.
`amount`obrigatório	string	Valor em unidades principais, enviado como STRING. Um float JSON perderia unidades fracionárias em valores grandes: uma string é o único formato no qual cliente e servidor concordam até o centavo.

Solicitaçãobash

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

Resposta — exemplo 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
}

A resposta carrega Cache-Control: no-store. Uma cotação em cache é um preço desatualizado servido como firme.
Uma violação de limite do canal não é um erro HTTP: a cotação é retornada com um objeto limitError contendo o código below_min ou above_max e o limite exato, para que sua interface possa mostrar a mensagem correta sem uma segunda chamada.
rateSource indica de onde veio o preço. O valor “mock” é a fonte de desenvolvimento determinística: ela não pode iniciar em produção, onde o processo se recusa a iniciar em vez de cotar preços congelados.

Erros possíveis: invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. Catálogo completo

Lendo o detalhamento

O array lines contém uma entrada por cobrança real. Uma linha zero não é retornada: mostrar “taxa de trilho: 0,00” não acrescenta nada e polui a interface.

Lendo o detalhamento
code	Quem recebe	O que é
`network`	A rede blockchain	Custo de movimentação do ativo, retirado em espécie do depósito antes da conversão. Varia com a rede escolhida, às vezes por um fator amplo: é por isso que networkId altera o valor líquido.
`spread`	Nós	Nossa margem, expressa como porcentagem do valor convertido. É a única linha que é nossa receita.
`rail`	A instituição de pagamento	Taxa do método de pagamento, fixa, proporcional ou ambas. Ausente quando o trilho não cobra nada, o que é o caso da maioria dos trilhos abertos.
`fx`	Câmbio	Linha reservada para um spread de câmbio explícito quando uma conversão extra acontece. Não aparece em corredores onde a moeda do trilho é a moeda da cotação.

O invariante que torna a tabela verificável

bruto menos a soma das linhas é igual a líquido exatamente, até a unidade menor. Essa igualdade é verificada em cada cotação antes de a resposta sair; se não fechar, existe uma margem não declarada em algum lugar, e o motor levanta erro em vez de retorná-la. Você pode refazer a aritmética: esse é o ponto.

Um exemplo com uma taxa de trilho

O mesmo valor em direção a um trilho que cobra pelo envio traz à tona a terceira linha. Resposta real, obtida na fonte de desenvolvimento determinística.

Solicitaçãobash

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

Resposta — exemplo 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
}

Três linhas, três destinatários diferentes: a rede, nós, a instituição de pagamento. O campo totalCostBps dá a diferença total da taxa de mercado intermediária em pontos-base — o único número que vale a pena comparar entre serviços, porque cobre tudo, incluindo o que de outra forma se esconderia dentro de uma taxa.

Limites do trilho

Um valor fora dos limites do trilho não produz um erro HTTP: a cotação é retornada, com um objeto limitError. Sua interface pode, portanto, mostrar o valor E o motivo exato, sem uma segunda chamada.

Trecho da resposta — exemplo realjson

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

Os valores possíveis são below_min e above_max, e limit contém o limite em unidades principais da moeda do trilho. Nota: o limite se aplica ao valor LÍQUIDO, não ao depósito — o que o beneficiário recebe é o que precisa se encaixar nos limites do trilho.

Janela de validade

O campo lockSeconds indica por quanto tempo a taxa será congelada uma vez que a ordem for criada. Depende do ativo: mais longo em uma stablecoin, mais curto em um volátil.

A cotação em si não é firme: é indicativa até que uma ordem seja criada. A taxa é bloqueada na criação da ordem, não na chamada de cotação.
A janela cobre sua decisão, não o tempo de confirmação da rede. Um depósito de bitcoin pode precisar de uma hora de confirmações: o bloqueio protege contra movimentos de mercado enquanto você decide e deposita.
Se o depósito chegar após o vencimento, a ordem é recotada e o novo valor deve ser aceito. Um reajuste silencioso contra o cliente é impossível por construção.
Não armazene em cache uma cotação para encobrir um erro de taxa desatualizada. Uma cotação em cache é um preço desatualizado apresentado como firme, que é exatamente o problema que o código de recusa previne.