wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/adapters/hyperliquid_adapter/test_adapter.py

@@ -0,0 +1,126 @@
+"""Tests for HyperliquidAdapter."""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+class TestHyperliquidAdapter:
+    """Tests for HyperliquidAdapter functionality."""
+
+    @pytest.fixture
+    def mock_info(self):
+        """Create a mock Info client."""
+        mock = MagicMock()
+        mock.meta_and_asset_ctxs.return_value = [
+            {"universe": [{"name": "BTC"}, {"name": "ETH"}]},
+            [{"funding": "0.0001"}],
+        ]
+        mock.spot_meta = {"tokens": [], "universe": []}
+        mock.funding_history.return_value = [
+            {"time": 1700000000000, "coin": "ETH", "fundingRate": "0.0001"}
+        ]
+        mock.candles_snapshot.return_value = [
+            {"t": 1700000000000, "o": "2000", "h": "2050", "l": "1980", "c": "2020"}
+        ]
+        mock.l2_snapshot.return_value = {
+            "levels": [[{"px": "2000", "sz": "10", "n": 5}]]
+        }
+        mock.user_state.return_value = {"assetPositions": [], "crossMarginSummary": {}}
+        mock.spot_user_state.return_value = {"balances": []}
+        mock.post.return_value = []
+        mock.asset_to_sz_decimals = {0: 4, 1: 3, 10000: 6}
+        mock.coin_to_asset = {"BTC": 0, "ETH": 1}
+        return mock
+
+    @pytest.fixture
+    def mock_constants(self):
+        """Create mock constants module."""
+        return SimpleNamespace(MAINNET_API_URL="https://api.hyperliquid.xyz")
+
+    @pytest.fixture
+    def adapter(self, mock_info, mock_constants):
+        """Create adapter with mocked Info client."""
+        with patch(
+            "wayfinder_paths.adapters.hyperliquid_adapter.adapter.Info",
+            return_value=mock_info,
+        ):
+            with patch(
+                "wayfinder_paths.adapters.hyperliquid_adapter.adapter.constants",
+                mock_constants,
+            ):
+                with patch(
+                    "wayfinder_paths.adapters.hyperliquid_adapter.adapter.HYPERLIQUID_AVAILABLE",
+                    True,
+                ):
+                    from wayfinder_paths.adapters.hyperliquid_adapter.adapter import (
+                        HyperliquidAdapter,
+                    )
+
+                    adapter = HyperliquidAdapter(config={})
+                    adapter.info = mock_info
+                    return adapter
+
+    @pytest.mark.asyncio
+    async def test_connect(self, adapter):
+        """Test connection verification."""
+        result = await adapter.connect()
+        assert result is True
+
+    @pytest.mark.asyncio
+    async def test_get_meta_and_asset_ctxs(self, adapter):
+        """Test fetching market metadata."""
+        success, data = await adapter.get_meta_and_asset_ctxs()
+        assert success is True
+        assert "universe" in data[0]
+
+    @pytest.mark.asyncio
+    async def test_get_spot_meta(self, adapter):
+        """Test fetching spot metadata."""
+        success, data = await adapter.get_spot_meta()
+        assert success is True
+
+    @pytest.mark.asyncio
+    async def test_get_funding_history(self, adapter):
+        """Test fetching funding history."""
+        success, data = await adapter.get_funding_history("ETH", 1700000000000)
+        assert success is True
+        assert isinstance(data, list)
+
+    @pytest.mark.asyncio
+    async def test_get_candles(self, adapter):
+        """Test fetching candle data."""
+        success, data = await adapter.get_candles("ETH", "1h", 1700000000000)
+        assert success is True
+        assert isinstance(data, list)
+
+    @pytest.mark.asyncio
+    async def test_get_l2_book(self, adapter):
+        """Test fetching order book."""
+        success, data = await adapter.get_l2_book("ETH")
+        assert success is True
+        assert "levels" in data
+
+    @pytest.mark.asyncio
+    async def test_get_user_state(self, adapter):
+        """Test fetching user state."""
+        success, data = await adapter.get_user_state("0x1234")
+        assert success is True
+        assert "assetPositions" in data
+
+    @pytest.mark.asyncio
+    async def test_health_check(self, adapter):
+        """Test health check."""
+        result = await adapter.health_check()
+        assert result["status"] == "healthy"
+
+    def test_get_sz_decimals(self, adapter):
+        """Test getting size decimals."""
+        decimals = adapter.get_sz_decimals(0)
+        assert decimals == 4
+
+    def test_get_sz_decimals_unknown_asset(self, adapter):
+        """Test error on unknown asset."""
+        with pytest.raises(ValueError, match="Unknown asset_id"):
+            adapter.get_sz_decimals(99999)

