Quick Start Guide

This guide will walk you through the essential steps to start using the Hyperliquid Python SDK, from configuration to fetching data and placing your first order.

1. Configuration

Before you can interact with the API, you need to configure your account credentials. The SDK is designed to read from a config.json file.

First, copy the example configuration file: 

cp examples/config.json.example examples/config.json

Now, open examples/config.json and edit it:

{
    "secret_key": "YOUR_PRIVATE_KEY_HERE",
    "account_address": "YOUR_PUBLIC_ADDRESS_HERE"
}
  • secret_key: Your 64-character hexadecimal private key (prefixed with 0x). This can be the key for your main wallet or a dedicated API wallet.
  • account_address: The public address of your main Hyperliquid account. This is required, especially if you are using an API wallet's secret_key.

For more details, see the Configuration page.

2. Fetching Public Information

The Info class is used to access public, read-only data from the Hyperliquid API. It does not require a private key.

Here's a simple script to fetch your account's state. Create a file named my_first_script.py:

import json
from hyperliquid.info import Info
from hyperliquid.utils import constants

# Your main account's public address
MY_ADDRESS = "YOUR_PUBLIC_ADDRESS_HERE"

def main():
    # Use constants.MAINNET_API_URL for mainnet
    info = Info(constants.TESTNET_API_URL, skip_ws=True)

    # Fetch your user state
    user_state = info.user_state(MY_ADDRESS)

    # Print the margin summary
    print("Margin Summary:")
    print(json.dumps(user_state["marginSummary"], indent=2))

    # Print your open positions
    print("\nOpen Positions:")
    for position in user_state["assetPositions"]:
        if float(position["position"]["szi"]) != 0:
            print(json.dumps(position["position"], indent=2))

if __name__ == "__main__":
    main()

Replace YOUR_PUBLIC_ADDRESS_HERE with your address and run the script:

python my_first_script.py

This will print your current margin summary and any open positions on the Testnet.

3. Placing an Order

The Exchange class is used for actions that require a signature, such as placing or canceling orders. It needs access to your private key.

This example places a small limit order for ETH that is priced far from the market to ensure it rests in the order book.

import json
import example_utils  # Helper for loading config
from hyperliquid.utils import constants

def main():
    # This helper function loads your secret key and address from config.json
    address, info, exchange = example_utils.setup(base_url=constants.TESTNET_API_URL, skip_ws=True)

    coin = "ETH"
    is_buy = True
    size = 0.01
    limit_price = 1000  # A price far from the market
    order_type = {"limit": {"tif": "Gtc"}} # Good 'til Canceled

    print(f"Placing a limit {'buy' if is_buy else 'sell'} order for {size} {coin} at ${limit_price}...")

    # Place the order
    order_result = exchange.order(coin, is_buy, size, limit_price, order_type)
    print(json.dumps(order_result, indent=2))

    # If the order was successful, cancel it
    if order_result["status"] == "ok":
        status = order_result["response"]["data"]["statuses"][0]
        if "resting" in status:
            oid = status["resting"]["oid"]
            print(f"\nOrder placed successfully with OID: {oid}. Now canceling it.")
            cancel_result = exchange.cancel(coin, oid)
            print(json.dumps(cancel_result, indent=2))

if __name__ == "__main__":
    main()

To run this, you will need the example_utils.py file from the examples directory of the SDK repository, and your config.json must be in the same directory.

This script demonstrates the basic flow:

  1. Initialize the Exchange object.
  2. Define the order parameters.
  3. Call exchange.order(...) to place the order.
  4. Parse the response to get the order ID (OID).
  5. Call exchange.cancel(...) to cancel the newly placed order.

Next Steps

You've now seen how to install, configure, and use the basic features of the SDK. To explore more advanced functionalities, check out the Examples section or dive into the detailed API Reference.