async-hyperliquid 0.1.0__tar.gz

async_hyperliquid-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.3
+Name: async-hyperliquid
+Version: 0.1.0
+Summary: Async Hyperliquid client using aiohttp
+Author: oneforalone
+Author-email: oneforalone@proton.me
+Requires-Python: >=3.10,<4
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiohttp (>=3.11.12,<4.0.0)
+Requires-Dist: eth-account (>=0.13.5,<0.14.0)
+Requires-Dist: eth-utils (>=5.2.0,<6.0.0)
+Requires-Dist: msgpack (>=1.1.0,<2.0.0)
+Project-URL: Documentation, https://github.com/oneforalone/async-hyperliquid
+Project-URL: Homepage, https://github.com/oneforalone/async-hyperliquid
+Project-URL: Issues, https://github.com/oneforalone/async-hyperliquid/issues
+Project-URL: Repository, https://github.com/oneforalone/async-hyperliquid
+Description-Content-Type: text/markdown
+
+# Async Hyperliquid
+
+An asynchronous Python client for interacting with the Hyperliquid API using `aiohttp`.
+
+## Overview
+
+This library provides an easy-to-use asynchronous interface for the Hyperliquid cryptocurrency exchange, supporting both mainnet and testnet environments. It handles API interactions, request signing, and data processing for both perpetual futures and spot trading.
+
+## Features
+
+- Asynchronous API communication using `aiohttp`
+- Support for both mainnet and testnet environments
+- Message signing for authenticated endpoints
+- Trading operations for both perpetual futures and spot markets
+- Comprehensive type hints for better IDE integration
+
+## Installation
+
+```bash
+# Using pip
+pip install async-hyperliquid
+
+# Using Poetry
+poetry add async-hyperliquid
+```
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from async_hyperliquid import AsyncHyper
+
+async def main():
+    # Initialize the client
+    address = os.getenv("HYPER_ADDRESS")
+    api_key = os.getenv("HYPER_API_KEY")
+    client = AsyncHyper(address, api_key, is_mainnet=True)
+
+    # Initialize metadata (required before making other calls)
+    await client.init_metas()
+
+    # Place a market order
+    response = await client.place_order(
+        coin="BTC",
+        is_buy=True,
+        sz=0.001,
+        px=0,  # For market orders, price is ignored
+        is_market=True
+    )
+
+    print(response)
+
+    # Clean up
+    await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Environment Variables
+
+Create a `.env.local` file with the following variables:
+
+```
+HYPER_ADDRESS=your_ethereum_address
+HYPER_API_KEY=your_ethereum_private_key
+```
+
+## API Reference
+
+### AsyncHyper
+
+The main client class that provides methods for interacting with the Hyperliquid API.
+
+#### Initialization
+
+```python
+client = AsyncHyper(address, api_key, is_mainnet=True)
+```
+
+#### Methods
+
+- `init_metas()`: Initialize metadata (required before using other methods)
+- `update_leverage(leverage, coin, is_cross=True)`: Update leverage for a specific coin
+- `place_order(coin, is_buy, sz, px, is_market=True, **kwargs)`: Place a single order
+- `place_orders(orders, builder=None)`: Place multiple orders at once
+
+### Additional Modules
+
+- `InfoAPI`: Access market information endpoints
+- `ExchangeAPI`: Access exchange operation endpoints
+- `utils`: Various utility functions and constants
+
+## Testing
+
+Tests use pytest and pytest-asyncio. To run tests:
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=async_hyperliquid
+```
+
+## License
+
+MIT
+
+## Acknowledgements
+
+This library is a community-developed project and is not officially affiliated with Hyperliquid.
+
+## TODO
+
+See the TODO.md file for upcoming features and improvements.
+

async_hyperliquid-0.1.0/README.md

@@ -0,0 +1,117 @@
+# Async Hyperliquid
+
+An asynchronous Python client for interacting with the Hyperliquid API using `aiohttp`.
+
+## Overview
+
+This library provides an easy-to-use asynchronous interface for the Hyperliquid cryptocurrency exchange, supporting both mainnet and testnet environments. It handles API interactions, request signing, and data processing for both perpetual futures and spot trading.
+
+## Features
+
+- Asynchronous API communication using `aiohttp`
+- Support for both mainnet and testnet environments
+- Message signing for authenticated endpoints
+- Trading operations for both perpetual futures and spot markets
+- Comprehensive type hints for better IDE integration
+
+## Installation
+
+```bash
+# Using pip
+pip install async-hyperliquid
+
+# Using Poetry
+poetry add async-hyperliquid
+```
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from async_hyperliquid import AsyncHyper
+
+async def main():
+    # Initialize the client
+    address = os.getenv("HYPER_ADDRESS")
+    api_key = os.getenv("HYPER_API_KEY")
+    client = AsyncHyper(address, api_key, is_mainnet=True)
+
+    # Initialize metadata (required before making other calls)
+    await client.init_metas()
+
+    # Place a market order
+    response = await client.place_order(
+        coin="BTC",
+        is_buy=True,
+        sz=0.001,
+        px=0,  # For market orders, price is ignored
+        is_market=True
+    )
+
+    print(response)
+
+    # Clean up
+    await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Environment Variables
+
+Create a `.env.local` file with the following variables:
+
+```
+HYPER_ADDRESS=your_ethereum_address
+HYPER_API_KEY=your_ethereum_private_key
+```
+
+## API Reference
+
+### AsyncHyper
+
+The main client class that provides methods for interacting with the Hyperliquid API.
+
+#### Initialization
+
+```python
+client = AsyncHyper(address, api_key, is_mainnet=True)
+```
+
+#### Methods
+
+- `init_metas()`: Initialize metadata (required before using other methods)
+- `update_leverage(leverage, coin, is_cross=True)`: Update leverage for a specific coin
+- `place_order(coin, is_buy, sz, px, is_market=True, **kwargs)`: Place a single order
+- `place_orders(orders, builder=None)`: Place multiple orders at once
+
+### Additional Modules
+
+- `InfoAPI`: Access market information endpoints
+- `ExchangeAPI`: Access exchange operation endpoints
+- `utils`: Various utility functions and constants
+
+## Testing
+
+Tests use pytest and pytest-asyncio. To run tests:
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=async_hyperliquid
+```
+
+## License
+
+MIT
+
+## Acknowledgements
+
+This library is a community-developed project and is not officially affiliated with Hyperliquid.
+
+## TODO
+
+See the TODO.md file for upcoming features and improvements.

