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

1

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

2

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).
3

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:

  1. The amount field
  2. 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.

Example with
{
  "amount": 750.23,
  "precision": 100,
  "reference": "ref_abc123",
  "currency": "USD",
  "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
  "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
  "description": "Wallet funding"
}
FieldTypeDescription
amountFloatThe transaction value as is.
precisionNumberThe precision value (e.g. 100 converts USD to cents)

The resulting precise_amount is stored and used to compute your ledger balances.

Response
{
  "transaction_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"
}
FieldTypeDescription
precise_amountNumberThe amount with precision applied.

​
Option 2: Using the precise_amount field

Available in version 0.10.1 or later

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.
Example with
{
  "precise_amount": 189207535698279000,
  "precision": 1000000000000000000,
  "reference": "ref_abc123",
  "currency": "ETH",
  "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
  "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
  "description": "Wallet funding"
}

The example above correctly logs an ETH amount (18 digits) with full precision down to the smallest unit as shown below:

Response
{
    "precise_amount": 189207535698279000,
    "amount": 0.189207535698279,
    "amount_string": "0.189207535698279",
    "rate": 1,
    "precision": 1000000000000000000,
    "transaction_id": "txn_d2616e76-5ec6-4621-afe0-c4e3b1d848cb",
    "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "reference": "ref_abc123",
    "currency": "ETH",
    "description": "Wallet funding",
    "status": "QUEUED"
}
FieldTypeDescription
amount_stringStringReturns the amount with precision applied without rounding errors or cut offs.

​
Important considerations

  1. amount and precise_amount cannot be passed simultaneously when recording a transaction.

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

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

  4. 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:

{
  "errors:": "amount: amount has more than 15 significant digits which may cause rounding errors; use precise_amount instead"
}

​
Using both precision options together

When you pass both the amount and precise_amount fields in your request:

{
  "errors": "amount: either amount or precise_amount should be provided, not both."
}

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