hyperliquid-sdk 0.1.0__tar.gz

hyperliquid_sdk-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+rust/target/
+typescript/node_modules/
+python/__pycache__/
+.env

hyperliquid_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuickNode, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hyperliquid_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: hyperliquid-sdk
+Version: 0.1.0
+Summary: The simplest way to trade on Hyperliquid. One line to place orders, zero ceremony.
+Project-URL: Homepage, https://hyperliquidapi.com
+Project-URL: Documentation, https://hyperliquidapi.com/docs
+Project-URL: Repository, https://github.com/quiknode-labs/hyperliquid-sdk-python
+Project-URL: Changelog, https://github.com/quiknode-labs/hyperliquid-sdk-python/releases
+Author-email: Mauro Delazeri <mauro@quicknode.com>, QuickNode <support@quicknode.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,crypto,defi,hyperliquid,perpetuals,perps,sdk,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: eth-account>=0.10.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Hyperliquid SDK
+
+**The simplest way to trade on Hyperliquid.** One line to place orders, zero ceremony.
+
+```python
+from hyperliquid_sdk import HyperliquidSDK
+
+sdk = HyperliquidSDK()
+order = sdk.market_buy("BTC", notional=100)  # Buy $100 of BTC
+```
+
+That's it. No build-sign-send ceremony. No manual hash signing. No nonce tracking. Just trading.
+
+## Installation
+
+```bash
+pip install hyperliquid-sdk
+```
+
+## Quick Start
+
+### 1. Set your private key
+
+```bash
+export PRIVATE_KEY="0xYOUR_PRIVATE_KEY"
+```
+
+### 2. Start trading
+
+```python
+from hyperliquid_sdk import HyperliquidSDK
+
+sdk = HyperliquidSDK()
+
+# Market orders
+order = sdk.market_buy("BTC", size=0.001)
+order = sdk.market_sell("ETH", notional=100)  # $100 worth
+
+# Limit orders
+order = sdk.buy("BTC", size=0.001, price=65000, tif="gtc")
+
+# Check your order
+print(order.status)  # "filled" or "resting"
+print(order.oid)     # Order ID
+```
+
+## Features
+
+### One-Line Orders
+
+```python
+# Market orders - execute immediately
+sdk.market_buy("BTC", size=0.001)
+sdk.market_sell("ETH", notional=100)
+
+# Limit orders
+sdk.buy("BTC", size=0.001, price=65000)
+sdk.sell("ETH", size=0.5, price=4000, tif="gtc")
+
+# Perp trader aliases
+sdk.long("BTC", size=0.001, price=65000)
+sdk.short("ETH", notional=500, tif="ioc")
+```
+
+### Order Management
+
+```python
+# Place a resting order
+order = sdk.buy("BTC", size=0.001, price=60000, tif="gtc")
+
+# Modify it
+order.modify(price=61000)
+
+# Cancel it
+order.cancel()
+
+# Cancel all orders
+sdk.cancel_all()
+sdk.cancel_all("BTC")  # Just BTC orders
+```
+
+### Position Management
+
+```python
+# Close a position completely (SDK figures out size and direction)
+sdk.close_position("BTC")
+```
+
+### Fluent Order Builder
+
+For power users who want maximum control:
+
+```python
+from hyperliquid_sdk import Order
+
+order = sdk.order(
+    Order.buy("BTC")
+         .size(0.001)
+         .price(65000)
+         .gtc()
+         .reduce_only()
+)
+```
+
+### HIP-3 Markets
+
+Trade HIP-3 markets (like Hypersea) with the same API:
+
+```python
+sdk.buy("xyz:SILVER", notional=100, tif="ioc")
+```
+
+### Market Data
+
+```python
+# Get mid price
+mid = sdk.get_mid("BTC")
+
+# List all markets
+markets = sdk.markets()
+
+# View open orders
+orders = sdk.open_orders()
+```
+
+## Error Handling
+
+Clear, actionable errors with guidance:
+
+```python
+from hyperliquid_sdk import (
+    HyperliquidSDK,
+    ApprovalError,
+    ValidationError,
+    GeoBlockedError,
+)
+
+try:
+    order = sdk.buy("BTC", size=0.001, price=65000)
+except ApprovalError as e:
+    print(f"Need approval: {e.guidance}")
+    sdk.approve_builder_fee("1%")
+except ValidationError as e:
+    print(f"Invalid order: {e.message}")
+except GeoBlockedError as e:
+    print(f"Access denied: {e.guidance}")
+```
+
+## Auto-Approval
+
+Skip the approval step entirely:
+
+```python
+sdk = HyperliquidSDK(auto_approve=True)
+# Now just trade - approval happens automatically
+```
+
+## API Reference
+
+### HyperliquidSDK
+
+```python
+HyperliquidSDK(
+    private_key=None,      # Falls back to PRIVATE_KEY env var
+    auto_approve=False,    # Auto-approve builder fee
+    max_fee="1%",          # Max fee for auto-approval
+)
+```
+
+### Order Methods
+
+| Method | Description |
+|--------|-------------|
+| `buy(asset, size=, price=, tif=)` | Place a buy order |
+| `sell(asset, size=, price=, tif=)` | Place a sell order |
+| `market_buy(asset, size=)` | Market buy |
+| `market_sell(asset, size=)` | Market sell |
+| `long(asset, ...)` | Alias for buy |
+| `short(asset, ...)` | Alias for sell |
+
+### Order Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `asset` | str | Asset name ("BTC", "ETH", "xyz:SILVER") |
+| `size` | float | Size in asset units |
+| `notional` | float | Size in USD (alternative to size) |
+| `price` | float | Limit price |
+| `tif` | str | Time in force: "ioc", "gtc", "alo", "market" |
+| `reduce_only` | bool | Close position only |
+
+### Management Methods
+
+| Method | Description |
+|--------|-------------|
+| `cancel(oid)` | Cancel order by ID |
+| `cancel_all(asset=None)` | Cancel all orders |
+| `close_position(asset)` | Close a position |
+| `modify(oid, price=, size=)` | Modify an order |
+
+### Query Methods
+
+| Method | Description |
+|--------|-------------|
+| `get_mid(asset)` | Get mid price |
+| `markets()` | List all markets |
+| `open_orders()` | Get open orders |
+| `order_status(oid)` | Get order status |
+| `approval_status()` | Check builder fee approval |
+
+### PlacedOrder Object
+
+```python
+order = sdk.buy("BTC", size=0.001, price=65000, tif="gtc")
+
+order.oid          # Order ID
+order.status       # "filled", "resting", "error: ..."
+order.asset        # "BTC"
+order.side         # "buy" or "sell"
+order.size         # "0.001"
+order.price        # "65000"
+order.filled_size  # Filled amount (if filled)
+order.is_filled    # True if filled
+order.is_resting   # True if resting
+
+order.cancel()     # Cancel this order
+order.modify(price=66000)  # Modify this order
+```
+
+## Examples
+
+See the [examples](./sdk_examples/) directory for complete working examples:
+
+- `market_order.py` - Market order in 5 lines
+- `place_order.py` - Limit order
+- `roundtrip.py` - Buy then sell
+- `cancel_order.py` - Place and cancel
+- `modify_order.py` - Place and modify
+- `close_position.py` - Close a position
+- `fluent_builder.py` - Power user patterns
+- `full_demo.py` - All features
+
+## Compared to Raw API
+
+| Operation | Raw API | SDK | Reduction |
+|-----------|---------|-----|-----------|
+| Market order | 35 lines | 1 line | 97% |
+| Limit order | 39 lines | 1 line | 97% |
+| Cancel order | 71 lines | 2 lines | 97% |
+| Roundtrip | 64 lines | 4 lines | 94% |
+
+## Links
+
+- **Website**: https://hyperliquidapi.com
+- **Documentation**: https://hyperliquidapi.com/docs
+- **Approval Page**: https://hyperliquidapi.com/approve
+- **GitHub**: https://github.com/quiknode-labs/hyperliquid-sdk-python
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

