Developers
Documentação da API
Uma API que retorna o mesmo detalhamento de taxas que o site, linha por linha, sem margem oculta. Esta página descreve as convenções compartilhadas por todos os endpoints e declara precisamente o que está aberto hoje.
O que está aberto hoje
O endpoint 1 está realmente exposto e chamável: cotação. Os outros 5 são publicados como contrato, para que você possa construir antes de abrirem, e cada um carrega um selo explícito.
Documentamos com antecedência porque ajuda uma integração. Deixar você acreditar que está conectado não ajudaria: cada endpoint declara seu status, e as respostas de exemplo para endpoints abertos são respostas realmente obtidas, não maquetes.
URL base e versionamento
Duas bases coexistem: a que responde hoje e a API versionada que virá com as chaves emitidas.
- Hoje
- /api Live
- API versionada
- /api/v1 Published contract, not open
A versão vive no caminho, não em um cabeçalho: uma URL precisa sobreviver a ser colada em um ticket. Uma mudança que quebra — um campo removido, um tipo alterado, semântica diferente — abre uma nova versão; a anterior continua sendo servida por pelo menos seis meses, com sua data de término anunciada no changelog. Adicionar um campo não quebra: seu cliente deve ignorar campos que não conhece.
Convenções
Elas valem em todos os endpoints, abertos ou futuros. A maioria existe por um motivo: nunca perder um centavo no trânsito.
Valores são strings ou inteiros de unidades menores
Nunca um float. Em JSON, 0.1 + 0.2 não é 0.3, e um valor grande perde unidades menores na serialização. Portanto, valores em unidades principais são enviados como strings, e valores internos como inteiros de unidades menores com sua contagem decimal.
{
"net": "912.28",
"currency": "EUR",
"currencyDecimals": 2
}Os decimais dependem da moeda
O euro tem duas casas decimais, o franco CFA e o dong vietnamita não têm nenhuma. Não codifique “× 100”: leia currencyDecimals ou o campo decimals dos dados de referência.
{ "amount": "125000", "currency": "XOF", "currencyDecimals": 0 }Valores de criptomoedas estão em unidades base
O depósito é retornado com sua contagem decimal: 8 para bitcoin, 6 para USDT, 18 para ether. O mesmo ticker pode existir com decimais diferentes dependendo da rede: confie no campo, não na sua memória.
{ "deposit": { "amount": "1000.000000", "ticker": "USDT", "decimals": 6 } }Carimbos de data/hora
As datas são ISO 8601 UTC. Uma exceção deliberada: rateAsOf é um carimbo de data/hora Unix em milissegundos, porque alimenta um cálculo de idade, não uma exibição. Ele carrega a data dos DADOS de mercado, não da sua solicitação: essa distinção é o que torna um preço desatualizado detectável.
{ "rateAsOf": 1788356981608, "rateSource": "coingecko" }Identificadores são estáveis
Um identificador de ativo, trilho ou país nunca muda e nunca é reatribuído. Um trilho fechado mantém o seu, com sua fase e motivo: sua integração pode ver por que ele saiu das suas opções, em vez de encontrar um buraco.
Mensagens voltadas a humanos são bilíngues
Um motivo de recusa é retornado em francês e inglês no mesmo objeto. Você mostra o que corresponde ao seu usuário, sem tabela de tradução para manter do seu lado.
{ "reason": { "fr": "…", "en": "…" } }Primeira chamada
Nenhuma chave é necessária para cotar. Esta chamada funciona como está.
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"
}'{
"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
}O campo rateSource declara de onde veio o preço. O valor “mock” é a fonte de desenvolvimento determinística, que não pode iniciar em produção: o processo se recusa a iniciar em vez de cotar preços congelados.
Seções
- AutenticaçãoComo o endpoint de cotações é protegido hoje, como as chaves serão emitidas e as regras para lidar com uma chave de produção.
- CotaçõesO endpoint de cotações, sua discriminação de taxas linha por linha, como os limites de canal retornam na resposta e por quanto tempo a taxa permanece bloqueada após a criação de um pedido.
- PedidosCriar um pedido, chave de idempotência, endereço de depósito, memo obrigatório em algumas redes e leitura de transições de estado.
- Dados de referênciaCatálogos de canal, ativo e país, o esquema de campos do beneficiário que permite gerar seu formulário de pagamento e paginação por cursor.
- WebhooksEventos emitidos, assinatura HMAC-SHA256 sobre o corpo bruto, janela de repetição, cronograma de novas tentativas e por que a verificação deve ser executada em tempo constante.
- ErrosCada código de erro com seu status HTTP, o que significa exatamente, o que fazer sobre ele no lado da integração e quais valem a pena tentar novamente.
O que a API não fará
Os limites de uma API são tão úteis de conhecer quanto suas capacidades.
- Sem pagamentos a terceiros. O nome do beneficiário deve corresponder à identidade verificada do titular do pedido, e os trilhos de pagamento agora verificam o nome contra a conta.
- Sem criação de conta ou verificação de identidade pela API. Essas etapas acontecem em um fluxo onde o usuário vê o que aceita.
- Sem chave em um parâmetro de URL. URLs acabam em logs, cabeçalhos de referência e históricos: uma chave passada dessa forma é uma chave para revogar.
- Sem cache de cotação do nosso lado. A resposta carrega Cache-Control: no-store, e sua integração não deve contornar isso: uma cotação em cache é um preço desatualizado apresentado como firme.
- Sem endpoint de compra de criptomoeda. O serviço opera em uma direção, ativo digital para moeda legal.