wayfinder_paths/adapters/hyperliquid_adapter/test_adapter_live.py

@@ -0,0 +1,219 @@
+"""
+Live API tests for HyperliquidAdapter.
+
+These tests hit the real Hyperliquid API to verify:
+- Spot asset ID resolution (PURR, ETH, BTC, HYPE)
+- Perp asset ID resolution
+- API connectivity
+
+Run with: pytest wayfinder_paths/adapters/hyperliquid_adapter/test_adapter_live.py -v
+"""
+
+import pytest
+
+from wayfinder_paths.adapters.hyperliquid_adapter.adapter import HyperliquidAdapter
+
+
+@pytest.fixture
+def live_adapter():
+    """Create adapter connected to real Hyperliquid API."""
+    return HyperliquidAdapter(config={}, simulation=True)
+
+
+class TestSpotAssetIDs:
+    """Test spot asset ID resolution against live API."""
+
+    @pytest.mark.asyncio
+    async def test_get_spot_assets_returns_dict(self, live_adapter):
+        """Verify get_spot_assets returns a populated dict."""
+        success, spot_assets = await live_adapter.get_spot_assets()
+
+        assert success is True
+        assert isinstance(spot_assets, dict)
+        assert len(spot_assets) > 0
+
+    @pytest.mark.asyncio
+    async def test_purr_spot_asset_id(self, live_adapter):
+        """PURR/USDC should be the first spot pair (index 0 + 10000 = 10000)."""
+        success, spot_assets = await live_adapter.get_spot_assets()
+
+        assert success is True
+        assert "PURR/USDC" in spot_assets
+        assert spot_assets["PURR/USDC"] == 10000
+
+    @pytest.mark.asyncio
+    async def test_hype_spot_asset_id(self, live_adapter):
+        """HYPE/USDC should have asset ID 10107."""
+        success, spot_assets = await live_adapter.get_spot_assets()
+
+        assert success is True
+        assert "HYPE/USDC" in spot_assets
+        # HYPE is index 107, so asset_id = 10107
+        assert spot_assets["HYPE/USDC"] == 10107
+
+    @pytest.mark.asyncio
+    async def test_eth_spot_exists(self, live_adapter):
+        """ETH/USDC spot pair should exist."""
+        success, spot_assets = await live_adapter.get_spot_assets()
+
+        assert success is True
+        # ETH spot may have different naming, check common variants
+        eth_pairs = [k for k in spot_assets if "ETH" in k and "USDC" in k]
+        assert len(eth_pairs) > 0, (
+            f"No ETH/USDC spot found. Available: {list(spot_assets.keys())[:20]}"
+        )
+
+    @pytest.mark.asyncio
+    async def test_btc_spot_exists(self, live_adapter):
+        """BTC/USDC spot pair should exist."""
+        success, spot_assets = await live_adapter.get_spot_assets()
+
+        assert success is True
+        # BTC spot may have different naming
+        btc_pairs = [k for k in spot_assets if "BTC" in k and "USDC" in k]
+        assert len(btc_pairs) > 0, (
+            f"No BTC/USDC spot found. Available: {list(spot_assets.keys())[:20]}"
+        )
+
+    @pytest.mark.asyncio
+    async def test_spot_asset_ids_are_valid(self, live_adapter):
+        """All spot asset IDs should be >= 10000."""
+        success, spot_assets = await live_adapter.get_spot_assets()
+
+        assert success is True
+        for name, asset_id in spot_assets.items():
+            assert asset_id >= 10000, f"{name} has invalid asset_id {asset_id}"
+
+    @pytest.mark.asyncio
+    async def test_get_spot_asset_id_helper(self, live_adapter):
+        """Test synchronous helper after cache is populated."""
+        # First populate cache
+        success, _ = await live_adapter.get_spot_assets()
+        assert success is True
+
+        # Now use sync helper
+        purr_id = live_adapter.get_spot_asset_id("PURR", "USDC")
+        assert purr_id == 10000
+
+        hype_id = live_adapter.get_spot_asset_id("HYPE", "USDC")
+        assert hype_id == 10107
+
+        # Non-existent should return None
+        fake_id = live_adapter.get_spot_asset_id("FAKECOIN", "USDC")
+        assert fake_id is None
+
+
+class TestPerpAssetIDs:
+    """Test perp asset ID resolution against live API."""
+
+    @pytest.mark.asyncio
+    async def test_coin_to_asset_mapping(self, live_adapter):
+        """Verify perp coin to asset mapping is populated."""
+        coin_to_asset = live_adapter.coin_to_asset
+
+        assert isinstance(coin_to_asset, dict)
+        assert len(coin_to_asset) > 0
+
+    @pytest.mark.asyncio
+    async def test_btc_perp_asset_id(self, live_adapter):
+        """BTC perp should be asset_id 0."""
+        coin_to_asset = live_adapter.coin_to_asset
+
+        assert "BTC" in coin_to_asset
+        assert coin_to_asset["BTC"] == 0
+
+    @pytest.mark.asyncio
+    async def test_eth_perp_asset_id(self, live_adapter):
+        """ETH perp should be asset_id 1."""
+        coin_to_asset = live_adapter.coin_to_asset
+
+        assert "ETH" in coin_to_asset
+        assert coin_to_asset["ETH"] == 1
+
+    @pytest.mark.asyncio
+    async def test_hype_perp_exists(self, live_adapter):
+        """HYPE perp should exist with valid asset_id."""
+        coin_to_asset = live_adapter.coin_to_asset
+
+        assert "HYPE" in coin_to_asset
+        assert coin_to_asset["HYPE"] < 10000  # Perp IDs are < 10000
+
+
+class TestSpotMetaStructure:
+    """Test spot_meta API response structure."""
+
+    @pytest.mark.asyncio
+    async def test_spot_meta_has_tokens(self, live_adapter):
+        """Spot meta should have tokens array."""
+        success, spot_meta = await live_adapter.get_spot_meta()
+
+        assert success is True
+        assert "tokens" in spot_meta
+        assert isinstance(spot_meta["tokens"], list)
+        assert len(spot_meta["tokens"]) > 0
+
+    @pytest.mark.asyncio
+    async def test_spot_meta_has_universe(self, live_adapter):
+        """Spot meta should have universe array with pairs."""
+        success, spot_meta = await live_adapter.get_spot_meta()
+
+        assert success is True
+        assert "universe" in spot_meta
+        assert isinstance(spot_meta["universe"], list)
+        assert len(spot_meta["universe"]) > 0
+
+    @pytest.mark.asyncio
+    async def test_spot_universe_pair_structure(self, live_adapter):
+        """Each spot universe entry should have tokens and index."""
+        success, spot_meta = await live_adapter.get_spot_meta()
+
+        assert success is True
+        for pair in spot_meta["universe"][:5]:  # Check first 5
+            assert "tokens" in pair, f"Missing tokens in {pair}"
+            assert "index" in pair, f"Missing index in {pair}"
+            assert len(pair["tokens"]) >= 2, f"Invalid tokens in {pair}"
+
+
+class TestL2BookResolution:
+    """Test that spot asset IDs work with L2 book API."""
+
+    @pytest.mark.asyncio
+    async def test_purr_spot_l2_book(self, live_adapter):
+        """PURR/USDC (10000) should return valid L2 book."""
+        success, book = await live_adapter.get_spot_l2_book(10000)
+
+        assert success is True
+        assert "levels" in book
+
+    @pytest.mark.asyncio
+    async def test_hype_spot_l2_book(self, live_adapter):
+        """HYPE/USDC (10107) should return valid L2 book."""
+        success, book = await live_adapter.get_spot_l2_book(10107)
+
+        assert success is True
+        assert "levels" in book
+
+
+class TestSzDecimals:
+    """Test size decimals resolution for spot assets."""
+
+    @pytest.mark.asyncio
+    async def test_spot_sz_decimals(self, live_adapter):
+        """Spot assets should have valid sz_decimals."""
+        # HYPE spot = 10107
+        decimals = live_adapter.get_sz_decimals(10107)
+        assert isinstance(decimals, int)
+        assert decimals >= 0
+
+    @pytest.mark.asyncio
+    async def test_perp_sz_decimals(self, live_adapter):
+        """Perp assets should have valid sz_decimals."""
+        # BTC perp = 0
+        decimals = live_adapter.get_sz_decimals(0)
+        assert isinstance(decimals, int)
+        assert decimals >= 0
+
+        # ETH perp = 1
+        decimals = live_adapter.get_sz_decimals(1)
+        assert isinstance(decimals, int)
+        assert decimals >= 0

