Conversão
A BSPAY oferece três endpoints de conversão FX:
A BSPAY oferece três endpoints de conversão FX:
| Endpoint | Uso | Auth |
|---|---|---|
POST /v2/conversions/rate | Cotação atual sem fees (display) | Bearer |
POST /v2/conversions/simulate | Cotação com fees + spread (preview pré-execução) | Bearer |
POST /v2/conversions/new | Executa conversão e movimenta saldo | Bearer + HMAC |
Simula uma conversão e retorna o valor estimado após spread e taxas. Nada é executado — use para exibir uma prévia ao usuário.
amountnumberobrigatóriobase_currencystringobrigatóriodestination_currencystringobrigatórioRate limit
60 reqs/min.
Resposta 200
Executa a conversão. O saldo de base_currency é debitado e destination_currency creditado imediatamente.
Esta rota exige assinatura HMAC. Inclua os headers X-Signature, X-Timestamp e X-Nonce além do Bearer token. Ver Autenticação → HMAC.
Headers
amountnumberobrigatóriobase_currency a converter. base_currencystringobrigatóriodestination_currencystringobrigatórioexternal_idstringRate limit
30 reqs/min.
Erros
| Código | HTTP | Descrição |
|---|---|---|
MISSING_SIGNATURE / INVALID_SIGNATURE | 401 | HMAC ausente ou inválido |
INVALID_CURRENCY | 422 | base_currency == destination_currency ou par não suportado |
INSUFFICIENT_BALANCE | 422 | Saldo insuficiente em base_currency |
LIMIT_EXCEEDED | 409 | Limite diário/mensal de conversão atingido |
RATE_EXPIRED | 409 | Cotação simulada expirou — simular novamente |
Resposta 200
Após conclusão, você recebe o webhook conversion.confirmed com conversion_id, rate, fee e completed_at.
Cotação atual entre duas moedas. Mais leve que simulate — não calcula spread/fees por valor, retorna só a taxa de conversão. Útil pra exibir o preço "spot" no UI.
amountnumberobrigatóriobase_currencystringobrigatóriodestination_currencystringobrigatórioRate limit
120 reqs/min.
Resposta 200