async_hyperliquid-0.1.0/async_hyperliquid/async_api.py

@@ -0,0 +1,46 @@
+import logging
+from types import TracebackType
+from typing import Optional
+from traceback import TracebackException
+
+from aiohttp import ClientSession
+
+from async_hyperliquid.utils.constants import MAINNET_API_URL
+
+
+class AsyncAPI:
+    def __init__(
+        self, endpoint: str, base_url: str = None, session: ClientSession = None
+    ):
+        self.endpoint = endpoint
+        self.base_url = base_url or MAINNET_API_URL
+        self.session = session
+        self.logger = logging.getLogger(__name__)
+
+    # for async with AsyncAPI() as api usage
+    async def __aenter__(self) -> "AsyncAPI":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Exception,
+        exc_val: TracebackException,
+        traceback: TracebackType,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self.session and not self.session.closed:
+            await self.session.close()
+
+    async def post(self, payloads: Optional[dict] = None) -> dict:
+        payloads = payloads or {}
+        req_path = f"{self.base_url}/{self.endpoint.value}"
+        self.logger.info(f"POST {req_path} {payloads}")
+        async with self.session.post(req_path, json=payloads) as resp:
+            resp.raise_for_status()
+            try:
+                return await resp.json()
+            except Exception as e:
+                self.logger.error(f"Error parsing JSON response: {e}")
+                return await resp.text()

async_hyperliquid-0.1.0/async_hyperliquid/async_hyper.py

