scan_vaults

Documentation for eth_defi.hyperliquid.vault_scanner.scan_vaults function.

scan_vaults(session, db_path=PosixPath('/home/runner/.tradingstrategy/hyperliquid/vaults.duckdb'), stats_url='https://stats-data.hyperliquid.xyz/Mainnet/vaults', fetch_follower_counts=True, timeout=30.0, limit=None, max_workers=16)

Scan all Hyperliquid vaults and store snapshots in DuckDB.

This function fetches all vault summaries from the Hyperliquid API, calculates key metrics (TVL, PnL, etc.), and stores a timestamped snapshot for each vault in the database.

Example:

from eth_defi.hyperliquid.session import create_hyperliquid_session
from eth_defi.hyperliquid.vault_scanner import scan_vaults

session = create_hyperliquid_session()
db = scan_vaults(session)

# Get latest snapshot for each vault
df = db.get_latest_snapshots()
print(f"Scanned {len(df)} vaults")

db.close()
Parameters

  • session (requests.sessions.Session) – HTTP session for API requests. Use eth_defi.hyperliquid.session.create_hyperliquid_session() to create one.

  • db_path (pathlib.Path) – Path to the DuckDB database file. Defaults to ~/.tradingstrategy/hyperliquid/vaults.duckdb.

  • stats_url (str) – Hyperliquid stats-data API URL for vault listing

  • fetch_follower_counts (bool) – If True, fetch detailed vault info to get follower counts. This requires an additional API call per vault and is slower.

  • timeout (float) – HTTP request timeout in seconds

  • limit (int | None) – Limit the number of vaults to scan. Internal testing only.

  • max_workers (int) – Maximum number of parallel workers for fetching vault details. Defaults to 16.

Returns

VaultSnapshotDatabase instance with the newly inserted snapshots

Return type

eth_defi.hyperliquid.vault_scanner.VaultSnapshotDatabase

Note

The session’s rate limiter restricts requests to 1/second by default. Having many parallel workers does not speed up processing - they will queue behind the rate limiter. With ~8000 vaults and 1 req/sec, a full scan takes approximately 2-3 hours. If you encounter 429 errors after retries are exhausted, the Hyperliquid API is rate limiting you beyond what the client-side limiter can prevent.