Skip to main content
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)
When recording transactions, pass the smallest unit in precise_amount and include precision so Blnk can derive the human-readable amount in responses. Alternatively, you can pass a float in amount and let Blnk convert it to an integer using precision.

​
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

151 fiat currencies and precision values.

​
Applying precision

You can apply precision to amounts in your ledger in one of two ways.
  1. Use precise_amount (recommended) to pass the smallest unit directly, or
  2. Pass a float in amount and let Blnk convert it using precision.
Available in version 0.10.1 or later
Pass the amount in its smallest unit in precise_amount, and include the corresponding precision value.Blnk stores precise_amount as the ledger integer and returns the human-readable amount in responses (amount = precise_amount / precision).
  • Convert the amount to its smallest unit. Learn how
  • Enter this value directly into the precise_amount field of your request.
  • Include the corresponding precision value.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 75023,
    "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
precise_amountIntegerThe transaction value in its smallest unit (e.g. 75023 cents for USD 750.23).
precisionNumberThe precision value (e.g. 100 converts USD to cents)
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"
}
When using precise_amount with multiple sources or destinations, use precise_distribution instead of distribution for fixed amounts in your sources or destinations array.Percentages ("10%") and the remainder ("left") still use distribution.
Example with precise_distribution
{
  ...
  "destinations": [
    {
      "identifier": "bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f",
      "precise_distribution": "2300000"
    },
    {
      "identifier": "bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d",
      "distribution": "left"
    }
  ]
}
See Multiple sources and Multiple destinations for more details.

​
Important considerations

  1. amount and precise_amount cannot be passed simultaneously when recording a transaction. Prefer precise_amount for consistency across your integration.
  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. Balance fields are integers in minor units. Core does not return precision on balances. To display an amount, divide by the precision you use for that currency (100000 / 100 = $1,000.00).
  5. Regularly review and audit your ledger to ensure that precision is applied consistently and correctly.

​
Error handling

Structured errors are available from Blnk Core 0.15.0 and later.
Create transaction returns 400 TXN_VALIDATION_ERROR when the amount fields in your request fail validation.
Neither amount nor precise_amount is set:
400 Bad Request
{
  "error_detail": {
    "code": "TXN_VALIDATION_ERROR",
    "message": "amount: either amount or precise_amount is required."
  },
  "errors": "amount: either amount or precise_amount is required."
}

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