@@ -0,0 +1,253 @@
+from typing import Any, Dict, List, Optional
+
+from aiohttp import ClientSession, ClientTimeout
+from eth_account import Account
+
+from async_hyperliquid.async_api import AsyncAPI
+from async_hyperliquid.utils.types import (
+    Cloid,
+    LimitOrder,
+    EncodedOrder,
+    OrderBuilder,
+    PlaceOrderRequest,
+    CancelOrderRequest,
+)
+from async_hyperliquid.info_endpoint import InfoAPI
+from async_hyperliquid.utils.signing import encode_order, orders_to_action
+from async_hyperliquid.utils.constants import MAINNET_API_URL, TESTNET_API_URL
+from async_hyperliquid.exchange_endpoint import ExchangeAPI
+
+
+class AsyncHyper(AsyncAPI):
+    def __init__(self, address: str, api_key: str, is_mainnet: bool = True):
+        self.address = address
+        self.is_mainnet = is_mainnet
+        self.account = Account.from_key(api_key)
+        self.session = ClientSession(timeout=ClientTimeout(connect=3))
+        self.base_url = MAINNET_API_URL if is_mainnet else TESTNET_API_URL
+        self._info = InfoAPI(self.base_url, self.session)
+        self._exchange = ExchangeAPI(
+            self.account, self.session, self.base_url, address=self.address
+        )
+        self.metas: Optional[Dict[str, Any]] = None
+        # TODO: figure out the vault address
+        self.vault: Optional[str] = None
+
+    def _init_coin_assets(self):
+        self.coin_assets = {}
+        for asset, asset_info in enumerate(self.metas["perps"]["universe"]):
+            self.coin_assets[asset_info["name"]] = asset
+
+        for asset_info in self.metas["spots"]["universe"]:
+            asset = asset_info["index"] + 10_000
+            self.coin_assets[asset_info["name"]] = asset
+
+    def _init_coin_names(self):
+        self.coin_names = {}
+        for asset_info in self.metas["perps"]["universe"]:
+            self.coin_names[asset_info["name"]] = asset_info["name"]
+
+        for asset_info in self.metas["spots"]["universe"]:
+            self.coin_names[asset_info["name"]] = asset_info["name"]
+            # For token pairs
+            base, quote = asset_info["tokens"]
+            base_info = self.metas["spots"]["tokens"][base]
+            quote_info = self.metas["spots"]["tokens"][quote]
+            base_name = (
+                base_info["name"] if base_info["name"] != "UBTC" else "BTC"
+            )
+            quote_name = quote_info["name"]
+            name = f"{base_name}/{quote_name}"
+            if name not in self.coin_names:
+                self.coin_names[name] = asset_info["name"]
+
+    def _init_asset_sz_decimals(self):
+        self.asset_sz_decimals = {}
+        for asset, asset_info in enumerate(self.metas["perps"]["universe"]):
+            self.asset_sz_decimals[asset] = asset_info["szDecimals"]
+
+        for asset_info in self.metas["spots"]["universe"]:
+            asset = asset_info["index"] + 10_000
+            base, _quote = asset_info["tokens"]
+            base_info = self.metas["spots"]["tokens"][base]
+            self.asset_sz_decimals[asset] = base_info["szDecimals"]
+
+    async def get_metas(self, perp_only: bool = False) -> dict:
+        perp_meta = await self._info.get_perp_meta()
+        if perp_only:
+            return {"perps": perp_meta, "spots": []}
+
+        spot_meta = await self._info.get_spot_meta()
+
+        return {"perps": perp_meta, "spots": spot_meta}
+
+    async def init_metas(self):
+        if not hasattr(self, "metas") or not self.metas:
+            self.metas = await self.get_metas()
+
+        if not self.metas.get("perps") or not self.metas["perps"]:
+            self.metas["perps"] = await self._info.get_perp_meta()
+
+        if not self.metas.get("spots") or not self.metas["spots"]:
+            self.metas["spots"] = await self._info.get_spot_meta()
+
+        if not hasattr(self, "coin_assets") or not self.coin_assets:
+            self._init_coin_assets()
+
+        if not hasattr(self, "coin_names") or not self.coin_names:
+            self._init_coin_names()
+
+        if not hasattr(self, "asset_sz_decimals") or not self.asset_sz_decimals:
+            self._init_asset_sz_decimals()
+
+    async def get_coin_name(self, coin: str) -> str:
+        await self.init_metas()
+
+        if coin not in self.coin_names:
+            raise ValueError(f"Coin {coin} not found")
+
+        return self.coin_names[coin]
+
+    async def get_coin_asset(self, coin: str) -> int:
+        await self.init_metas()
+
+        if coin not in self.coin_assets:
+            raise ValueError(f"Coin {coin} not found")
+
+        return self.coin_assets[coin]
+
+    async def get_coin_sz_decimals(self, coin: str) -> int:
+        await self.init_metas()
+
+        asset = await self.get_coin_asset(coin)
+
+        return self.asset_sz_decimals[asset]
+
+    async def get_token_id(self, coin: str) -> str:
+        coin_name = await self.get_coin_name(coin)
+        spot_metas: Dict[str, Any] = self.metas["spots"]
+        for coin_info in spot_metas["universe"]:
+            if coin_name == coin_info["name"]:
+                base, _quote = coin_info["tokens"]
+                return spot_metas["tokens"][base]["tokenId"]
+
+        return None
+
+    async def update_leverage(
+        self, leverage: int, coin: str, is_cross: bool = True
+    ):
+        action = {
+            "type": "updateLeverage",
+            "asset": await self.get_coin_asset(coin),
+            "isCross": is_cross,
+            "leverage": leverage,
+        }
+
+        return await self._exchange.post_action(action)
+
+    async def place_orders(
+        self,
+        orders: List[PlaceOrderRequest],
+        builder: Optional[OrderBuilder] = None,
+    ):
+        encoded_orders: List[EncodedOrder] = []
+        for order in orders:
+            asset = await self.get_coin_asset(order["coin"])
+            encoded_orders.append(encode_order(order, asset))
+
+        if builder:
+            builder["b"] = builder["b"].lower()
+        action = orders_to_action(encoded_orders, builder)
+
+        return await self._exchange.post_action(action)
+
+    async def _slippage_price(
+        self, coin: str, is_buy: bool, slippage: float, px: float
+    ) -> float:
+        coin_name = await self.get_coin_name(coin)
+        if not px:
+            all_mids = await self._info.get_all_mids()
+            px = float(all_mids[coin_name])
+
+        asset = await self.get_coin_asset(coin)
+        is_spot = asset >= 10_000
+        sz_decimals = await self.get_coin_sz_decimals(coin)
+        px *= (1 + slippage) if is_buy else (1 - slippage)
+        return round(
+            float(f"{px:.5g}"), (6 if not is_spot else 8) - sz_decimals
+        )
+
+    async def place_order(
+        self,
+        coin: str,
+        is_buy: bool,
+        sz: float,
+        px: float,
+        is_market: bool = True,
+        *,
+        order_type: dict = LimitOrder.IOC.value,
+        reduce_only: bool = False,
+        cloid: Optional[Cloid] = None,
+        slippage: float = 0.01,  # Default slippage is 1%
+        builder: Optional[OrderBuilder] = None,
+    ):
+        if is_market:
+            px = self._slippage_price(coin, is_buy, slippage, px)
+            # Market order is an aggressive Limit Order IoC
+            order_type = LimitOrder.IOC
+            reduce_only = False
+
+        name = await self.get_coin_name(coin)
+
+        order_req = {
+            "coin": name,
+            "is_buy": is_buy,
+            "sz": sz,
+            "limit_px": px,
+            "order_type": order_type,
+            "reduce_only": reduce_only,
+            "cloid": cloid,
+        }
+
+        if cloid:
+            order_req["cloid"] = cloid
+
+        return await self.place_orders([order_req], builder=builder)
+
+    async def cancel_order(self, coin: str, oid: int | str):
+        name = await self.get_coin_name(coin)
+        if not isinstance(oid, int):
+            oid = int(oid)
+        cancel_req = {"coin": name, "oid": oid}
+        return await self.cancel_orders([cancel_req])
+
+    async def cancel_orders(self, orders: List[CancelOrderRequest]):
+        # TODO: support cloid
+        action = {
+            "type": "cancel",
+            "cancels": [
+                {
+                    "a": await self.get_coin_asset(order["coin"]),
+                    "o": order["oid"],
+                }
+                for order in orders
+            ],
+        }
+
+        return await self._exchange.post_action(action, self.vault)
+
+    async def modify_order(self):
+        # TODO: implement modify order
+        pass
+
+    async def set_referrer_code(self, code: str):
+        action = {"type": "setReferrer", "code": code}
+        return await self._exchange.post_action(action)
+
+    async def close_all_positions(self):
+        # TODO: implement close all positions
+        pass
+
+    async def close_position(self, coin: str):
+        # TODO: implement close position
+        pass

