Version 0.7.0

Author: traderben

assets/images/coverage.svg

@@ -0,0 +1,23 @@
+from hyperliquid.utils import constants
+import example_utils
+
+
+def main():
+    address, info, exchange = example_utils.setup(constants.TESTNET_API_URL, skip_ws=True)
+
+    if exchange.account_address != exchange.wallet.address:
+        raise Exception("Only the main wallet has permission to approve a builder fee")
+
+    # approve setting a builder fee
+    approve_result = exchange.approve_builder_fee("0x0000000000000000000000000000000000000000", "0.001%")
+    print(approve_result)
+
+    # place an order with builder set, this will cause an additional fee to be added to the order which is sent to the builder
+    order_result = exchange.market_open(
+        "ETH", True, 0.05, None, 0.01, builder={"b": "0x0000000000000000000000000000000000000000", "f": 1}
+    )
+    print(order_result)
+
+
+if __name__ == "__main__":
+    main()

examples/basic_builder_fee.py

@@ -3,18 +3,14 @@
 
 
 def main():
-    address, info, exchange = example_utils.setup(
-        constants.TESTNET_API_URL, skip_ws=True)
+    address, info, exchange = example_utils.setup(constants.TESTNET_API_URL, skip_ws=True)
 
     if exchange.account_address != exchange.wallet.address:
-        raise Exception(
-            "Agents do not have permission to perform internal transfers")
+        raise Exception("Agents do not have permission to perform internal transfers")
 
     # Transfer 1 PURR token to the zero address for demonstration purposes
     transfer_result = exchange.spot_transfer(
-        1,
-        "0x0000000000000000000000000000000000000000",
-        "PURR:0xc4bf3f870c0e9465323c0b6ed28096c2"
+        1, "0x0000000000000000000000000000000000000000", "PURR:0xc4bf3f870c0e9465323c0b6ed28096c2"
     )
     print(transfer_result)
 

examples/basic_spot_transfer.py

@@ -2,6 +2,8 @@
 import example_utils
 
 
+# This example shows how to create, query, and transfer funds to a subaccount.
+# To trade as a subaccount set vault_address to the subaccount's address. See basic_vault.py for an example.
 def main():
     address, info, exchange = example_utils.setup(constants.TESTNET_API_URL, skip_ws=True)
 

examples/basic_sub_account.py

@@ -6,7 +6,7 @@
 def main():
     address, info, exchange = example_utils.setup(constants.TESTNET_API_URL, skip_ws=True)
 
-    # Change this address to a vault that you lead
+    # Change this address to a vault that you lead or a subaccount that you own
     vault = "0x1719884eb866cb12b2287399b15f7db5e7d775ea"
 
     # Place an order that should rest by setting the price very low

examples/basic_vault.py

@@ -20,13 +20,15 @@
     get_timestamp_ms,
     order_request_to_order_wire,
     order_wires_to_order_action,
+    sign_approve_builder_fee,
     sign_l1_action,
+    sign_usd_class_transfer_action,
     sign_usd_transfer_action,
     sign_spot_transfer_action,
     sign_withdraw_from_bridge_action,
     sign_agent,
 )
-from hyperliquid.utils.types import Any, List, Meta, SpotMeta, Optional, Tuple, Cloid
+from hyperliquid.utils.types import Any, List, Meta, SpotMeta, Optional, Tuple, Cloid, BuilderInfo
 
 
 class Exchange(API):
