hyperliquid.session

Documentation for eth_defi.hyperliquid.session Python module.

HTTP session management for Hyperliquid API.

This module provides session creation with retry logic and rate limiting for Hyperliquid API requests.

Rate limiting is thread-safe using SQLite backend, so the session can be shared across multiple threads when using joblib.Parallel or similar.

Module Attributes

DEFAULT_RETRIES	Default number of retries for API requests
DEFAULT_BACKOFF_FACTOR	Default backoff factor for retries (seconds)
DEFAULT_REQUESTS_PER_SECOND	Default rate limit for Hyperliquid API requests per second.

Functions

create_hyperliquid_session([retries, ...])

Create a requests Session configured for Hyperliquid API.

HYPERLIQUID_RATE_LIMIT_SQLITE_DATABASE = PosixPath('/home/runner/.tradingstrategy/hyperliquid/rate-limit.sqlite')

Default SQLite database path for rate limiting state.

Using SQLite ensures thread-safe rate limiting across multiple threads when using joblib.Parallel or similar parallel processing.

DEFAULT_RETRIES = 5

Default number of retries for API requests

DEFAULT_BACKOFF_FACTOR = 0.5

Default backoff factor for retries (seconds)

DEFAULT_REQUESTS_PER_SECOND = 1.0

Default rate limit for Hyperliquid API requests per second.

Hyperliquid has a limit of 1200 weight per minute per IP. Most info endpoints have weight 20, so: 1200 / 20 = 60 requests/minute = 1 request/second.

See https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/rate-limits-and-user-limits

create_hyperliquid_session(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'))

Create a requests Session configured for Hyperliquid API.

The session is configured with:

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

• Retry logic for handling transient errors using exponential backoff

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

• See rate limits here.

Example:

from eth_defi.hyperliquid.session import create_hyperliquid_session

session = create_hyperliquid_session()
response = session.get("https://api.hyperliquid.xyz/info")

Parameters

• 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.

Returns

Configured requests Session with rate limiting and retry logic

Return type

requests.sessions.Session