async_hyperliquid-0.1.0/async_hyperliquid/exchange_endpoint.py

@@ -0,0 +1,43 @@
+from typing import Optional
+
+from aiohttp import ClientSession
+from eth_account import Account
+
+from async_hyperliquid.async_api import AsyncAPI
+from async_hyperliquid.utils.miscs import get_timestamp_ms
+from async_hyperliquid.utils.types import Endpoint
+from async_hyperliquid.utils.signing import sign_action
+from async_hyperliquid.utils.constants import MAINNET_API_URL
+
+
+class ExchangeAPI(AsyncAPI):
+    def __init__(
+        self,
+        account: Account,
+        session: ClientSession,
+        base_url: Optional[str] = None,
+        address: str = None,
+    ):
+        self.account = account
+        self.address = address or account.address
+        super().__init__(Endpoint.EXCHANGE, base_url, session)
+
+    async def post_action(
+        self, action: dict, vault: Optional[str] = None
+    ) -> dict:
+        assert self.endpoint == Endpoint.EXCHANGE, (
+            "only exchange endpoint supports action"
+        )
+
+        nonce = get_timestamp_ms()
+        signature = sign_action(
+            self.account, action, None, nonce, self.base_url == MAINNET_API_URL
+        )
+        vault_address = vault if action["type"] != "usdClassTransfer" else None
+        payloads = {
+            "action": action,
+            "nonce": nonce,
+            "signature": signature,
+            "vaultAddress": vault_address,
+        }
+        return await self.post(payloads)

async_hyperliquid-0.1.0/async_hyperliquid/info_endpoint.py