@@ -87,6 +89,7 @@ def order(
         order_type: OrderType,
         reduce_only: bool = False,
         cloid: Optional[Cloid] = None,
+        builder: Optional[BuilderInfo] = None,
     ) -> Any:
         order: OrderRequest = {
             "coin": name,
@@ -98,15 +101,15 @@ def order(
         }
         if cloid:
             order["cloid"] = cloid
-        return self.bulk_orders([order])
+        return self.bulk_orders([order], builder)
 
-    def bulk_orders(self, order_requests: List[OrderRequest]) -> Any:
+    def bulk_orders(self, order_requests: List[OrderRequest], builder: Optional[BuilderInfo] = None) -> Any:
         order_wires: List[OrderWire] = [
             order_request_to_order_wire(order, self.info.name_to_asset(order["coin"])) for order in order_requests
         ]
         timestamp = get_timestamp_ms()
 
-        order_action = order_wires_to_order_action(order_wires)
+        order_action = order_wires_to_order_action(order_wires, builder)
 
         signature = sign_l1_action(
             self.wallet,
@@ -184,11 +187,14 @@ def market_open(
         px: Optional[float] = None,
         slippage: float = DEFAULT_SLIPPAGE,
         cloid: Optional[Cloid] = None,
+        builder: Optional[BuilderInfo] = None,
     ) -> Any:
         # Get aggressive Market Price
         px = self._slippage_price(name, is_buy, slippage, px)
         # Market Order is an aggressive Limit Order IoC
-        return self.order(name, is_buy, sz, px, order_type={"limit": {"tif": "Ioc"}}, reduce_only=False, cloid=cloid)
+        return self.order(
+            name, is_buy, sz, px, order_type={"limit": {"tif": "Ioc"}}, reduce_only=False, cloid=cloid, builder=builder
+        )
 
     def market_close(
         self,
@@ -197,6 +203,7 @@ def market_close(
         px: Optional[float] = None,
         slippage: float = DEFAULT_SLIPPAGE,
         cloid: Optional[Cloid] = None,
+        builder: Optional[BuilderInfo] = None,
     ) -> Any:
         address = self.wallet.address
         if self.account_address:
@@ -215,7 +222,16 @@ def market_close(
             # Get aggressive Market Price
             px = self._slippage_price(coin, is_buy, slippage, px)
             # Market Order is an aggressive Limit Order IoC
-            return self.order(coin, is_buy, sz, px, order_type={"limit": {"tif": "Ioc"}}, reduce_only=True, cloid=cloid)
+            return self.order(
+                coin,
+                is_buy,
+                sz,
+                px,
+                order_type={"limit": {"tif": "Ioc"}},
+                reduce_only=True,
+                cloid=cloid,
+                builder=builder,
+            )
 
     def cancel(self, name: str, oid: int) -> Any:
         return self.bulk_cancel([{"coin": name, "oid": oid}])
@@ -384,6 +400,22 @@ def create_sub_account(self, name: str) -> Any:
             timestamp,
         )
 
+    def usd_class_transfer(self, amount: float, to_perp: bool) -> Any:
+        timestamp = get_timestamp_ms()
+        action = {
+            "type": "usdClassTransfer",
+            "amount": str(amount),
+            "toPerp": to_perp,
+            "nonce": timestamp,
+        }
+        signature = sign_usd_class_transfer_action(self.wallet, action, self.base_url == MAINNET_API_URL)
+        return self._post_action(
+            action,
+            signature,
+            timestamp,
+        )
+
+    # Deprecated in favor of usd_class_transfer
     def user_spot_transfer(self, usdc: float, to_perp: bool) -> Any:
         usdc = int(round(usdc, 2) * 1e6)
         timestamp = get_timestamp_ms()
@@ -427,22 +459,21 @@ def sub_account_transfer(self, sub_account_user: str, is_deposit: bool, usd: int
             signature,
             timestamp,
         )
-    
+
     def vault_usd_transfer(self, vault_address: str, is_deposit: bool, usd: int) -> Any:
         timestamp = get_timestamp_ms()
         vault_transfer_action = {
             "type": "vaultTransfer",
             "vaultAddress": vault_address,
             "isDeposit": is_deposit,
-            "usd": usd}
+            "usd": usd,
+        }
         is_mainnet = self.base_url == MAINNET_API_URL
         signature = sign_l1_action(self.wallet, vault_transfer_action, None, timestamp, is_mainnet)
-        return (
-            self._post_action(
-                vault_transfer_action,
-                signature,
-                timestamp,
-            )
+        return self._post_action(
+            vault_transfer_action,
+            signature,
+            timestamp,
         )
 
     def usd_transfer(self, amount: float, destination: str) -> Any:
@@ -458,8 +489,13 @@ def usd_transfer(self, amount: float, destination: str) -> Any:
 
     def spot_transfer(self, amount: float, destination: str, token: str) -> Any:
         timestamp = get_timestamp_ms()
-        action = {"destination": destination, "amount": str(
-            amount), "token": token, "time": timestamp, "type": "spotSend"}
+        action = {
+            "destination": destination,
+            "amount": str(amount),
+            "token": token,
+            "time": timestamp,
+            "type": "spotSend",
+        }
         is_mainnet = self.base_url == MAINNET_API_URL
         signature = sign_spot_transfer_action(self.wallet, action, is_mainnet)
         return self._post_action(
@@ -502,3 +538,10 @@ def approve_agent(self, name: Optional[str] = None) -> Tuple[Any, str]:
             ),
             agent_key,
         )
+
+    def approve_builder_fee(self, builder: str, max_fee_rate: str) -> Any:
+        timestamp = get_timestamp_ms()
+
+        action = {"maxFeeRate": max_fee_rate, "builder": builder, "nonce": timestamp, "type": "approveBuilderFee"}
+        signature = sign_approve_builder_fee(self.wallet, action, self.base_url == MAINNET_API_URL)
+        return self._post_action(action, signature, timestamp)

hyperliquid/exchange.py

@@ -207,6 +207,21 @@ def sign_withdraw_from_bridge_action(wallet, action, is_mainnet):
     )
 
 
+def sign_usd_class_transfer_action(wallet, action, is_mainnet):
+    return sign_user_signed_action(
+        wallet,
+        action,
+        [
+            {"name": "hyperliquidChain", "type": "string"},
+            {"name": "amount", "type": "string"},
+            {"name": "toPerp", "type": "bool"},
+            {"name": "nonce", "type": "uint64"},
+        ],
+        "HyperliquidTransaction:UsdClassTransfer",
+        is_mainnet,
+    )
+
+
 def sign_agent(wallet, action, is_mainnet):
     return sign_user_signed_action(
         wallet,
@@ -222,6 +237,21 @@ def sign_agent(wallet, action, is_mainnet):
     )
 
 
+def sign_approve_builder_fee(wallet, action, is_mainnet):
+    return sign_user_signed_action(
+        wallet,
+        action,
+        [
+            {"name": "hyperliquidChain", "type": "string"},
+            {"name": "maxFeeRate", "type": "string"},
+            {"name": "builder", "type": "address"},
+            {"name": "nonce", "type": "uint64"},
+        ],
+        "HyperliquidTransaction:ApproveBuilderFee",
+        is_mainnet,
+    )
+
+
 def sign_inner(wallet, data):
     structured_data = encode_structured_data(data)
     signed = wallet.sign_message(structured_data)
@@ -272,9 +302,12 @@ def order_request_to_order_wire(order: OrderRequest, asset: int) -> OrderWire:
     return order_wire
 
 
-def order_wires_to_order_action(order_wires):
-    return {
+def order_wires_to_order_action(order_wires, builder=None):
+    action = {
         "type": "order",
         "orders": order_wires,
         "grouping": "na",
     }
+    if builder:
+        action["builder"] = builder
+    return action

hyperliquid/utils/signing.py

@@ -1,14 +1,7 @@
 from __future__ import annotations
 
-import sys
-
-if sys.version_info >= (3, 8):
-    from typing import Literal, TypedDict
-    from typing_extensions import NotRequired
-else:
-    from typing_extensions import TypedDict, Literal, NotRequired
-
-from typing import Any, Callable, Dict, List, NamedTuple, Optional, Tuple, Union, cast
+from typing_extensions import NotRequired
+from typing import Any, Callable, Dict, List, NamedTuple, Optional, Tuple, Union, cast, Literal, TypedDict
 
 Any = Any
 Option = Optional
@@ -111,6 +104,9 @@
 )
 WsMsg = Union[AllMidsMsg, L2BookMsg, TradesMsg, UserEventsMsg, PongMsg, UserFillsMsg, OtherWsMsg]
 
+# b is the public address of the builder, f is the amount of the fee in tenths of basis points. e.g. 10 means 1 basis point
+BuilderInfo = TypedDict("BuilderInfo", {"b": str, "f": int})
+
 
 class Cloid:
     def __init__(self, raw_cloid: str):