Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt

Use this file to discover all available pages before exploring further.

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 valueAPI value (amount integer)
R$ 1.00100
R$ 150.0015000
R$ 1,234.56123456
R$ 10,000.001000000
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"
}
Where money carries richer context (a wallet balance), the API uses the structured Amount object: 
{
  "amount": { "ccy": "BRL", "decimals": 2, "value": 1250075 }
}
FieldDescription
ccyCurrency or asset code (e.g., BRL).
decimalsDecimal places of value to produce the major-unit number.
valueAmount 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 fieldNotes
ccyCurrency/asset code.
typefiat or crypto.
symbolDisplay symbol (e.g., R$).
decimalsDefault decimal places.
nameHuman-readable currency name.
asset.decimals is informational — always trust amount.decimals for the specific value at hand. In practice they will match.

​
Supported currencies

The Transactions Engine API currently supports:
CodeTypeDecimalsNotes
BRLfiat2PIX network.
USDfiat2Future.
BTCcrypto8Future.
ETHcrypto18Future.
TRXcrypto6Future.
SOLcrypto9Future.
USDTcrypto6Future.
For PIX operations, currency is always BRL.

​
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 }
}
FieldMeaning
amountTotal balance, including funds reserved for in-flight outbound orders.
lockedFunds reserved for outbound orders currently in PENDING or PROCESSING. Not spendable.
availableFunds 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.

​
Next

Wallet balance

Endpoint that returns the three balances and the asset descriptor.

Payments overview

How payment orders consume available and update balances.