Skip to content

Execution

Hyperliquid Size Decimals vs Price Precision

Check size and price independently, resolve the right metadata, and preserve a proposed buy ceiling through two exact spot and perpetual examples.

Ivory ceramic comb and stepped precision gate joined by a lime bar on a dark studio surface
Illustration for execution; examples in this article are educational.

Hyperliquid size decimals limit the decimal places in an order's quantity. Price precision is checked separately: a noninteger price needs at most five significant figures and no more than 6 minus szDecimals decimal places for perpetuals, or 8 minus szDecimals for spot. Integer prices have an exception to the five-figure limit. Resolve the market metadata before validating either field.

An order can pass its quantity check and still fail its price check. A price can also fit its decimal allowance while containing too many significant figures. The practical task is to identify which condition failed before changing the proposed trade. Hyperliquid documents these conditions in its tick and lot size rules.

The examples here use hypothetical metadata for an ordinary native perpetual and a spot pair. They demonstrate local validation and exact arithmetic; they do not claim that an exchange accepted an order or that KLINEO uses this implementation.

Read szDecimals from the resolved market

For perpetuals, the meta response contains a universe whose entries include the market name and szDecimals. The request can specify a perpetual DEX through dex; the empty string identifies the original DEX. Match the intended market within that context before reading its precision. The perpetual metadata reference provides the request and response structure.

Spot requires an additional lookup. Its metadata contains token records and a universe of pairs referencing token indices. In the official Python SDK's pinned implementation, a pair's first token is the base token, and that token supplies the pair's size precision. See the spot metadata response and the SDK's base-token lookup.

For example, suppose a fictional pair references tokens [17, 0]. Token 17 has szDecimals = 2 and weiDecimals = 8. Use 2 for order-size precision. Substituting the second field would authorize fractional quantities outside this fixture's order grid. Reading token 0 would instead apply the quote token's properties to a base-token quantity.

Keep the market type alongside the resolved identifier. The Hyperliquid asset ID guide develops the identifier mappings across spot, native perpetuals and builder markets. Resolving the wrong instrument can produce a perfectly calculated answer to the wrong precision question.

Check decimal places and significant figures independently

Let d be the resolved szDecimals. Quantity has a decimal ceiling of d. For noninteger prices, calculate the price ceiling separately:

  • Perpetual price decimals: 6 − d.
  • Spot price decimals: 8 − d.

Count significant figures from the first nonzero digit, ignoring leading zeros. Thus 0.012345 has five significant figures and six decimal places. These are different measurements of the same value. Fractional trailing zeros can be removed without changing its value; 27.3200 becomes 27.32.

The following hypothetical perpetual has d = 3, giving a price decimal ceiling of 3. Each row tests the stated field independently.

FieldCandidatePrecision resultReason
Size4.567PassThree quantity decimals
Size4.5678FailFour quantity decimals
Price27.321PassFive significant figures, three decimals
Price274.321FailSix significant figures, despite three decimals
Price0.01234FailFive decimals, despite only four significant figures
Price274321PassInteger-price exception

The effective price step also changes with magnitude. Here, 27.321 and 27.322 are adjacent valid prices, separated by 0.001. Around 274.32, the next valid price is 274.33, separated by 0.01. Deriving a permanent 0.001 price step from the decimal ceiling alone would admit invalid candidates between them.

The last row matters when testing a validator. Applying a five-digit cutoff to every price would reject that integer incorrectly. Conversely, allowing every three-decimal price would incorrectly admit 274.321. Both mistakes can survive a test suite containing only ordinary prices around 10 or 100.

“Pass” here means the precision conditions pass. It leaves every other order requirement open.

Perpetual example: preserve the requested buy ceiling

Consider a hypothetical buy proposal for the perpetual above. The requested quantity is 4.5678 base units, and the maximum limit price is 27.3216 quote units per base unit. The original proposal fails the quantity test and both price tests.

Assume the caller has explicitly authorized a normalization policy: reduce quantity to a permitted amount and choose the greatest valid price at or below the requested buy ceiling. This policy preserves the two upper bounds. It is a chosen policy for this example, rather than a universal instruction to round all orders downward.

The revised quantity is 4.567. The revised price is 27.321. That price fits five significant figures and three decimal places. Both values are smaller than their original proposals, so calculate the notional again using the revised pair.

CalculationOriginal proposalRevised candidate
Quantity4.56784.567
Limit price27.321627.321
Quantity × price124.79960448124.775007

