Configuration

The SDK requires your account credentials to sign and send transactions to the Hyperliquid API. This is handled through a config.json file.

Creating the `config.json` File

All examples in this repository are configured to load credentials from a config.json file located in the examples/ directory. To get started, you should copy the provided template:

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

Then, edit the examples/config.json file to add your credentials.

`config.json` Structure

The configuration file has the following structure:

{
    "comments": "...",
    "keystore_path": "",
    "secret_key": "",
    "account_address": "",
    "multi_sig": {
        "authorized_users": [
            {
                "comment": "signer 1",
                "secret_key": "",
                "account_address": ""
            },
            {
                "comment": "signer 2",
                "secret_key": "",
                "account_address": ""
            }
        ]
    }
}

Key Fields Explained

`secret_key`

This is the private key of the wallet you want to use for signing transactions. It must be a 64-character hexadecimal string, prefixed with 0x.

Main Wallet: You can use the private key of your main Hyperliquid account.
API Wallet (Recommended for Security): For enhanced security, it is highly recommended to generate a dedicated API wallet on the Hyperliquid API page. This key has trading permissions but cannot perform withdrawals. Set the secret_key to the private key of this API wallet.

Example:

"secret_key": "0x0123456789012345678901234567890123456789012345678901234567890123"

`account_address`

This is the public Ethereum address of your main Hyperliquid account (the one you deposited funds into). It should be a 42-character hexadecimal string, prefixed with 0x.

If secret_key is for your main wallet: This field is optional. If left blank, it will be automatically derived from the secret_key.
If secret_key is for an API wallet: This field is mandatory. You must provide the public address of your main account so the API knows which account the agent is acting on behalf of.

Example:

"account_address": "0xcd5051944f780a621ee62e39e493c489668acf4d"

`keystore_path` (Alternative to `secret_key`)

As an alternative to storing your private key directly in the config file, you can provide a path to an encrypted JSON keystore file. The script will then prompt you to enter the password interactively to decrypt the key.

Note: If both secret_key and keystore_path are provided, secret_key will take precedence.

`multi_sig`

This section is for advanced multi-signature account configurations. It allows you to specify the secret keys of authorized users who can sign actions for a multi-sig account. This is not needed for standard accounts.

Loading Configuration in Code

The examples/example_utils.py file provides a helper function setup() that handles loading the config.json file and initializing the Info and Exchange objects.

# From examples/example_utils.py

import json
import os
import eth_account

def setup(base_url=None, skip_ws=False):
    config_path = os.path.join(os.path.dirname(__file__), "config.json")
    with open(config_path) as f:
        config = json.load(f)

    account = eth_account.Account.from_key(config["secret_key"])
    address = config["account_address"]
    if address == "":
        address = account.address

    # ... initialization of Info and Exchange objects ...
    return address, info, exchange

You can use this utility in your own scripts or adapt its logic for your specific application structure.

Configuration

Creating the config.json File

config.json Structure

Key Fields Explained

secret_key

account_address

keystore_path (Alternative to secret_key)

multi_sig