Python SDK

Overview

The hypercore-sdk package is a typed, async-ready Python client for accessing Hyperliquid market data through Aleatoric infrastructure. It covers all supported transport protocols — HTTP JSON-RPC, gRPC, WebSocket, and Server-Sent Events — behind a consistent, well-documented interface.

The SDK is open-source on GitHub and published to PyPI as hypercore-sdk. It passes mypy in strict mode with zero errors, ships with 127 tests at 92.45% line coverage, and requires Python 3.10 or later.

Installation

Install from PyPI:

pip install hypercore-sdk

For development (includes test runner, linter, type checker, and build tools):

pip install hypercore-sdk[dev]

Configuration

All clients read their defaults from environment variables. Override any value by passing the corresponding argument to the client constructor.

Variable	Purpose	Default
HYPER_RPC_URL	JSON-RPC endpoint	https://rpc.aleatoric.systems/
HYPER_GRPC_TARGET	gRPC endpoint	hl.grpc.aleatoric.systems:443
HYPER_UNIFIED_STREAM_URL	Unified Stream endpoint	https://unified.grpc.aleatoric.systems
HYPER_WS_URL	WebSocket endpoint	wss://api.hyperliquid.xyz/ws
HYPER_API_KEY	API key for authenticated requests	—
UNIFIED_STREAM_KEY	Unified Stream API key	—
ALEATORIC_GRPC_KEY	gRPC API key	—
HYPER_TIMEOUT_MS	Request timeout in milliseconds	10000
HYPER_VERIFY_TLS	Enable TLS certificate verification (HTTP)	true
HYPER_GRPC_TLS	Enable TLS for gRPC channel	true

Core Clients

HyperCoreAPI

The primary HTTP client. Built on httpx with connection pooling, keepalive, and context manager support for deterministic resource cleanup.

from hypercore_sdk import HyperCoreAPI

with HyperCoreAPI() as api:
    block = api.block_number()
    mids = api.all_mids()
    btc = api.coin_mid("BTC")

Market intelligence

These methods aggregate multiple upstream calls into a single return value, reducing round trips and simplifying common workflows.

• market_snapshot(coin) — returns mid price, top-of-book bid/ask, and asset context in one call.
• user_flow_snapshot(address, dex) — returns open orders and a fill summary for a given address.

Account and history

• user_fills(), user_fills_by_time() — trade execution history.
• funding_history() — funding rate payments received or paid.
• portfolio() — current positions and margin state.
• historical_orders() — past order records including cancellations.
• user_non_funding_ledger_updates() — deposits, withdrawals, and other non-funding ledger events.

GrpcClient

Async gRPC client with TLS, metadata-based authentication, and built-in health checking. Streaming methods return async generators that yield events as they arrive.

from hypercore_sdk import GrpcClient

async with GrpcClient() as grpc:
    health = await grpc.health_check()
    services = await grpc.list_services()

    async for price in grpc.mid_price_stream("BTC", max_events=10):
        print(f"BTC: {price}")

    async for liq in grpc.liquidations_stream("BTC", max_events=5):
        print(f"Liquidation: {liq}")

The health_check() method uses the standard gRPC health checking protocol. list_services() uses server reflection to enumerate available service definitions at runtime.

UnifiedStreamClient

SSE event consumer that provides both point-in-time REST snapshots and long-lived streaming generators. Useful when you need a single client for both polling and real-time consumption.

from hypercore_sdk import UnifiedStreamClient

client = UnifiedStreamClient()

# REST snapshots
stats = client.stats()
pulse = client.consensus_pulse()
book = client.l2_book(coin="BTC", depth=10)
mids = client.all_mids()

# SSE streaming (generators)
for event in client.sse_events(max_events=20):
    print(event["event_type"], event["payload"])

for mid in client.sse_all_mids(max_events=5):
    print(mid)

Streaming methods accept a max_events parameter to bound consumption. Omit it to stream indefinitely until the connection closes or you break out of the loop.

CLI

The SDK ships with a command-line interface that exposes the most common operations without writing code. After installation, the hypercore-sdk command is available on your PATH.

hypercore-sdk --help
hypercore-sdk block-number
hypercore-sdk all-mids
hypercore-sdk grpc-health
hypercore-sdk grpc-stream-mids BTC
hypercore-sdk unified-stats

The CLI reads the same environment variables described in the Configuration section above.

MCP Server

The SDK includes a built-in MCP server for integration with AI assistants such as Claude and ChatGPT. The server exposes 12 tools that map to the SDK’s core methods. See MCP Servers for setup instructions.

hypercore-sdk-mcp

Quality

The SDK is designed for production use in trading systems where correctness and reliability are non-negotiable.

Aspect	Detail
Type safety	mypy strict mode, zero errors
Test coverage	127 tests, 92.45% line coverage (90% gate)
Build verification	python -m build + twine check in CI
Async support	Full async/await via grpcio and httpx
Connection pooling	httpx connection limits with keepalive
Error handling	Typed exceptions with status propagation
Docker	Runtime and dev targets with docker-compose

Changelog

0.3.0

• Added UnifiedStreamClient with REST snapshots and SSE streaming generators.
• Added consensus_pulse() endpoint.
• Added liquidations_stream() to GrpcClient.
• MCP server with 12 tools.

0.2.0

• Added GrpcClient with health checking and server reflection.
• Added market_snapshot() and user_flow_snapshot() convenience methods.

0.1.0

• Initial release with HyperCoreAPI and CLI.

Next Steps

• TypeScript SDK — Node.js and browser client.
• MCP Servers — Connect to Claude, ChatGPT, and other AI assistants.
• Connecting — Transport-level integration examples.
• Unified Stream — Full event type reference.