The notional difference is 0.02459748 quote units, excluding fees. This is a change in the proposed order's limit notional, not a realized saving or account profit. The original pair was never a valid precision candidate under the assumptions.

Nearest rounding would produce 4.568 for quantity and 27.322 for price. Those values pass this fixture's precision rules, but both exceed the original upper bounds. A validator checking only the final grid would miss that change in authorization.

For a sell limit, reducing price could weaken the minimum acceptable sale price. Record order side and the intended price boundary before selecting a rounding direction. If no permitted positive quantity satisfies the approved constraints, stop and return that result instead of quietly increasing the commitment.

Spot example: the larger price allowance still has limits

Now use the fictional spot pair whose base token has szDecimals = 2. The price ceiling is six decimal places. A price of 0.012345 passes: it has six decimal places but only five significant figures. With the same szDecimals on a perpetual, the decimal ceiling would be four, so this price would fail.

The larger spot allowance does not admit every six-decimal price. For this spot fixture, 1.23456 fails because it has six significant figures. Meanwhile, 0.0001234 has only four significant figures but fails because it needs seven decimal places. Testing those two values distinguishes the two failure reasons.

Suppose a hypothetical spot buy requests 1000.129 base units at a maximum price of 0.0123456 quote units. Apply the same explicit upper-bound policy. The revised quantity is 1000.12, and the greatest valid price at or below the requested ceiling is 0.012345.

Exact multiplication gives an original proposal notional of 12.3471925824 quote units and a revised limit notional of 12.34648140. The reduction is 0.0007111824. These arithmetic checks use decimal values constructed from strings, with no binary floating-point intermediate.

A tiny price change can combine with a quantity change, so carrying the old notional forward is an accounting error even when both adjustments look small. The decimal-preservation guide explains how parsing and transport can create a separate discrepancy before a market-rule check even starts.

The SDK serializer is one stage of validation

The implementation inspected here is the official Python SDK 0.24.0 at commit 2fdb18f9517675ea03695a0962bd19eece9c83f0. Its direct order conversion sends price and size through float_to_wire. That helper formats a float to eight decimal places, checks a rounding tolerance, and normalizes the result through Decimal. The pinned serializer and order conversion show these operations.

The helper receives no asset-specific szDecimals. In a local reproduction of that pure function, 4.5678 remains 4.5678, and 274.321 remains 274.321. Both serialize, yet they fail the respective size and price checks for the perpetual fixture above. Eight-place formatting therefore cannot establish market-specific validity.

The repository also includes a separate rounding example that uses metadata before submitting an order. Inspect the actual caller path when adopting an SDK. A helper's successful return value does not show which rules the caller already enforced. These source observations describe client behavior; they do not reveal the matching engine's internal implementation.

Build a validation record before signing

A practical independent check can follow this sequence:

  1. Resolve network, market type, DEX context and identifier. Save the metadata used for that decision.
  2. Parse the proposed price and quantity from their original strings into an exact decimal representation. Require positive, finite values for these order fields.
  3. Normalize fractional trailing zeros for counting. Test quantity decimals against d. For a noninteger price, test its decimal count and significant figures separately; preserve the integer exception.
  4. If a value fails, reject it or create an explicitly revised candidate under the caller's approved policy. Record the original and revised values, side, direction and reason.
  5. Recompute notional and remaining budget on that candidate. Recheck balance, margin, minimums, order type and any other applicable constraints.
  6. Construct the final wire values, verify that they match the validated candidate, and sign that final action.

Keep normalization and signing together operationally. Hyperliquid's signing guidance identifies trailing zeros among common sources of signature problems. Changing a value's wire spelling after constructing the signed action can create a payload mismatch. The signer nonce guide covers the separate signer-state and timing checks that follow a correctly constructed action.

Precision validation also leaves account funding unresolved. For perpetuals, the cross versus isolated margin guide explains why the collateral boundary deserves its own review. Hyperliquid's documented error responses distinguish tick failures from margin, balance, notional and other rejections; some pre-validation errors can reject an entire batch.

When a candidate fails, return a specific reason such as “quantity has four decimals; metadata permits three” or “price fits three decimal places but has six significant figures.” Include the resolved market and the exact candidate that failed. That record lets the caller correct one assumption at a time while preserving the trade's approved limits.

Keep the context with the example.

Each worked example is illustrative, with its sources and assumptions in the article. Read our editorial standards for authorship, verification and corrections.