hl-sdk 0.1.0

An unofficial client SDK for Hyperliquid

Unofficial Hyperliquid Python SDK

📚 Documentation | API Reference | Examples

A high-performance, async Python SDK for interacting with the Hyperliquid decentralized exchange.

Features

• 🚀 Async/await support - Built for high-performance async applications
• 📊 Complete API coverage - Leverage all available Hyperliquid functionalities
• 🔄 WebSocket support - Real-time market data and order updates
• 🛡️ Type-safe - Full type hints and runtime error handling

Installation

Requirements

• Python 3.11 or higher

Install from PyPI

pip install hl-sdk

Install from source

git clone https://github.com/papicapital/hl-sdk.git
cd hl-sdk
pip install -e .

Quickstart

Basic Usage

import asyncio
from hl import Api
from hl.account import Account

async def main():
    # Initialize with your credentials
    account = Account(
        address="0xYourAddress",
        secret_key="0xYourSecretKey"
    )

    # Create API client
    api = await Api.create(account=account)

    # Get market data
    result = await api.info.perpetual_meta()
    if result.is_ok():
        meta = result.unwrap()
        print(f"Connected to Hyperliquid: {len(meta.universe)} markets available")

    # Get your open orders
    result = await api.info.user_open_orders()
    if result.is_ok():
        orders = result.unwrap()
        print(f"You have {len(orders)} open orders")

if __name__ == "__main__":
    asyncio.run(main())

Environment Variables

For security, store your credentials in environment variables:

export HL_ADDRESS="0xYourAddress"
export HL_SECRET_KEY="0xYourSecretKey"

Then in your code:

import os
from hl.account import Account

account = Account(
    address=os.environ["HL_ADDRESS"],
    secret_key=os.environ["HL_SECRET_KEY"]
)

Place an Order

from hl.types import OrderType, OrderRequest

async def place_limit_order():
    # Create a limit order
    order = OrderRequest(
        asset="BTC",
        is_buy=True,
        size=Decimal("0.001"),  # Size in BTC
        limit_price=Decimal("50000.0"),  # Limit price
        order_type={"limit": {"tif": "Gtc"}},
        reduce_only=False
    )

    # Place the order
    result = await api.exchange.order(order)
    print(f"Order placed: {result.unwrap()}")

WebSocket Subscriptions

from hl.types import L2BookSubscription

async def stream_orderbook():
    # Use WebSocket context manager
    async with api.ws.run():
        # Subscribe to the L2 book for BTC
        sub_id, queue = await api.ws.subscribtions.l2_book(asset="BTC")

        # Process incoming messages
        for _ in range(10):  # Process 10 messages
            msg = await queue.get()
            print(f"Orderbook update: {msg}")

        # Unsubscribe when done
        await api.ws.unsubscribe(sub_id)

Examples

Check out the examples directory for more detailed examples:

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/papicapital/hl-sdk.git
cd hl-sdk

# Install with development dependencies
uv sync --all-groups

# Install pre-commit hooks
uv run pre-commit install

Run Tests

uv run pytest

Type Checking

uv run mypy hl tests

Code Formatting

uv run ruff check --fix
uv run ruff format

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This is an unofficial SDK and is not affiliated with Hyperliquid. Use at your own risk.