Amounts and Numeric Precision in the Hashless API

Most on-chain assets (tokens) allow for much more fractionalization than traditional currencies. For example, many assets on Ethereum (including Ethereum's native asset, Ether) allow for 18 decimal places of fractional precision – so you can transfer as little as 0.000000000000000001 Ether. Slightly less well-known is that this precision level is configurable per smart-contract based asset via the ERC-20 standard decimals interface. Under the hood, Ethereum amounts are stored and processed as integers, meaning that data consumers must handle decimalization for each different asset themselves across hundreds of popular assets and hundreds of thousands of long-tail ones.

Hashless automatically handles decimalization of all asset amounts. For display purposes, you can pass any quantity returned from the API directly through to your end users.

However, handling decimal numbers with high precision requires special care in many programming languages. For example, in both Python and JavaScript, by default, when deserializing numbers from JSON, numbers containing a decimal point will be mapped into floating point numbers.

Use of floating point types for monetary operations can cause precision loss and surprising results (for example, balance changes that should net to zero may not do so) -- for more on this topic, see this Stack Overflow answer.

If you need numeric accuracy, we strongly recommend using your programming environment's facilities to map these numbers into fixed-precision Decimal types instead. This needs to be done before deserializing the API's JSON responses into numeric types.

This can be achieved in Python by installing the simplejson library and passing the use_decimal=True option to simplejson.loads.

📘

Future improvements

In a future update, Hashless will allow disabling automatic decimalization via an API parameter, for use with existing data pipelines that expect to perform decimalization themselves.