Amount

Midaz now uses a precise and simplified model to store financial values by adopting the PostgreSQL numeric type. This change replaces the previous amount and scale structure and marks an important step toward improving accuracy, scalability, and developer experience across all financial operations.

What's new?

Previously, Midaz stored monetary values using:

• amount: a raw integer
• scale: the number of decimal places

For example:

R$1.00 → amount = 100, scale = 2

This model has now been replaced with a single, more precise and simplified field:

• value: a string representing a decimal number (e.g., "12.50" is stored exactly as "12.50")

❗️

Important

The value must be sent as a string in API requests — not as a float or integer — to ensure arbitrary precision and avoid rounding errors that often occur with floating-point representations in financial operations.

This new structure eliminates scale mismatches, simplifies integration logic, and guarantees consistent precision across all asset types — from fiat currencies to high-precision crypto tokens.

Why this matters

The migration to numeric eliminates several limitations of the previous model:

• No more scale normalization: No need to align decimal places manually before performing operations.
• Simpler pre-transaction logic: Balance checks and reservations become straightforward — no scaling adjustments required.
• Cleaner API experience: Send and receive values in their exact decimal form, without worrying about integer conversions.
• Dynamic precision: The database stores only the necessary decimal digits — no padding or truncation.

Example:

• value = "12.50" is stored and returned exactly as "12.50", with no transformations or loss of precision.

What should i do?

❗️

Important

The amount + scale format is now deprecated.

All new integrations and API calls must use the new value field. If you're currently using amount and scale, it's important to begin your migration process immediately.

Midaz will continue to support the old format temporarily, but support will be discontinued in a future version.

We recommend:

1. Updating your API requests to send the value field as a decimal.
2. Reviewing any internal normalization logic and removing references to amount and scale.
3. Testing key flows — such as transfers, pre-transactions, and fee calculations — using the new format.

Need help migrating?

Our team is here to assist. Whether you need help updating your integration or validating data consistency, we’re ready to support you through the transition.

📘

Note

The previous amount and scale format will remain supported during a deprecation window. A formal timeline for discontinuation will be announced. Meanwhile, clients are strongly encouraged to adopt the new structure as soon as possible.