Conversão

A BSPAY oferece três endpoints de conversão FX:

A BSPAY oferece três endpoints de conversão FX:

EndpointUsoAuth
POST /v2/conversions/rateCotação atual sem fees (display)Bearer
POST /v2/conversions/simulateCotação com fees + spread (preview pré-execução)Bearer
POST /v2/conversions/newExecuta conversão e movimenta saldoBearer + HMAC

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
X-Signature:   hex(hmac_sha256(timestamp + "." + nonce + "." + body, signing_key))
X-Timestamp:   <unix_seconds>
X-Nonce:       <uuid_v4>
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ódigoHTTPDescrição
MISSING_SIGNATURE / INVALID_SIGNATURE401HMAC ausente ou inválido
INVALID_CURRENCY422base_currency == destination_currency ou par não suportado
INSUFFICIENT_BALANCE422Saldo insuficiente em base_currency
LIMIT_EXCEEDED409Limite diário/mensal de conversão atingido
RATE_EXPIRED409Cotação simulada expirou — simular novamente
cURL
PHP
JavaScript
Python
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen)
BODY='{"amount":80,"base_currency":"USDT","destination_currency":"BRL","external_id":"conv_001"}'
SIGNATURE=$(printf '%s' "$TIMESTAMP.$NONCE.$BODY" | openssl dgst -sha256 -hmac "$SIGNING_KEY" -hex | awk '{print $2}')

curl -X POST https://api.bspay.co/v2/conversions/new \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $NONCE" \
  -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"
}

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

Esta página foi útil?