Version 0.3.0

Author: Louis Tao

assets/images/coverage.svg

@@ -0,0 +1,42 @@
+import json
+
+from hyperliquid.utils import constants
+import example_utils
+
+
+COIN = "PURR/USDC"
+
+
+def main():
+    address, info, exchange = example_utils.setup(base_url=constants.TESTNET_API_URL, skip_ws=True)
+
+    # Get the user state and print out position information
+    spot_user_state = info.spot_user_state(address)
+    if len(spot_user_state["balances"]) > 0:
+        print("spot balances:")
+        for balance in spot_user_state["balances"]:
+            print(json.dumps(balance, indent=2))
+    else:
+        print("no available token balances")
+
+    # Place an order that should rest by setting the price very low
+    order_result = exchange.order(COIN, True, 1200, 0.01, {"limit": {"tif": "Gtc"}})
+    print(order_result)
+
+    # Query the order status by oid
+    if order_result["status"] == "ok":
+        status = order_result["response"]["data"]["statuses"][0]
+        if "resting" in status:
+            order_status = info.query_order_by_oid(address, status["resting"]["oid"])
+            print("Order status by oid:", order_status)
+
+    # Cancel the order
+    if order_result["status"] == "ok":
+        status = order_result["response"]["data"]["statuses"][0]
+        if "resting" in status:
+            cancel_result = exchange.cancel(COIN, status["resting"]["oid"])
+            print(cancel_result)
+
+
+if __name__ == "__main__":
+    main()

examples/basic_spot_order.py

@@ -0,0 +1,18 @@
+from hyperliquid.utils import constants
+import example_utils
+
+
+def main():
+    address, info, exchange = example_utils.setup(constants.TESTNET_API_URL, skip_ws=True)
+
+    # Transfer 1.23 USDC from perp wallet to spot wallet
+    transfer_result = exchange.user_spot_transfer(1.23, False)
+    print(transfer_result)
+
+    # Transfer 1.23 USDC from spot wallet to perp wallet
+    transfer_result = exchange.user_spot_transfer(1.23, True)
+    print(transfer_result)
+
+
+if __name__ == "__main__":
+    main()

examples/basic_spot_to_perp.py

@@ -26,7 +26,7 @@
     sign_withdraw_from_bridge_action,
     sign_agent,
 )
-from hyperliquid.utils.types import Any, List, Meta, Optional, Tuple, Cloid
+from hyperliquid.utils.types import Any, List, Meta, SpotMeta, Optional, Tuple, Cloid
 
 
 class Exchange(API):
@@ -41,6 +41,7 @@ def __init__(
         meta: Optional[Meta] = None,
         vault_address: Optional[str] = None,
         account_address: Optional[str] = None,
+        spot_meta: Optional[SpotMeta] = None,
     ):
         super().__init__(base_url)
         self.wallet = wallet
@@ -51,8 +52,18 @@ def __init__(
             self.meta = self.info.meta()
         else:
             self.meta = meta
+
+        if spot_meta is None:
+            self.spot_meta = self.info.spot_meta()
+        else:
+            self.spot_meta = spot_meta
+
         self.coin_to_asset = {asset_info["name"]: asset for (asset, asset_info) in enumerate(self.meta["universe"])}
 
+        # spot assets start at 10000
+        for i, spot_pair in enumerate(self.spot_meta["universe"]):
+            self.coin_to_asset[spot_pair["name"]] = i + 10000
+
     def _post_action(self, action, signature, nonce):
         payload = {
             "action": action,
@@ -389,6 +400,29 @@ def create_sub_account(self, name: str) -> Any:
             timestamp,
         )
 
+    def user_spot_transfer(self, usdc: float, to_perp: bool) -> Any:
+        usdc = int(round(usdc, 2) * 1e6)
+        timestamp = get_timestamp_ms()
+        spot_user_action = {
+            "type": "spotUser",
+            "classTransfer": {
+                "usdc": usdc,
+                "toPerp": to_perp,
+            },
+        }
+        signature = sign_l1_action(
+            self.wallet,
+            spot_user_action,
+            self.vault_address,
+            timestamp,
+            self.base_url == MAINNET_API_URL,
+        )
+        return self._post_action(
+            spot_user_action,
+            signature,
+            timestamp,
+        )
+
     def sub_account_transfer(self, sub_account_user: str, is_deposit: bool, usd: int) -> Any:
         timestamp = get_timestamp_ms()
         sub_account_transfer_action = {

hyperliquid/exchange.py

@@ -1,5 +1,5 @@
 from hyperliquid.api import API
-from hyperliquid.utils.types import Any, Callable, Meta, Optional, Subscription, cast, Cloid
+from hyperliquid.utils.types import Any, Callable, Meta, SpotMeta, Optional, Subscription, cast, Cloid
 from hyperliquid.websocket_manager import WebsocketManager
 
 
@@ -54,6 +54,9 @@ def user_state(self, address: str) -> Any:
         """
         return self.post("/info", {"type": "clearinghouseState", "user": address})
 
+    def spot_user_state(self, address: str) -> Any:
+        return self.post("/info", {"type": "spotClearinghouseState", "user": address})
+
     def open_orders(self, address: str) -> Any:
         """Retrieve a user's open orders.
 
@@ -152,7 +155,7 @@ def user_fills(self, address: str) -> Any:
         return self.post("/info", {"type": "userFills", "user": address})
 
     def meta(self) -> Meta:
-        """Retrieve exchange metadata
+        """Retrieve exchange perp metadata
 
         POST /info
 
@@ -169,6 +172,32 @@ def meta(self) -> Meta:
         """
         return cast(Meta, self.post("/info", {"type": "meta"}))
 
+    def spot_meta(self) -> SpotMeta:
+        """Retrieve exchange spot metadata
+
+        POST /info
+
+        Returns:
+            {
+                tokens: [
+                    {
+                        name: str,
+                        szDecimals: int,
+                        weiDecimals: int
+                    },
+                    ...
+                ],
+                universe: [
+                    {
+                        name: str,
+                        tokens: [int, int]
+                    },
+                    ...
+                ]
+            }
+        """
+        return cast(SpotMeta, self.post("/info", {"type": "spotMeta"}))
+
     def funding_history(self, coin: str, startTime: int, endTime: Optional[int] = None) -> Any:
         """Retrieve funding history for a given coin
 

hyperliquid/info.py

@@ -22,6 +22,10 @@
 Side = Union[Literal["A"], Literal["B"]]
 SIDES: List[Side] = ["A", "B"]
 
+SpotAssetInfo = TypedDict("SpotAssetInfo", {"name": str, "tokens": List[int]})
+SpotTokenInfo = TypedDict("SpotTokenInfo", {"name": str, "szDecimals": int, "weiDecimals": int})
+SpotMeta = TypedDict("SpotMeta", {"universe": List[SpotAssetInfo], "tokens": List[SpotTokenInfo]})
+
 AllMidsSubscription = TypedDict("AllMidsSubscription", {"type": Literal["allMids"]})
 L2BookSubscription = TypedDict("L2BookSubscription", {"type": Literal["l2Book"], "coin": str})
 TradesSubscription = TypedDict("TradesSubscription", {"type": Literal["trades"], "coin": str})

hyperliquid/utils/types.py

@@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "hyperliquid-python-sdk"
-version = "0.2.3"
+version = "0.3.0"
 description = "SDK for Hyperliquid API trading with Python."
 readme = "README.md"
 authors = ["Hyperliquid <[email protected]>"]