hyperliquid_sdk-0.1.0/README.md

@@ -0,0 +1,261 @@
+# Hyperliquid SDK
+
+**The simplest way to trade on Hyperliquid.** One line to place orders, zero ceremony.
+
+```python
+from hyperliquid_sdk import HyperliquidSDK
+
+sdk = HyperliquidSDK()
+order = sdk.market_buy("BTC", notional=100)  # Buy $100 of BTC
+```
+
+That's it. No build-sign-send ceremony. No manual hash signing. No nonce tracking. Just trading.
+
+## Installation
+
+```bash
+pip install hyperliquid-sdk
+```
+
+## Quick Start
+
+### 1. Set your private key
+
+```bash
+export PRIVATE_KEY="0xYOUR_PRIVATE_KEY"
+```
+
+### 2. Start trading
+
+```python
+from hyperliquid_sdk import HyperliquidSDK
+
+sdk = HyperliquidSDK()
+
+# Market orders
+order = sdk.market_buy("BTC", size=0.001)
+order = sdk.market_sell("ETH", notional=100)  # $100 worth
+
+# Limit orders
+order = sdk.buy("BTC", size=0.001, price=65000, tif="gtc")
+
+# Check your order
+print(order.status)  # "filled" or "resting"
+print(order.oid)     # Order ID
+```
+
+## Features
+
+### One-Line Orders
+
+```python
+# Market orders - execute immediately
+sdk.market_buy("BTC", size=0.001)
+sdk.market_sell("ETH", notional=100)
+
+# Limit orders
+sdk.buy("BTC", size=0.001, price=65000)
+sdk.sell("ETH", size=0.5, price=4000, tif="gtc")
+
+# Perp trader aliases
+sdk.long("BTC", size=0.001, price=65000)
+sdk.short("ETH", notional=500, tif="ioc")
+```
+
+### Order Management
+
+```python
+# Place a resting order
+order = sdk.buy("BTC", size=0.001, price=60000, tif="gtc")
+
+# Modify it
+order.modify(price=61000)
+
+# Cancel it
+order.cancel()
+
+# Cancel all orders
+sdk.cancel_all()
+sdk.cancel_all("BTC")  # Just BTC orders
+```
+
+### Position Management
+
+```python
+# Close a position completely (SDK figures out size and direction)
+sdk.close_position("BTC")
+```
+
+### Fluent Order Builder
+
+For power users who want maximum control:
+
+```python
+from hyperliquid_sdk import Order
+
+order = sdk.order(
+    Order.buy("BTC")
+         .size(0.001)
+         .price(65000)
+         .gtc()
+         .reduce_only()
+)
+```
+
+### HIP-3 Markets
+
+Trade HIP-3 markets (like Hypersea) with the same API:
+
+```python
+sdk.buy("xyz:SILVER", notional=100, tif="ioc")
+```
+
+### Market Data
+
+```python
+# Get mid price
+mid = sdk.get_mid("BTC")
+
+# List all markets
+markets = sdk.markets()
+
+# View open orders
+orders = sdk.open_orders()
+```
+
+## Error Handling
+
+Clear, actionable errors with guidance:
+
+```python
+from hyperliquid_sdk import (
+    HyperliquidSDK,
+    ApprovalError,
+    ValidationError,
+    GeoBlockedError,
+)
+
+try:
+    order = sdk.buy("BTC", size=0.001, price=65000)
+except ApprovalError as e:
+    print(f"Need approval: {e.guidance}")
+    sdk.approve_builder_fee("1%")
+except ValidationError as e:
+    print(f"Invalid order: {e.message}")
+except GeoBlockedError as e:
+    print(f"Access denied: {e.guidance}")
+```
+
+## Auto-Approval
+
+Skip the approval step entirely:
+
+```python
+sdk = HyperliquidSDK(auto_approve=True)
+# Now just trade - approval happens automatically
+```
+
+## API Reference
+
+### HyperliquidSDK
+
+```python
+HyperliquidSDK(
+    private_key=None,      # Falls back to PRIVATE_KEY env var
+    auto_approve=False,    # Auto-approve builder fee
+    max_fee="1%",          # Max fee for auto-approval
+)
+```
+
+### Order Methods
+
+| Method | Description |
+|--------|-------------|
+| `buy(asset, size=, price=, tif=)` | Place a buy order |
+| `sell(asset, size=, price=, tif=)` | Place a sell order |
+| `market_buy(asset, size=)` | Market buy |
+| `market_sell(asset, size=)` | Market sell |
+| `long(asset, ...)` | Alias for buy |
+| `short(asset, ...)` | Alias for sell |
+
+### Order Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `asset` | str | Asset name ("BTC", "ETH", "xyz:SILVER") |
+| `size` | float | Size in asset units |
+| `notional` | float | Size in USD (alternative to size) |
+| `price` | float | Limit price |
+| `tif` | str | Time in force: "ioc", "gtc", "alo", "market" |
+| `reduce_only` | bool | Close position only |
+
+### Management Methods
+
+| Method | Description |
+|--------|-------------|
+| `cancel(oid)` | Cancel order by ID |
+| `cancel_all(asset=None)` | Cancel all orders |
+| `close_position(asset)` | Close a position |
+| `modify(oid, price=, size=)` | Modify an order |
+
+### Query Methods
+
+| Method | Description |
+|--------|-------------|
+| `get_mid(asset)` | Get mid price |
+| `markets()` | List all markets |
+| `open_orders()` | Get open orders |
+| `order_status(oid)` | Get order status |
+| `approval_status()` | Check builder fee approval |
+
+### PlacedOrder Object
+
+```python
+order = sdk.buy("BTC", size=0.001, price=65000, tif="gtc")
+
+order.oid          # Order ID
+order.status       # "filled", "resting", "error: ..."
+order.asset        # "BTC"
+order.side         # "buy" or "sell"
+order.size         # "0.001"
+order.price        # "65000"
+order.filled_size  # Filled amount (if filled)
+order.is_filled    # True if filled
+order.is_resting   # True if resting
+
+order.cancel()     # Cancel this order
+order.modify(price=66000)  # Modify this order
+```
+
+## Examples
+
+See the [examples](./sdk_examples/) directory for complete working examples:
+
+- `market_order.py` - Market order in 5 lines
+- `place_order.py` - Limit order
+- `roundtrip.py` - Buy then sell
+- `cancel_order.py` - Place and cancel
+- `modify_order.py` - Place and modify
+- `close_position.py` - Close a position
+- `fluent_builder.py` - Power user patterns
+- `full_demo.py` - All features
+
+## Compared to Raw API
+
+| Operation | Raw API | SDK | Reduction |
+|-----------|---------|-----|-----------|
+| Market order | 35 lines | 1 line | 97% |
+| Limit order | 39 lines | 1 line | 97% |
+| Cancel order | 71 lines | 2 lines | 97% |
+| Roundtrip | 64 lines | 4 lines | 94% |
+
+## Links
+
+- **Website**: https://hyperliquidapi.com
+- **Documentation**: https://hyperliquidapi.com/docs
+- **Approval Page**: https://hyperliquidapi.com/approve
+- **GitHub**: https://github.com/quiknode-labs/hyperliquid-sdk-python
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

