How do I correctly handle asset decimals when trading?

To trade correctly, you must dynamically fetch the decimal values for both the base and quote assets and provide them when you submit an order. This is a critical step because the Hibit system operates with an asset's smallest unit for precision, while the SDK allows you to work with human-readable numbers.

The workflow always involves using the decimals of the root asset. You cannot hardcode these values. The specific API calls you use will depend on your starting point: whether you are selecting from a list of markets or searching for specific assets first.

---

Understanding the Key Concepts

Before looking at the workflow, it's important to understand why this process is necessary.

1. Why Do Decimals Exist?

Every asset on a blockchain has a decimal property. This defines the relationship between its human-readable value (e.g., 1.5 ETH) and its smallest, indivisible on-chain unit (e.g., 1,500,000,000,000,000,000 Wei). The Hibit backend system uses these smallest units for all calculations to ensure mathematical precision and avoid rounding errors. The SDK requires you to provide the decimal value so it can accurately convert your human-readable input into the system-required format.

2. The Root Asset Model for Cross-Chain Assets

Assets like USDT exist on multiple blockchains, often with different decimal values on each chain. Hibit harmonizes this using a parent/sub-asset model.

• Root Asset: For a given token, one version is designated the "root asset." For example, the USDT on Ethereum (which has 6 decimals) is the root asset for all USDT on Hibit.

• Sub-Assets: All other versions of USDT from other chains are treated as sub-assets.

When you deposit any version of USDT into Hibit, its value is automatically converted and merged into your single, unified Ethereum USDT balance. Consequently, all trading and balance operations within Hibit are performed against the root asset and its properties. This is why for any trade involving USDT, you must use the decimal value of the Ethereum root asset (6).

The Correct API Workflow to Get Decimals

The most convenient method depends on whether your user journey starts with finding a market or finding an asset. Both methods are reliable.

Method 1: The "Market-First" Approach

Use this method when a user selects a trading pair from a list of available markets.

• Step 1: Get Market Information. Call the getMarket or getMarkets API to get the details of the desired market. From the response, you will obtain the marketId as well as the unique IDs for the baseAssetId and quoteAssetId.

• Step 2: Get Asset Decimals. Now that you have the specific asset IDs, call the getAsset API for each ID. This API is efficient for fetching a single asset's details when you already know its ID. The response for each call will give you the correct decimals value for that root asset.

• Step 3: Submit the Order. Call the submitSpotOrder API. Provide the marketId from Step 1 and the baseDecimal and quoteDecimal values you retrieved in Step 2.

Method 2: The "Asset-First" Approach

Use this method when you start by searching for specific assets, for example by their name or contract address in a user interface.

• Step 1: Get Asset Information. Call the getAssets API. This function is ideal for searching or filtering through all available assets (e.g., by contract address, with pagination). From this response, you can identify the assets you need and retrieve their id and decimals values directly.

• Step 2: Find the Corresponding Market. Now that you have the id for your base and quote assets, call the getMarkets API to fetch all available markets. Search through the returned list to find the one market where the baseAssetId and quoteAssetId match the IDs you found in Step 1. This will give you the correct marketId.

• Step 3: Submit the Order. Call the submitSpotOrder API. Provide the marketId from Step 2 and the baseDecimal and quoteDecimal values you already have from Step 1.