Conversão

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

POST/v2/conversions/simulate

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.

Parâmetros

amountnumberobrigatório

Valor a converter.

base_currencystringobrigatório

Moeda de origem.

destination_currencystringobrigatório

Moeda de destino.

Rate limit

60 reqs/min.

cURL

PHP

JavaScript

Python

curl -X POST https://api.bspay.co/v2/conversions/simulate \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "base_currency": "BRL",
    "destination_currency": "USDT"
  }'

Resposta 200

{
  "success": true,
  "data": {
    "base_currency": "BRL",
    "destination_currency": "USDT",
    "from_amount": "100.00",
    "to_amount": "19.00",
    "rate": "0.1900",
    "spread": "0.0039",
    "fee": "0.50",
    "expires_at": "2026-04-30T13:25:37Z"
  },
  "request_id": "39aabe4c786257fde4b35c0d",
  "timestamp": "2026-04-30T13:20:37Z"
}

POST/v2/conversions/new

Executa a conversão. O saldo de base_currency é debitado e destination_currency creditado imediatamente.

Headers

Authorization: Bearer {access_token}
Content-Type:  application/json

Parâmetros

amountnumberobrigatório

Valor em base_currency a converter.

base_currencystringobrigatório

Moeda de origem.

destination_currencystringobrigatório

Moeda de destino.

external_idstring

ID único no seu sistema para idempotência.

Rate limit

30 reqs/min.

Erros

Código	HTTP	Descrição
`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

cURL

PHP

JavaScript

Python

BODY='{"amount":80,"base_currency":"USDT","destination_currency":"BRL","external_id":"conv_001"}'

curl -X POST https://api.bspay.co/v2/conversions/new \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Resposta 200

{
  "success": true,
  "data": {
    "conversion_id": "conv_09ff0e84a608427259c609af2be3434b",
    "amount_from": 80,
    "currency_from": "USDT",
    "amount_to": 432.00,
    "currency_to": "BRL",
    "rate": 5.40,
    "fee": 1.50,
    "completed_at": "2026-04-30T13:21:18Z"
  },
  "request_id": "a928cebe6393b3e5f33d10fa",
  "timestamp": "2026-04-30T13:21:18Z"
}

Após conclusão, você recebe o webhook conversion.confirmed com conversion_id, rate, fee e completed_at.

POST/v2/conversions/rate

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.

Parâmetros

amountnumberobrigatório

Valor de referência.

base_currencystringobrigatório

Moeda de origem.

destination_currencystringobrigatório

Moeda de destino.

Rate limit

120 reqs/min.

cURL

JavaScript

curl -X POST https://api.bspay.co/v2/conversions/rate \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "base_currency": "USDT",
    "destination_currency": "BRL"
  }'

Resposta 200

{
  "success": true,
  "data": {
    "base_currency": "USDT",
    "destination_currency": "BRL",
    "amount": "100.00",
    "rate": "5.4012",
    "estimated_amount": "540.12",
    "timestamp": "2026-04-30T13:20:00Z"
  }
}

AnteriorTransf. InternaPróximoCarteira Fixa