Hyperliquid rejects orders with wrong precision. BTC requires 5 decimal places, some memecoins need 2, others need 8. If you hardcode precision, your bot breaks when trading new assets. This guide shows you how to query metadata and calculate valid order sizes dynamically.
The precision problem
This order gets rejected:
# Wrong: BTC spot order with 3 decimals
exchange.order(
name="@0", # BTC spot
is_buy=True,
sz=0.001, # Rejected: BTC spot needs exactly 5 decimals
limit_px=65000.0,
order_type={"limit": {"tif": "Gtc"}}
)
Error: "Tick size violation" or "Invalid order size"
This works:
# Correct: BTC spot with 5 decimals
exchange.order(
name="@0",
is_buy=True,
sz=0.00100, # Valid: 5 decimal places
limit_px=65000.0,
order_type={"limit": {"tif": "Gtc"}}
)
Hardcoding 0.00100 breaks when you switch to another asset. You need dynamic precision.
Tick size vs lot size
Hyperliquid enforces precision on both price and quantity:
Tick size — price precision:
- Prices limited to 5 significant figures
- Max decimals: 6 for perps, 8 for spot
- Examples:
1234.5 ✓, 1234.56 ✗ (too many sig figs)
Lot size — order quantity precision:
- Determined by
szDecimals in asset metadata
- Varies per asset (BTC: 5 decimals, some memecoins: 2 decimals)
- Must query from API—cannot hardcode
Both are enforced at the API level. Violating either causes immediate order rejection.
Hyperliquid uses multiple formats to identify assets:
Spot assets:
@{index} — direct index reference (for example, @0 = BTC/USDC)
{TOKEN}/USDC — pair name (for example, PURR/USDC)
Perpetual assets:
{SYMBOL} — direct symbol (for example, BTC, ETH, SOL)
You need to handle all three formats when querying metadata.
Query spotMetaAndAssetCtxs for comprehensive spot data including precision requirements:
from hyperliquid.info import Info
async def get_spot_asset_info(info: Info, coin_field: str) -> dict:
"""Get price and size decimals for spot assets"""
# Get both metadata and live contexts
spot_data = info.spot_meta_and_asset_ctxs()
spot_meta = spot_data[0] # Metadata (universe, tokens)
asset_ctxs = spot_data[1] # Live data (prices, volumes)
if coin_field.startswith("@"):
# Handle @index format
index = int(coin_field[1:])
if index >= len(asset_ctxs):
raise ValueError(f"Invalid spot index: {coin_field}")
# Get current price (try midPx first, fallback to markPx)
ctx = asset_ctxs[index]
price = float(ctx.get("midPx", ctx.get("markPx", 0)))
if price <= 0:
raise ValueError(f"No price available for {coin_field}")
# Find pair metadata
pair_info = next(
(p for p in spot_meta["universe"] if p["index"] == index),
None
)
if not pair_info:
raise ValueError(f"No metadata for {coin_field}")
# Get base token size decimals
token_indices = pair_info["tokens"]
base_token_index = token_indices[0]
token_info = spot_meta["tokens"][base_token_index]
size_decimals = token_info.get("szDecimals", 6)
return {
"coin": coin_field,
"price": price,
"szDecimals": size_decimals,
"name": pair_info.get("name", coin_field)
}
elif "/" in coin_field:
# Handle PAIR/USDC format - convert to @index
pair = next(
(p for p in spot_meta["universe"] if p["name"] == coin_field),
None
)
if not pair:
raise ValueError(f"Pair not found: {coin_field}")
# Recursively get info using @index format
return await get_spot_asset_info(info, f"@{pair['index']}")
else:
raise ValueError(f"Unsupported spot format: {coin_field}")
Perps use a simpler structure via metaAndAssetCtxs:
async def get_perp_asset_info(info: Info, symbol: str) -> dict:
"""Get price and size decimals for perpetual contracts"""
meta_and_contexts = info.meta_and_asset_ctxs()
meta = meta_and_contexts[0]
asset_ctxs = meta_and_contexts[1]
# Find asset in universe
asset_index = None
for i, asset in enumerate(meta["universe"]):
if asset["name"] == symbol:
asset_index = i
break
if asset_index is None:
raise ValueError(f"Perp asset not found: {symbol}")
# Get metadata
asset_meta = meta["universe"][asset_index]
size_decimals = asset_meta.get("szDecimals", 8)
# Get current price
ctx = asset_ctxs[asset_index]
price = float(ctx.get("markPx", "0"))
if price <= 0:
raise ValueError(f"No price for {symbol}")
return {
"coin": symbol,
"price": price,
"szDecimals": size_decimals,
"name": asset_meta["name"]
}
Working with order precision
Calculating valid order sizes (lot size)
Order sizes must be rounded to the szDecimals specified in asset metadata. This is also known as the lot size—the minimum increment for order quantities.
def calculate_order_size(target_value_usdc: float, asset_info: dict) -> float:
"""Calculate order size with correct precision (lot size)"""
price = asset_info["price"]
size_decimals = asset_info["szDecimals"]
# Calculate raw size
raw_size = target_value_usdc / price
# Round to valid precision based on szDecimals
valid_size = round(raw_size, size_decimals)
return valid_size
Example (from the copy trading implementation):
- Target value: $15 USDC
- BTC spot price: $65,000
- Size decimals (
szDecimals): 5
- Raw size: 15 / 65000 = 0.000230769…
- Valid size:
round(0.000230769, 5) = 0.00023 (5 decimals)
The szDecimals field in metadata determines lot size precision. Query this value from spot_meta_and_asset_ctxs() for spot or meta_and_asset_ctxs() for perps.
Minimum notional value
Hyperliquid enforces minimum order values (typically ~$10). Check before placing:
def validate_order_size(size: float, price: float, min_notional: float = 10.0) -> bool:
"""Verify order meets minimum notional value"""
notional_value = size * price
if notional_value < min_notional:
raise ValueError(
f"Order value \${notional_value:.2f} below minimum \${min_notional}"
)
return True
Price precision (tick size)
Price precision on Hyperliquid follows specific rules:
Significant figures rule — prices can have up to 5 significant figures
Maximum decimal places:
- Perpetuals — max 6 decimal places
- Spot — max 8 decimal places
Examples of valid perpetual prices:
1234.5 ✓ (5 significant figures)
1234.56 ✗ (6 significant figures—too many)
0.001234 ✓ (4 significant figures)
0.0012345 ✗ (5 sig figs but more precision than needed)
Price formatting for API:
def format_price_for_hyperliquid(price: float, max_decimals: int = 6) -> float:
"""Format price with 5 significant figures and max decimals"""
# Hyperliquid requires up to 5 significant figures
# Convert to string with proper precision
price_str = f"{price:.{max_decimals}f}"
# Remove trailing zeros (required for signing)
price_str = price_str.rstrip('0').rstrip('.')
return float(price_str)
# Example: Perpetual price
raw_price = 65432.789123
formatted = format_price_for_hyperliquid(raw_price, max_decimals=6) # 65432.8 (5 sig figs)
When signing orders, trailing zeros should be removed from price strings.
Implementation examples
Complete order placement flow
Putting it together for dynamic multi-asset trading:
async def place_dynamic_order(
exchange: Exchange,
info: Info,
coin_field: str,
is_buy: bool,
target_value_usdc: float,
price_offset_pct: float = 0
):
"""Place order with automatic precision handling"""
# Get asset info
if coin_field.startswith("@") or "/" in coin_field:
asset_info = await get_spot_asset_info(info, coin_field)
else:
asset_info = await get_perp_asset_info(info, coin_field)
# Calculate order size with proper precision
order_size = calculate_order_size(target_value_usdc, asset_info)
# Validate minimum notional
validate_order_size(order_size, asset_info["price"])
# Calculate limit price with offset
market_price = asset_info["price"]
offset_multiplier = 1 + (price_offset_pct / 100)
limit_price = market_price * offset_multiplier
# Round price to tick size (assume 1.0 for simplicity)
limit_price = round(limit_price, 0)
print(f"Placing order: {order_size} {coin_field} @ \${limit_price}")
# Place order
result = exchange.order(
name=coin_field,
is_buy=is_buy,
sz=order_size,
limit_px=limit_price,
order_type={"limit": {"tif": "Gtc"}},
reduce_only=False
)
return result
Handling unknown assets
When trading new or obscure assets:
def get_asset_info_safe(info: Info, coin_field: str) -> Optional[dict]:
"""Get asset info with graceful fallback"""
try:
if coin_field.startswith("@") or "/" in coin_field:
return get_spot_asset_info(info, coin_field)
else:
return get_perp_asset_info(info, coin_field)
except Exception as e:
print(f"Failed to get metadata for {coin_field}: {e}")
# Fallback to safe defaults
return {
"coin": coin_field,
"price": None,
"szDecimals": 6, # Conservative default
"name": coin_field
}
Use conservative defaults when metadata is unavailable, but warn users.
Query metadata once, reuse for multiple orders:
class AssetMetadataCache:
def __init__(self, info: Info):
self.info = info
self.cache = {}
async def get_asset_info(self, coin_field: str) -> dict:
if coin_field not in self.cache:
self.cache[coin_field] = await get_spot_asset_info(
self.info, coin_field
)
return self.cache[coin_field]
def invalidate(self, coin_field: str = None):
"""Clear cache for asset or all assets"""
if coin_field:
self.cache.pop(coin_field, None)
else:
self.cache.clear()
Refresh cache periodically or when orders get rejected.
Troubleshooting
Common rejection reasons
“Invalid order size” (lot size violation) — wrong size decimals. Query szDecimals from metadata and round order size accordingly.
“Tick size violation” (price precision) — price has too many significant figures (>5) or exceeds max decimals (6 for perps, 8 for spot). Format with up to 5 significant figures.
“Order too small” — below minimum notional value (~$10 USDC). Increase order size.
“Asset not found” — wrong coin field format (@index for spot, SYMBOL for perps) or delisted asset.
“Insufficient balance” — not a precision issue, but verify wallet has enough collateral before placing orders.
Summary
Query szDecimals from asset metadata to calculate valid order sizes dynamically—never hardcode precision. Prices must have ≤5 significant figures with max 6 decimals (perps) or 8 decimals (spot). Support all asset formats (@index, PAIR/USDC, SYMBOL), validate minimum notional (~$10 USDC), and cache metadata to reduce API calls.
The complete implementation is available in the Chainstack Hyperliquid trading bot repository.