> ## 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.

# Amounts & currency

> Minor-unit integers, the Amount and Asset shapes, and supported currency codes.

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

<Warning>
  **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.
</Warning>

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**:

```json theme={"dark"}
{
  "amount": 25000,
  "currency": "BRL"
}
```

Where money carries richer context (a wallet balance), the API uses the **structured `Amount` object**:

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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 currencies

The Transactions Engine API currently supports:

| Code   | Type   | Decimals | Notes        |
| ------ | ------ | -------: | ------------ |
| `BRL`  | fiat   |        2 | PIX network. |
| `USD`  | fiat   |        2 | Future.      |
| `BTC`  | crypto |        8 | Future.      |
| `ETH`  | crypto |       18 | Future.      |
| `TRX`  | crypto |        6 | Future.      |
| `SOL`  | crypto |        9 | Future.      |
| `USDT` | crypto |        6 | Future.      |

For PIX operations, `currency` is always `BRL`.

## Three balances, not one

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

```json theme={"dark"}
{
  "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:

```ts theme={"dark"}
const cents = BigInt(response.amount); // safe for all values
const reais = Number(cents) / 100;     // safe ONLY for display; precision lost on large values
```

Python:

```python theme={"dark"}
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

```ts theme={"dark"}
// ✗ 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**:

```ts theme={"dark"}
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

<CardGroup cols={2}>
  <Card title="Wallet balance" icon="wallet" href="/api-reference/wallets/get-balance">
    Endpoint that returns the three balances and the asset descriptor.
  </Card>

  <Card title="Payments overview" icon="money-bill-transfer" href="/get-started/payments/overview">
    How payment orders consume `available` and update balances.
  </Card>
</CardGroup>