Understanding precision

​

Overview

While transaction amounts are accepted as float, float, balances are stored as integers, int64, in Blnk. To compute your balance, transaction amounts have to be stored as integers. This makes sure that your computed balance is accurate and precise.

Precision allows Blnk to convert your transaction amounts into the lowest unit possible for your asset class (or currency), e.g. converting Naira to kobo. This guide shows you how precision works and best practices for applying it in your application.

​

Why use precision?

Precision is crucial because computers are not great at storing and managing floating points as best as Blnk needs it to. Read more → Floating Point Math

For instance, if a customer sends 1000.50 to a vendor, Blnk accepts the amount value as 1000.50 (float), retrieves the defined precision (e.g. 100), and applies it to the amount. This converts our amount from 1000.50 to 100050.

This ensures that all amounts are accounted for when computing the balances, and we can accurately store amounts without dealing with the technical issues of managing floating points.

​

Applying precision to your transactions

To set a precision value, the precision field must be passed while recording a transaction. If it is not passed, the default value is 1.

{
    "amount": 750.23,
    "reference": "ref_001adcfgf",
    "currency": "USD",
    "precision": 100,
    "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "description": "For fees",
    "meta_data": {
      "sender_name": "John Doe",
      "sender_account": "00000000000"
    }
}

When recording a transaction with a particular asset class (e.g., USD), determine the lowest possible amount and choose a precision value that ensures that the amount is converted to the lowest unit possible.

{
    "id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
    "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "reference": "ref_001adcfgf",
    "amount": 750.23,
    "precision": 100,
    "precise_amount": 75023,
    "currency": "USD",
    "description": "For fees",
    "status": "QUEUED",
    "created_at": "2024-02-20 05:28:03 UTC",
    "meta_data": {
      "sender_name": "John Doe",
      "sender_account": "00000000000"
    }
}

Once a transaction is recorded with precision, its precise_amount is stored by default as the amount in your ledger and used to compute the balances of the source and destination.

When retrieving transaction amounts or balances to display in your application, you can always convert the lowest unit back to its primary asset class by dividing with the precision.

For instance, to display the amount above in your application:

• Retrieve the amount using the Get Transaction endpoint.
• Divide the amount by the applied precision. This converts it from 75023 to 750.23 to display in your app.

​

Important to note

It is very crucial to maintain consistency in how precision is applied in your application. Consider the following when using balance precision:

1. Transactions with the same asset class must have the same precision applied to its amounts: An asset class is defined by its currency attribute. If you set precision for one USD transaction, then all transactions with the same asset class must have the same value.

2. Ensure your precision value converts all amounts to the lowest unit possible: For instance, while "precision": 100 converts most national currencies in the world to their lowest unit, it is not the same for crypto assets. Bitcoin can have up to 100000000 as their precision value.

​

Best practices

1. Define a standard: Establish a clear policy on how precision is applied for different asset classes (currency) within your system.

2. Consistency: Always apply the same precision across all transactions with the same asset class.

3. Review and audit: Regularly review and audit your Blnk Ledger to ensure that precision is applied consistently and correctly.

​

🚨 Warning

Do not perform transactions between balances with asset classes of different precision values, e.g., you can record transactions from a USD balance to a GBP balance (they have the same precision value). Learn how → Applying rates to your transactions.

However, it is not advisable to record transactions from a USD balance to a BTC balance because they have different precision values.

This can complicate your financial operations, cause inconsistencies in your ledger and will definitely lead to errors in balance calculations.

​

Why consistency matters

To ensure the integrity and accuracy of your financial data, choose a consistent approach for applying balance precision across your application.

1. Accuracy: Consistent use of precision ensures that all transaction amounts and balances are accurately represented in your Blnk Ledger, preventing calculation errors, where applicable.

2. Comparability: Transactions and balances with the same precision are directly comparable, simplifying financial analysis and reporting.

3. Integrity: Maintaining a uniform approach to precision preserves the integrity of your Blnk Ledger, making it more reliable and trustworthy for other financial operations.

​

See also

​

Need help?

Are you stuck? Do you have a question that isn’t answered in this doc? Have you run into a problem you can’t solve? Want to file a bug report?

Join our Discord server and share your questions/thoughts with other developers building financial applications like you.