Decimal precision for API calculations
Calculated versus displayed precision
Internal API calculations are performed using as many decimal places as necessary depending upon the precision of the currency in question, but displayed values are sometimes rounded/truncated to achieve a usable value or for formatting purposes.
For example, Bitcoin (BTC) calculations use up to 10 decimal places (the maximum usable precision for BTC is 8 places), but are sometimes displayed using only 5 decimal places. Similarly, US Dollar (USD) calculations use up to 4 decimal places (the maximum usable precision for USD is of course 2 places), but are often displayed using only 2 decimal places.
The REST API Assets endpoint can be used to determine the maximum decimal precisions for individual currencies:
$ ./krakenapi Assets asset=xbt,usd{"error":[],"result":{"XXBT":{"aclass":"currency","altname":"XBT","decimals":10,"display_decimals":5},"ZUSD":{"aclass":"currency","altname":"USD","decimals":4,"display_decimals":2}}}
As shown, the Assets endpoint provides the calculation decimal precisions via the decimals fields, and provides the display decimal precisions via the display_decimals fields.
Matching local values with API values
Values derived from local calculations (such as calculating balance changes from a trade's price and volume) often have more decimal places than required, and need to be rounded/truncated to match the values provided by the API.
For example, a SHIB/USD order to buy 50,123 SHIB at $0.00002901 results in a trade worth $1.45406823 (50,123 x 0.00002901 = 1.45406823), but the REST API Ledgers endpoint shows that the USD balance decreased by a smaller precision value of $1.4541:
"L2A7BN-OLRUR-DGZH7F":{"refid":"T5JORM-HM432-GQ3RGY","time":1639991413.4671,"type":"trade","subtype":"","aclass":"currency","asset":"ZUSD","amount":"-1.4541","fee":"0.0000","balance":"124.7277"}
The solution to this type of decimal precision discrepancy is to round/truncate local values to match the decimal precision provided by the REST API Assets endpoint.
Continuing the SHIB/USD example, the Assets endpoint indicates a USD calculation precision of 4 (see the previous section above), hence the locally calculated value of $1.45406823 should also be rounded/truncated to a decimal precision of 4:
50,123 x 0.00002901 = 1.45406823 rounded to 4 places = 1.4541
As shown, by rounding/truncating to the appropriate decimal precision, the final value of $1.4541 corresponds exactly to the value provided by the Ledgers endpoint, allowing local values to be matched with API values successfully.
