Version 0.14.0

Author: traderben

examples/basic_order_with_builder_deployed_dex.py

@@ -0,0 +1,53 @@
+# This example shows how to place and query orders for a builder-deployed perp dex
+import json
+
+import example_utils
+
+from hyperliquid.utils import constants
+
+DUMMY_DEX = "test"
+COIN = f"{DUMMY_DEX}:ABC"
+
+
+def main():
+    # Supply the builder-deployed perps dex as an argument
+    address, info, exchange = example_utils.setup(
+        base_url=constants.TESTNET_API_URL, skip_ws=True, perp_dexs=[DUMMY_DEX]
+    )
+
+    # Get the user state and print out position information
+    user_state = info.user_state(address)
+    positions = []
+    for position in user_state["assetPositions"]:
+        positions.append(position["position"])
+    if len(positions) > 0:
+        print("positions:")
+        for position in positions:
+            print(json.dumps(position, indent=2))
+    else:
+        print("no open positions")
+
+    # Print the meta for DUMMY_DEX
+    print("dummy dex meta:", info.meta(dex=DUMMY_DEX))
+
+    # Place an order that should rest by setting the price very low
+    order_result = exchange.order(COIN, True, 20, 1, {"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/example_utils.py

@@ -8,7 +8,7 @@
 from hyperliquid.info import Info
 
 
-def setup(base_url=None, skip_ws=False):
+def setup(base_url=None, skip_ws=False, perp_dexs=None):
     config_path = os.path.join(os.path.dirname(__file__), "config.json")
     with open(config_path) as f:
         config = json.load(f)
@@ -19,7 +19,7 @@ def setup(base_url=None, skip_ws=False):
     print("Running with account address:", address)
     if address != account.address:
         print("Running with agent address:", account.address)
-    info = Info(base_url, skip_ws)
+    info = Info(base_url, skip_ws, perp_dexs=perp_dexs)
     user_state = info.user_state(address)
     spot_user_state = info.spot_user_state(address)
     margin_summary = user_state["marginSummary"]
@@ -28,7 +28,7 @@ def setup(base_url=None, skip_ws=False):
         url = info.base_url.split(".", 1)[1]
         error_string = f"No accountValue:\nIf you think this is a mistake, make sure that {address} has a balance on {url}.\nIf address shown is your API wallet address, update the config to specify the address of your account, not the address of the API wallet."
         raise Exception(error_string)
-    exchange = Exchange(account, base_url, account_address=address)
+    exchange = Exchange(account, base_url, account_address=address, perp_dexs=perp_dexs)
     return address, info, exchange
 
 

examples/perp_deploy.py

@@ -0,0 +1,65 @@
+# Example script to for deploying a perp dex
+#
+# IMPORTANT: Replace any arguments for the exchange calls below to match your deployment requirements.
+
+import example_utils
+
+from hyperliquid.utils import constants
+
+# Set to True to register a new perp dex.
+REGISTER_PERP_DEX = False
+
+DUMMY_DEX = "test"
+
+
+def main():
+    address, info, exchange = example_utils.setup(constants.TESTNET_API_URL, skip_ws=True)
+
+    # Step 1: Registering a Perp Dex and Assets
+    #
+    # Takes part in the perp deploy auction and if successful, registers asset "TEST0".
+    # The max gas is $1M USDC and represents the max amount to be paid for the perp deploy auction.
+    # Registering an asset can be done multiple times.
+    perp_dex_schema_input = None
+    if REGISTER_PERP_DEX:
+        perp_dex_schema_input = {
+            "fullName": "test dex",
+            "collateralToken": 0,
+            "oracleUpdater": address,
+        }
+    register_asset_result = exchange.perp_deploy_register_asset(
+        dex=DUMMY_DEX,
+        max_gas=1000000000000,
+        coin="TEST0",
+        sz_decimals=2,
+        oracle_px="10.0",
+        margin_table_id=10,
+        only_isolated=False,
+        schema=perp_dex_schema_input,
+    )
+    print("register asset result:", register_asset_result)
+    # If registration is successful, the "dex" that was used can serve as the index into this clearinghouse for later asset
+    # registrations and oracle updates.
+
+    # Step 2: Set the Oracle Prices
+    #
+    # Oracle updates can be sent multiple times
+    set_oracle_result = exchange.perp_deploy_set_oracle(
+        DUMMY_DEX,
+        {
+            "TEST0": "12.0",
+            "TEST1": "1.0",
+        },
+        {
+            "TEST1": "3.0",
+            "TEST0": "14.0",
+        },
+    )
+    print("set oracle result:", set_oracle_result)
+
+    # get DUMMY_DEX meta
+    print("dummy dex meta:", info.meta(dex=DUMMY_DEX))
+
+
+if __name__ == "__main__":
+    main()

hyperliquid/exchange.py

@@ -32,7 +32,18 @@
     sign_usd_transfer_action,
     sign_withdraw_from_bridge_action,
 )
-from hyperliquid.utils.types import Any, BuilderInfo, Cloid, List, Meta, Optional, SpotMeta, Tuple
+from hyperliquid.utils.types import (
+    Any,
+    BuilderInfo,
+    Cloid,
+    Dict,
+    List,
+    Meta,
+    Optional,
+    PerpDexSchemaInput,
+    SpotMeta,
+    Tuple,
+)
 
 
 class Exchange(API):
@@ -47,12 +58,13 @@ def __init__(
         vault_address: Optional[str] = None,
         account_address: Optional[str] = None,
         spot_meta: Optional[SpotMeta] = None,
+        perp_dexs: Optional[List[str]] = None,
     ):
         super().__init__(base_url)
         self.wallet = wallet
         self.vault_address = vault_address
         self.account_address = account_address
-        self.info = Info(base_url, True, meta, spot_meta)
+        self.info = Info(base_url, True, meta, spot_meta, perp_dexs)
         self.expires_after: Optional[int] = None
 
     def _post_action(self, action, signature, nonce):
@@ -831,6 +843,87 @@ def spot_deploy_set_deployer_trading_fee_share(self, token: int, share: str) ->
             timestamp,
         )
 