hyperliquid_sdk-0.1.0/approve.py

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

hyperliquid_sdk-0.1.0/cancel_order.py

@@ -0,0 +1,71 @@
+"""Place a resting order (GTC, 3% below mid), then cancel it."""
+
+import json
+from client import exchange, sign_hash, get_mid
+
+COIN = "BTC"
+
+mid = get_mid(COIN)
+if mid == 0:
+    print(f"Could not fetch {COIN} mid price")
+    raise SystemExit(1)
+
+sz = round(11.0 / mid, 5)
+rest_px = int(mid * 0.97)
+
+print(f"{COIN} mid: ${mid:,.2f}")
+print(f"Placing resting BUY {sz} @ {rest_px} (GTC, 3% below mid)\n")
+
+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 = exchange({
+    "action": res["action"],
+    "nonce": res["nonce"],
+    "signature": sig,
+})
+
+exchange_resp = result["exchangeResponse"]
+statuses = exchange_resp.get("response", {}).get("data", {}).get("statuses", [])
+
+oid = None
+for s in statuses:
+    if isinstance(s, dict) and "resting" in s:
+        oid = s["resting"].get("oid")
+        break
+
+if oid is None:
+    print("Could not extract OID from resting order")
+    print(json.dumps(exchange_resp, indent=2))
+    raise SystemExit(1)
+
+print(f"Order resting (OID: {oid})")
+print("Cancelling...\n")
+
+cancel_action = {
+    "type": "cancel",
+    "cancels": [{"a": COIN, "o": oid}],
+}
+
+res = exchange({"action": cancel_action})
+sig = sign_hash(res["hash"])
+
+result = exchange({
+    "action": cancel_action,
+    "nonce": res["nonce"],
+    "signature": sig,
+})
+
+print(json.dumps(result["exchangeResponse"], indent=2))
+print("\nOrder cancelled.")

hyperliquid_sdk-0.1.0/check_status.py

@@ -0,0 +1,7 @@
+"""Check builder fee approval status."""
+
+import json
+from client import get_approval, address
+
+res = get_approval(address)
+print(json.dumps(res, indent=2))