@@ -0,0 +1,207 @@
+from typing import Any, Dict, List
+
+from aiohttp import ClientSession
+
+from async_hyperliquid.async_api import AsyncAPI
+from async_hyperliquid.utils.types import (
+    Depth,
+    Order,
+    Endpoint,
+    RateLimit,
+    FilledOrder,
+    FundingRate,
+    OrderStatus,
+    UserFunding,
+    TokenDetails,
+    SpotDeployState,
+    PerpMetaResponse,
+    SpotMetaResponse,
+    ClearinghouseState,
+    PerpMetaCtxResponse,
+    SpotMetaCtxResponse,
+    SpotClearinghouseState,
+)
+
+
+class InfoAPI(AsyncAPI):
+    def __init__(self, base_url: str, session: ClientSession):
+        super().__init__(Endpoint.INFO, base_url, session)
+
+    async def get_all_mids(self) -> List[Dict[str, int]]:
+        payloads = {"type": "allMids"}
+        return await self.post(payloads)
+
+    async def get_user_open_orders(
+        self, address: str, is_frontend: bool = False
+    ) -> List[Order]:
+        payloads = {
+            "type": "frontendOpenOrders" if is_frontend else "openOrders",
+            "user": address,
+        }
+        return await self.post(payloads)
+
+    async def get_user_fills(
+        self,
+        address: str,
+        start_time: int = None,
+        end_time: int = None,
+        aggregated: bool = False,
+    ) -> List[FilledOrder]:
+        payloads = {
+            "type": "userFillsByTime" if start_time else "userFills",
+            "user": address,
+            "aggregateByTime": aggregated,
+        }
+        if start_time:
+            payloads["startTime"] = start_time
+            payloads["endTime"] = end_time
+        return await self.post(payloads)
+
+    async def get_user_rate_limit(self, address: str) -> RateLimit:
+        payloads = {"type": "userRateLimit", "user": address}
+        return await self.post(payloads)
+
+    async def get_order_status(
+        self, order_id: str, address: str
+    ) -> OrderStatus:
+        payloads = {"type": "orderStatus", "user": address, "oid": order_id}
+        return await self.post(payloads)
+
+    async def get_depth(
+        self, coin: str, level: int = None, mantissa: int = None
+    ) -> List[Depth]:
+        payloads = {"type": "l2Book", "coin": coin}
+        if level:
+            payloads["nSigFigs"] = level
+        if level and level == 5 and mantissa:
+            payloads["mantissa"] = mantissa
+        return await self.post(payloads)
+
+    async def get_candles(self, **data):
+        # TODO: to implement
+        # https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#candle-snapshot
+        pass
+
+    async def check_user_builder_fee(self, user: str, builder: str) -> None:
+        payloads = {"type": "maxBuilderFee", "user": user, "builder": builder}
+        return await self.post(payloads)
+
+    async def get_user_order_history(
+        self, address: str
+    ) -> List[Dict[str, Any]]:
+        payloads = {"type": "historicalOrders", "user": address}
+        return await self.post(payloads)
+
+    async def get_user_twap_fills(self, address: str) -> List[Dict[str, Any]]:
+        payloads = {"type": "userTwapSliceFills", "user": address}
+        return await self.post(payloads)
+
+    async def get_user_subaccounts(self, address: str) -> List[Dict[str, Any]]:
+        payloads = {"type": "subAccounts", "user": address}
+        return await self.post(payloads)
+
+    async def get_vault_info(
+        self, address: str, user: str = None
+    ) -> Dict[str, Any]:
+        payloads = {"type": "vaultDetails", "vaultAddress": address}
+        if user:
+            payloads["user"] = user
+        return await self.post(payloads)
+
+    async def get_user_vault_deposits(
+        self, address: str
+    ) -> List[Dict[str, Any]]:
+        payloads = {"type": "userVaultEquities", "user": address}
+        return await self.post(payloads)
+
+    async def get_user_role(self, address: str) -> Dict[str, str]:
+        payloads = {"type": "userRole", "user": address}
+        return await self.post(payloads)
+
+    async def get_user_staking(self, address: str) -> List[Dict[str, Any]]:
+        payloads = {"type": "delegations", "user": address}
+        return await self.post(payloads)
+
+    async def get_user_staking_summary(self, address: str) -> Dict[str, Any]:
+        payloads = {"type": "delegatorSummary", "user": address}
+        return await self.post(payloads)
+
+    async def get_user_staking_history(
+        self, address: str
+    ) -> List[Dict[str, Any]]:
+        payloads = {"type": "delegatorHistory", "user": address}
+        return await self.post(payloads)
+
+    async def get_user_staking_rewards(
+        self, address: str
+    ) -> List[Dict[str, Any]]:
+        payloads = {"type": "delegatorRewards", "user": address}
+        return await self.post(payloads)
+
+    async def get_perp_meta(self) -> PerpMetaResponse:
+        payloads = {"type": "meta"}
+        return await self.post(payloads)
+
+    async def get_perp_meta_ctx(self) -> PerpMetaCtxResponse:
+        payloads = {"type": "metaAndAssetCtxs"}
+        return await self.post(payloads)
+
+    async def get_positions(self, address: str) -> ClearinghouseState:
+        payloads = {"type": "clearinghouseState", "user": address}
+        return await self.post(payloads)
+
+    async def get_user_funding(
+        self,
+        address: str,
+        start_time: int,
+        end_time: int = None,
+        is_funding: bool = True,
+    ) -> List[UserFunding]:
+        payloads = {
+            "type": "userFunding"
+            if is_funding
+            else "userNonFundingLedgerUpdates",
+            "user": address,
+            "startTime": start_time,
+            "endTime": end_time,
+        }
+        return await self.post(payloads)
+
+    async def get_funding_rate(
+        self, coin: str, start_time: int, end_time: int = None
+    ) -> List[FundingRate]:
+        payloads = {
+            "type": "fundingHistory",
+            "coin": coin,
+            "startTime": start_time,
+            "endTime": end_time,
+        }
+        return await self.post(payloads)
+
+    async def get_predicted_funding(self) -> List[Any]:
+        payloads = {"type": "predictedFundings"}
+        return await self.post(payloads)
+
+    async def get_perps_at_open_interest_cap(self) -> List[str]:
+        payloads = {"type": "perpsAtOpenInterestCap"}
+        return await self.post(payloads)
+
+    async def get_spot_meta(self) -> SpotMetaResponse:
+        payloads = {"type": "spotMeta"}
+        return await self.post(payloads)
+
+    async def get_spot_meta_ctx(self) -> SpotMetaCtxResponse:
+        payloads = {"type": "spotMetaAndAssetCtxs"}
+        return await self.post(payloads)
+
+    async def get_user_balances(self, address: str) -> SpotClearinghouseState:
+        payloads = {"type": "spotClearinghouseState", "user": address}
+        return await self.post(payloads)
+
+    async def get_spot_deploy_state(self, address: str) -> SpotDeployState:
+        payloads = {"type": "spotDeployState", "user": address}
+        return await self.post(payloads)
+
+    async def get_token_info(self, token_id: str) -> TokenDetails:
+        payloads = {"type": "tokenDetails", "tokenId": token_id}
+        return await self.post(payloads)