wayfinder_paths/adapters/hyperliquid_adapter/test_utils.py

@@ -0,0 +1,220 @@
+"""Tests for Hyperliquid adapter utility functions."""
+
+import pytest
+
+from wayfinder_paths.adapters.hyperliquid_adapter.utils import (
+    normalize_l2_book,
+    round_size_for_asset,
+    size_step,
+    spot_index_from_asset_id,
+    sz_decimals_for_asset,
+    usd_depth_in_band,
+)
+
+
+class TestSpotIndexFromAssetId:
+    """Tests for spot_index_from_asset_id function."""
+
+    def test_valid_spot_id(self):
+        """Valid spot asset IDs (>=10000) should return index."""
+        assert spot_index_from_asset_id(10000) == 0
+        assert spot_index_from_asset_id(10001) == 1
+        assert spot_index_from_asset_id(10107) == 107
+
+    def test_rejects_perp_id(self):
+        """Perp asset IDs (<10000) should raise ValueError."""
+        with pytest.raises(ValueError, match="Expected spot asset_id >= 10000"):
+            spot_index_from_asset_id(0)
+
+        with pytest.raises(ValueError, match="Expected spot asset_id >= 10000"):
+            spot_index_from_asset_id(9999)
+
+
+class TestNormalizeL2Book:
+    """Tests for normalize_l2_book function."""
+
+    def test_levels_format(self):
+        """Should handle Hyperliquid 'levels' format (nested arrays)."""
+        raw = {
+            "levels": [
+                [{"px": "100.5", "sz": "10"}],  # bids
+                [{"px": "101.0", "sz": "5"}],  # asks
+            ],
+            "midPx": "100.75",
+        }
+        result = normalize_l2_book(raw)
+
+        assert result["bids"] == [(100.5, 10.0)]
+        assert result["asks"] == [(101.0, 5.0)]
+        assert result["midPx"] == 100.75
+
+    def test_bids_asks_format(self):
+        """Should handle flat bids/asks format."""
+        raw = {
+            "bids": [{"px": "100.5", "sz": "10"}],
+            "asks": [{"px": "101.0", "sz": "5"}],
+        }
+        result = normalize_l2_book(raw)
+
+        assert result["bids"] == [(100.5, 10.0)]
+        assert result["asks"] == [(101.0, 5.0)]
+
+    def test_calculates_mid_from_bids_asks(self):
+        """Should calculate mid price from best bid/ask when not provided."""
+        raw = {
+            "levels": [
+                [{"px": "100.0", "sz": "10"}],
+                [{"px": "102.0", "sz": "5"}],
+            ],
+        }
+        result = normalize_l2_book(raw)
+
+        assert result["midPx"] == 101.0  # (100 + 102) / 2
+
+    def test_fallback_mid(self):
+        """Should use fallback_mid when no mid can be calculated."""
+        raw = {"levels": [[], []]}
+        result = normalize_l2_book(raw, fallback_mid=99.0)
+
+        assert result["midPx"] == 99.0
+
+    def test_invalid_levels_skipped(self):
+        """Invalid level entries should be skipped."""
+        raw = {
+            "levels": [
+                [
+                    {"px": "100.0", "sz": "10"},  # valid
+                    {"px": "invalid", "sz": "5"},  # invalid - non-numeric
+                    {"px": "0", "sz": "5"},  # invalid - zero price
+                    {"px": "50", "sz": "0"},  # invalid - zero size
+                ],
+                [{"px": "101.0", "sz": "5"}],
+            ],
+        }
+        result = normalize_l2_book(raw)
+
+        assert result["bids"] == [(100.0, 10.0)]  # Only valid entry
+
+    def test_tuple_format_levels(self):
+        """Should handle tuple/list format levels."""
+        raw = {
+            "levels": [
+                [[100.0, 10.0]],  # bids as tuples
+                [[101.0, 5.0]],  # asks as tuples
+            ],
+        }
+        result = normalize_l2_book(raw)
+
+        assert result["bids"] == [(100.0, 10.0)]
+        assert result["asks"] == [(101.0, 5.0)]
+
+
+class TestUsdDepthInBand:
+    """Tests for usd_depth_in_band function."""
+
+    def test_buy_side(self):
+        """Buy side should measure ask depth within band."""
+        book = {
+            "bids": [(99.0, 10.0), (98.0, 20.0)],  # $990 + $1960 = $2950
+            "asks": [(101.0, 5.0), (102.0, 10.0)],  # $505 + $1020 = $1525
+            "midPx": 100.0,
+        }
+        # 100 bps = 1% band, so hi = 101.0
+        depth, mid = usd_depth_in_band(book, band_bps=100, side="buy")
+
+        assert mid == 100.0
+        # Only asks <= 101.0 count: 101.0 * 5.0 = 505
+        assert depth == 505.0
+
+    def test_sell_side(self):
+        """Sell side should measure bid depth within band."""
+        book = {
+            "bids": [(99.0, 10.0), (98.0, 20.0)],
+            "asks": [(101.0, 5.0), (102.0, 10.0)],
+            "midPx": 100.0,
+        }
+        # 100 bps = 1% band, so lo = 99.0
+        depth, mid = usd_depth_in_band(book, band_bps=100, side="sell")
+
+        assert mid == 100.0
+        # Only bids >= 99.0 count: 99.0 * 10.0 = 990
+        assert depth == 990.0
+
+    def test_zero_mid(self):
+        """Zero mid price should return zero depth."""
+        book = {"bids": [(99.0, 10.0)], "asks": [(101.0, 5.0)], "midPx": 0.0}
+        depth, mid = usd_depth_in_band(book, band_bps=100, side="buy")
+
+        assert depth == 0.0
+        assert mid == 0.0
+
+
+class TestSzDecimalsForAsset:
+    """Tests for sz_decimals_for_asset function."""
+
+    def test_known_asset(self):
+        """Should return decimals for known asset."""
+        asset_to_sz = {0: 4, 1: 3, 10000: 6}
+
+        assert sz_decimals_for_asset(asset_to_sz, 0) == 4
+        assert sz_decimals_for_asset(asset_to_sz, 1) == 3
+        assert sz_decimals_for_asset(asset_to_sz, 10000) == 6
+
+    def test_unknown_raises(self):
+        """Unknown asset should raise ValueError."""
+        asset_to_sz = {0: 4}
+
+        with pytest.raises(ValueError, match="Unknown asset_id 999"):
+            sz_decimals_for_asset(asset_to_sz, 999)
+
+
+class TestSizeStep:
+    """Tests for size_step function."""
+
+    def test_size_step_calculation(self):
+        """Size step should be 10^(-decimals)."""
+        from decimal import Decimal
+
+        asset_to_sz = {0: 4, 1: 2}
+
+        assert size_step(asset_to_sz, 0) == Decimal("0.0001")
+        assert size_step(asset_to_sz, 1) == Decimal("0.01")
+
+
+class TestRoundSizeForAsset:
+    """Tests for round_size_for_asset function."""
+
+    def test_floors_correctly(self):
+        """Should floor to size step."""
+        asset_to_sz = {0: 4}  # Step = 0.0001
+
+        # 1.23456789 should floor to 1.2345
+        result = round_size_for_asset(asset_to_sz, 0, 1.23456789)
+        assert result == 1.2345
+
+    def test_zero_returns_zero(self):
+        """Zero or negative size returns 0."""
+        asset_to_sz = {0: 4}
+
+        assert round_size_for_asset(asset_to_sz, 0, 0.0) == 0.0
+        assert round_size_for_asset(asset_to_sz, 0, -1.0) == 0.0
+
+    def test_ensure_min_step(self):
+        """With ensure_min_step=True, tiny values become one step."""
+        asset_to_sz = {0: 4}  # Step = 0.0001
+
+        # Without ensure_min_step: 0.00001 floors to 0
+        result = round_size_for_asset(asset_to_sz, 0, 0.00001, ensure_min_step=False)
+        assert result == 0.0
+
+        # With ensure_min_step: 0.00001 becomes 0.0001 (one step)
+        result = round_size_for_asset(asset_to_sz, 0, 0.00001, ensure_min_step=True)
+        assert result == 0.0001
+
+    def test_preserves_precision(self):
+        """Should not introduce float precision errors."""
+        asset_to_sz = {0: 2}  # Step = 0.01
+
+        # 0.1 + 0.2 = 0.30000000000000004 in float
+        result = round_size_for_asset(asset_to_sz, 0, 0.1 + 0.2)
+        assert result == 0.30

