Bloobank API Documentation

Money in the Bloobank API is represented as integer minor units. This page explains the model so you never lose a penny to floating-point arithmetic.

The golden rule

Never represent money as a floating-point number. The API sends and receives integers in the smallest unit of the currency. Your code must do the same.

For Brazilian Real (BRL):

Display value	API value (`amount` integer)
R$ 1.00	`100`
R$ 150.00	`15000`
R$ 1,234.56	`123456`
R$ 10,000.00	`1000000`

The conversion is fixed: apiValue = displayValue × 10^decimals.

Two shapes you will encounter

Where money flows in a single direction (a payment-order amount), the API uses a plain integer:

{
  "amount": 25000,
  "currency": "BRL"
}

On payment orders, amount is always required and must be a positive integer (> 0) in minor units. There is no open-amount semantics — the payer always settles exactly the amount you specify. Where money carries richer context (a wallet balance), the API uses the structured Amount object:

{
  "amount": { "ccy": "BRL", "decimals": 2, "value": 1250075 }
}

Field	Description
`ccy`	Currency or asset code (e.g., `BRL`).
`decimals`	Decimal places of `value` to produce the major-unit number.
`value`	Amount in minor units (e.g., cents).

Either form represents the same idea — just at different levels of self-description.

The `Asset` shape

When the API exposes a wallet balance, it accompanies the Amount with an Asset descriptor:

{
  "amount": { "ccy": "BRL", "decimals": 2, "value": 1250075 },
  "locked": { "ccy": "BRL", "decimals": 2, "value": 25000 },
  "available": { "ccy": "BRL", "decimals": 2, "value": 1225075 },
  "asset": {
    "ccy": "BRL",
    "type": "fiat",
    "symbol": "R$",
    "decimals": 2,
    "name": "Brazilian Real"
  }
}

Asset field	Notes
`ccy`	Currency/asset code.
`type`	`fiat` or `crypto`.
`symbol`	Display symbol (e.g., `R$`).
`decimals`	Default decimal places.
`name`	Human-readable currency name.

asset.decimals is informational — always trust amount.decimals for the specific value at hand. In practice they will match.

Supported assets

The currency field carries a currency or asset code — ISO 4217 for fiat, the network’s ticker for crypto assets:

Code	Type	Decimals
`BRL`	fiat (ISO 4217)	2
`BTC`	crypto	8
`ETH`	crypto	18
`TRX`	crypto	6
`SOL`	crypto	9
`USDT`	crypto	6

PIX payment orders and wallet balances are always denominated in BRL; the crypto asset codes are reserved for wallets custodying those assets.

Three balances, not one

When you query a wallet balance, you receive three amounts:

{
  "amount": { "ccy": "BRL", "decimals": 2, "value": 1250075 },
  "locked": { "ccy": "BRL", "decimals": 2, "value": 25000 },
  "available": { "ccy": "BRL", "decimals": 2, "value": 1225075 }
}

Field	Meaning
`amount`	Total balance, including funds reserved for in-flight outbound orders.
`locked`	Funds reserved for outbound orders currently in `PENDING` or `PROCESSING`. Not spendable.
`available`	Funds you can immediately commit to a new outbound order. `available = amount - locked`.

When deciding whether a new outbound payment can be created, check available, not amount.

Client-side handling

Use BigInt or arbitrary-precision integers

JavaScript:

const cents = BigInt(response.amount); // safe for all values
const reais = Number(cents) / 100;     // safe ONLY for display; precision lost on large values

Python:

cents = response['amount']     # already an int
reais = cents / 100            # fine; Python ints are arbitrary precision

Go / Java / Rust: native int64 is more than sufficient — BRL values up to ≈ 92 quadrillion fit.

Never multiply with floats

// ✗ Wrong — precision loss on certain values
const cents = Math.round(reais * 100);

// ✓ Right — parse as integers from the start
const cents = parseInt(reais.replace('.', ''), 10);

If you must accept user-typed decimal input, validate it as a string against ^\d+(\.\d{1,2})?$ (for BRL) and convert by digit manipulation, not multiplication.

Display formatting

Always format with the user’s locale on the client side:

new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' })
  .format(response.amount / 100);   // "R$ 12.500,75"

The API never returns localized strings. That separation is intentional — the same response can be rendered in any locale.

Wallet balance

Endpoint that returns the three balances and the asset descriptor.

Payments overview

How payment orders consume available and update balances.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Webhooks

Amounts & currency

The golden rule

Two shapes you will encounter

The `Asset` shape

Supported assets

Three balances, not one

Client-side handling

Use BigInt or arbitrary-precision integers

Never multiply with floats

Display formatting

Next

Wallet balance

Payments overview

​The golden rule

​Two shapes you will encounter

​The Asset shape

​Supported assets

​Three balances, not one

​Client-side handling

​Use BigInt or arbitrary-precision integers

​Never multiply with floats

​Display formatting

​Next

Wallet balance

Payments overview

The golden rule

Two shapes you will encounter

The `Asset` shape

Supported assets

Three balances, not one

Client-side handling

Use BigInt or arbitrary-precision integers

Never multiply with floats

Display formatting

Next