async_hyperliquid-0.1.0/async_hyperliquid/utils/constants.py

@@ -0,0 +1,2 @@
+MAINNET_API_URL = "https://api.hyperliquid.xyz"
+TESTNET_API_URL = "https://api.hyperliquid-testnet.xyz"

async_hyperliquid-0.1.0/async_hyperliquid/utils/miscs.py

@@ -0,0 +1,28 @@
+import time
+from typing import Any
+from decimal import Decimal
+
+
+def get_timestamp_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def is_numeric(n: Any) -> bool:
+    try:
+        Decimal(n)
+        return True
+    except ValueError:
+        return False
+
+
+def convert_to_numeric(data: Any) -> Any:
+    if isinstance(data, dict):
+        for k, v in data.items():
+            if isinstance(v, str) and is_numeric(v):
+                data[k] = Decimal(v)
+            else:
+                data[k] = convert_to_numeric(v)
+    elif isinstance(data, list):
+        for i in data:
+            convert_to_numeric(i)
+    return data

async_hyperliquid-0.1.0/async_hyperliquid/utils/signing.py

@@ -0,0 +1,127 @@
+from typing import List
+from decimal import Decimal
+
+import msgpack
+from eth_utils import keccak, to_hex
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+from async_hyperliquid.utils.types import (
+    OrderType,
+    OrderAction,
+    EncodedOrder,
+    OrderBuilder,
+    PlaceOrderRequest,
+    SignedAction,
+)
+
+
+def address_to_bytes(address: str) -> bytes:
+    return bytes.fromhex(address[2:] if address.startswith("0x") else address)
+
+
+def hash_action(action, vault, nonce) -> bytes:
+    data = msgpack.packb(action)
+    data += nonce.to_bytes(8, "big")
+
+    if vault is None:
+        data += b"\x00"
+    else:
+        data += b"\x01"
+        data += bytes.fromhex(vault.removeprefix("0x"))
+    return keccak(data)
+
+
+def sign_action(
+    wallet: Account,
+    action: dict,
+    active_pool: str,
+    nonce: int,
+    is_mainnet: bool,
+) -> SignedAction:
+    h = hash_action(action, active_pool, nonce)
+    msg = {"source": "a" if is_mainnet else "b", "connectionId": h}
+    data = {
+        "domain": {
+            "chainId": 1337,
+            "name": "Exchange",
+            "verifyingContract": "0x0000000000000000000000000000000000000000",
+            "version": "1",
+        },
+        "types": {
+            "Agent": [
+                {"name": "source", "type": "string"},
+                {"name": "connectionId", "type": "bytes32"},
+            ],
+            "EIP712Domain": [
+                {"name": "name", "type": "string"},
+                {"name": "version", "type": "string"},
+                {"name": "chainId", "type": "uint256"},
+                {"name": "verifyingContract", "type": "address"},
+            ],
+        },
+        "primaryType": "Agent",
+        "message": msg,
+    }
+    encodes = encode_typed_data(full_message=data)
+    signed = wallet.sign_message(encodes)
+    return {
+        "r": to_hex(signed["r"]),
+        "s": to_hex(signed["s"]),
+        "v": signed["v"],
+    }
+
+
+def round_float(x: float) -> str:
+    rounded = f"{x:.8f}"
+    if abs(float(rounded) - x) >= 1e-12:
+        raise ValueError("round_float causes rounding", x)
+
+    if rounded == "-0":
+        rounded = "0"
+    normalized = Decimal(rounded).normalize()
+    return f"{normalized:f}"
+
+
+def ensure_order_type(order_type: OrderType) -> OrderType:
+    if "limit" in order_type:
+        return {"limit": order_type["limit"]}
+    elif "trigger" in order_type:
+        return {
+            "trigger": {
+                "isMarket": order_type["trigger"]["isMarket"],
+                "triggerPx": round_float(order_type["trigger"]["triggerPx"]),
+                "tpsl": order_type["trigger"]["tpsl"],
+            }
+        }
+
+    raise ValueError("Invalid order type", order_type)
+
+
+def encode_order(order: PlaceOrderRequest, asset: int) -> EncodedOrder:
+    encoded_order: EncodedOrder = {
+        "a": asset,
+        "b": order["is_buy"],
+        "p": round_float(order["limit_px"]),
+        "s": round_float(order["sz"]),
+        "r": order["reduce_only"],
+        "t": ensure_order_type(order["order_type"]),
+    }
+
+    if order["cloid"] is not None:
+        encoded_order["c"] = order["cloid"].to_raw()
+
+    return encoded_order
+
+
+def orders_to_action(
+    encoded_orders: List[EncodedOrder], builder: OrderBuilder = None
+) -> OrderAction:
+    action: OrderAction = {
+        "type": "order",
+        "orders": encoded_orders,
+        "grouping": "na",
+    }
+    if builder:
+        action["builder"] = builder
+    return action

