create_hyperliquid_session

Documentation for eth_defi.hyperliquid.session.create_hyperliquid_session function.

create_hyperliquid_session(api_url='https://api.hyperliquid.xyz', retries=5, backoff_factor=0.5, requests_per_second=1.0, pool_maxsize=32, rate_limit_db_path=PosixPath('/home/runner/.tradingstrategy/hyperliquid/rate-limit.sqlite'), rotator=None, verbose_throttling=None, proxy_failure_log_level=None)

Create a HyperliquidSession configured for Hyperliquid API.

The session is configured with:

  • The API URL stored in HyperliquidSession.api_url

  • Rate limiting to respect Hyperliquid API throttling (thread-safe via SQLite)

  • Retry logic for handling transient errors using exponential backoff

  • Optional proxy support with automatic rotation on failure

The rate limiter uses SQLite backend for thread-safe coordination across multiple threads (e.g., when using joblib.Parallel with threading backend).

When proxies are configured and workers are cloned via HyperliquidSession.clone_for_worker(), each worker gets its own rate limiter because Hyperliquid rate limits are per IP.

Example:

from eth_defi.hyperliquid.session import create_hyperliquid_session, HYPERLIQUID_TESTNET_API_URL

# Mainnet (default)
session = create_hyperliquid_session()

# Testnet
session = create_hyperliquid_session(api_url=HYPERLIQUID_TESTNET_API_URL)

# With Webshare rotator (persistent failure tracking via ProxyStateManager)
from eth_defi.event_reader.webshare import load_proxy_rotator

rotator = load_proxy_rotator()
session = create_hyperliquid_session(rotator=rotator)
Parameters

  • api_url (str) – Hyperliquid API base URL. Defaults to mainnet (HYPERLIQUID_API_URL). Pass HYPERLIQUID_TESTNET_API_URL for testnet.

  • retries (int) – Maximum number of retry attempts for failed requests

  • backoff_factor (float) – Backoff factor for exponential retry delays

  • requests_per_second (float) – Maximum requests per second to avoid rate limiting. Defaults to 1.0 based on Hyperliquid’s 1200 weight/minute limit with most info endpoints having weight 20.

  • pool_maxsize (int) – Maximum number of connections to keep in the connection pool. Should be at least as large as max_workers when using parallel requests. Defaults to 32.

  • rate_limit_db_path (pathlib.Path) – Path to SQLite database for storing rate limit state. Using SQLite ensures thread-safe rate limiting across multiple threads. Defaults to ~/.tradingstrategy/hyperliquid/rate-limit.sqlite.

  • rotator (eth_defi.event_reader.webshare.ProxyRotator | None) – Optional ProxyRotator (typically from load_proxy_rotator()). Provides proxy rotation with persistent failure tracking via ProxyStateManager.

  • verbose_throttling (bool | None) –

    Control rate-limit / throttling log messages.

    • None (default): off when proxies are used, on otherwise. With proxies, every worker thread hits the rate limiter independently and the resulting log spam is not useful.

    • True: always log throttling messages.

    • False: always suppress throttling messages.

  • proxy_failure_log_level (int | None) –

    Log level for proxy failure/rotation messages (from ProxyRotator, ProxyStateManager, and LoggingRetry).

    • None (default): logging.DEBUG when proxies are used, logging.WARNING otherwise.

    • Pass e.g. logging.DEBUG to suppress or logging.WARNING to always show.

Returns

Configured HyperliquidSession with rate limiting and retry logic

Return type

eth_defi.hyperliquid.session.HyperliquidSession