Merge pull request #3 from quiknode-labs/update-examples-to-rest-api

rest overhaul

Author: yaanakbr

python/approve.py

@@ -1,16 +1,18 @@
 """Approve builder fee (one-time setup)."""
 
-from client import rpc, sign_hash
+from client import exchange, sign_hash
 
 MAX_FEE = "1%"
 
-res = rpc("hl_buildApproveBuilderFee", {"maxFeeRate": MAX_FEE})
-sig = sign_hash(res["result"]["hash"])
+res = exchange({
+    "action": {"type": "approveBuilderFee", "maxFeeRate": MAX_FEE},
+})
+sig = sign_hash(res["hash"])
 
-rpc("hl_sendApproval", {
-    "nonce": res["result"]["nonce"],
+exchange({
+    "action": {"type": "approveBuilderFee", "maxFeeRate": MAX_FEE},
+    "nonce": res["nonce"],
     "signature": sig,
-    "maxFeeRate": MAX_FEE,
 })
 
 print("Builder fee approved.")

python/cancel_order.py

@@ -1,7 +1,7 @@
 """Place a resting order (GTC, 3% below mid), then cancel it."""
 
 import json
-from client import rpc, sign_hash, get_mid
+from client import exchange, sign_hash, get_mid
 
 COIN = "BTC"
 
@@ -16,30 +16,28 @@
 print(f"{COIN} mid: ${mid:,.2f}")
 print(f"Placing resting BUY {sz} @ {rest_px} (GTC, 3% below mid)\n")
 
-order_action = {
-    "type": "order",
-    "orders": [{
-        "a": COIN,
-        "b": True,
-        "p": str(rest_px),
-        "s": str(sz),
-        "r": False,
-        "t": {"limit": {"tif": "Gtc"}},
-    }],
-    "grouping": "na",
-}
-
-res = rpc("hl_buildOrder", {"action": order_action})
-sig = sign_hash(res["result"]["hash"])
+res = exchange({
+    "action": {
+        "type": "order",
+        "orders": [{
+            "asset": COIN,
+            "side": "buy",
+            "price": str(rest_px),
+            "size": str(sz),
+            "tif": "gtc",
+        }],
+    },
+})
+sig = sign_hash(res["hash"])
 
-result = rpc("hl_sendOrder", {
-    "action": res["result"].get("action", order_action),
-    "nonce": res["result"]["nonce"],
+result = exchange({
+    "action": res["action"],
+    "nonce": res["nonce"],
     "signature": sig,
 })
 
-exchange = result["result"]["exchangeResponse"]
-statuses = exchange.get("response", {}).get("data", {}).get("statuses", [])
+exchange_resp = result["exchangeResponse"]
+statuses = exchange_resp.get("response", {}).get("data", {}).get("statuses", [])
 
 oid = None
 for s in statuses:
@@ -49,7 +47,7 @@
 
 if oid is None:
     print("Could not extract OID from resting order")
-    print(json.dumps(exchange, indent=2))
+    print(json.dumps(exchange_resp, indent=2))
     raise SystemExit(1)
 
 print(f"Order resting (OID: {oid})")
@@ -60,14 +58,14 @@
     "cancels": [{"a": COIN, "o": oid}],
 }
 
-res = rpc("hl_buildCancel", {"action": cancel_action})
-sig = sign_hash(res["result"]["hash"])
+res = exchange({"action": cancel_action})
+sig = sign_hash(res["hash"])
 
-result = rpc("hl_sendCancel", {
+result = exchange({
     "action": cancel_action,
-    "nonce": res["result"]["nonce"],
+    "nonce": res["nonce"],
     "signature": sig,
 })
 
-print(json.dumps(result["result"]["exchangeResponse"], indent=2))
+print(json.dumps(result["exchangeResponse"], indent=2))
 print("\nOrder cancelled.")

python/check_status.py

@@ -1,7 +1,7 @@
 """Check builder fee approval status."""
 
 import json
-from client import rpc, wallet
+from client import get_approval, address
 
-res = rpc("hl_getMaxBuilderFee", {"user": wallet.address})
-print(json.dumps(res["result"], indent=2))
+res = get_approval(address)
+print(json.dumps(res, indent=2))

python/client.py

@@ -1,4 +1,7 @@
-"""Thin RPC client for Hyperliquid API builder API."""
+"""REST client for Hyperliquid API (via QuickNode builder API).
+
+No SDK required -- just requests + eth_account.
+"""
 
 import json
 import os
@@ -7,41 +10,52 @@
 import requests
 from eth_account import Account
 
-ENDPOINT = "https://send.hyperliquidapi.com"
+API_URL = "https://send.hyperliquidapi.com"
+HL_INFO_URL = "https://api.hyperliquid.xyz/info"
 
 _pk = os.environ.get("PRIVATE_KEY")
 if not _pk:
     print("Set PRIVATE_KEY environment variable (hex, with or without 0x)")
     sys.exit(1)
 
 wallet = Account.from_key(_pk)
-print(f"Wallet: {wallet.address}")
-
-_req_id = 0
+address = wallet.address
+print(f"Wallet: {address}")
 
 
-def rpc(method, params=None):
-    global _req_id
-    _req_id += 1
-    r = requests.post(ENDPOINT, json={
-        "jsonrpc": "2.0",
-        "method": method,
-        "params": params or {},
-        "id": _req_id,
-    })
+def exchange(body):
+    """POST /exchange -- build (no signature) or send (with signature)."""
+    r = requests.post(f"{API_URL}/exchange", json=body)
     data = r.json()
     if data.get("error"):
-        err = data["error"]
-        print(f"\nRPC error ({method}):")
-        print(f"  code:     {err.get('code')}")
-        print(f"  message:  {err.get('message')}")
-        guidance = err.get("data", {}).get("guidance")
+        print(f"\nError ({r.status_code}):")
+        print(f"  error:    {data.get('error')}")
+        print(f"  message:  {data.get('message')}")
+        guidance = data.get("guidance")
         if guidance:
             print(f"  guidance: {guidance}")
         sys.exit(1)
     return data
 
 
+def get_approval(user):
+    """GET /approval?user=<addr> -- check builder fee approval status."""
+    r = requests.get(f"{API_URL}/approval", params={"user": user})
+    return r.json()
+
+
+def get_markets():
+    """GET /markets -- list all available markets."""
+    r = requests.get(f"{API_URL}/markets")
+    return r.json()
+
+
+def post_endpoint(path, body):
+    """POST to a utility endpoint (e.g. /openOrders, /orderStatus, /preflight)."""
+    r = requests.post(f"{API_URL}{path}", json=body)
+    return r.json()
+
+
 def sign_hash(hash_hex):
     h = bytes.fromhex(hash_hex.removeprefix("0x"))
     s = wallet.unsafe_sign_hash(h)
@@ -50,5 +64,12 @@ def sign_hash(hash_hex):
 
 def get_mid(coin):
     """Get the current mid price for a coin from Hyperliquid."""
-    r = requests.post("https://api.hyperliquid.xyz/info", json={"type": "allMids"})
+    r = requests.post(HL_INFO_URL, json={"type": "allMids"})
+    return float(r.json().get(coin, 0))
+
+
+def get_hip3_mid(coin):
+    """Get mid price for a HIP-3 market (requires dex parameter)."""
+    dex = coin.split(":")[0]
+    r = requests.post(HL_INFO_URL, json={"type": "allMids", "dex": dex})
     return float(r.json().get(coin, 0))

python/close_position.py

@@ -0,0 +1,31 @@
+"""Close a position — worker queries your position and builds the counter-order."""
+
+import json
+from client import exchange, sign_hash, address
+
+COIN = "HYPE"
+
+print(f"Closing {COIN} position for {address}\n")
+
+res = exchange({
+    "action": {
+        "type": "closePosition",
+        "asset": COIN,
+        "user": address,
+    },
+})
+
+ctx = res.get("closePositionContext", {})
+print(f"Position: {ctx.get('positionSize')} {ctx.get('positionSide')}")
+print(f"Close: {ctx.get('closeSide')} {ctx.get('closeSize')} @ {ctx.get('slippedPrice')}")
+
+sig = sign_hash(res["hash"])
+
+result = exchange({
+    "action": res["action"],
+    "nonce": res["nonce"],
+    "signature": sig,
+})
+
+print(json.dumps(result["exchangeResponse"], indent=2))
+print("\nPosition closed.")

python/hip3_order.py

@@ -1,44 +1,39 @@
 """Place an IOC order on a HIP-3 market by name (e.g. xyz:SILVER)."""
 
 import json
-import requests
-from client import rpc, sign_hash
+from client import exchange, sign_hash, get_hip3_mid
 
 COIN = "xyz:SILVER"
-DEX = COIN.split(":")[0]
 
-r = requests.post("https://api.hyperliquid.xyz/info", json={"type": "allMids", "dex": DEX})
-mid = float(r.json().get(COIN, 0))
+mid = get_hip3_mid(COIN)
 if mid == 0:
     print(f"Could not fetch {COIN} mid price, using fallback")
     mid = 78.0
 
-sz = round(10.0 / mid, 2)
+sz = round(11.0 / mid, 2)
 buy_px = round(mid * 1.03, 2)
 
 print(f"{COIN} mid: ${mid:,.2f}")
 print(f"BUY {sz} @ {buy_px} (IOC, ~${sz * mid:.2f} notional)\n")
 
-action = {
-    "type": "order",
-    "orders": [{
-        "a": COIN,
-        "b": True,
-        "p": str(buy_px),
-        "s": str(sz),
-        "r": False,
-        "t": {"limit": {"tif": "Ioc"}},
-    }],
-    "grouping": "na",
-}
-
-res = rpc("hl_buildOrder", {"action": action})
-sig = sign_hash(res["result"]["hash"])
-
-result = rpc("hl_sendOrder", {
-    "action": res["result"].get("action", action),
-    "nonce": res["result"]["nonce"],
+res = exchange({
+    "action": {
+        "type": "order",
+        "orders": [{
+            "asset": COIN,
+            "side": "buy",
+            "price": str(buy_px),
+            "size": str(sz),
+            "tif": "ioc",
+        }],
+    },
+})
+sig = sign_hash(res["hash"])
+
+result = exchange({
+    "action": res["action"],
+    "nonce": res["nonce"],
     "signature": sig,
 })
 
-print(json.dumps(result["result"]["exchangeResponse"], indent=2))
+print(json.dumps(result["exchangeResponse"], indent=2))

python/list_markets.py

@@ -1,9 +1,8 @@
 """List all available markets (perps, spot, HIP-3)."""
 
-from client import rpc
+from client import get_markets
 
-res = rpc("hl_listMarkets")
-data = res["result"]
+data = get_markets()
 
 perps = data.get("perps", [])
 spot = data.get("spot", [])

python/market_order.py

@@ -0,0 +1,35 @@
+"""Place a market order — no price needed, worker computes it automatically."""
+
+import json
+from client import exchange, sign_hash
+
+COIN = "BTC"
+SIZE = "0.00011"
+
+print(f"Market BUY {SIZE} {COIN}\n")
+
+res = exchange({
+    "action": {
+        "type": "order",
+        "orders": [{
+            "asset": COIN,
+            "side": "buy",
+            "size": SIZE,
+            "tif": "market",
+        }],
+    },
+})
+
+computed_price = res["action"]["orders"][0]["p"]
+print(f"Computed price (mid + 3% slippage): {computed_price}")
+print(f"Builder fee: {res['builderFee']}")
+
+sig = sign_hash(res["hash"])
+
+result = exchange({
+    "action": res["action"],
+    "nonce": res["nonce"],
+    "signature": sig,
+})
+
+print(json.dumps(result["exchangeResponse"], indent=2))