+    def perp_deploy_register_asset(
+        self,
+        dex: str,
+        max_gas: Optional[int],
+        coin: str,
+        sz_decimals: int,
+        oracle_px: str,
+        margin_table_id: int,
+        only_isolated: bool,
+        schema: Optional[PerpDexSchemaInput],
+    ) -> Any:
+        timestamp = get_timestamp_ms()
+        schema_wire = None
+        if schema is not None:
+            schema_wire = {
+                "fullName": schema["fullName"],
+                "collateralToken": schema["collateralToken"],
+                "oracleUpdater": schema["oracleUpdater"].lower() if schema["oracleUpdater"] is not None else None,
+            }
+        action = {
+            "type": "perpDeploy",
+            "registerAsset": {
+                "maxGas": max_gas,
+                "assetRequest": {
+                    "coin": coin,
+                    "szDecimals": sz_decimals,
+                    "oraclePx": oracle_px,
+                    "marginTableId": margin_table_id,
+                    "onlyIsolated": only_isolated,
+                },
+                "dex": dex,
+                "schema": schema_wire,
+            },
+        }
+        signature = sign_l1_action(
+            self.wallet,
+            action,
+            None,
+            timestamp,
+            self.expires_after,
+            self.base_url == MAINNET_API_URL,
+        )
+        return self._post_action(
+            action,
+            signature,
+            timestamp,
+        )
+
+    def perp_deploy_set_oracle(
+        self,
+        dex: str,
+        oracle_pxs: Dict[str, str],
+        mark_pxs: Optional[Dict[str, str]],
+    ) -> Any:
+        timestamp = get_timestamp_ms()
+        oracle_pxs_wire = sorted(list(oracle_pxs.items()))
+        mark_pxs_wire = None
+        if mark_pxs is not None:
+            mark_pxs_wire = sorted(list(mark_pxs.items()))
+        action = {
+            "type": "perpDeploy",
+            "setOracle": {
+                "dex": dex,
+                "oraclePxs": oracle_pxs_wire,
+                "markPxs": mark_pxs_wire,
+            },
+        }
+        signature = sign_l1_action(
+            self.wallet,
+            action,
+            None,
+            timestamp,
+            self.expires_after,
+            self.base_url == MAINNET_API_URL,
+        )
+        return self._post_action(
+            action,
+            signature,
+            timestamp,
+        )
+
     def c_signer_unjail_self(self) -> Any:
         return self.c_signer_inner("unjailSelf")