Handling Numerical Precision and Amounts
A critical concept to understand when using the HiBIT API is how the system handles numerical values for assets, especially regarding decimal precision. A mismatch in precision handling is a common source of errors for developers.
This guide explains the system's precision limit, why it exists, and how to correctly format your requests to ensure your transactions are processed successfully.
The System's 8-Decimal Limit
All numerical values related to asset amounts (e.g., prices, quantities, and transfer values) are processed by the HiBIT trading engine with a maximum precision of 8 decimal places.
Any precision beyond the 8th decimal place will be ignored or "truncated" by the system. To prevent unexpected behavior and silent value changes that could lead to financial loss, the API will reject any request that implies a precision greater than 8 decimals.
Important: This rejection is a protective measure designed to safeguard your assets, not a bug.
Why Does This Issue Occur?
The problem typically arises when you work with an asset that has a native on-chain precision greater than 8.
A classic example is an asset like WKAIA, which has 18 decimal places on its native network.
When you submit an amount for an order or a withdrawal, you provide a raw, integer-like string (e.g., amount: "1000"). The system interprets this raw value using the asset's specified decimal places, which are retrievable from the API.
Example Scenario: The Conflict
Let's say you want to place an order for a very small amount of WKAIA and submit the raw value 94999999.
Your Input: You provide the raw amount value: "94999999".
Asset's Precision: The system knows WKAIA has 18 decimals (from its configuration).
System's Interpretation: It interprets your input as 0.000000000094999999 WKAIA.
Validation Failure: This interpreted number has 18 decimal places. This exceeds the system's 8-decimal limit.
API Response: The request is rejected with a precision error to prevent your intended value from being truncated down to 0.
How to Correctly Format Amounts
To submit a valid amount, you must ensure the raw value you provide corresponds to a number with 8 or fewer decimal places when interpreted.
The formula is: Raw Amount = Desired Decimal Amount * (10 ^ Asset's Decimals)
Correct Example 1: Placing an order for 0.5 WKAIA
Desired Amount: 0.5
Asset's Decimals: 18
Calculation: 0.5 * (10^18) = 500000000000000000
API Input:
{
"amount": "500000000000000000" // This represents 0.5 and is valid.
}Correct Example 2: Placing an order for 0.12345678 WKAIA (the max precision)
Desired Amount: 0.12345678
Asset's Decimals: 18
Calculation: 0.12345678 * (10^18) = 123456780000000000
API Input:
{
"amount": "123456780000000000" // This represents 0.12345678 and is valid.
}Best Practices
Always Query Asset Details: Before performing calculations, always use the GET /api/v1/assets/{asset_id} or GET /api/v1/assets endpoint to retrieve the decimalPlaces for the asset you are trading. Do not hardcode these values, as they could change.
Use a BigNumber Library: Standard floating-point math in many languages (like JavaScript's number type) can introduce small precision errors. It is strongly recommended to use a reliable BigNumber library for all calculations involving asset amounts.
JavaScript/TypeScript: bignumber.js or ethers.js
Python: Decimal
Java/Kotlin: BigDecimal
Validate Before Sending: Before submitting a request, validate that the number you are trying to represent does not resolve to a value with more than 8 decimal places. This client-side check can prevent unnecessary API errors.
Last updated