Convenções da API de Cripto

As regras abaixo valem para todas as rotas /crypto/*.

Autenticação

Base URL e autenticação iguais ao resto da API:

Base URL
https://api.xgateglobal.com

Header	Valor	Descrição
`Authorization`	`Bearer <seu_token>`	Token obtido no login.
`Accept-Language`	`pt-BR` ou `en`	(Opcional) Idioma das mensagens de erro. Padrão: `pt-BR`.

A empresa é sempre a do token: não há parâmetro de empresa nas rotas.

A empresa precisa ter a lista de IPs permitidos cadastrada no painel da XGate. A mesma lista usada para saque vale para toda a API de cripto.

Situação	Resposta
Empresa sem lista de IPs	`403 ALLOWED_IPS_REQUIRED`
Requisição de um IP fora da lista	`403 CLIENT_IP_NOT_ALLOWED`

Dinheiro é sempre string decimal

Todo valor monetário trafega como string decimal, nunca como número: "amount": "1500.00". Enviar número resulta em 400 AMOUNT_MUST_BE_STRING.

Datas seguem ISO 8601 em UTC (ex: 2026-10-13T14:03:52.114Z).

Todo erro vem no mesmo envelope:

{
  "reason": "INSUFFICIENT_BALANCE",
  "message": "Saldo insuficiente para a compra.",
  "traceId": "1-6710b8e4-3c1f2a9b7d5e4f6a8b9c0d1e"
}

Campo	Descrição
`reason`	Código estável do erro. Use este campo na sua lógica.
`message`	Texto legível, em pt-BR por padrão ou em inglês com `Accept-Language: en`. Pode mudar.
`traceId`	Protocolo para informar ao suporte da XGate.

A lista completa está em Códigos de Erro.

A compra é idempotente pelo campo externalId (não existe header Idempotency-Key). Veja Comprar Cripto.

Situação	Resposta
Excesso de chamadas por minuto em cotação, estimativa e compra	`429 RATE_LIMITED` com header `Retry-After`
Corpo da requisição acima de 256 KiB	`413 PAYLOAD_TOO_LARGE`
Serviço sobrecarregado	`503 SERVICE_OVERLOADED` com `Retry-After`

Respeite o Retry-After (em segundos) antes de tentar de novo.