async_hyperliquid-0.1.0/async_hyperliquid/utils/types.py

@@ -0,0 +1,336 @@
+from enum import Enum
+from typing import Any, List, Tuple, Union, Literal, Optional, TypedDict
+
+from typing_extensions import NotRequired
+
+
+class Cloid:
+    def __init__(self, raw_cloid: str):
+        self._raw_cloid: str = raw_cloid
+        self._validate()
+
+    def _validate(self) -> None:
+        if not self._raw_cloid[:2] == "0x":
+            raise TypeError("cloid is not a hex string")
+        if not len(self._raw_cloid[2:]) == 32:
+            raise TypeError("cloid is not 16 bytes")
+
+    def __str__(self) -> str:
+        return str(self._raw_cloid)
+
+    def __repr__(self) -> str:
+        return str(self._raw_cloid)
+
+    @staticmethod
+    def from_int(cloid: int) -> "Cloid":
+        return Cloid(f"{cloid:#034x}")
+
+    @staticmethod
+    def from_str(cloid: str) -> "Cloid":
+        return Cloid(cloid)
+
+    def to_raw(self) -> str:
+        return self._raw_cloid
+
+
+class SignedAction(TypedDict):
+    r: str
+    s: str
+    v: int
+
+
+class LimitOrderOptions(TypedDict):
+    tif: Literal["Alo", "Ioc", "Gtc"]
+
+
+class LimitOrderType(TypedDict):
+    limit: LimitOrderOptions
+
+
+class LimitOrder(Enum):
+    ALO = {"limit": {"tif": "Alo"}}
+    IOC = {"limit": {"tif": "Ioc"}}
+    GTC = {"limit": {"tif": "Gtc"}}
+
+
+class TriggerOrderOptions(TypedDict):
+    isMarket: bool
+    triggerPx: str
+    tpsl: Literal["tp", "sl"]
+
+
+class TriggerOrderType(TypedDict):
+    trigger: TriggerOrderOptions
+
+
+OrderType = Union[LimitOrderType, TriggerOrderType]
+
+
+class PlaceOrderRequest(TypedDict):
+    coin: str
+    is_buy: bool
+    sz: float
+    limit_px: float
+    reduce_only: bool
+    order_type: OrderType
+    cloid: NotRequired[Cloid]
+
+
+class CancelOrderRequest(TypedDict):
+    coin: str
+    oid: str
+    cloid: NotRequired[Cloid]
+
+
+class EncodedOrder(TypedDict):
+    a: int  # asset universe index
+    b: bool  # is_buy
+    p: str  # limit_px
+    s: str  # size
+    r: bool  # reduce_only
+    t: OrderType  # order type
+    c: NotRequired[Cloid]  # cloid
+
+
+class OrderBuilder(TypedDict):
+    b: str  # builder address
+    f: float
+
+
+class OrderAction(TypedDict):
+    type: Literal["order"]
+    orders: List[EncodedOrder]
+    grouping: Literal["na", "normalTpsl", "positionTpsl"]
+    builder: NotRequired[OrderBuilder]
+
+
+class Endpoint(str, Enum):
+    INFO = "info"
+    EXCHANGE = "exchange"
+
+
+class Order(TypedDict):
+    # TODO: add order type
+    pass
+
+
+class FilledOrder(Order):
+    # TODO: add filled order type
+    pass
+
+
+class RateLimit(TypedDict):
+    cumVlm: str
+    nRequestsUsed: int
+    nRequestsCap: int
+
+
+class OrderStatus(TypedDict):
+    # TODO: add order status
+    pass
+
+
+class L2Book(TypedDict):
+    px: str
+    sz: str
+    n: int
+
+
+class Depth(TypedDict):
+    bids: List[L2Book]
+    asks: List[L2Book]
+
+
+class PerpMeta(TypedDict):
+    name: str
+    szDecimals: int
+    maxLeverage: int
+    onlyIsolated: NotRequired[bool]
+    isDelisted: NotRequired[bool]
+
+
+class PerpMetaResponse(TypedDict):
+    universe: List[PerpMeta]
+
+
+class PerpMetaCtx(TypedDict):
+    dayNtlVlm: str
+    funding: str
+    impactPxs: List[str]
+    markPx: str
+    midPx: str
+    openInterest: str
+    oraclePx: str
+    premium: str
+    prevDayPx: str
+
+
+PerpMetaCtxResponse = List[Union[PerpMetaResponse, List[PerpMetaCtx]]]
+
+
+class AssetFunding(TypedDict):
+    allTime: str
+    sinceChange: str
+    sinceOpen: str
+
+
+class AssetLeverage(TypedDict):
+    rawUsd: str
+    type: str
+    value: int
+
+
+class Position(TypedDict):
+    coin: str
+    cumFunding: AssetFunding
+    entryPx: str
+    leverage: AssetLeverage
+    liquidationPx: str
+    marginUsed: str
+    maxLeverage: int
+    positionValue: str
+    returnOnEquity: str
+    szi: str
+    unrealizedPnl: str
+
+
+class AssetPosition(TypedDict):
+    type: str
+    position: Position
+
+
+class MarginSummary(TypedDict):
+    accountValue: str
+    totalMarginUsed: str
+    totalNtlPos: str
+    totalRawUsd: str
+
+
+class ClearinghouseState(TypedDict):
+    assetPositions: List[AssetPosition]
+    crosssMaintenanceMarginUsed: str
+    crossMarginSummary: MarginSummary
+    marginSummary: MarginSummary
+    time: int
+    withdrawable: str
+
+
+class UserFundingDelta(TypedDict):
+    coin: str
+    fundingRate: str
+    szi: str
+    type: str
+    usdc: str
+
+
+class UserFunding(TypedDict):
+    delta: UserFundingDelta
+    hash: str
+    time: int
+
+
+class FundingRate(TypedDict):
+    coin: str
+    fundingRate: str
+    premium: str
+    time: int
+
+
+class Token(TypedDict):
+    name: str
+    index: int
+    isCanonical: bool
+
+
+class TokenPairs(Token):
+    tokens: Tuple[int, int]
+
+
+class SpotMeta(Token):
+    szDecimals: int
+    weiDecimals: int
+    tokenId: str
+    evmContract: Optional[str]
+    fullName: Optional[str]
+
+
+class SpotMetaResponse(TypedDict):
+    tokens: List[SpotMeta]
+    universe: List[TokenPairs]
+
+
+class SpotMetaCtx(TypedDict):
+    dayNtlVlm: str
+    markPx: str
+    midPx: str
+    prevDayPx: str
+
+
+SpotMetaCtxResponse = List[Union[SpotMetaResponse, List[SpotMetaCtx]]]
+
+
+class TokenBalance(TypedDict):
+    coin: str
+    token: int
+    hold: str
+    total: str
+    entryNtl: str
+
+
+class SpotClearinghouseState(TypedDict):
+    balances: List[TokenBalance]
+
+
+class GasAuction(TypedDict):
+    startTimeSeconds: int
+    durationSeconds: int
+    startGas: str
+    currentGas: Optional[str]
+    endGas: str
+
+
+class DeployStateSpec(TypedDict):
+    name: str
+    szDecimals: int
+    weiDecimals: int
+
+
+class DeployState(TypedDict):
+    token: int
+    spec: DeployStateSpec
+    fullName: str
+    spots: List[int]
+    maxSupply: int
+    hyperliquidityGenesisBalance: str
+    totalGenesisBalanceWei: str
+    userGenesisBalances: List[Tuple[str, str]]
+    existingTokenGenesisBalances: List[Tuple[int, str]]
+
+
+class SpotDeployState(TypedDict):
+    states: List[DeployState]
+    gasAuction: GasAuction
+
+
+class TokenGenesis(TypedDict):
+    userBalances: List[Tuple[str, str]]
+    existingTokenBalances: List[Any]
+
+
+class TokenDetails(TypedDict):
+    name: str
+    maxSupply: str
+    totalSupply: str
+    circulatingSupply: str
+    szDecimals: int
+    weiDecimals: int
+    midPx: str
+    markPx: str
+    prevDayPx: str
+    genesis: List[TokenGenesis]
+    deployer: str
+    deployGas: str
+    deployTime: str
+    seededUsdc: str
+    nonCirculatingUserBalances: List[Any]
+    futureEmissions: str