wayfinder_paths/adapters/hyperliquid_adapter/utils.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from decimal import ROUND_DOWN, Decimal
+from typing import Any
+
+
+def spot_index_from_asset_id(spot_asset_id: int) -> int:
+    """Convert Hyperliquid spot asset_id (>=10000) to spot index."""
+    if spot_asset_id < 10000:
+        raise ValueError(f"Expected spot asset_id >= 10000, got {spot_asset_id}")
+    return int(spot_asset_id) - 10000
+
+
+def normalize_l2_book(
+    raw: dict[str, Any],
+    *,
+    fallback_mid: float | None = None,
+) -> dict[str, Any]:
+    """Normalize Hyperliquid L2 into bids/asks lists with floats."""
+
+    def coerce_levels(levels: Any) -> list[tuple[float, float]]:
+        normalized: list[tuple[float, float]] = []
+        if not isinstance(levels, list):
+            return normalized
+        for level in levels:
+            try:
+                if isinstance(level, dict):
+                    px = float(level.get("px"))
+                    sz = float(level.get("sz"))
+                elif isinstance(level, (list, tuple)) and len(level) >= 2:
+                    px = float(level[0])
+                    sz = float(level[1])
+                else:
+                    continue
+            except (TypeError, ValueError):
+                continue
+            if px > 0 and sz > 0:
+                normalized.append((px, sz))
+        return normalized
+
+    bids: list[tuple[float, float]] = []
+    asks: list[tuple[float, float]] = []
+
+    levels = raw.get("levels")
+    if isinstance(levels, list) and levels:
+        bids = coerce_levels(levels[0])
+        if len(levels) > 1:
+            asks = coerce_levels(levels[1])
+    else:
+        bids = coerce_levels(raw.get("bids"))
+        asks = coerce_levels(raw.get("asks"))
+
+    mid_px = None
+    try:
+        mid_raw = raw.get("midPx")
+        if mid_raw is not None:
+            mid_px = float(mid_raw)
+    except (TypeError, ValueError):
+        mid_px = None
+
+    if (mid_px is None or mid_px <= 0) and bids and asks:
+        mid_px = (bids[0][0] + asks[0][0]) / 2.0
+    if (mid_px is None or mid_px <= 0) and fallback_mid:
+        mid_px = float(fallback_mid)
+
+    return {
+        "bids": bids,
+        "asks": asks,
+        "midPx": float(mid_px or 0.0),
+    }
+
+
+def usd_depth_in_band(
+    book: dict[str, Any], band_bps: int, side: str
+) -> tuple[float, float]:
+    """Return USD depth inside a +/- band (bps) around mid price for a side."""
+    bids = book.get("bids") or []
+    asks = book.get("asks") or []
+    mid = float(book.get("midPx") or 0.0)
+
+    if mid <= 0.0:
+        return 0.0, mid
+
+    lo = mid * (1.0 - band_bps / 1e4)
+    hi = mid * (1.0 + band_bps / 1e4)
+
+    def usd_sum(levels: list[tuple[float, float]], predicate) -> float:
+        total = 0.0
+        for px, sz in levels:
+            if predicate(px):
+                total += float(px) * float(sz)
+        return total
+
+    bids_usd = usd_sum(bids, lambda px: px >= lo)
+    asks_usd = usd_sum(asks, lambda px: px <= hi)
+
+    depth_side = asks_usd if side.lower() == "buy" else bids_usd
+    return float(depth_side), mid
+
+
+def sz_decimals_for_asset(
+    asset_to_sz_decimals: Mapping[int, int], asset_id: int
+) -> int:
+    """Return Hyperliquid size decimals (szDecimals) for an asset_id."""
+    if asset_id not in asset_to_sz_decimals:
+        raise ValueError(f"Unknown asset_id {asset_id}: missing szDecimals")
+    return int(asset_to_sz_decimals[asset_id])
+
+
+def size_step(asset_to_sz_decimals: Mapping[int, int], asset_id: int) -> Decimal:
+    """Return the size increment step for an asset_id."""
+    return Decimal(10) ** (-sz_decimals_for_asset(asset_to_sz_decimals, asset_id))
+
+
+def round_size_for_asset(
+    asset_to_sz_decimals: Mapping[int, int],
+    asset_id: int,
+    size: float | Decimal,
+    *,
+    ensure_min_step: bool = False,
+) -> float:
+    """Floor to size step using Decimal to avoid float issues."""
+    size_d = size if isinstance(size, Decimal) else Decimal(str(size))
+    if size_d <= 0:
+        return 0.0
+
+    step = size_step(asset_to_sz_decimals, asset_id)
+    q = (size_d / step).to_integral_value(rounding=ROUND_DOWN) * step
+    if ensure_min_step and q == 0:
+        q = step
+
+    decimals = sz_decimals_for_asset(asset_to_sz_decimals, asset_id)
+    return float(f"{q:.{decimals}f}")