Transaction precision
Ensure correctness when recording amounts with floating points in your Blnk Ledger
Overview
Blnk ensures accuracy by storing transaction amounts and balances as integers, even though real-world values are typically expressed as decimals, such as USD 25.34, BTC 0.248917, or ETH 0.18920753698279.
Precision is a feature that converts these decimals into integers by converting amounts into their smallest asset-specific units:
- Dollar to cent (USD 25.34 becomes 2534 cents)
- Bitcoin to satoshi (BTC 0.248917 becomes 24891700 satoshis)
- Ethereum to wei (ETH 0.189207535698279 becomes 189207535698279000 wei)
Blnk uses the precise_amount
parameter to store amounts with precision applied in your ledger.
Determining your precision value
Follow these steps to calculate the best precision value for an asset class:
Identify the smallest possible unit of the asset.
For example, the smallest unit for USD is $0.01 (1 cent), and for BTC, it’s 0.00000001 (1 satoshi).
Convert this smallest unit into an integer.
To do this, multiply the smallest unit by a factor that results in a whole number. For instance:
- For USD, multiply 0.01 by 100 to get 1 (since 100 cents makes a dollar).
- For BTC, multiply 0.00000001 by 100,000,000 to get 1 (since 100 million satoshis makes 1 BTC).
Use the multiplication factor as your precision value.
The number you used to convert the smallest unit to an integer becomes the precision value. In the examples above:
- USD precision value: 100
- BTC precision value: 100,000,000
Fiat currencies and their precision values
Open source repo of all 151 fiat currencies and their respective precision values.
Applying precision
You can apply precision to amounts in your ledger using one of two options:
- The
amount
field - The
precise_amount
field
Option 1: Using the amount
field
To apply precision with the amount
field, enter the amount as a floating-point value and specify its precision value when recording a transaction.
Important to note:
The amount
field supports up to 15 digits. Exceeding this will throw a rounding error or truncation; switch to precise_amount
for accuracy with larger values.
Field | Type | Description |
---|---|---|
amount | Float | The transaction value as is. |
precision | Number | The precision value (e.g. 100 converts USD to cents) |
The resulting precise_amount
is stored and used to compute your ledger balances.
Field | Type | Description |
---|---|---|
precise_amount | Number | The amount with precision applied. |
Option 2: Using the precise_amount
field
To apply precision with the precise_amount
field:
- Convert the amount to its smallest unit.
- Enter this value directly into the
precise_amount
field of your request. - Include the corresponding
precision
value.
The example above correctly logs an ETH amount (18 digits) with full precision down to the smallest unit as shown below:
Field | Type | Description |
---|---|---|
amount_string | String | Returns the amount with precision applied without rounding errors or cut offs. |
Important considerations
-
amount
andprecise_amount
cannot be passed simultaneously when recording a transaction. -
Ensure that your precision value converts the target amount to the lowest unit possible for its asset class. For example, while 100 works for most fiat currencies, it is not advisable to use it for cryptocurrencies like Bitcoin or Ethereum.
-
Be consistent with how precision is applied in your application. Transactions with the same
currency
should always have the same precision applied to their amounts. -
Regularly review and audit your ledger to ensure that precision is applied consistently and correctly.
Error handling
More than 15 digits in the amount
field
When you pass a number with more than 15 digits in the amount
field:
Using both precision options together
When you pass both the amount
and precise_amount
fields in your request:
Need help?
We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.
To ask questions or discuss issues, please contact us or join our Discord community.
Love building with Blnk? We’d love to hear your feedback. Tell us here.