async_hyperliquid-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "async-hyperliquid"
+version = "0.1.0"
+description = "Async Hyperliquid client using aiohttp"
+authors = [{ name = "oneforalone", email = "oneforalone@proton.me" }]
+readme = "README.md"
+requires-python = ">=3.10,<4"
+dependencies = [
+    "aiohttp (>=3.11.12,<4.0.0)",
+    "msgpack (>=1.1.0,<2.0.0)",
+    "eth-account (>=0.13.5,<0.14.0)",
+    "eth-utils (>=5.2.0,<6.0.0)",
+]
+
+[project.urls]
+Homepage = "https://github.com/oneforalone/async-hyperliquid"
+Documentation = "https://github.com/oneforalone/async-hyperliquid"
+Repository = "https://github.com/oneforalone/async-hyperliquid"
+Issues = "https://github.com/oneforalone/async-hyperliquid/issues"
+# Changelog = "https://github.com/oneforalone/async-hyperliquid/blob/master/CHANGELOG.md"
+
+[tool.poetry]
+packages = [{ include = "async_hyperliquid" }]
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.5"
+pytest-asyncio = "^0.25.3"
+pytest-ruff = "^0.4.1"
+pytest-cov = "^6.0.0"
+pre-commit = "^4.1.0"
+python-dotenv = "^1.0.1"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--verbose --capture=no"
+asyncio_default_fixture_loop_scope = "session"